From c29d76fa2e1c131fcf87c849a8d02b0ee73fb8ab Mon Sep 17 00:00:00 2001
From: Martin Kouba <mkouba@redhat.com>
Date: Tue, 25 Jun 2024 10:10:10 +0200
Subject: [PATCH] WebSockets Next: document WebSocket#inboundProcessingMode()

- resolves #41393
---
 docs/src/main/asciidoc/websockets-next-reference.adoc    | 9 +++++++++
 .../quarkus/websockets/next/InboundProcessingMode.java   | 8 +++++---
 .../main/java/io/quarkus/websockets/next/WebSocket.java  | 2 +-
 .../java/io/quarkus/websockets/next/WebSocketClient.java | 2 +-
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/src/main/asciidoc/websockets-next-reference.adoc b/docs/src/main/asciidoc/websockets-next-reference.adoc
index f2af366a9bd49..ff4bf6b790da1 100644
--- a/docs/src/main/asciidoc/websockets-next-reference.adoc
+++ b/docs/src/main/asciidoc/websockets-next-reference.adoc
@@ -521,6 +521,15 @@ void pong(Buffer data) {
 
 NOTE: The server/client 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)`.
 
+[[inbound-processing-mode]]
+=== Inbound processing mode
+
+WebSocket endpoints can define the mode used to process incoming events for a specific connection using the `@WebSocket#inboundProcessingMode()`, and `@WebSocketClient.inboundProcessingMode()` respectively. 
+An incoming event can represent a message (text, binary, pong), opening connection and closing connection.
+By default, events are processed serially and ordering is guaranteed.
+This means that if an endpoint receives events `A` and `B` (in this particular order) then callback for event `B` will be invoked after the callback for event `A` completed.
+However, in some situations it is preferable to process events concurrently, i.e. with no ordering guarantees but also with no concurrency limits.
+For this cases, the `InboundProcessingMode#CONCURRENT` should be used.
 
 == Server API
 
diff --git a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/InboundProcessingMode.java b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/InboundProcessingMode.java
index dc206f4a23743..c1c1ee4505923 100644
--- a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/InboundProcessingMode.java
+++ b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/InboundProcessingMode.java
@@ -3,7 +3,9 @@
 import io.smallrye.common.annotation.Experimental;
 
 /**
- * Defines the mode used to process incoming messages for a specific connection.
+ * WebSocket endpoints define the mode used to process incoming events for a specific connection.
+ * <p>
+ * An incoming event can represent a message (text, binary, pong), opening connection and closing connection.
  *
  * @see WebSocketConnection
  * @see WebSocketClientConnection
@@ -12,12 +14,12 @@
 public enum InboundProcessingMode {
 
     /**
-     * Messages are processed serially, ordering is guaranteed.
+     * Events are processed serially, ordering is guaranteed.
      */
     SERIAL,
 
     /**
-     * Messages are processed concurrently, there are no ordering guarantees.
+     * Events are processed concurrently, there are no ordering guarantees.
      */
     CONCURRENT,
 
diff --git a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java
index ccb13c958003c..aa7b118a4d40b 100644
--- a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java
+++ b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocket.java
@@ -48,7 +48,7 @@
     public String endpointId() default FCQN_NAME;
 
     /**
-     * The mode used to process incoming messages for a specific connection.
+     * The mode used to process incoming events for a specific connection.
      */
     public InboundProcessingMode inboundProcessingMode() default InboundProcessingMode.SERIAL;
 
diff --git a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocketClient.java b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocketClient.java
index 92c960b5fc4ae..77600575eb9cd 100644
--- a/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocketClient.java
+++ b/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/WebSocketClient.java
@@ -48,7 +48,7 @@
     public String clientId() default FCQN_NAME;
 
     /**
-     * The execution mode used to process incoming messages for a specific connection.
+     * The mode used to process incoming events for a specific connection.
      */
     public InboundProcessingMode inboundProcessingMode() default InboundProcessingMode.SERIAL;