feat: add the GraphQL WebSocket client (G4, graphql-transport-ws) by jlouvel · Pull Request #1594 · restlet/restlet-framework-java

jlouvel · 2026-10-30T03:05:30Z

Closes #1586. Part of #1581.

Draft: depends on #1566 and #1568 (#1567, snag S1). This branch is the G4 server branch (#1593) merged with fix/websocket-client-shared-event-loop, so the diff against #1593 also shows the commits of #1566 and #1568 until they are merged. Once they are, I'll rebase and mark this ready.

Summary

GraphqlClientAdapter graphql = new GraphqlClientAdapter(getContext());
graphql.setClient(restletClient);                         // started Netty HTTP client with a context
graphql.setEndpoint("https://api.example.com/graphql");   // wss://api.example.com/graphql
graphql.setSubscriptionTransport(GraphqlTransport.WEBSOCKET);
graphql.setConnectionInitPayload(Map.of("token", token));
graphql.start();
Publisher<ExecutionResult> events = graphql.subscribe("subscription { issueUpdated { id } }", null, null);

subscribe() multiplexes operations over one graphql-transport-ws connection, opened on the first demand (with connection_init and a 10 s acknowledgement timeout) and reopened if it was closed.
Shared engine: the WebSocketClient borrows the event loop of the adapter's HTTP client through WebSocketClient.setClient (fix: let WebSocketClient share a borrowed client's event loop #1568), so the extension creates no Netty event loop group. stop() stops the WebSocket client but never the borrowed HTTP client.
Each operation is delivered by its own virtual thread, honoring demand. graphql-transport-ws has no flow control: results received without demand are buffered up to maxResponseBytes per operation; beyond it the operation fails with a GraphqlTransportException and the server is sent complete, which cancels the server-side subscription.
Errors before execution (error message) are a single result with errors, as with HTTP and SSE. A closed connection fails its operations with the close code and reason. cancel() sends complete.
The request customizer adds handshake headers (for example an API key); the connection_init payload carries tokens for servers that authenticate there.
The WebSocket code is only loaded when the transport is selected; org.restlet.ext.websocket stays optional.

Finding on #1568

WebSocketClient.setClient requires the borrowed client to have a Context (it reads the helper from the context attributes). new Client(Protocol.HTTP) has none, so it can't be borrowed: new Client(new Context(), Protocol.HTTP) is needed. Worth a clearer error message or a fallback there.

Validation

./mvnw -B verify -P default,test -pl org.restlet.ext.graphql (with core and the WebSocket extension from this branch): 63 tests, 0 failures; 91.6% instruction coverage (gate 80%); Spotless, SpotBugs, Javadoc, -Werror and dependency convergence pass.

New GraphqlWebSocketClientTestCase (7 tests) against GraphqlServerAdapter: a subscription and a query share one upgrade (counted by a filter) with demand honored, the init payload and a handshake header reaching data fetchers; cancelling one of two subscriptions cancels it on the server; adapter stop fails the other one and keeps the borrowed client; errors before execution as results; buffered results bounded, cancelling the server-side subscription; server shutdown (1001) fails subscriptions; endpoint without WebSocket; a borrowed client that isn't a started Netty client is rejected at start().

🤖 Generated with Claude Code

Copilot

🟡 Changes recommended

Unresolved cancellation and shutdown races can leak server operations and WebSocket connections, while decoding failures can leave subscribers waiting indefinitely.

7 open issues

What changed in this PR

Adds the client side of GraphQL G4: graphql-transport-ws subscriptions integrated with GraphqlClientAdapter. The PR also includes the prerequisite WebSocket lifecycle and shared-event-loop changes.

Changes:

Adds multiplexed WebSocket subscriptions, connection initialization, demand-aware delivery, buffering limits, and cancellation.
Lets WebSocket clients borrow the HTTP client’s Netty event loop without owning its lifecycle.
Adds integration tests and release notes while keeping the WebSocket dependency optional.

File	Description
`org.restlet/src/main/java/org/restlet/engine/netty/NettyClientHelper.java`	Exposes the connector’s event loop for extensions.
`org.restlet/src/main/java/org/restlet/Client.java`	Publishes the helper when the context is assigned.
`org.restlet.ext.websocket/src/test/java/org/restlet/ext/websocket/WebSocketTestCase.java`	Migrates setup to setter-based configuration.
`org.restlet.ext.websocket/src/test/java/org/restlet/ext/websocket/WebSocketSharedEventLoopTestCase.java`	Tests borrowed event-loop ownership and validation.
`org.restlet.ext.websocket/src/test/java/org/restlet/ext/websocket/WebSocketSessionTestCase.java`	Updates configuration tests and checks lifecycle restrictions.
`org.restlet.ext.websocket/src/test/java/org/restlet/ext/websocket/WebSocketCompressionTestCase.java`	Migrates compression tests to the new client API.
`org.restlet.ext.websocket/src/main/java/org/restlet/ext/websocket/WebSocketClient.java`	Adds setters, lifecycle methods, and HTTP-client borrowing.
`org.restlet.ext.websocket/src/main/java/org/restlet/ext/websocket/internal/NettyWebSocketConnector.java`	Supports shared event loops and tracks connections for shutdown.
`org.restlet.ext.graphql/src/test/java/org/restlet/ext/graphql/GraphqlWebSocketClientTestCase.java`	Tests multiplexing, demand, cancellation, limits, and failures.
`org.restlet.ext.graphql/src/main/java/org/restlet/ext/graphql/GraphqlWebSocketTransport.java`	Implements the GraphQL WebSocket client protocol.
`org.restlet.ext.graphql/src/main/java/org/restlet/ext/graphql/GraphqlSubscriptionTransport.java`	Isolates the optional subscription transport.
`org.restlet.ext.graphql/src/main/java/org/restlet/ext/graphql/GraphqlClientAdapter.java`	Adds transport selection and connection-init configuration.
`changes.md`	Documents GraphQL client support and connector changes.

