supabase / supabase-flutter / 28190414303

85%

push

github

fix(realtime): surface async postgres_changes system error as channelError (#1470)

## Summary

Fixes #1466.

A `postgres_changes` channel can report
`RealtimeSubscribeStatus.subscribed` and stay joined while delivering
**zero** events, indefinitely, when the server-side replication
subscription fails *after* the phoenix join succeeds. The failure is
delivered as an asynchronous `system` event with `status: error`, but
the SDK only exposes that via `onSystemEvents(...)` (documented "for
debugging purposes") and never forwards it to the `.subscribe()` status
callback — a silent "zombie" channel: green/connected to the app, but
dead.

This is especially painful on reconnect/resume flows where the access
token may be stale (e.g. the refresh timer was throttled while the app
was idle/backgrounded). The channel re-subscribes, the join succeeds,
the app marks it healthy, and it silently delivers nothing until the
next reconnect. It bit us as a user-facing incident: live data silently
stopped updating after a reconnect.

## Root cause

`postgres_changes` is an extension whose replication subscription is set
up asynchronously by the server, *after* the channel join.
`.subscribe()`'s status is driven by the phoenix join
(`joined/errored/closed/timeout`), and there is no
`RealtimeSubscribeStatus` value for "joined, but the extension
subscription failed." The join reply optimistically echoes the requested
`postgres_changes` config (with server-assigned binding ids), so binding
reconciliation succeeds and `subscribed` fires *before* the replication
is confirmed live. The real verdict arrives on a later `system
status=error` event, which the high-level API drops on the floor.

Wire sequence with a **stale/expired** token (`auth.uid()` no longer
satisfies the policy):

```
<- phx_reply   status=ok    response={postgres_changes:[{id, event:INSERT, schema, table, filter}]}
   // subscribe() callback fires RealtimeSubscribeStatus.subscribed here
<- system      status=... (continued)

4 of 4 new or added lines in 1 file covered. (100.0%)

4098 of 4795 relevant lines covered (85.46%)

3.64 hits per line