Skip to content

Commit

Permalink
WebSockets Next: document ping/pong messages
Browse files Browse the repository at this point in the history
(cherry picked from commit 8c3d8e9)
  • Loading branch information
mkouba authored and gsmet committed Jun 18, 2024
1 parent 7c09a87 commit f8a7112
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 7 deletions.
26 changes: 22 additions & 4 deletions docs/src/main/asciidoc/websockets-next-reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -610,12 +610,28 @@ Item find(Item item) {
1. Specify the codec to use for both the deserialization of the incoming message
2. Specify the codec to use for the serialization of the outgoing message

== Handle Pong message
== Ping/pong messages

The `@OnPongMessage` annotation is used to consume pong messages.
A websocket endpoint must declare at most one method annotated with `@OnPongMessage`.
A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2[ping message] may serve as a keepalive or to verify the remote endpoint.
A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3[pong message] is sent in response to a ping message and it must have an identical payload.

The method must accept a single parameter of type `Buffer`:
The server automatically responds to a ping message sent from the client.
In other words, there is no need for `@OnPingMessage` callback declared on an endpoint.

The server can send ping messages to a connected client.
The `WebSocketConnection` declares methods to send ping messages; there is a non-blocking variant: `WebSocketConnection#sendPing(Buffer)` and a blocking variant: `WebSocketConnection#sendPingAndAwait(Buffer)`.
By default, the ping messages are not sent automatically.
However, the configuration property `quarkus.websockets-next.server.auto-ping-interval` can be used to set the interval after which, the server sends a ping message to a connected client automatically.

[source,properties]
----
quarkus.websockets-next.server.auto-ping-interval=2 <1>
----
<1> Sends a ping message to a connected client every 2 seconds.

The `@OnPongMessage` annotation is used to define a callback that consumes pong messages sent from the client.
An endpoint must declare at most one method annotated with `@OnPongMessage`.
The callback method must return either `void` or `Uni<Void>`, and it must accept a single parameter of type `Buffer`.

[source,java]
----
Expand All @@ -625,6 +641,8 @@ void pong(Buffer data) {
}
----

NOTE: The server can also send unsolicited pong messages that may serve as a unidirectional heartbeat. There is a non-blocking variant: `WebSocketConnection#sendPong(Buffer)` and also a blocking variant: `WebSocketConnection#sendPongAndAwait(Buffer)`.

[[websocket-next-security]]
== Security

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,8 @@
* <p>
* <ul>
* <li>Methods returning {@code void} are considered blocking and should be executed on a worker thread.</li>
* <li>Methods returning {@link io.smallrye.mutiny.Uni} or {@link io.smallrye.mutiny.Multi} are considered non-blocking and
* should be executed on an event loop thread.</li>
* <li>Methods returning any other type are considered blocking and should be executed on a worker thread.</li>
* <li>Methods returning {@code io.smallrye.mutiny.Uni<Void>} are considered non-blocking and should be executed on an event
* loop thread.</li>
* </ul>
*
* <h2>Method parameters</h2>
Expand Down

0 comments on commit f8a7112

Please sign in to comment.