Websockets — io.pedestal/pedestal.service 0.7.0

Websockets

Websocket support was present prior to Pedestal 0.7, but was a container-specific option for Jetty. In Pedestal 0.7, websocket support was refactored to be more universal and declarative, part of the service-map.adoc.

Websockets are an asynchronous and bidirectional connection between a client and a server. Once a Websocket connection is established, either party may send messages to the other party - this unleashes truly unbounded possibilities for creating dynamic, real-time, and asynchronous applications.

Websocket requests are not routed the way HTTP requests are; instead, the mapping from incoming requests to Websocket handlers is defined in the service-map.adoc.

In the service map, the :io.pedestal.http/websockets key maps string routes to endpoint maps.

The endpoint map is a set of callbacks and configuration. The path and endpoint map are ultimately passed to the api:add-endpoint[] function, which describes in detail how the callbacks are used.

Table 1. Callbacks
Key	Signature	Description
:on-open	(Session, EndpointConfig) → Object	Invoked when the client first opens a connection. The returned value is retained and passed as the first argument of the remaining callbacks.
:on-close	(Object, Session, CloseReason) → nil	Invoked when the socket is closed, allowing any resources to be freed.
:on-error	(Object, Session, Throwable) → nil	Passed any unexpected exception.
:on-text	(Object, String) → nil	Passed a text message from the client, as a single String.
:on-binary	(Object, ByteBuffer) → nil	Passed a binary message, as a single ByteBuffer.
:configure	(ServerEndpointConfig$Builder) → nil	Allows additional configuration using an instance of `jakarta.websocket.server.ServerEndpointConfig.Builder`.

Table 1. Callbacks

Key

Signature

Description

:on-open

(Session, EndpointConfig) → Object

Invoked when the client first opens a connection. The returned value is retained and passed as the first argument of the remaining callbacks.

:on-close

(Object, Session, CloseReason) → nil

Invoked when the socket is closed, allowing any resources to be freed.

:on-error

(Object, Session, Throwable) → nil

Passed any unexpected exception.

:on-text

(Object, String) → nil

Passed a text message from the client, as a single String.

:on-binary

(Object, ByteBuffer) → nil

Passed a binary message, as a single ByteBuffer.

:configure

(ServerEndpointConfig$Builder) → nil

Allows additional configuration using an instance of jakarta.websocket.server.ServerEndpointConfig.Builder.

Table 2. Configuration
Key	Type	Description
:subprotocols	vector of String	Optional, specifies sub-protocols for the websocket connection
:idle-timeout-ms	long	Sets the max idle timeout for the websocket to a fixed value.

Table 2. Configuration

Key

Type

Description

:subprotocols

vector of String

Optional, specifies sub-protocols for the websocket connection

:idle-timeout-ms

long

Sets the max idle timeout for the websocket to a fixed value.

Essentially, the :on-open callback is invoked when the client initiates the connection.

It is intended that, when the client connects, some form of server-side process will be initiated capable of sending messages to the client asynchronously. It is the responsibility of the :on-open callback to create such a process. One common option is to use the api:on-open-start-ws-connection[] function to create the callback, or construct the :on-open callback around the api:start-ws-connection[] function.

The :on-text and :on-binary callbacks are invoked when a text or binary message from the client is received.