[sproctor]

What changed

When the server refuses a postgres_changes subscription (for example, the table isn't in the supabase_realtime publication), it replies OK to the join and then sends a system message with status: "error". supabase-kt treated every message with status: "error" as a channel error and rejoined: leave, wait for UNSUBSCRIBED, join. That rejoin ran inline on the websocket message loop, which is the only thing that reads the reply to the leave, so the loop hung until a heartbeat timeout forced a reconnect. Then it joined, was refused, and hung again. The refusal itself never reached systemFlow(), because RSystemEvent only handled status: "ok".

This handles channel errors and rejoins the way realtime-js does (through Phoenix's JS client):

1. A system error is reported, not rejoined. It's logged and forwarded to systemFlow(), and the channel stays joined. Only phx_error and a rejected join (a phx_reply with status: "error" while joining) rejoin, as in Phoenix. A reply error to some other push is logged.
2. Rejoins are scheduled. scheduleRejoin() launches the rejoin in the realtime scope after rejoinDelay instead of running it in the caller's coroutine (Phoenix's rejoinTimer). It replaces a pending rejoin, and subscribe(), unsubscribe(), teardown and disconnect() cancel it. scheduleRejoin() (@SupabaseInternal) is no longer suspend.
3. A rejoin sends the join again instead of leaving first. The server replaces the channel's current join, as with Phoenix's rejoin(). Enabling presence on a subscribed channel (presenceChangeFlow()) rejoins the same way, so it no longer goes through UNSUBSCRIBED.
4. Messages for an earlier join_ref are dropped, as in Phoenix's isMember: for example, the server's close for the join a rejoin replaced, which would otherwise remove the channel.

Unchanged: maxAttempts and rejoinDelay keep their meaning. Phoenix retries forever with backoff; this keeps supabase-kt's fixed delay and limit, and a successful join still resets the count.

Behavior change on token expiry. When a channel's access token expires on the server, Realtime sends a system error ("Token has expired …") and closes the channel. Before, the error made the channel rejoin, which deadlocked as above, and the heartbeat timeout's reconnect then rejoined with a fresh token. Now the error goes to systemFlow() and the server's close removes the channel, as in realtime-js. supabase-kt already sends refreshed tokens to joined channels, so this only matters when a refresh doesn't reach the server in time.

Resolving each message to exactly one event (second commit)

RealtimeEvent.resolveEvent took the first event in EVENTS whose condition matched, so overlapping conditions were settled by the set's iteration order. Two already overlapped: a successful join reply listing postgres changes matched both RPostgresServerChangesEvent and RSystemReplyEvent, and a system message about an expired access token matched both RSystemEvent and RTokenExpiredEvent. The second commit makes the conditions mutually exclusive (each broader event leaves out what a more specific one handles), resolves with singleOrNull, and leaves EVENTS in its original order.

It's in this PR because this PR widens one of those overlaps: RSystemEvent now also handles system messages with status: "error", so whether an expired-token message reached RTokenExpiredEvent would have depended on the order of EVENTS, which I'd otherwise have had to reorder. If you'd rather review it on its own, I'm happy to split it into a separate PR; this one would then only keep RSystemEvent from claiming RTokenExpiredEvent's messages.

Why

We hit this in production: an app release subscribed to a table that wasn't in the publication yet. Every device's channel deadlocked until a heartbeat timeout, reconnected about every 37 seconds, and never received changes for any table, while status kept flipping back to SUBSCRIBED, so the app saw nothing wrong.

Testing

• RealtimeChannelRejoinTest, against a scripted socket (ScriptedWebsocket, test-only): a refused subscription reaches systemFlow() while the channel stays subscribed and nothing more is sent; a rejected join is retried with a join, not a leave; rejected joins give up after maxAttempts; a channel error rejoins without leaving; the server's close for the replaced join is ignored; a successful join resets the attempt count. All six fail on master. Without the earlier-join_ref check, the close test fails; with system errors still rejoining, the refusal test fails.
• RealtimeEventTest: a system error resolves to RSystemEvent, a rejected reply to RErrorEvent, a join reply listing postgres changes to RPostgresServerChangesEvent (and a rejected one to RErrorEvent), and an expired-token system error to RTokenExpiredEvent. testEachMessageHasOneEvent checks that every kind of message matches exactly one event, which resolveEvent relies on; it fails with the previous conditions.
• testResubscribeOnPresenceChange now expects the presence rejoin to join again without leaving.
• ./gradlew :realtime-kt:jvmTest :realtime-kt:detekt pass.
• An earlier version of this fix was checked against a local Supabase stack with a table removed from the publication: before, the deadlock and reconnect loop above.

Not changed here: RealtimeImpl.onMessage takes any message whose ref equals the idle heartbeat ref (0) for a heartbeat reply, which swallows the server's messages for a socket's first join. That's #1434, which builds on this.

🤖 Generated with Claude Code