_{Review effort: Balanced}

jlouvel · 2026-10-31T06:30:17Z

+
+    /** The open connections, closed with the connector. */
+    private final ChannelGroup channels =
+            new DefaultChannelGroup("restlet-websocket-client", GlobalEventExecutor.INSTANCE);


Not fixed in this PR: NettyWebSocketConnector comes from #1568 (fix/websocket-client-shared-event-loop), which this branch includes and where the same comment was posted (r4424962845). The fix belongs there and will come in when this branch is restacked on it.

Follow the Restlet API conventions used by the RPC extensions: constructors, getter and void setter pairs, and a start/stop lifecycle instead of a fluent builder. - Remove WebSocketClient.Builder, builder() and create(). Settings are now configured with setters on a new WebSocketClient(). - Add start(), stop() and isStarted(). close() stops the client, which can be started again. connect() starts a stopped client, like Restlet.handle(). - Reject setting changes while the client is started. The extension is unreleased, so the builder is removed rather than deprecated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

Also describe the setter-based configuration and restartable lifecycle of WebSocketClient in the changes log. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

WebSocketClient created its own Netty event loop group in every instance, next to the one of the core HTTP client connector, with a thread count that could not be configured. - Add NettyClientHelper.getEventLoopGroup(), an engine extension point exposing the client connector's event loop group. - Add WebSocketClient.setClient(Client): a borrowed, started Netty HTTP client whose event loop is shared. Without it, the client still creates its own threads. - Track the WebSocket connections in a channel group, so stopping the client closes its sessions without shutting down a shared event loop. - Store the helper in the "org.restlet.engine.helper" context attribute in Client.setContext(), as the constructors do. Clients added with Component.getClients().add(Protocol) get their context this way, and did not expose their helper. Fixes #1567 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

A connect() racing with stop() could register its channel after the channel group was closed. With a borrowed event loop, which isn't shut down, that connection stayed open. Keep the group closed so that late channels are closed when added. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

- GraphqlClientAdapter.setSubscriptionTransport(WEBSOCKET): subscribe() multiplexes operations over one graphql-transport-ws connection, opened on the first demand at the endpoint with the ws or wss scheme. - The WebSocketClient borrows the event loop of the adapter's HTTP client (WebSocketClient.setClient, #1567), so no extra Netty threads are created. The request customizer adds handshake headers and setConnectionInitPayload sets the connection_init payload. - Each operation is delivered by its own virtual thread, honoring demand. The protocol has no flow control: results received without demand are buffered up to maxResponseBytes per operation, beyond which the operation fails and the server is sent complete. - Errors before execution are a single result; a closed connection fails its operations with the close code; cancel() sends complete; stop() fails open operations, closes the connection and stops the WebSocket client, but not the borrowed HTTP client. - The WebSocket code is only loaded when the transport is selected. Refs #1586 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

The client signals the overflow at once, possibly before delivering the first buffered result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

Track subscribers from onSubscribe() so that stop() fails them all, signal non-positive demand without waiting for a result and complete the server operation, close the connection when its reader fails, send subscribe before any complete of a cancellation, signal setup failures, and count buffered results until they are delivered. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

sonarqubecloud · 2026-10-31T07:34:25Z

Quality Gate passed

Issues
12 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.5% Duplication on New Code

See analysis details on SonarQube Cloud

jlouvel requested a balanced review from Copilot October 30, 2026 15:13

jlouvel self-assigned this Oct 30, 2026

jlouvel marked this pull request as ready for review October 30, 2026 15:13

Copilot started reviewing on behalf of jlouvel October 30, 2026 15:13

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

jlouvel force-pushed the feat/graphql-g4-websocket-server branch from ab5539d to 63ed523 Compare October 31, 2026 06:18

jlouvel force-pushed the feat/graphql-g4-websocket-client branch from 950f70d to 0f851b5 Compare October 31, 2026 06:26

jlouvel and others added 7 commits October 31, 2026 03:18

test: don't require a result before a GraphQL buffer overflow

a98b04c

The client signals the overflow at once, possibly before delivering the first buffered result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Jerome Louvel <374450+jlouvel@users.noreply.github.com>

jlouvel force-pushed the feat/graphql-g4-websocket-client branch from 0f851b5 to 50d00cb Compare October 31, 2026 07:32

Navigation Menu

Repository navigation

feat: add the GraphQL WebSocket client (G4, graphql-transport-ws) - #1594

feat: add the GraphQL WebSocket client (G4, graphql-transport-ws)#1594
jlouvel wants to merge 7 commits into
feat/graphql-g4-websocket-serverfrom
feat/graphql-g4-websocket-client

jlouvel commented Oct 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

jlouvel Oct 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 31, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jlouvel commented Oct 30, 2026

Summary

Finding on #1568

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

jlouvel Oct 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 31, 2026

Quality Gate passed

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants