ballerina/websocket

Package Overview

This package provides an implementation for connecting and interacting with WebSocket endpoints. The package facilitates three types of network entry points as ‘Client’, ‘AsyncClient’, and ‘Listener’.

The websocket:Client reads text and binary messages synchronously. A callback service with the two onPing and onPong remote functions can be registered at the initialization of the client to receive ping/pong control frames. The websocket:AsyncClient, which behaves asynchronously also has a callback websocket:Service that can be registered at the initialization of the client. It has a fixed set of remote methods in this service and they get called on the receipt of messages from the server.

On the server-side, an initial WebSocket service is there 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.

WebSocket upgrade: During a WebSocket upgrade, the initial message received is an HTTP request.

1service /ws on new websocket:Listener(21003) {
2 resource function get .(http:Request req) returns websocket:Service|websocket:UpgradeError {
3 return new WsService();
4}
5
6service class WsService {
7 *websocket:Service;
8 remote isolated function onTextMessage(websocket:Caller caller, string data) returns websocket:Error? {
9 check caller->writeTextMessage(data);
10 }
11}

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.

Remote methods associated with websocket:Client service

onPing: The received ping messages are dispatched to this remote method.

onPong: The received pong messages are dispatched to this remote method.

For more information, see the following.

Listeners

[1]

Listener

This is used for creating Websocket server endpoints.

Clients

[2]

Caller

Represents a WebSocket caller.

Client

Represents a WebSocket synchronous client endpoint.

Functions

[1]

addCookies

Adds cookies to the custom header.

Object Types

[3]

PingPongService

The Websocket Sync client service type

Service

The Websocket service type

UpgradeService

The Websocket upgrade service type

Records

[14]

BearerTokenConfig

Represents token for Bearer token authentication.

ClientConfiguration

Configurations for the WebSocket client.

ClientSecureSocket

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

CommonClientConfiguration

Common client configurations for WebSocket clients.

CredentialsConfig

Represents credentials for Basic Auth authentication.

JwtIssuerConfig

Represents JWT issuer configurations for JWT authentication.

ListenerConfiguration

Provides a set of configurations for HTTP service endpoints.

ListenerHttp1Settings

Provides settings related to HTTP/1.x protocol.

ListenerSecureSocket

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

OAuth2ClientCredentialsGrantConfig

Represents OAuth2 client credentials grant configurations for OAuth2 authentication.

OAuth2PasswordGrantConfig

Represents OAuth2 password grant configurations for OAuth2 authentication.

OAuth2RefreshTokenGrantConfig

Represents OAuth2 refresh token grant configurations for OAuth2 authentication.

RequestLimitConfigs

Provides inbound request URI, total header and entity body size threshold configurations.

WSServiceConfig

Configurations for a WebSocket service.

Constants

[3]

AUTH_HEADER

Represents the Authorization header name.

AUTH_SCHEME_BASIC

The prefix used to denote the Basic authentication scheme.

AUTH_SCHEME_BEARER

The prefix used to denote the Bearer authentication scheme.

Annotations

[1]

ServiceConfig

The annotation which is used to configure a WebSocket service.

Types

[2]

ClientAuthConfig

Defines the authentication configurations for the WebSocket client.

OAuth2GrantConfig

Represents OAuth2 grant configurations for OAuth2 authentication.

Errors

[1]

Error

Represents any error related to the WebSocket module