Specification: Ballerina TCP Library
Owners: @shafreenAnfar @bhashinee
Edition: Swan Lake
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.
- Service Types
- Securing the TCP Connections
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.
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
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.
The TCP listener can be initialized by providing the
port and optionally a
This service has a single
onConnect remote function which gets invoked when a new client is connected. The new client is represented using the
onConnect(tcp:Caller) method may return
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.
This remote method is invoked once the data is received from the client.
This remote method is invoked in an error situation.
This remote method is invoked when the connection gets closed.
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.
When initializing the client, following configurations can be provided,
A client can be initialized by providing the
remoteHost and the
remotePort and optionally the
writeBytes API can be used to send data to the remote host.
readBytes API can be used to read data receiving from the remote host.
close API can be used to close the connection established with the remote host.
Ballerina provides inbuilt support for securing TCP connections with SSL/TLS protocol.
This expects a secure socket to be set in the connection configuration as shown below.