supabase / supabase-flutter / 27424656399

85%

Build Type

push

github

Committed by web-flow

Commit Message

feat(realtime): add support for protocol format 2.0.0 (#1397)

## What

Adds Realtime protocol **2.0.0** support to the Dart/Flutter SDK and
makes the protocol version selectable.

Closes
[SDK-583](https://linear.app/supabase/issue/SDK-583/realtime-add-support-to-protocol-format-200-flutter).

Protocol 2.0.0 changes the WebSocket frame format:
- **Text frames** use the positional JSON array `[join_ref, ref, topic,
event, payload]` instead of the 1.0.0 object layout, reducing JSON work
on the backend (lower latency).
- **Binary frames** allow raw binary payloads for broadcast user events.

## Changes

### Serializer (`serializer.dart`, new)
- Text encode/decode as the positional array `[join_ref, ref, topic,
event, payload]`.
- Binary encode for broadcast pushes (`userBroadcastPush`, kind `3`).
- Binary decode for incoming broadcasts (`userBroadcast`, kind `4`).
- JSON/binary encoding flag and `allowedMetadataKeys`.
- `decode` validates the text frame shape and throws a clear
`FormatException` on malformed input; `onConnMessage` logs and drops
such frames instead of crashing the connection.

### Selectable protocol version
- New `RealtimeProtocolVersion` enum (`v1` → `1.0.0`, `v2` → `2.0.0`);
each carries the `vsn` value sent as the connection parameter.
- `RealtimeClient` takes a `version` parameter, **defaulting to `v2`**.
`v2` uses the serializer; `v1` uses the legacy object-shaped JSON
frames.

### Codec override
- Optional `encode` / `decode` constructor arguments (and the
`RealtimeEncode` / `RealtimeDecode` typedefs) let consumers swap in a
custom serializer; they default to the codec for the selected `version`.
- Return-based signatures: `RealtimeEncode` = `Object
Function(Map<String, dynamic>)`, `RealtimeDecode` = `Map<String,
dynamic> Function(Object)` (synchronous — async/isolate codec is a
follow-up, see below).

### Binary broadcasts
Incoming binary broadcast frames are decoded into the same map shape as
JSON broadcasts. To send binary, pro... (continued)

Coverage Stats

137 of 144 new or added lines in 3 files covered. (95.14%)

1 existing line in 1 file now uncovered.

3729 of 4575 relevant lines covered (81.51%)

3.15 hits per line