supabase / supabase-flutter / 28278469437

86%

Build Type

push

github

Committed by web-flow

Commit Message

feat(gotrue): surface the sign-out reason on the signedOut event (#1453)

## What

Adds `AuthState.signOutReason`, a typed `SignOutReason` populated on the
`signedOut` event so listeners can tell **why** the user was signed out:

- `userInitiated` for an explicit `signOut()`.
- `sessionExpired` when the refresh token was rejected (invalid or
expired) and the session was removed.
- `sessionMissing` when a stored session could not be recovered because
it was missing required data.

It is `null` for every event other than `signedOut`, and also `null` for
`signedOut` events received from another tab via `web.BroadcastChannel`.

## Why

Follow-up to #1450, which stops `recoverSession` from double-reporting
an expected sign-out as an uncaught stream error. The remaining concern
was that a pure `onAuthStateChange` listener then sees `signedOut`
without knowing why the user was signed out, removing the ability to
handle it differently or notify the user.

This restores that capability through the event itself, rather than
through an error that only reaches listeners with an `onError` handler:

```dart
supabase.auth.onAuthStateChange.listen((state) {
  if (state.event == AuthChangeEvent.signedOut &&
      state.signOutReason != null &&
      state.signOutReason != SignOutReason.userInitiated) {
    // involuntary sign out (e.g. expired session) -> show a message
  }
});
```

## How

- New `SignOutReason` enum (`userInitiated`, `sessionExpired`,
`sessionMissing`), exported from `gotrue.dart`.
- `AuthState` gains a nullable `signOutReason` field, threaded through
`notifyAllSubscribers`.
- `signOut()` now delegates to a private `_signOut({scope, reason})` so
the public API is unchanged while internal callers can pass a reason.
- `recoverSession` and `setInitialSession` sign out with the appropriate
reason and now throw `AuthException`s tagged with
`ErrorCode.sessionMissing` / `ErrorCode.sessionExpired` (new error
codes).
- The non-retryable refresh failure path s... (continued)

Coverage Stats

20 of 24 new or added lines in 2 files covered. (83.33%)

112 existing lines in 2 files now uncovered.

4121 of 4812 relevant lines covered (85.64%)

3.69 hits per line