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

Cloneable

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


Reads data from the WebSocket connection.



readMessage

A `string` if a text message is received, `byte[]` if a binary message is received or a `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

Defines the authentication error type that returned from the listener.


AuthnError

Defines the authorization error type that returned from the listener.


AuthzError

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

Uses for declarative auth design, where the authentication/authorization decision is taken
by reading the auth annotations provided in service/resource and the `Authorization` header of request.



authenticateResource

The service reference where the resource locates


serviceRef

Service

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

UpgradeService

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


Common client configurations for WebSocket clients.


subProtocols

Custom headers, which should be sent to the server

customHeaders

readTimeout

writeTimeout

secureSocket

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

maxFrameSize

Enable support for compression in the WebSocket

webSocketCompressionEnabled

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)

handShakeTimeout

cookies

Configurations related to client authentication

auth

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

pingPongHandler

retryConfig

CommonClientConfiguration

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


Provides configurations for facilitating secure communication with a remote HTTP endpoint.


enable

Configurations associated with `crypto:TrustStore` or single certificate file that the client trusts

cert

Configurations associated with `crypto:KeyStore` or combination of certificate and private key of the client

protocol

Certificate validation against OCSP_CRL, OCSP_STAPLING related options

certValidation

List of ciphers to be used
eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

ciphers

verifyHostName

shareSession

handshakeTimeout

sessionTimeout

ClientSecureSocket

Common client configurations for WebSocket clients.



Custom headers, which should be sent to the server


Write timeout (in seconds) of the client


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


WebSocketRetryConfig

Represents credentials for Basic Auth authentication.


username

password

CredentialsConfig

Represents file user store configurations for Basic Auth authentication.


FileUserStoreConfig

Represents the auth annotation for file user store configurations with scopes.



File user store configurations for Basic Auth authentication


fileUserStoreConfig

scopes

FileUserStoreConfigWithScopes

Represents JWT issuer configurations for JWT authentication.


issuer

JWT username, which is mapped to the `sub`

JWT audience, which is mapped to the `aud`

audience

jwtId

keyId

customClaims

IssuerConfig

JwtIssuerConfig

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


Record: ListenerSecureSocket

Fields