This module provides APIs for connecting and interacting with WebSocket endpoints.
This module facilitates two types of network entry points as the
websocket:Client can be used to read/write text/binary messages synchronously.
A simple client code to handle text messages as follows.
Similar to the above,
readMessage can be used to handle binary messages as well. This module also has some low-level APIs to handle
binary messages such as
A callback service with the two
onPong remote functions can be registered at the initialization of the client to receive the
ping/pong control frames.
On the listener-side, an initial WebSocket upgrade service can be attached to the
websocket:Listener to handle upgrade requests. It has a single
get resource, which takes in an
http:Request optionally. The
get resource returns a
websocket:Service to which incoming messages get dispatched after a successful WebSocket connection upgrade. This resource can be used to intercept the initial HTTP upgrade with custom headers or to cancel the WebSocket upgrade by returning an error.
websocket:Service has a fixed set of remote methods.
Remote methods associated with
onOpen: As soon as the WebSocket handshake is completed and the connection is established, the
onOpen remote method is dispatched.
onMessage: This remote function accepts both types of text and binary messages. This function accepts
anydata as the function parameter as this remote function supports data binding.
onTextMessage: The received text messages are dispatched to this remote method. Users are not allowed to have this remote functions along with the
onMessage remote function.
onBinaryMessage: The received binary messages are dispatched to this remote method. Users are not allowed to have this remote functions along with the
onMessage remote function.
onPing and onPong: The received ping and pong messages are dispatched to these remote methods respectively.
onIdleTimeout: This remote method is dispatched when the idle timeout is reached. The
idleTimeout has to be configured either in the WebSocket service or the client configuration.
onClose: This remote method is dispatched when a close frame with a
statusCode and a reason is received.
onError: This remote method is dispatched when an error occurs in the WebSocket connection. This will always be preceded by a connection closure with an appropriate close frame.
A WebSocket contains three types of control messages:
pong. A WebSocket server or a client can send a
ping message and the opposite side should respond with a corresponding
pong message by returning the same payload sent with the
ping message. These ping/pong sequences are used as a heartbeat mechanism to check if the connection is healthy.
You do not need to explicitly control these messages as they are handled automatically by the services and clients. However, if required, you can override the default implementations of the ping/pong messages by registering a
websocket:PingPongService in the client side as given in the above client code sample and by including the
onPong remote functions in the
websocket:Service in the server side.
A WebSocket server or a client can close the WebSocket connection by calling the
close function. In the event of a connection closure, the service will be notified by invoking the
onClose remote function. Also, on the client side, you will get a connection closure error if you try to read/write messages.
Per message compression extensions are supported by the Ballerina
websocket module and this is enabled by default for both the WebSocket client and the server. Compression can be enabled or disabled by setting the
false in the
ListenerConfiguration. Once the compression is successfully negotiated, receiving compressed messages will be automatically decompressed when reading.
Origin header can be used to differentiate between WebSocket connections from different hosts or between those made from a browser and some other kind of network client. It is recommended to validate this
Origin header before accepting the WebSocket upgrade.
Using the TLS protocol to secure WebSocket communication
It is strongly recommended to use the
wss:// protocol to protect against man-in-the-middle attacks. The Ballerina
websocket module allows the use of TLS in communication to do this. This expects a secure socket to be set in the connection configuration as shown below.