Skip to content

feat(client): add Hrana 3 Protobuf over WebSocket transport - #191

Merged
magnusp merged 6 commits into
mainfrom
feat/i188-hrana-ws-protobuf
Oct 24, 2026
Merged

magnusp merged 6 commits into
mainfrom
feat/i188-hrana-ws-protobuf

Conversation

@magnusp

@magnusp magnusp commented Oct 24, 2026

Copy link
Copy Markdown
Owner

Add the Protobuf encoding for Hrana 3 over WebSocket (hrana3-protobuf subprotocol, binary frames). JSON stays the default. A URL of jdbc:libsql:ws://host:port?encoding=protobuf selects it.

Fixes #188.

This PR is stacked on #190 and targets feat/i187-hrana-ws-json. Merge #190 first.

What changes

  • HranaWsProtobufCodec implements HranaWsCodec over the already vendored hrana_ws.proto and hrana.proto schemas. It maps Stmt, Value, Batch, BatchCond, StmtResult, and BatchResult both ways.
  • LibsqlClientConfig gains an Encoding enum (JSON, PROTOBUF) as its last component. The existing constructors still default to JSON.
  • LibsqlUrlParser reads encoding=json|protobuf|proto. An unknown value throws, and encoding=protobuf on an http or https URL throws because Protobuf over HTTP is out of scope.
  • LibsqlWebSocketClient derives the subprotocol from the codec, hrana3 for JSON and hrana3-protobuf for Protobuf, and rejects a server that negotiates a different one.
  • LibsqlDriver selects the codec from the encoding.

No new dependency. protobuf-java and the codegen were already present.

Evidence

  • ./mvnw -q -pl libsql-hrana-codec,libsql-client,libsql-jdbc -am test passes.
  • ./mvnw -q spotless:check passes.
  • DOCKER_CONFIG="$PWD/libsql-conformance/src/test/docker-config" ./mvnw -pl libsql-itests -am -Dit.test='WebSocket*TransportIT' -DfailIfNoTests=false verify passes 8 of 8, split as WebSocketTransportIT 5 of 5 on JSON and WebSocketProtobufTransportIT 3 of 3 on Protobuf.

The Protobuf integration test covers typed select values including Long.MIN_VALUE and a blob, transaction commit and rollback, and error mapping. The codec unit test covers Long.MIN_VALUE, Long.MAX_VALUE, doubles, unicode text, null, empty and non-empty blobs, named arguments, batch conditions, and both error messages.

Limits

  • Protobuf over HTTP (v3-protobuf/pipeline) is out of scope.
  • wss has no TLS integration test. The container runs plain ws.
  • Cursor requests are not implemented. Nothing in the driver uses them.

Base automatically changed from feat/i187-hrana-ws-json to main October 24, 2026 01:58
@magnusp
magnusp force-pushed the feat/i188-hrana-ws-protobuf branch from 7c52aa9 to f5e0b41 Compare October 24, 2026 01:59
@magnusp
magnusp merged commit 6591155 into main Oct 24, 2026
6 checks passed
@magnusp
magnusp deleted the feat/i188-hrana-ws-protobuf branch October 24, 2026 02:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hrana WebSocket: support Protobuf over WebSocket (phase 2)

1 participant