The annotation which is used to configure a WebSocket service.


ServiceConfig

WSServiceConfig

Pushes text messages to the connection. If an error occurs while sending the text message to the connection, that message
will be lost.



writeTextMessage

data

string

A `websocket:Error` if an error occurs when sending


Error

Pushes binary data to the connection. If an error occurs while sending the binary message to the connection,
that message will be lost.



writeBinaryMessage

Pings the connection. If an error occurs while sending the ping frame to the server, that frame will be lost.



ping

Sends a pong message to the connection. If an error occurs while sending the pong frame to the connection, that
the frame will be lost.



pong

close

statusCode

reason

Time to wait (in seconds) for the close frame to be received from the remote endpoint before closing the
connection. If the timeout exceeds, then the connection is terminated even though a close frame
is not received from the remote endpoint. If the value < 0 (e.g., -1), then the connection waits
until a close frame is received. If the WebSocket frame is received from the remote endpoint
within the waiting period, the connection is terminated immediately.


timeout

decimal

setAttribute

value

Gets connection related attribute if any.



getAttribute

The attribute related to the given key or `nil`


Removes connection related attribute if any.



removeAttribute

Gives the connection id associated with this connection.



getConnectionId

The unique ID associated with the connection


Gives the subprotocol if any that is negotiated with the client.



getNegotiatedSubProtocol

The subprotocol if any negotiated with the client or `nil`


Gives the secured status of the connection.



isSecure

boolean

Gives the open or closed status of the connection.



isOpen

Caller

Represents a WebSocket synchronous client endpoint.


Initializes the synchronous client when called.



init

The configurations to be used when initializing the client


config

ClientConfiguration

initEndpoint

Writes text messages to the connection. If an error occurs while sending the text message to the connection, that message
will be lost.



Writes binary data to the connection. If an error occurs while sending the binary message to the connection,
that message will be lost.



Time to wait (in seconds) for the close frame to be received from the remote endpoint before closing the
connection. If the timeout exceeds, then the connection is terminated even though a close frame
is not received from the remote endpoint. If the value is < 0 (e.g., -1), then the connection
waits until a close frame is received. If the WebSocket frame is received from the remote
endpoint within the waiting period, the connection is terminated immediately.


A `websocket:Error` if an error occurs while closing the WebSocket connection


Gets connection-related attributes if any.



Gives the HTTP response if any received for the client handshake request.



getHttpResponse

The HTTP response received from the client handshake request


Response

Reads text messages in a synchronous manner



readTextMessage

The text data sent by the server or a `websocket:Error` if an error occurs when receiving


Reads binary data in a synchronous manner



readBinaryMessage

The binary data sent by the server or an `websocket:Error` if an error occurs when receiving


Client

Represents the Authorization header name.


AUTH_HEADER

The prefix used to denote the Basic authentication scheme.


AUTH_SCHEME_BASIC

The prefix used to denote the Bearer authentication scheme.


AUTH_SCHEME_BEARER

## Overview

This module provides APIs for connecting and interacting with WebSocket endpoints. 

This module facilitates two types of network entry points as the ‘Client’ and ‘Listener’. 

#### Client

The `websocket:Client` can be used to read/write text/binary messages synchronously. 

A simple client code to handle text messages as follows.
```ballerina
import ballerina/websocket;

public function main() returns error? {
   websocket:Client wsClient = check new("ws://echo.websocket.org");

   check wsClient->writeTextMessage("Text message");

   string textResp = check wsClient->readTextMessage();
}
```
Similar to the above, this module has the `writeBinaryMessage` and `readBinaryMessage` functions to handle binary messages.
A callback service with the two `onPing` and `onPong` remote functions can be registered at the initialization of the client to receive the `ping/pong` control frames.
```ballerina
import ballerina/io;
import ballerina/websocket;

public function main() returns error? {
   websocket:Client wsClient = check new("ws://echo.websocket.org", pingPongHandler = new clientPingPongCallbackService());
   check wsClient->writeTextMessage("Text message");
}

service class clientPingPongCallbackService {
    *websocket:PingPongService;
    remote isolated function onPing(websocket:Caller caller, byte[] localData) returns byte[] {
        io:println("Ping message received");
        return localData;
    }

    remote isolated function onPong(websocket:Caller caller, byte[] localData) {
        io:println("Pong message received");
    }
}
```

