feat: Python client implementation for River protocol v2.0

[Monkatraz]

Why

Add a Python client for the River protocol, enabling Python applications to call River services. This is a clean room implementation referencing the TypeScript client and PROTOCOL.md.

Slack thread: https://slack.com/archives/C0AEE1W8E3X/p1771490314906739

What changed

Added python-client/ directory containing a complete River v2.0 client implementation in Python.

Core modules:

• river/types.py — Transport message types, control flags, handshake payloads, result types, ID generation
• river/codec.py — NaiveJsonCodec (JSON) and BinaryCodec (msgpack) with CodecMessageAdapter
• river/streams.py — Async Readable/Writable stream abstractions for procedure I/O
• river/session.py — Session state machine with seq/ack bookkeeping, send buffer, heartbeat echo, grace periods
• river/transport.py — WebSocketClientTransport with connection lifecycle, handshake, reconnection with exponential backoff, message dispatch
• river/client.py — RiverClient providing rpc(), stream(), upload(), subscribe() APIs
• river/codegen/ — Code generator producing typed Python client stubs from River service schemas

Protocol features implemented:

• All 4 procedure types (rpc, stream, upload, subscription)
• Handshake with protocol version negotiation and custom metadata
• Seq/ack bookkeeping with exactly-once delivery semantics
• Send buffer for transparent reconnection (message retransmission)
• Heartbeat echo (client echoes server heartbeats)
• Session grace period with disconnect detection
• Exponential backoff with jitter for reconnection (LeakyBucketRateLimit)
• Stream lifecycle (open/close/cancel control flags)
• Client-initiated cancellation via abort signals
• Service-level errors vs protocol errors (UNEXPECTED_DISCONNECT, CANCEL, UNCAUGHT_ERROR)

Test suite (168 tests, all passing):

• test_e2e.py (57 tests) — E2E tests against a TS server: rpc, stream, upload, subscription, fallible procedures, concurrent operations, disconnect handling, cancellation, idempotent close, transparent reconnect, Readable/Writable edge cases, codec unit tests, listener cleanup
• test_equivalence.py (64 tests) — Cross-codec parametrized equivalence tests running every scenario against both NaiveJsonCodec and BinaryCodec (each codec paired with a matching TS server instance). Covers RPC, stream, upload, subscription, cancellation, disconnect, and ordering
• test_handshake.py (4 tests) — Custom handshake metadata: valid token, invalid token (protocolError event), missing metadata, metadata resent across reconnect. Uses a dedicated TS server with handshake validation
• test_session.py (6 tests) — Deterministic session lifecycle with short timeouts: heartbeat miss → NO_CONNECTION, active RPCs keep connection alive, grace period expiry destroys session, reconnect within grace preserves session, retry budget backoff increases, budget restores after success
• test_codegen.py (23 tests) — Schema conversion, generated imports, typed client live tests

Test infrastructure:

• test_server.ts — 6 services (test, ordering, fallible, subscribable, uploadable, cancellation) with RIVER_CODEC env var for binary codec support
• test_server_handshake.ts — Server with {token: string} handshake validation
• extract_test_schema.ts — Schema extraction for codegen tests
• conftest.py — Session-scoped server fixtures (JSON, binary, handshake), codec_and_url parametrized fixture, esbuild bundling

Running the tests:

cd python-client
pip install -e ".[dev]"
pytest tests/ -v

Versioning

• Breaking protocol change
• Breaking ts/js API change