Specification: Ballerina TCP Library

Owners: @shafreenAnfar @bhashinee
Reviewers: @shafreenAnfar
Created: 2021/12/20
Updated: 2022/02/18
Edition: Swan Lake

Introduction

This is the specification for the TCP standard library of Ballerina language, which provides TCP client-server functionalities.

The TCP library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

  1. Overview
  2. Listener
  3. Service Types
  4. Client
  5. Securing the TCP Connections
  6. Samples

1. Overview

TCP is a protocol that enables applications to exchange messages over a network. It is designed to ensure the successful delivery of data over the network. This specification elaborates on how Ballerina language provides a tested TCP client and server implementation that is compliant with the RFC 793.

2. Listener

The tcp:Listener is used to listen to the incoming socket request. It can be constructed with a port number and optionally providing other configurations. When initiating the listener it opens up the port and attaches the tcp:Service.

2.1. Configurations

When initializing the listener, following configurations can be provided,

ListenerSecureSocket record contains configurations related to enabling SSL/TLS on the listener side. More details and examples of how to configure them can be found in a following section on Securing the TCP Connections.

2.2. Initialization

The TCP listener can be initialized by providing the port and optionally a ListenerConfiguration.

3. Service Types

3.1. Service

This service has a single onConnect remote function which 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.

3.2. Connection Service

Once the TCP connection is established, it returns a tcp:ConnectionService. This service has a fixed set of remote functions that do not have any configs. Receiving messages will get dispatched to the relevant remote function. Each remote function is explained below.

3.2.1. Remote methods associated with the Connection Service

onBytes

This remote method is invoked once the data is received from the client.

onError

This remote method is invoked in an error situation.

onClose

This remote method is invoked when the connection gets closed.

4. Client

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

4.1. Configurations

When initializing the client, following configurations can be provided,

4.2. Initialization

A client can be initialized by providing the remoteHost and the remotePort and optionally the ClientConfiguration.

4.3. Send and receive data

writeBytes

writeBytes API can be used to send data to the remote host.

readBytes

readBytes API can be used to read data receiving from the remote host.

close

close API can be used to close the connection established with the remote host.

5. Securing the TCP Connections

Ballerina provides inbuilt support for securing TCP connections with SSL/TLS protocol.

5.1 Using the TLS protocol

This expects a secure socket to be set in the connection configuration as shown below.

5.1.1 Configuring TLS in server side

5.1.2 Configuring TLS in client side

6. Samples

Listener

Client