ballerina/tcp

Overview

This module provides APIs for sending/receiving messages to/from another application process (local or remote) over connection-oriented TCP protocol.

Client

The tcp:Client is used to connect to a socket server and interact with it. The client can send the data to the server and retrieve the data from the server.

A client can be defined by providing the remoteHost and the remotePort. A simple client code is as follows.

1import ballerina/tcp;
2
3public function main() returns error? {
4 tcp:Client socketClient = check new("localhost", 3000);
5
6 string msg = "Hello Ballerina";
7 byte[] msgByteArray = msg.toBytes();
8 check socketClient->writeBytes(msgByteArray);
9
10 readonly & byte[] receivedData = check socketClient->readBytes();
11
12 check socketClient->close();
13}

Listener

The tcp:Listener is used to listen to the incoming socket request. The onConnect(tcp:Caller) remote method gets invoked when a new client is connected. The new client is represented using the tcp:Caller. The onConnect(tcp:Caller) method may return tcp:ConnectionService|tcp:Error.

The tcp:ConnectionService can have the following remote methods

  • onBytes(readonly & byte[] data) - This remote method is invoked once the content is received from the client.
  • onError(readonly & tcp:Error err) - This remote method is invoked in an error situation.
  • onClose() - This remote method is invoked when the connection is closed.

A tcp:Listener can be defined as follows:

1import ballerina/tcp;
2import ballerina/io;
3import ballerina/log;
4
5service on new tcp:Listener(3000) {
6 remote function onConnect(tcp:Caller caller) returns tcp:ConnectionService {
7 io:println("Client connected to echoServer: ", caller.remotePort);
8 return new EchoService();
9 }
10}
11
12service class EchoService {
13
14 remote function onBytes(readonly & byte[] data) returns byte[]|tcp:Error? {
15 // echo back the data to the client
16 return data;
17 }
18
19 remote function onError(tcp:Error err) returns tcp:Error? {
20 log:printError("An error occurred", 'error = err);
21 }
22
23 remote function onClose() returns tcp:Error? {
24 io:println("Client left");
25 }
26}

Using the TLS protocol

The Ballerina TCP module allows the use of TLS in communication. This expects a secure socket to be set in the connection configuration as shown below.

Configuring TLS in server side
1tcp:ListenerSecureSocket listenerSecureSocket = {
2 key: {
3 certFile: "../resource/path/to/public.crt",
4 keyFile: "../resource/path/to/private.key"
5 }
6};
7
8service on new tcp:Listener(9002, secureSocket = listenerSecureSocket) {
9 isolated remote function onConnect(tcp:Caller caller) returns tcp:ConnectionService {
10 return new EchoService();
11 }
12}
Configuring TLS in client side
1tcp:Client socketClient = check new ("localhost", 9002, secureSocket = {
2 cert: "../resource/path/to/public.crt",
3});

Listeners

[1]

Listener

This is used for creating TCP server endpoints.

Clients

[2]

Caller

Represents caller object in tcp service remote methods.

Client

Initializes the TCP connection client based on the provided configurations.

Object Types

[2]

ConnectionService

Represent TCP Listener ConnectionService service type.

Service

Represent TCP Listener service type.

Records

[5]

CertKey

Represents a combination of the certificate, private key, and private key password (if encrypted).

ClientConfiguration

Configurations for the connection-oriented TCP client.

ClientSecureSocket

Secure Socket configuration for TCP Client.

ListenerConfiguration
ListenerSecureSocket

Secure Socket configuration for TCP Listener.

Enums

[1]

Protocol

Represents protocol options.

Errors

[1]

Error

Represents TCP module related errors.