#### Listener

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.
The returning `websocket:Service` has a fixed set of remote methods.

```ballerina
service /ws on new websocket:Listener(21003) {
    resource function get .(http:Request req) returns websocket:Service|websocket:UpgradeError {
        return new WsService();
}
        
service class WsService {
  *websocket:Service;
  remote isolated function onTextMessage(websocket:Caller caller, string data) returns websocket:Error? {
      check caller->writeTextMessage(data);
  }
}              
```

##### Remote methods associated with `websocket:Service`

**onOpen**: As soon as the WebSocket handshake is completed and the connection is established, the `onOpen` remote method is dispatched.

**onTextMessage**: The received text messages are dispatched to this remote method.

**onBinaryMessage**: The received binary messages are dispatched to this remote method.

**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.

#### Control Messages

A WebSocket contains three types of control messages: `close`, `ping`, and `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 `onPing` and `onPong` remote functions in the `websocket:Service` in the server side.

```ballerina
remote function onPing(websocket:Caller caller, byte[] data) returns error? {
    io:println(string `Ping received with data: ${data.toBase64()}`);
    check caller->pong(data);
}
 
remote function onPong(websocket:Caller caller, byte[] data) {
    io:println(string `Pong received with data: ${data.toBase64()}`);
}
```

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.

```ballerina
remote function onClose(websocket:Caller caller, int statusCode, string reason) {
    io:println(string `Client closed connection with ${statusCode} because of ${reason}`);
}
```

#### WebSocket Compression

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 `webSocketCompressionEnabled` to `true` or `false` in the `ClientConfiguration` and `ListenerConfiguration`. Once the compression is successfully negotiated, receiving compressed messages will be automatically decompressed when reading.

#### Origin Considerations

The `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.
```ballerina
import ballerina/http;
import ballerina/websocket;

service /basic/ws on new websocket:Listener(9090) {
   resource isolated function get .(http:Request httpRequest) returns websocket:Service|websocket:UpgradeError {
       string|error header = httpRequest.getHeader("Origin");
       if header is string {
           // Implement validateOrigin function to validate the origin header.
	       boolean validated = validateOrigin(header);
           if validated {
              return new WsService();
           }
       }
       return error("Invalid upgrade request");
   }
}
service class WsService {
    *websocket:Service;
    remote function onTextMessage(websocket:Caller caller, string text) {
        
    }
}
```

#### 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.

##### Configuring TLS in server side

```ballerina
listener websocket:Listener wssListener = new (9090, {
    secureSocket: {
        key: {
            certFile: "../resource/path/to/public.crt",
            keyFile: "../resource/path/to/private.key"
        }
    }
});
service /basic/ws on wssListener {
    
}
```

##### Configuring TLS in client side

```ballerina
websocket:Client wssClient = new ("wss://echo.websocket.org", {
    secureSocket: {
        cert: "../resource/path/to/public.crt"
    }
});
```


Defines the Auth error types that returned from the client


AuthError

Raised during failures in connection closure


ConnectionError

ConnectionClosureError

Represents any error related to the WebSocket module


Raised when the initial WebSocket handshake timed out


HandshakeTimedOut

Raised when an out of order/invalid continuation frame is received


ProtocolError

InvalidContinuationFrameError

Raised during the handshake when the WebSocket upgrade fails


InvalidHandshakeError

Raised when receiving a frame with a payload exceeding the maximum size


PayloadTooLargeError

