feat: port Realtime V2 serializer from supabase-js PRs #1829, #1894

[grdsdev]

Summary

Ports Realtime V2 serializer feature from supabase-js PRs #1829 and #1894.

Source

• Source PRs:
  • PR #1829: feat(realtime): implement V2 serializer
  • PR #1894: feat(realtime): add metadata to realtime user broadcast push
• Original implementation: Binary serializer for Realtime V2 protocol with support for binary payloads and metadata

Changes

From PR #1829

• Added Serializer class with binary encoding/decoding support
• Implemented V2 serializer version 2.0.0 (experimental)
• Added support for two new message types: user broadcast and user broadcast push
• Enabled binary user payloads
• Reduced JSON encoding overhead on the server side
• Updated types.py to add VSN constants (VSN_1_0_0, VSN_2_0_0, DEFAULT_VSN)
• Updated AsyncRealtimeClient to support vsn parameter and serializer selection

From PR #1894

• Added optional metadata support for user broadcast push messages
• Implemented metadata filtering based on allowed_metadata_keys parameter
• Added validation to ensure metadata and field lengths don't exceed 255 characters

Combined Changes

• Both features are integrated into a single serializer implementation
• Backward compatible with V1 (1.0.0) as default serializer version
• V2 (2.0.0) can be enabled by passing vsn="2.0.0" to AsyncRealtimeClient
• Metadata support is only available when using V2 serializer

Testing

• All existing tests pass
• New tests added for ported feature (16 test cases)
• Test coverage includes:
  • JSON encoding/decoding (V1 format)
  • Binary encoding/decoding (V2 format)
  • User broadcast push with JSON payloads
  • User broadcast push with binary payloads
  • Metadata encoding/decoding
  • Field length validation
  • Edge cases and error scenarios

Breaking Changes

None - This PR contains no breaking changes. The default serializer version remains 1.0.0, and V2 is opt-in.

Notes

• The implementation follows Python conventions (snake_case, type hints, docstrings)
• Binary encoding uses Python's bytes and bytearray types
• Metadata filtering uses a _pick helper method similar to the JS implementation
• All field length validations match the JS implementation (max 255 characters)
• The serializer is initialized based on the vsn parameter in AsyncRealtimeClient
• Metadata keys must be explicitly allowed via allowed_metadata_keys parameter

References

• feat(realtime): implement V2 serializer supabase-js#1829
• feat(realtime): add metadata to realtime user broadcast push supabase-js#1894

[coveralls]

Pull Request Test Coverage Report for Build 19963050962

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 67 unchanged lines in 2 files lost coverage.
• Overall coverage decreased (-0.03%) to 91.25%

---

Files with Coverage Reduction	New Missed Lines	%
src/realtime/types.py	7	95.63%
src/realtime/_async/client.py	60	70.23%

Totals
Change from base Build 19905261542:	-0.03%
Covered Lines:	9115
Relevant Lines:	9989

---

💛 - Coveralls