Towards a new websocket model

[cescoffier]

Hello,

WIP

For some time now, we have been thinking about improving how to handle web sockets in Quarkus. This discussion presents some ideas for enhancement.

The goal is to simplify the development of application serving (server-side) and consuming (client-side) web sockets. The proposed model aims to be coherent with the Quarkus development model. The proposal also covers some integration points, such as observability and service discovery.

Current situation (<= Quarkus 3.7/3.8)

At the moment, to implement a web socket (on the server side), we use undertow, and the code relies on the JSR 356.

This model needs to be better integrated with the rest of Quarkus. CDI scopes are a mystery when using a web socket; it does not use a duplicated context (breaking tracing), and metrics are limited.

However, the goal is not to replace this current support but to provide an alternative. Applications using this legacy model must still be supported using the same extension as Today.

Structure of this document

This document distinguishes three parts:

• server-side - how to serve a web socket
• client-side - how to connect, send, and consume messages from a web socket
• observability - a discussion on the metrics and tracing support

While the server and client sides are covered in this document, they are independent and do not depend on each other.

Serving web sockets (server-side)

NOTE: The annotations utilized in this section differ from those in JSR 356 despite sharing the same name. The JSR annotations carry a semantic that the proposal does not follow. Furthermore, incorporating multiple sets of annotations could have confused the user.

Overall idea

To serve a web socket, the user needs to create a class annotated with @WebSocket, indicating the path of the web socket. In addition, the user would have to create methods annotated with:

• OnMessage to receive messages and optionally reply to messages
• OnOpen to be notified when a new client connects to the web socket
• OnClose to be notified when a client disconnects from the web socket

The following sections will describe the supported signatures.

Furthermore, the method can declare a static inner class representing sub-websockets. A sub-web socket is another web socket endpoint located under the main one. For example, if the main class is annotated with @WebSocket("my/path") and the inner class with @WebSocket("sub-ws"), the framework exposes:

1. a web socket on my/path
2. another web socket on my/path/sub-ws

The following code gives some examples of usage:

@WebSocket("my/path")
public class MyWebSocketEndpoint {

       @Inject WebSocketServerConnection connection;

       @OnMessage
       MyOutputMessage onMessage(MyInputMessage msg) { 
          // ...
          // the returned object is sent to the client.
       }
       
        @OnOpen  
        void onOpen() { 
           // socket can be used to emit messages to the other side 
            socket.send(MyOutputMessage.create()) // Uni<Void>
	           .subscribe().asCompletionStage(); // Subscribe to the uni
           socket.sendAndAwait(...);  // void
        }
        
        @OnClose 
        void onClose() {
           // ...
        }

    @WebSocket("sub-ws")
	public static class MySubWebSocket {
	   @OnMessage(broadcast=true)      
       MyOutputMessage onMessage(MySecondInputMessage msg) { 
          // ...
          // The endpoint is my/path/sub-ws
          // the returned object is broadcasted to all the connected clients
       }
	}

}

Note that both classes are transformed into CDI beans by the framework and thus can access the other beans exposed by the application.

Web Socket endpoint

A WebSocket endpoint comprises the following components:

