ballerina/socket module

Module overview

This module provides an implementation for connecting to a remote socket server or acts as a server for an incoming socket request. The module facilitates two types of endpoints called Client and Listener.

Samples

Listener endpoints

The sample given below shows how a listener is used to listen to the incoming socket request. The onAccept(socket:Caller) resource function gets invoked when a new client is connected. The new client is represented using the socket:Caller. onReadReady(socket:Caller, byte[]) resource gets invoked once the remote client sends some data and onClose(socket:Caller) is invoked once the client is departs.

import ballerina/io;
import ballerina/socket;

listener socket:Listener server = new ({ port:61598 });

service echoServer on server {
    resource function onAccept (socket:Caller caller) {
        io:println("Join: ", caller.remotePort);
    }

    resource function onReadReady (socket:Caller caller, byte[] content) {
        _ = caller->write(content);
    }

    resource function onClose(socket:Caller caller) {
        io:println("Leave: " + caller.remotePort);
    }

    resource function onError(socket:Caller caller, error er) {
        io:println(er.reason());
    }
}

Client endpoints

Client endpoints are used to connect to and interact with a socket server. The client can only send the data to the server. Client's callbackService needs to retrieve the data from the server and do multiple requests/responses between client and the server.

import ballerina/io;
import ballerina/socket;

public function main() {
    socket:Client socketClient = new({host: "localhost", port: 9999, callbackService: ClientService});
    string msg = "Hello Ballerina\n";
    byte[] c1 = msg.toByteArray("utf-8");
    _ = socketClient->write(c1);
}

service ClientService = service {

    resource function onConnect(socket:Caller caller) {
        io:println("connect: ", caller.remotePort);
    }
    
    resource function onReadReady (socket:Caller caller, byte[] content) {
        io:println("client write");
        _ = caller->write(content);
    }
    
    resource function onClose(socket:Caller caller) {
        io:println("Leave: ", caller.remotePort);
    }
    
    resource function onError(socket:Caller caller, error er) {
        io:println(er.reason());
    }
};

Type Definitions

Type Values Description
Caller Client

Represents caller object in socket service resources and client callback service resources. This has all the remote functions expose by socket:Client.

Records Summary

Record Description
ClientConfig Configuration for socket client endpoint.
ListenerConfig Represents the socket server configuration.
SocketError SocketError will return in a socket related error situation.

Objects Summary

Object Description
Listener

Represents service endpoint where socket server service registered and start.

Endpoints Summary

Endpoint Description
Client

Represents socket client and related remote functions.

public type ClientConfig record

Configuration for socket client endpoint.

Field Name Data Type Default Value Description
host string

Target service URL

port int

Port number of the remote service

callbackService service

The callback service for the client. Resources in this service gets called on receipt of messages from the server.

public type ListenerConfig record

Represents the socket server configuration.

Field Name Data Type Default Value Description
interface string? null

the interface that server with to bind

public type SocketError record

SocketError will return in a socket related error situation.

Field Name Data Type Default Value Description
message string

the cause for the error

public type Listener object

Represents service endpoint where socket server service registered and start.

  • <Listener> __init(int port, socket:ListenerConfig? config)

    Parameter Name Data Type Default Value Description
    port int
    config socket:ListenerConfig? null
  • <Listener> __start() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __stop() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __attach(service s, map annotationData) returns (error?<>)

    Parameter Name Data Type Default Value Description
    s service
    annotationData map
    Return Type Description
    error?<>

Endpoint Client

Represents socket client and related remote functions.

Field Name Data Type Default Value Description
remotePort int 0

the remote port number to which this socket is connected

localPort int 0

the local port number to which this socket is bound

remoteAddress string? null

the remote IP address string in textual presentation to which the socket is connected

localAddress string? null

the local IP address string in textual presentation to which the socket is bound

id int 0

a unique identifier to identify each client

  • <Client> write(byte[] content) returns (int | error<>)

    Writes given data to the client socket.

    Parameter Name Data Type Default Value Description
    content byte[]
    • the content that wish to send to the client socket
    Return Type Description
    int | error<>
    • number of bytes got written or an error if encounters an error while writing
  • <Client> close() returns (error?<>)

    Closes the client socket connection.

    Return Type Description
    error?<>
    • an error if encounters an error while closing the connection or returns nil otherwise
  • <Client> shutdownRead() returns (error?<>)

    Shutdowns the further read from socket.

    Return Type Description
    error?<>

    an error if encounters an error while shutdown the read from socket or returns nil otherwise

  • <Client> shutdownWrite() returns (error?<>)

    Shutdowns the further write from socket.

    Return Type Description
    error?<>

    an error if encounters an error while shutdown the write from socket or returns nil otherwise