supabase / supabase-flutter / 36693820421

93%

push

github

feat(supabase_flutter): add RealtimeLifecycleOptions to delay or skip the realtime disconnect on pause (#1899)

## Summary

`Supabase.initialize` installs an app lifecycle listener that
disconnects the realtime socket as soon as the app is paused and, on
resume, reconnects it and rejoins every joined channel. That is not
configurable, and on iOS a full-screen view such as a video ad or a
system sheet reports the app as paused while it is on screen. An app
that shows many of those tears down and rebuilds the socket, and
re-authorizes every private channel, once per ad.

This adds `RealtimeLifecycleOptions`, passed as
`realtimeLifecycleOptions` to `Supabase.initialize`:

- `disconnectAfterPause`: a grace period. The disconnect is scheduled
when the app is paused and cancelled if the app is resumed first, so a
short pause costs nothing. `detached` still disconnects right away.
Defaults to `Duration.zero`, which is the current behaviour.
- `RealtimeLifecycleOptions.manual()`: the socket is left out of the
lifecycle handling entirely. Plugins are still resumed.

```dart
await Supabase.initialize(
  url: url,
  publishableKey: key,
  realtimeLifecycleOptions: const RealtimeLifecycleOptions(
    disconnectAfterPause: Duration(minutes: 1),
  ),
);
```

## Notes

- The pending pause timer is cancelled on resume, detach and dispose, so
a disposed instance never disconnects a client it no longer owns.
- iOS suspends a backgrounded app within seconds and Android 12+ freezes
cached apps, and no Dart timer runs while frozen. The pause therefore
also records a `DateTime.now()` stamp, and a resume after a pause that
outlasted the grace period closes the possibly dead socket before
reconnecting, which is today's behaviour for real backgrounding. A short
pause such as a full-screen ad, where the process stays in the
foreground on both platforms, still costs nothing.
- The new symbols are registered under
`realtime.configuration.deferred_disconnect` in `sdk-compliance.y... (continued)

38 of 39 new or added lines in 2 files covered. (97.44%)

8834 of 9677 relevant lines covered (91.29%)

4.94 hits per line