• Path: This is the URL path where the WebSocket connection is established (e.g., ws://localhost:8080/).
• Maximum one @OnMessage method: Handles the messages the connected client sends.
• Maximum one @OnOpen method: Invoked when a client connects to the WebSocket.
• Maximum one @OnClose method: Executed upon the client disconnecting from the WebSocket.

Only some endpoints need to include all three methods. However, it must contain at least @OnMessage or @OnOpen.

If any endpoint violates these rules, an error must be thrown.

The inner classes representing sub-websockets adhere to the same guidelines.

WebSocketServerConnection

The WebSocketServerConnection interface represents a connection to a client. This structure facilitates various actions, such as sending messages to the connected client or broadcasting to all connected clients, closing the current connection, and accessing path parameters.

A WebSocketServerConnection can be obtained as a CDI session-scoped bean, as explained in the [[#CDI Scope]] section.

The API offers blocking and non-blocking methods for transmitting messages by utilizing the WebSocketServerConnection. The non-blocking methods return Uni instances, providing flexibility in handling asynchronous operations:

/**
 * Represents a WebSocket (server) connection.
 * 
 * This interface provides methods to interact with a connected client,
 * including sending messages, broadcasting to all connected clients,
 * closing the connection and accessing path parameters.
 */
public interface WebSocketServerConnection {
    /**
     * Retrieves the unique identifier assigned to this connection.
     *
     * @return the unique identifier assigned to this connection
     */
    String id();

    /**
     * Retrieves the value of the specified path parameter.
     *
     * @param name the name of the path parameter
     * @return the actual value of the path parameter or {@code null} if not found
     */
    String pathParam(String name);

    /**
     * Sends a text message to the connected client.
     *
     * @param message the text message to send
     * @return a new {@link Uni} that completes when the message is sent successfully
     */
    @CheckReturnValue
    Uni<Void> sendText(String message);

    /**
     * Sends a text message of type {@code M} to the connected client.
     *
     * @param <M>     the type of the message
     * @param message the message to send
     * @return a new {@link Uni} that completes when the message is sent successfully
     */
    @CheckReturnValue
    <M> Uni<Void> sendText(M message);

    /**
     * Sends a text message to the connected client and waits for the completion.
     *
     * @param message the text message to send
     */
    void sendTextAndAwait(String message);

    /**
     * Sends a text message of type {@code M} to the connected client and waits for the completion.
     *
     * @param <M>     the type of the message
     * @param message the message to send
     */
    @CheckReturnValue
    <M> Uni<Void> sendText(M message);

    /**
     * Sends a binary message to the connected client.
     *
     * @param message the binary message to send
     * @return a new {@link Uni} that completes when the message is sent successfully
     */
    @CheckReturnValue
    Uni<Void> sendBinary(Buffer message);

    /**
     * Sends a binary message to the connected client.
     *
     * @param message the binary message to send
     * @return a new {@link Uni} that completes when the message is sent successfully
     */
    @CheckReturnValue
    Uni<Void> sendBinary(byte[] message);

    /**
     * Sends a binary message to the connected client and waits for the completion.
     *
     * @param message the binary message to send
     */
    void sendBinaryAndAwait(Buffer message);

    /**
     * Sends a binary message to the connected client and waits for the completion.
     *
     * @param message the binary message to send
     */
    void sendBinaryAndAwait(byte[] message);

    /**
     * Initiates broadcast messaging to all clients connected to the same WebSocket endpoint.
     *
     * @return a {@link BroadcastSender} for sending broadcast messages
     */
    BroadcastSender broadcast();

    /**
     * Closes the WebSocket connection.
     *
     * @return a new {@link Uni} that completes when the connection is closed successfully
     */
    @CheckReturnValue
    Uni<Void> close();

    /**
     * Closes the WebSocket connection and waits for the completion.
     */
    void closeAndAwait();

    /**
     * Checks if the HTTP connection is encrypted via SSL/TLS.
     *
     * @return {@code true} if the HTTP connection is encrypted via SSL/TLS, otherwise {@code false}
     */
    boolean isSecure();

    /**
     * Checks if the WebSocket connection is closed.
     *
     * @return {@code true} if the WebSocket connection is closed, otherwise {@code false}
     */
    boolean isClosed();

    /**
     * Provides methods for sending broadcast messages to all clients connected to the same WebSocket endpoint.
     */
    interface BroadcastSender {

        /**
         * Sends a text message to all clients connected to the same WebSocket endpoint.
         *
         * @param message the text message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendText(String message);

        /**
         * Sends a message of type {@code M} to all clients connected to the same WebSocket endpoint.
         *
         * @param <M>     the type of the message
         * @param message the message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        <M> Uni<Void> sendText(M message);

        /**
         * Sends a binary message to all clients connected to the same WebSocket endpoint.
         *
         * @param message the binary message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendBinary(Buffer message);

        /**
         * Sends a binary message to all clients connected to the same WebSocket endpoint.
         *
         * @param message the binary message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendBinary(byte[] message);

        
        /**
         * Sends a text message to all clients connected to the same WebSocket endpoint. Waits for the messages to be written to all web sockets.
         *
         * @param message the text message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendTextAndAwait(String message);

        /**
         * Sends a message of type {@code M} to all clients connected to the same WebSocket endpoint. Waits for the messages to be written to all web sockets.
         *
         * @param <M>     the type of the message
         * @param message the message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        <M> Uni<Void> sendTextAndAwait(M message);

        /**
         * Sends a binary message to all clients connected to the same WebSocket endpoint. Waits for the messages to be written to all web sockets.
         *
         * @param message the binary message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendBinaryAndAwait(Buffer message);

        /**
         * Sends a binary message to all clients connected to the same WebSocket endpoint. Waits for the messages to be written to all web sockets.
         *
         * @param message the binary message to broadcast
         * @return a new {@link Uni} that completes when the message is broadcasted successfully
         */
        @CheckReturnValue
        Uni<Void> sendBinaryAndAwait(byte[] message);

    }
  
}

Note that this class provides both reactive and imperative methods. Imperative methods are suffixed with andAwait and block the caller thread until the operation's completion. Errors are reported using exceptions.

Declaring a WebSocket Endpoint with the @WebSocket Annotation

The @WebSocket annotation declares a WebSocket endpoint and is exclusive to class-level declarations. Its parameter (value) denotes the path of the WebSocket.

/**
 * Annotation used to define WebSocket endpoints.
 */
@Retention(RUNTIME)
@Target({ TYPE })
public @interface WebSocket {

    /**
     * Retrieves the path associated with the WebSocket endpoint.
     * 
     * @return the path of the WebSocket endpoint, must not be {@code null}
     */
    public String value();

}

WebSocket Endpoint Declaration

The @WebSocket annotation is used to define a WebSocket endpoint. Consequently, methods annotated with @OnMessage, @OnOpen, and @OnClose are considered within its context. When managing the resulting endpoint, following the guidelines outlined in the [[#WebSocket Endpoint]] section is very important.

Any methods annotated with OnMessage, OnOpen, and OnClose outside a WebSocket endpoint are considered erroneous and should be flagged during the build process.

Path Parameters

The path specified in the @WebSocket annotation can incorporate path parameters, such as /ws/product/{id}. Methods can retrieve these values utilizing the WebSocketServerConnection#pathParam(id) method:

@WebSocket("/ws/products/{id}")
public class Example {

   @Inject WebSocketServerConnection connection;

   @OnMessage
   String process(String message) {
      String id = connection.pathParam("id");    
      return ...;
   }

}

Note that query parameters are not supported.

Inner Classes and Sub-Web Sockets

A class annotated with @WebSocket can encapsulate inner classes also annotated with @WebSocket, representing sub-web sockets. The resulting path of these sub-web sockets concatenates the path from the enclosing class and the inner class. The resulting path must be normalized, following the HTTP URL rules.

Sub-web sockets inherit access to the path parameters declared in the @WebSocket annotation of both the enclosing and inner classes. In the example, the consumePrimary method within the enclosing class can access the version parameter. Meanwhile, the consumeNested method within the inner class can access both version and id.

@WebSocket("/ws/v{version}") 
public class MyPrimaryWebSocket {

    @OnMessage
    void consumePrimary(String s)    { ... }

    @WebSocket("/products/{id}")
    public static class MyNestedWebSocket {

      @OnMessage
      void consumeNested(String s)    { ... }
    
    }

}

CDI Scopes for WebSocket Endpoints

Classes annotated with @WebSocket are intended to be managed as CDI beans, allowing for flexible scope management within the application.

By default, WebSocket endpoints are considered in the singleton pseudo-scope. However, developers can specify alternative scopes to suit their specific requirements.

@WebSocket("/ws")
public class MyWebSocket {
   // Singleton scoped bean
}

@WebSocket("/ws")
@RequestScoped		   
public class MyRequestScopedWebSocket {
   // Request scoped bean
}

Furthermore, each WebSocket connection is associated with its own session scope. When the @OnOpen method is invoked, a session scope corresponding to the WebSocket connection is established. Subsequent calls to @OnMessage or @OnClose methods utilize this same session scope. The session scope remains active until the @OnClose method completes execution, at which point it is terminated.

The WebSocketServerConnection object, which represents the connection itself, is also a session-scoped bean, allowing developers to access and manage WebSocket-specific data within the context of the session.

In cases where a WebSocket endpoint does not declare an @OnOpen method, the session scope is still created and remains active until the connection terminates, regardless of the presence of an @OnClose method.

Methods annotated with @OnMessage, @OnOpen and @OnClose do not have the request scope activated by default. The user can activate it using the @ActivateRequestScope. In this case, the scope is terminated when the method completes its execution.

Duplicated Context

Each WebSocket connection is associated with a duplicated context, providing a segregated execution environment for handling WebSocket interactions.

Upon invocation of the @OnOpen method, a duplicated context specific to the WebSocket connection is established. Subsequent invocations of @OnMessage or @OnClose methods utilize this duplicated context.

The duplicated context may be utilized as a transport mechanism for the session scope, facilitating the management of WebSocket-specific state and data.

Relationship Between @WebSocket and @Path

Although there might be an initial inclination to leverage the @Path annotation from JAX-RS for WebSocket endpoints, such an approach may not be advisable due to nuanced differences in semantics, particularly concerning sub-resources.

WebSocket Path and HTTP Root

WebSocket paths configured within the application are concatenated with the root path defined by quarkus.http.root (which defaults to /). This concatenation ensures that WebSocket endpoints are appropriately positioned within the application's URL structure.

Method Annotations to serve WebSocket endpoints

This section delineates the behavior associated with methods annotated with @OnMessage, @OnClose, and @OnOpen.

Invocation Rules

When invoking these annotated methods:

• The method operates within the WebSocket connection's duplicated context.
• The session scope linked with the WebSocket connection remains active.
• Optionally, developers can activate the request scope explicitly.

The proposed framework supports blocking and non-blocking logic, akin to RESTEasy Reactive, determined by the method signature and additional annotations such as @Blocking and @NonBlocking.

Here are the rules governing execution:

• Non-blocking methods must execute on the connection's event loop.
• Methods annotated with @RunOnVirtualThread are considered blocking and should execute on a virtual thread.
• Blocking methods must execute on a worker thread if not annotated with @RunOnVirtualThread.
• When @RunOnVirtualThread is employed, each invocation spawns a new virtual thread.

For a WebSocket connection, the methods OnMessage, OnClose, and OnOpen must not be invoked concurrently.

Receiving Messages with @OnMessage

Methods marked with OnMessage trigger upon receiving a message from a connected client.

/**
 * Annotated method is invoked when an incoming web socket message is received.
 */
@Retention(RUNTIME)
@Target(METHOD)
public @interface OnMessage {

    /**    
     * @return {@code true} if all the connected clients should receive the objects emitted by the annotated method
     */
    public boolean broadcast() default false;

}

Parameters

These methods can accept parameters in two formats:

• The message object (of any type).
• A Multi<X> with X as the message type.

Any other parameters should be flagged as errors.

The message object represents the data sent and can be accessed as either raw content (String or byte[]) or deserialized high-level objects, which is the recommended approach.

When receiving a Multi, the method is invoked once per connection, and the provided Multi receives items transmitted by this connection. The method must subscribe to the Multi to receive these items (or return a Multi). Cancelling this subscription closes the associated connection.

Allowed Returned Types

Methods annotated with @OnMessage can return various types to handle WebSocket communication efficiently:

• void: Indicates a blocking method where no explicit response is sent back to the client.
• Uni<Void>: Denotes a non-blocking method where the completion of the returned Uni signifies the end of processing. no explicit response is sent back to the client.
• An object of type X: Represents a blocking method where the returned object is serialized and sent back to the client as a response.
• Uni<X>: Specifies a non-blocking method where the item emitted by the non-null Uni is sent to the client as a response.
• Multi<X>: Indicates a non-blocking method where the items emitted by the non-null Multi are sequentially sent to the client until completion or cancellation.

@OnMessage
void consume(Message m) {
 // Process the incoming message. The method is called for each incoming message.
}

@OnMessage
Uni<Void> consumeAsync(Message m) {
 // Process the incoming message. The method is called for each incoming message.
 // The method completes when the returned Uni emits its item.
}

@OnMessage
ReponseMessage process(Message m) {
  // Process the incoming message and send a response to the client.
  // The method is called for each incoming message.
  // Note that if the method returns `null`, no response will be sent to the client.
}

@OnMessage
Uni<ReponseMessage> processAsync(Message m) {
  // Process the incoming message and send a response to the client.
  // The method is called for each incoming message.
  // Note that if the method returns `null`, no response will be sent to the client. The method completes when the returned Uni emits its item.
}

Multi<ResponseMessage> stream(Message m) {
 // Process the incoming message and send multiple responses to the client.
  // The method is called for each incoming message.
  // The method completes when the returned Multi emits its completion signal.
  // The method cannot return `null` (but an empty multi if no response must be sent)
}

When returning a Multi, the framework subscribes to the returned Multi and writes the emitted items until completion, failure, or cancellation. Failure or cancellation necessitates the termination of the connection.

Raw Payload

Items sent back to the client are serialized except for the String, Buffer, and byte[] types, offering flexibility in data transmission.

@OnMessage
String processText(String rawPayload) {
// Process the incoming text message.
}

@OnMessage
byte[] processBinary(byte[] rawPayload) {
// Process the incoming binary message.
}

Strings are sent as text messages. Buffers and byte arrays are sent as binary messages.

Skipping reply

When a method is intended to produce a message written to the client, it can emit null. Emitting null signifies no response to be sent to the client, allowing for skipping a response when needed.

Json Object and Json Array

Vert.x `JSON Object and JSON Array instances are also bypassing the serialization and deserialization mechanism. Messages are sent as text message.

Bi-directional Streaming

Methods annotated with @OnMessage, handling both incoming and outgoing Multi, facilitate bi-directional streaming seamlessly.

@WebSocket("/foo")
@OnMessage 
public Multi<X> stream(Multi<Y> multi) {
    return multi
       .map(y -> toX(y));
}

Broadcasting

By default, responses produced by @OnMessage methods are sent back to the connected client. However, using the broadcast parameter, responses can be broadcasted to all connected clients .

@OnMessage(broadcast=true)
String emitToAll(String message) {
	// Send the response to all connected clients.
}

The same principle applies to methods returning instances of Multi or Uni.

Request Scope

When the user explicitly enables the request scope for a method annotated with @OnMessage, the duration of the request scope is contingent upon the method's signature:

• For blocking methods, the request scope terminates upon the method's completion or when it returns its result (for methods returning void).
• For methods returning Uni, the request scope concludes when the returned Uni emits an item or encounters a failure.
• For methods returning Multi, the request scope concludes when the returned Multi emits a completion signal or encounters a failure event.

@onopen and @onclose Annotations

These annotations inform the user about client connections and disconnections from the WebSocket.

@OnOpen is triggered upon client connection, while @OnClose is invoked upon disconnection.

These methods have access to the session-scoped WebSocketServerConnection bean.

/**
 * Annotated method is invoked when the client connects to a web socket.
 */
@Retention(RUNTIME)
@Target(METHOD)
public @interface OnOpen {

    /**    
     * @return {@code true} if all the connected clients should receive the objects emitted by the annotated method
     */
    public boolean broadcast() default false;

}

/**
 * Annotated method is invoked when the client disconnects from the web socket.
 */
@Retention(RUNTIME)
@Target(METHOD)
public @interface OnClose {

}

Parameters

Methods annotated with @OnOpen and @OnClose do not accept any parameters. If such methods declare parameters, they should be flagged as errors and reported to the user.

Allowed Returned Types

@OnOpen and @OnClose methods support different returned types.

For @OnOpen methods, the same rules as @OnMessage apply. Thus, a method annotated with @OnOpen can send messages to the client immediately after connecting. The supported return types for @OnOpen methods are:

• void: Indicates a blocking method where no explicit message is sent back to the connected client.
• Uni<Void>: Denotes a non-blocking method where the completion of the returned Uni signifies the end of processing. No message is sent back to the client.
• An object of type X: Represents a blocking method where the returned object is serialized and sent back to the client.
• Uni<X>: Specifies a non-blocking method where the item emitted by the non-null Uni is sent to the client.
• Multi<X>: Indicates a non-blocking method where the items emitted by the non-null Multi are sequentially sent to the client until completion or cancellation.

Items sent to the client are serialized except for the String and, Buffer byte[] types. In the case of Multi, the framework must subscribe to the returned Multi and write the items to the WebSocket as they are emitted. Strings are sent as text messages. Buffers and byte arrays are sent as binary messages.

For @OnClose methods, the allowed return types are:

• void: The method is considered blocking.
• Uni<Void>: The method is considered non-blocking.

@OnClose methods cannot send items to the connection client.

Server-side Streaming

Methods annotated with @OnOpen can utilize server-side streaming by returning a Multi<X>:

@WebSocket("/foo")
@OnOpen 
public Multi<Integer> streaming() {
    return Multi.createFrom().ticks().every(Duration.ofSecond(1))
       .onOverflow().ignore();
}

Broadcasting with @onopen

Similar to @OnMessage, items sent to the client from a method annotated with @OnOpen can be broadcasted to all clients instead of just the connecting client:

@OnOpen(broadcast=true)
String onOpen() {
	return "We have a new member!";
}

Serialization and Deserialization

In WebSocket communication, items received and sent undergo automatic serialization and deserialization processes by default, utilizing JSON (Jackson). However, developers can implement custom serializers and deserializers for specific requirements. The encode (serialization) and decode (deserialization) methods are packaged in a codec class.

/**
 * Serialized / Deserialized text messages to/from the type {@code T}.
 **/
public interface TextMessageCodec<T> {

    /**
     * Determines whether this codec can handle the provided type.
     * 
     * @param type the type to check
     * @return {@code true} if this codec can handle the provided type, {@code false} otherwise
     */
    boolean canHandle(Type type);

    /**
     * Encodes the provided value into a textual representation.
     * 
     * @param value the value to encode, must not be {@code null}
     * @return the encoded textual representation of the value
     */
    String encode(T value);

    /**
     * Decodes the provided textual representation into an object of the specified type.
     * 
     * @param type the type of the object to decode
     * @param value the textual representation to decode
     * @return the decoded object
     */
    T decode(Type type, String value);

}

/**
 * Serialized / Deserialized binary messages to/from the type {@code T}.
 **/
public interface BinaryMessageCodec<T> {

    /**
     * Determines whether this codec can handle the provided type.
     * 
     * @param type the type to check
     * @return {@code true} if this codec can handle the provided type, {@code false} otherwise
     */
    boolean canHandle(Type type);

    /**
     * Encodes the provided value into a binary representation.
     * 
     * @param value the value to encode, must not be {@code null}
     * @return the encoded representation of the value
     */
    Buffer encode(T value);

    /**
     * Decodes the provided binary representation into an object of the specified type.
     * 
     * @param type the type of the object to decode
     * @param value the binary representation to decode
     * @return the decoded object
     */
    T decode(Type type, Buffer value);

}

Codecs implementation must be exposed as CDI beans. When declared within the session scope, they must align with the session scope of the WebSocket connection.

Notably, the types String, JsonObject, JsonArray, Buffer, and byte[] bypass serialization and deserialization processes. For strings, JSON Object, and JSON Array, the default encoding is UTF-8, as mandated by the WebSocket specification, and the messages are sent as text messages. Buffer and byte[] are binary messages.

The default serialization/deserialization uses JSON (Jackson). Thus, messages would be received and sent as text messages.

---

Consuming Web Sockets (Client-Side)

The client side has been reworked and proposed as an ADR:
See #40333.

Observability Support

Metrics

Server Side

On the server side, we should expose, per path, the following metrics:

• number of alive connections

• number of exchanged messages
• sum of the received and sent message size
• number of failures (per exception type)

Client Side

On the client side, per client, we should expose the following metrics:

• number of exchanged messages
• sum of the received and sent message size
• number of connection/reconnection
• number of failures (per exception type)

Tracing

Because web sockets do not allow "headers" or "baguages", tracing implementation is complicated.

[mkouba]

CDI Scope

Classe annotated with @WebSocket should be in the @ApplicationScoped; otherwise, it is not indicated.

In theory, we could also support other scopes. If @ApplicationScoped or @Singleton is used the endpoint instance is shared for all conntections. If @SessionScoped or @Dependent is used then a new endpoint could be created for each connection.

In addition, a session scope is associated with a web socket connection.
When the @OnOpen method is called, a session scope associated with this web socket connection is created. Subsequent calls to the OnMessage or the OnClose methods use the same scope. The scope is terminated after the completion of the OnClose method.

We could also provide a session scoped bean for the WebSocketConnection object.

[cescoffier]

@maxandersen there is no problem to have the request scope enabled when onMessage is invoked. There are some interesting cases. For example:

@OnMessage
Multi<T> onMessage(Multi<X> messages) {
    // client messages are received from `messages` and our responses are emitted in the returned multi. Not necessariily 1 to 1, but n to m.
}

In this case, the request scope would spread from method invocation (even if there is no message sent by the client yet) to the completion of the returned Multi. We already do that in various places. However, if we consider the request scope as something "short", that is not necessarily the case.

The session scope as describe at the moment spread from the connection establishement (just before the onOpen invocation) to the disconnection (just after onClose). All the invocation to onMessage from that connection would have also use that scope. One of the nice benefit is the Memory handling from Quarkus Langchain4J as we can just use @SessionScoped and it will keep the messages for the length of the session.

[cescoffier]

So, the question is more:

Should we enable the request scope automatically, or should it be up to the user to use @ActivateRequestScope on the onMessage annotation?

Both are possible. It we to that automatically, we must make sure we cover it in the documentation (and in this doc)

[Ladicek]

Comparing the sections CDI Scope and Duplicated context, it seems to me that whatever you call session scope in the CDI Scope section is in fact a CDI request scope, because unless you do some extra work, there's 1:1 correspondence between the CDI request scope and the Vert.x duplicated context.

It is not. It's an implementation detail that we use the duplicated context to store the request context. But unless it's activated there is no request context active.

We discussed this with Clement and we believe that the session context is a more appropriate match for a websocket connection. I don't think we should activate the request context for a websocket connection at all...

Fair enough, but when the programmer adds @ActivateRequestContext to all the methods (or use RequestContextController), wouldn't they observe that the request scope actually lives as long as the session scope? (Assuming we store the session context in the duplicated context, which seems natural from the description, but of course under a different key than the request context.)

On and off, we discussed the idea of a "long running request scope" or a "stream scope" (gRPC, SSE, perhaps Reactive Messaging), this seems to be another place where the concept would match the reality. Using the session scope as the closest approximation kinda sorta makes sense, except this is the only (first?) place where we do it, so consistency becomes a concern.

[mkouba]

Fair enough, but when the programmer adds @ActivateRequestContext to all the methods (or use RequestContextController), wouldn't they observe that the request scope actually lives as long as the session scope?

Not really. The state of the request context is invalidated during destruction - so the scope is not active. See also #38107.

[Ladicek]

Ah! I vaguely recalled we did something around this, but couldn't remember exactly. OK, so the session scope would be valid for the entire duration of the WS connection, and the request scope (if activated by the user) would be valid for the duration of one method (or until completion of the async object the method returns). That makes sense.

[geoand]

The annotations used in this section are NOT the ones from the JSR 356, even if they reuse the same name.

What's the exact reasoning for this?

[cescoffier]

There are several reasons:

1. These annotations have a semantic attached to them, which we do not follow (signature-wise and execution-model-wise).
2. We are adding attributes to some annotations (@OnMessage and @OnOpen). The broadcast attribute is Quarkus-specific.
3. It would mix two sets of annotations: @WebSocket and the "next-to-be" @WebSocketClient are not defined in the JSR, while there are annotations named OnMessage, OnOpen and OnClose. BTW, I'm not attached to these names. I was acutally trying with @OnConnection, @OnDisconnection, and OnMessage, but it's a bit too long and can be slightly misleading.

[geoand]

👍🏼

[cescoffier]

For those following - I just posted the first ideas about the client side.

@maxandersen, I've tried to find a way to avoid the giant switch we generally see. I'm not totally happy, but it should work.

[geoand]

Looking at it more I underwhat was bothering me - basically it looked like the users had to implement some of the methods, but that's not the case as all they are doing is registering callbacks.

[cescoffier]

Yes. At the moment, the methods from the interface do not use annotations, because the signature is enough. However, for clarity, I believe it would be better to have/accept annotations.

[geoand]

Yeah, it would probably make things more clear

[cescoffier]

I did a complete rewrite of the proposal. I rewrote the client side completely.

[geoand]

I'll have another look

[mschorsch]

Kotlin coroutines should be supported out-of-the-box, this means suspend functions and Kotlin Flow as return type.

Note: There is still a long way to go before the virtual threads are really usable and there are still some RFCs to be finalized (e.g. structured concurrency). That will take a few more years. Kotlin coroutines, on the other hand, already work today and are in widespread use. For this reason, Kotlin users should not be ignored here 😉.

[geoand]

Good point.

[cescoffier]

That is a good point.

The main module must not depend on Kotlin types. It should be made in a way we can extend the signature.

[mkouba]

FTR the minimal POC (that aims to test the ideas from this proposal) can be found here: https://github.com/mkouba/quarkus/tree/websockets-next

So far it's very basic, contains a ton of TODOs, and only covers the functionality used in the websockets-quickstart. This is what the new API looks like: https://github.com/mkouba/quarkus-quickstarts/blob/websockets-next/websockets-quickstart/src/main/java/org/acme/websockets/ChatSocketNext.java

[cescoffier]

Awesome @mkouba - I will have a look to the code and update the doc :-D

[geoand]

Thanks a lot @mkouba!

How do you want to proceed with this in terms of contributions?
I do have some comments / ideas and would like to move forward, but I want to make sure we are on the same page and don't step on each other's toes.

[mkouba]

I would like to send a DRAFT pull request later next week so that we can polish the API/add tests/fix bugs/etc together...

[geoand]

👍🏼

[cescoffier]

@brunobat I need your brain for the tracing part. Does OTEL says anything about web socket?

[brunobat]

Hi @cescoffier.
There are no semantic conventions for web sockets and nothing specific to instrumenting web sockets in the spec.
There is no Java instrumentation for any known java web sockets library.
However, we can try something...
There is a javascript instrumentation we can use as inspiration and mimic it's context propagation mechanism to achieve interoperability. See: https://github.com/gadget-inc/opentelemetry-instrumentations/tree/main/packages/opentelemetry-instrumentation-ws
We need to keep in mind that Web socket communication fits better with messaging than http, tracking individual messages seems costly and tracking open and close connections have little semantic value.
As we can see in the library, tracking messages is off by default.

[geoand]

I have a question about Serialization / Deserialization:

The current proposal only implies that only text data is supported, but from what I understand, there are real world cases where a binary representation of objects is used mainly to improve performance.
It would be a shame if excluded those use cases from the high level API

[cescoffier]

yes, the injection of the session-scoped WebSocketConnection is necessary, for both server and client.

[geoand]

Another question I have is whether we should provide something to handle exceptions that occur during serialization.

[mkouba]

I was thinking about something like this:

@Inject WebSocketConnection connection;

@OnMessage
Buffer echo(Buffer foo) {
  Foo f = connection.fromText(Foo.class, FooCodec.class); 
  Bar bar = new Bar(f);
  return connection.toBinary(bar, BarCodec.class);
}

Not really nice, I agree.

Also, I don't believe it would work as the framework does not know if the returned object must be sent as binary or text.

The Buffer foo param is not used in the snippet ;-). You probably meant connection.fromText(foo, FooCodec.class) or something like that. In any case, this does not seem to help a lot since you can do somethig like:

@Inject FooCodec fooCodec;
@Inject BarCodec barCodec;

@OnMessage
Buffer echo(Buffer foo) {
  Foo f = fooCodec.decode(Foo.class, foo); 
  Bar bar = new Bar(f);
  return barCodec.encode(bar);
}

[mkouba]

But the ability to inject WebSocketConnection will probably become necessary (if not from day 1)

Yes, this is available since the very first version of the POC ;-)

[mkouba]

Another question I have is whether we should provide something to handle exceptions that occur during serialization.

This is a good question. TBH I did not think about error handling yet. That's the next thing I'd like to ponder after the "codec" stuff ;-).

[maxandersen]

In one part we use "AndAwait" in another "Async" - shouldn't it be consistent?

And I would say my preference is that its "Async" as that seems to be more correct (linguistically at least), but happy to be shown/explained otherwise

[cescoffier]

It should be andAwait. I will amend the doc.

[maxandersen]

But why...andAwait isn't something we really use otherwise is it ?

[mkouba]

The thing is that in these APIs the Async is the default and thus AndAwait (which is analogous to Uni.await().indefinitely()) makes sense. Async is usually used when you try to add some async functionality to a "legacy" blocking API. That said, it depends on what the usual usage is 🤷 and if we tend to promote the "async way" as the default...

[cescoffier]

AndAwait also indicates it works with virtual threads.

Also, it's generally good to indicate that the underlying operation is not immediate and it does some network-related stuff. Distribution cannot be transparent, here, we have a hint.

The other solution would be to have 2 variants of everything: reactive and blocking. We generally do that when the API is big enough to justify that split. Here, not so sure.

[geoand]

For a given WebSocket connection, the methods OnMessage, OnClose, and OnOpen must not be invoked concurrently

Intuitively this makes sense, but do we have a strong reason to enforce it?

[mkouba]

For a given WebSocket connection, the methods OnMessage, OnClose, and OnOpen must not be invoked concurrently

Intuitively this makes sense, but do we have a strong reason to enforce it?

Technically, there is a single Vertx duplicated context for the connection so if we don't enforce it we're in trouble as the duplicated context should not be accessed concurrently..

[geoand]

And Vert.x itself does not handle this already?

[mkouba]

Nope AFAIK. But that's more a question for @cescoffier.

BTW it seems that Jakarta WebSocket enforces the same rule in https://jakarta.ee/specifications/websocket/2.1/jakarta-websocket-spec-2.1#threading-considerations:
"In all cases, the implementation must not invoke an endpoint instance with more than one thread per peer at a time [WSC-5.1-2]."
and
"This guarantees that a WebSocket endpoint instance is never called by more than one container thread at a time per peer [WSC-5.1-4]."

[geoand]

Great info!

[chonton]

Where does authentication and authorization fit into this model? When a server receives a connection request, where can the application consume the endpoint path and headers and add custom authorization checks?

[geoand]

The Quarkus security components continue to work as they are also built on Vertx and come into play before.

We might want to look into supporting the Jakarta security annotations however

[chonton]

Having implemented authz on top of current undertow solution, I can tell you that security context is unavailable during the handshake phase. Will security context and headers be available at handshake interceptor in this proposed implementation?

[geoand]

We should definitely look into making that happen

[emattheis]

I would love to see abstraction that allows full control of the handshake. I am currently stuck between a rock and hard place with websockets in Quarkus:

• There is no way to programmatically return a 404 response using the official websocket extension based on JSR 356
• There is no way to programmatically control the subprotocol negotiation using the low-level vert.x websocket API

[sarxos]

Hi @cescoffier :)

This is a very nice API! But I see no support for closing WS connection with the code and reason bytes as per websocket spec here https://websockets.spec.whatwg.org/#dom-websocket-close

Do you plan to have support for this case? I can imagine API to be something like:

public class WebSocketServerConnection {

    /**
     * Closes the WebSocket connection.
     *
     * @return a new {@link Uni} that completes when the connection is closed successfully
     */
    @CheckReturnValue
    Uni<Void> close();

    /**
     * Closes the WebSocket connection with code (integer equal to 1000 or in the range 3000 to 4999) and reason (max 123 bytes long).
     *
     * @return a new {@link Uni} that completes when the connection is closed successfully
     */
    @CheckReturnValue
    Uni<Void> close(int code, String reason);

    /**
     * Closes the WebSocket connection and waits for the completion.
     */
    void closeAndAwait();

    /**
     * Closes the WebSocket connection with code (integer equal to 1000 or in the range 3000 to 4999) and reason (max 123 bytes long) 
     * and waits for the completion.
     */
    void closeAndAwait(int code, String reason);

And in the @WebSocket-annotated class:

@WebSocket("my/path")
public class MyWebSocketEndpoint {

    @OnClose 
    void onClose(int code, String reason) {
        System.out.println(code); // prints 1000
        if (reason != null) {
            System.out.println(reason); // prints whatever reason is
        }
    }

    @OnClose 
    void onClose(int code) {
        System.out.println(code); // prints 1000 in case of normal close or a different number according to spec
    }

    @OnClose 
    void onClose() {
        // ignore the code and reason
    }

A default WS close code is always 1000, but the user can provide custom values from a range of 3000 to 4999, see https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1 for more details

References:

• https://websockets.spec.whatwg.org/#dom-websocket-close
• https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1
• https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code
• https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/reason

[nithinbandaru1]

Hi,

I was just curious about how this implementation (API Interfaces only I assume) works with java eco system.

After some reading., I see that.

Specifications

• JSR 356: Part of Java EE
• Jakarta WebSocket: Part of Jakarta EE, just a renaming done for JSR 356.

Implementations

• Apache Tomcat
• GlassFish
• WildFly
• Payara Server
• Tyrus
• Undertow
• Jetty

Interestingly I see that all implementations are actually part of Web server hosts and not application framework itself.

Q1. So, now with this new interface change will this not work with these webservers as they are supposed to be according to specifications?
Q2. So, does this mean you guys did a complete implementation of WebSocket Server and Client and will be part of Application framework itself or new APIs will act just as a wrapper?
Q3. I see that there is use of Vert.x WebSocket API, is this implementation of WebSocket and this new API is acting like a wrapper for Vert.x and this is like having full implementation of WebSocket itself in Application framework code instead of having it in web server hosts?
Q4. Vert.x does not satisfy Jakarta WebSocket or JSR 356 specification, right?
Q5. Did I get it all wrong 😀?

[cescoffier]

As indicated in the document, we do NOT want to follow the specifications used by all the mentioned frameworks (JSR 356). We don't believe it has the characteristics we need these days.

Q1 - no, it is Quarkus-specific. Note that Quarkus principles allow for verifying many things during build time.
Q2 - Yes, Quarkus (actually Vert.x, the network stack of Quarkus) implements the web socket protocol
Q3 - Yes, we use the Vert.x WebSocket support. Like in many other areas, much of the heavy lifting is delegated to Vert.x
Q4—No, as mentioned above, we do not want to support JSR 356 in this effort. The "legacy" Quarkus websocket extension does.

[geoand]

In Quarkus when using Vertx (as almost all of our stack does), there is no web server, so most of the points above don't apply. What was done was to build a declarative API on top of the Vertx Websockets programmatic API (similarly to what we did with RESTEasy Reactive/Quarkus REST)

…

On Sun, Apr 7, 2024, 18:18 Nithin Bandaru ***@***.***> wrote: Hi, I was just curious about how this implementation (API Interfaces only I assume) works with java eco system. After some reading., I see that. Specifications - JSR 356: Part of Java EE - Jakarta WebSocket: Part of Jakarta EE, just a renaming done for JSR 356. Implementations - Apache Tomcat - GlassFish - WildFly - Payara Server - Tyrus - Undertow - Jetty Interestingly I see that all implementations are actually part of Web server hosts and not application framework itself. Q1. So, now with this new interface change will this not work with these webservers as they are supposed to be according to specifications? Q2. So, does this mean you guys did a complete implementation of WebSocket Server and Client and will be part of Application framework itself or new APIs will act just as a wrapper? Q3. I see that there is use of Vert.x WebSocket API, is this implementation of WebSocket and this new API is acting like a wrapper for Vert.x and this is like having full implementation of WebSocket itself in Application framework code instead of having it in web server hosts? Q4. Vert.x does not satisfy Jakarta WebSocket or JSR 356 specification, right? Q5. Did I get it all wrong 😀? — Reply to this email directly, view it on GitHub <#38473 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABBMDP73WJDVQXFO3GWKERLY4FPTVAVCNFSM6AAAAABCQ5SURKVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TAMZWGU4DK> . You are receiving this because you commented.Message ID: ***@***.***>

[smsajid]

Hello Quarkus team.
Thank you for the great work you are doing. I have couple of questions:

• What is the strategy of Quarkus to be compliant with other Jakarta EE specifications?

• Regarding JSR 356, will Quarkus update the implementation according to upcoming releases of the specification? Or this path is totally closed?

• Since Redhat is a contributor to Jakarata EE specifications, can your team not propose the semantic differences (as mentioned in your comments) to an upcoming spec update?

[cescoffier]

What is the strategy of Quarkus to be compliant with other Jakarta EE specifications?

WebSocket Next does not intend to be compatible with the Jakarta EE specification. The legacy extension provides support for it.

Regarding JSR 356, will Quarkus update the implementation according to upcoming releases of the specification? Or this path is totally closed?

We won't implement it. Again, we have another implementation implementing the spec. But the spec has many inconveniences, and the development and execution model look weird in the Quarkus context.

Since Redhat is a contributor to Jakarata EE specifications, can your team not propose the semantic differences (as mentioned in your comments) to an upcoming spec update?

First, we need a lot of community feedback before even thinking of contributing this to a spec. It may happen, but not before at least a year.

[maxandersen]

Just to clarify websockets-next does not target JSR 356 but Quarkus has since early days had a JSR 356 implementation and plan to continue to have one for those having needs for spec compliant code. It has though has @cescoffier says many inconveniences and doesn't fit well together with the rest.

[cescoffier]

The client-side ADR is now ready for review: #40333.

It does not contain many details as it's the direct companion of the server-side.

[smsajid]

Is there any plan to implement fallback handling like https://quarkus.io/guides/vertx-reference#bidirectional-communication-with-browsers-by-using-sockjs ?
What is the best option now to handle graceful degradation ?

[cescoffier]

Quarkus also has some support for sockjs: https://quarkus.io/guides/vertx-reference#bidirectional-communication-with-browsers-by-using-sockjs.

But no, it's not supported by websocket-next. Also, sockjs and degradation were useful when websockets were not supported by all browsers. Now, all recent browsers support websockets natively.

[smsajid]

Some corporate environments still block web socket connection for security reasons. So, the vertx solution will be the best bet to use WS in such environments?

[cescoffier]

Sure, but the cost of the degradation should not be ignored. In these cases, directly implementing with SockJS in mind is better. Typically, sub-protocol, security and so on are totally different.