io.pedestal.service.websocket
added in 0.8.0
WebSocket support abstracted away from the Servlet API.
InitializeWebSocket
protocol
Converts a native value (supplied by the network connector) into a WebSocketChannel. Expects the native value to be stored in the Ring request map under key :websocket-channel-source.
members
initialize-websocket
(initialize-websocket source context ws-opts)Passed the native channel (specific to the network connector), the context, and options.
Performs initialization to initialize a WebSocketChannel, and performs any modification to the context needed, including setting the :websocket-channel key to the WebSocketChannel instance.
start-ws-connection
(start-ws-connection ws-channel opts)Starts a simple WebSocket connection around a WebSocketChannel. The connection allows the server to asyncronously send messages to the client.
Returns a core.async channel used to send messages to the client.
Closing the channel will close the WebSocketChannel.
Writing a value to the channel will send a message to the client. A value is either the message (as a String, ByteBuffer, InputStream, or byte array) or a tuple of the message and a response channel.
When the response channel is provided, the result of sending the message is written to it: Either the keyword :success, :closed, or an Exception thrown when attempting to send the message.
Message delivery is sequential, not parallel.
Options:
- :send-buffer-or-n
- Used to create the channel, defaults to 10
upgrade-request-to-websocket
(upgrade-request-to-websocket context ws-opts)Initializes a WebSocketChannel for the request stored in the context.
Returns a modified context map.
ws-opts:
:on-open - callback passed the WebSocketChannel and the request map, returns a process object.
:on-close - callback passed the WebSocketChannel, the process object, and the close reason; return value is ignored.
The close reason is a keyword, but the values vary slightly between network connectors.
:on-text callback passed the WebSocketChannel, the process object, and a String; return value is ignored.
:on-binary callback passed the WebSocketChannel, the process object, and the binary data (as a ByteBuffer); return value is ignored.
Note that in order to override the type of binary data passed to the callback, you must make use of on-binary from your :on-open callback.
websocket-interceptor
(websocket-interceptor interceptor-name ws-opts)Creates and returns an interceptor as a wrapper around upgrade-request-to-websocket.
WebSocketChannel
protocol
Defines the behavior of an asynchronous WebSocket connection capable of sending and receiving messages.
members
close!
(close! this)Closes the channel, preventing further sends or receives. Returns nil.
on-binary
(on-binary this format callback)Sets up a callback for received binary messages.
The format may be :bytes, :byte-buffer, or :input-stream.
The callback receives the channel, the process object, and the binary message (in the chosen format). The return value is ignored.
May only be called once. Returns nil.
on-text
(on-text this callback)Sets up a callback for received text messages.
The callback receives the channel, the process object, and message. The return value is ignored.
May only be called once. Returns nil.
send-binary!
(send-binary! this data)Sends the given binary data to the channel as either a byte array or an InputStream.
Returns true on success, false if the channel has closed.
send-text!
(send-text! this string)Sends the given string to the channel as a text frame.
Returns true on success, false if the channel has closed.