From f8a71128c1140b12a72df317fc6d382527b83e9e Mon Sep 17 00:00:00 2001
From: Martin Kouba <mkouba@redhat.com>
Date: Mon, 17 Jun 2024 13:47:54 +0200
Subject: [PATCH] WebSockets Next: document ping/pong messages

(cherry picked from commit 8c3d8e9f353573a2f9cde5cee774fa3498eea3a4)
---
 .../asciidoc/websockets-next-reference.adoc   | 26 ++++++++++++++++---
 .../websockets/next/OnPongMessage.java        |  5 ++--
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/docs/src/main/asciidoc/websockets-next-reference.adoc b/docs/src/main/asciidoc/websockets-next-reference.adoc
index 11e14ba18a2c4..4b93f261aa4eb 100644
--- a/docs/src/main/asciidoc/websockets-next-reference.adoc
+++ b/docs/src/main/asciidoc/websockets-next-reference.adoc
@@ -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]
 ----
@@ -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
 
diff --git a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnPongMessage.java b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnPongMessage.java
index 4491ba0150a75..b8efe45d646e2 100644
--- a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnPongMessage.java
+++ b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/OnPongMessage.java
@@ -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>