Raised when the other side breaks the protocol


Raised when the client read time out reaches


ReadTimedOutError

SslError

Raised when the WebSocket upgrade is not accepted


UpgradeError

addCookies

This is used for creating WebSocket server endpoints. A WebSocket server endpoint is capable of responding to
remote callers. The `Listener` is responsible for initializing the endpoint using the provided configurations.


Gets invoked during the module initialization to initialize the listener.



'listener

Configurations for the WebSocket service listener


ListenerConfiguration

attach

websocketService

Service

name

An `error` if an error occurred during the service attachment process or else `()`


error

Starts the registered service programmatically.



'start

An `error` if an error occurred during the listener starting process


Stops the service listener gracefully. Already-accepted requests will be served before connection closure.



gracefulStop

An `error` if an error occurred during the listener stopping process


Stops the service listener immediately. It is not implemented yet.



immediateStop

An `error` if an error occurred during the listener stop process


Detaches a WebSocket service from the listener. Note that detaching a WebSocket service would not affect
The functionality of the existing connections.



detach

An `error` if one occurred during detaching of a service or else `()`


Listener

The WebSocket service type to handle ping/pong frames


PingPongService

Represents token for Bearer token authentication.



token

BearerTokenConfig

Configurations for the WebSocket client.
The following fields are inherited from the other configuration records in addition to the client-specific configs.                    |


subProtocols

customHeaders

readTimeout

secureSocket

maxFrameSize

webSocketCompressionEnabled

handShakeTimeout

cookies

auth

pingPongHandler

CommonClientConfiguration

Configures the SSL/TLS options to be used for WebSocket client.


enable

cert

protocol

certValidation

ciphers

verifyHostName

shareSession

handshakeTimeout

sessionTimeout

ClientSecureSocket

Common client configurations for WebSocket clients.



Custom headers, which should be sent to the server


The maximum payload size of a WebSocket frame in bytes.
If this is not set, is negative, or is zero, the default frame size of 65536 will be used


Enable support for compression in the WebSocket


Time (in seconds) that a connection waits to get the response of
the WebSocket handshake. If the timeout exceeds, then the connection is terminated with
an error. If the value < 0, then the value sets to the default value(300)


Cookie

Configurations related to client authentication


ClientAuthConfig

A service to handle the ping/pong frames.
Resources in this service gets called on the receipt of ping/pong frames from the server


Represents credentials for Basic Auth authentication.


username

password

CredentialsConfig

Represents JWT issuer configurations for JWT authentication.


issuer

audience

jwtId

keyId

customClaims

expTime

signatureConfig

IssuerConfig

JwtIssuerConfig

Provides a set of configurations for HTTP service endpoints.



host

Configurations related to HTTP/1.x protocol


http1Settings

ListenerHttp1Settings

The SSL configurations for the service endpoint. This needs to be configured in order to
communicate through WSS.


ListenerSecureSocket

Period of time in seconds that a connection waits for a read/write operation in the
initial upgrade request. Use value 0 to disable timeout


The server name which should appear as a response header


server

Enable support for compression in WebSocket


Configurations associated with inbound request size limits


requestLimits

RequestLimitConfigs

Provides settings related to HTTP/1.x protocol.


keepAlive

maxPipelinedRequests

Configures the SSL/TLS options to be used for WebSocket service.


mutualSsl

Represents OAuth2 client credentials grant configurations for OAuth2 authentication.


tokenUrl

clientId

clientSecret

scopes

defaultTokenExpTime

clockSkew

optionalParams

credentialBearer

clientConfig

ClientCredentialsGrantConfig

OAuth2ClientCredentialsGrantConfig

Represents OAuth2 password grant configurations for OAuth2 authentication.


refreshConfig

PasswordGrantConfig

OAuth2PasswordGrantConfig

This module provides APIs for connecting and interacting with WebSocket endpoints. 

Object type: PingPongService