Sockets
In addition to HTTP/WebSocket handling for the server and client, Ktor supports TCP and UDP raw sockets. It exposes a suspending API that uses java.nio under the hood.
Add dependencies
To use Sockets
, you need to include the ktor-network
artifact in the build script:
To use secure sockets in the client, you also need to add io.ktor:ktor-network-tls
.
Server
Create a server socket
To build a server socket, create the SelectorManager
instance, call the SocketBuilder.tcp()
function on it, and then use bind
to bind a server socket to specific port:
The snippet above creates a TCP socket, which is the ServerSocket instance. To create a UDP socket, use SocketBuilder.udp()
.
Accept incoming connections
After creating a server socket, you need to call the ServerSocket.accept
function that accepts a socket connection and returns a connected socket (a Socket instance):
Once you have a connected socket, you can receive/send data by reading from or writing to the socket.
Receive data
To receive data from the client, you need to call the Socket.openReadChannel
function, which returns ByteReadChannel:
ByteReadChannel
provides API for asynchronous reading of data. For example, you can read a line of UTF-8 characters using ByteReadChannel.readUTF8Line
:
Send data
To send data to the client, call the Socket.openWriteChannel
function, which returns ByteWriteChannel:
ByteWriteChannel
provides API for asynchronous writing of sequences of bytes. For example, you can write a line of UTF-8 characters using ByteWriteChannel.writeStringUtf8
:
Close a socket
To release resources associated with the connected socket, call Socket.close
:
Example
A code sample below demonstrates how to use sockets on the server side:
You can find the full example here: sockets-server.
Client
Create a socket
To build a client socket, create the SelectorManager
instance, call the SocketBuilder.tcp()
function on it, and then use connect
to establish a connection and get a connected socket (a Socket instance):
Once you have a connected socket, you can receive/send data by reading from or writing to the socket.
Create a secure socket (SSL/TLS)
Secure sockets allow you to establish TLS connections. To use secure sockets, you need to add the ktor-network-tls dependency. Then, call the Socket.tls
function on a connected socket:
The tls
function allows you to adjust TLS parameters provided by TLSConfigBuilder:
You can find the full example here: sockets-client-tls.
Receive data
To receive data from the server, you need to call the Socket.openReadChannel
function, which returns ByteReadChannel:
ByteReadChannel
provides API for asynchronous reading of data. For example, you can read a line of UTF-8 characters using ByteReadChannel.readUTF8Line
:
Send data
To send data to the server, call the Socket.openWriteChannel
function, which returns ByteWriteChannel:
ByteWriteChannel
provides API for asynchronous writing of sequences of bytes. For example, you can write a line of UTF-8 characters using ByteWriteChannel.writeStringUtf8
:
Close connection
To release resources associated with the connected socket, call Socket.close
and SelectorManager.close
:
Example
A code sample below demonstrates how to use sockets on the client side:
You can find the full example here: sockets-client.