Skip to content

Refactor FxA state machine to simplify transitions#7359

Open
skhamis wants to merge 1 commit into
mozilla:mainfrom
skhamis:fxa-state-machine-refactor
Open

Refactor FxA state machine to simplify transitions#7359
skhamis wants to merge 1 commit into
mozilla:mainfrom
skhamis:fxa-state-machine-refactor

Conversation

@skhamis
Copy link
Copy Markdown
Contributor

@skhamis skhamis commented May 8, 2026

Now that FxiOS has the new state machine, we're able to now re-look at the state machine system as a whole and we realized we can simplify it now that we're not merging with existing systems on the consumers. My main goals were:

  1. Make it easy to reason about how clients move through the FxA flows
  2. Make it simple to add/modify existing states
  3. Try limit any API churn (for now), and simplify the internal parts before any public-facing API changes (if any)

@bendk had to manage two state machines in android which was the reason for the initial system, but now that they've migrated fully over, the idea came that we can remove the internal state completely and move to a flat-state-machine style. It's in draft now as I think this is a strong denature and want to get thoughts on this before moving on.

Pull Request checklist

  • Breaking changes: This PR follows our breaking change policy
    • This PR follows the breaking change policy:
      • This PR has no breaking API changes, or
      • There are corresponding PRs for our consumer applications that resolve the breaking changes and have been approved
  • Quality: This PR builds and tests run cleanly
    • Note:
      • For changes that need extra cross-platform testing, consider adding [ci full] to the PR title.
      • If this pull request includes a breaking change, consider cutting a new release after merging.
  • Tests: This PR includes thorough tests or an explanation of why it does not
  • Changelog: This PR includes a changelog entry in CHANGELOG.md or an explanation of why it does not need one
    • Any breaking changes to Swift or Kotlin binding APIs are noted explicitly
  • Dependencies: This PR follows our dependency management guidelines
    • Any new dependencies are accompanied by a summary of the due diligence applied in selecting them.

@skhamis skhamis requested a review from bendk May 8, 2026 21:41
@skhamis skhamis force-pushed the fxa-state-machine-refactor branch from 6b5e283 to bd490c0 Compare May 8, 2026 23:12
Copy link
Copy Markdown
Contributor

@bendk bendk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this approach a lot, it feels way more direct than having the internal states implicitly trigger a FirefoxAccount method call. I just left some comments/questions about the details.

impl StateMachineErr {
/// Programming errors (logic / invalid-transition) become `Fatal` and
/// ignore `target_if_handled`; everything else becomes `Handled`.
pub fn from_cause(cause: Error, target_if_handled: FxaState) -> Self {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: StateMachineErr:from_cause() and Result<T, StateMachineError>::err_state() do pretty much the same thing but have very different names. I can't think of a good single name, but maybe we could get a pair of names that seem related like StateMachineErr::new() and Result<T, StateMachineError>::map_err_to_state_machine_err() . I don't really love those names either though, so whatever you want to go with is good with me.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah good callouts, I'll go to ::new() as that feels the most "rust-y". I feel like for chaining on the result maybe going to_state_machine_err has the strongest readability imo.

Comment thread components/fxa-client/src/state_machine/transitions.rs Outdated
@skhamis skhamis force-pushed the fxa-state-machine-refactor branch from bd490c0 to 2ceb842 Compare May 12, 2026 01:03
@skhamis skhamis marked this pull request as ready for review May 12, 2026 19:22
@skhamis
Copy link
Copy Markdown
Contributor Author

skhamis commented May 12, 2026

@mhammond since you also recently used the FxA state machine/authorization I'd love to also get your thoughts to ensure we're moving in the right direction here.

@skhamis skhamis requested a review from mhammond May 12, 2026 22:41
Copy link
Copy Markdown
Member

@mhammond mhammond left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a nice improvement, thanks!

FxaError::Authentication
if self.policy.auth_retry_with_cache_clear && !auth_retried =>
{
self.inner.clear_access_token_cache();
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm actually skeptical this is needed here (I don't think access tokens are used by the state machine?) - but I see it already existed, so I wont get too distracted by it :)

Comment thread components/fxa-client/src/state_machine/README.md Outdated
Comment thread components/fxa-client/src/state_machine/README.md Outdated
.to_state_machine_err(|| S::AuthIssues)?;
Ok(if active { S::Connected } else { S::AuthIssues })
}
Err(cause) => Err(StateMachineErr::new(cause, S::Disconnected)),
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems a little wrong (and may also be wrong currently) - if ensure_capabilities() fails due to a non-auth error (eg, a network error), the state becomes disconnected? Shouldn't this use something like with_auth_recovery where there's a bit of retry logic (even though, as I mentioned, clearing the access token cache and retrying isn't going to help in practice because ensure_capabilities() doesn't use an access token).

And for the is_auth_error case, it also seems wrong that failure to ensure capabilities due to an auth error ends up in the Connected state when we haven't set the device capabilities?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely agree with this, I think this makes sense to prioritize in the follow-up where we're removing some of the public APIs and then we can start changing what we're actually doing in the state machine. Right now I'm leaning towards just keeping the patch for simplifying and consolidating just incase we need to think through what actually happens here (and also maybe removing clearing the access token too)

Comment thread components/fxa-client/src/state_machine/transitions.rs Outdated
@skhamis skhamis force-pushed the fxa-state-machine-refactor branch from 2ceb842 to c730c06 Compare May 13, 2026 01:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants