Hrana WebSocket: support Protobuf over WebSocket (phase 2) #188

Goal

Speak Hrana 3 protobuf over WebSocket (hrana3-protobuf subprotocol, binary frames), selected the same way as the JSON transport. This is phase 2 of the Hrana WebSocket work tracked in #189.

Depends on

#187. This issue reuses its transport, URL handling, seam, and error mapping, and changes only the frame encoding.

What already exists (the scope is smaller than it looks)

The protobuf schemas are already vendored and compiling:

• libsql-hrana-codec/src/main/proto/hrana_ws.proto defines the WebSocket envelope: ClientMsg / ServerMsg, HelloMsg / HelloOkMsg / HelloErrorMsg, RequestMsg / ResponseOkMsg / ResponseErrorMsg, and the request/response oneofs.
• libsql-hrana-codec/src/main/proto/hrana.proto defines the shared structures, with Value using sint64 for integers and bytes for blobs — 64-bit precision and binary blobs are already preserved by the schema.
• protobuf-java is already declared in libsql-hrana-codec/pom.xml, and the protobuf-maven-plugin already generates the classes under target/generated-sources/protobuf.

So this phase is: add a protobuf codec behind the phase-1 seam and frame binary messages — no new dependency, no new .proto, no codegen wiring.

Scope

• Encode ClientMsg and decode ServerMsg with the generated com.github.magnusp.libsql.hrana.proto.HranaWsProto / HranaProto classes, sent as binary frames (opcode 0x2).
• Offer hrana3-protobuf in Sec-WebSocket-Protocol; fail the connection if the server selects anything else.
• Map the protobuf values, columns, rows, and errors into the same codec model the JSON path uses, so the JDBC layer above the seam does not change.
• Preserve 64-bit integers and blobs through the round trip (already guaranteed by sint64 / bytes, but assert it).

Out of scope

• Protobuf over HTTP (v3-protobuf/pipeline, v3-protobuf/cursor). Track separately if it is wanted.
• Cursor ops, for the same reason as Hrana WebSocket: support JSON over WebSocket (phase 1) #187.

Source of truth

vendor/HRANA_3_SPEC.md: the subprotocol table, the protobuf schema under "Hrana over WebSocket", and the message semantics shared with JSON.

Acceptance (outside check)

• The Hrana WebSocket: support JSON over WebSocket (phase 1) #187 integration tests run in protobuf mode against the pinned sqld image.
• Round-trip tests for Long.MIN_VALUE, Long.MAX_VALUE, NULL, empty and non-empty blobs, and supplementary Unicode text.
• spotless:check and ./mvnw test pass.

Open decisions

1. Encoding selection. Proposed: an explicit option (for example encoding=protobuf in the URL or properties), with JSON as the default. Alternative: use protobuf whenever the server offers it.
2. Codec structure. Proposed: a second implementation behind the phase-1 seam, beside the JSON path. Alternative: replace the JSON path for WebSocket.