socket

TCP socket manipulation

optionally supports SSL/TLS (if the OpenSSL library is available)

Import

_ <- fat.socket

Structures

ClientSocket

Represents a client connection, i.e., a socket connected to a remote server.

Properties

since v4.7.0, connection replaces the internal ClientSocket.ssl field; treat it as opaque and use the socket methods to manage the connection

Methods

receive(nBytes) will block until it obtains some data or until the connection is closed

ServerSocket

Represents a socket in server mode, which waits for client connections.

Properties

Methods

Standalone methods

Usage notes

Client mode

Establishing a connection

Use the connect(addr, port, useSSL) function to create a ClientSocket. For example:

_      <- fat.type._
socket <- fat.socket

con = socket.connect("example.org", 80)
con.send("GET / HTTP/1.1\r\nHost: example.org\r\n\r\n".toChunk)
response = con.receive(1024)
...
con.close

Certificate verification

• To enable SSL/TLS, pass true to the useSSL parameter in connect.
• By default, certificate verification is active when using SSL. If you use self-signed certificates on your test server, you can call verifySSL(false) to disable verification:

socket.verifySSL(false)
con = socket.connect("localhost", 443, true)
...

Reading and writing

send waits until all supplied bytes have been accepted for transmission or an error occurs; it can block when the connection cannot accept more data. receive(nBytes) waits for data and returns up to nBytes bytes, or an empty Chunk at end of stream. This includes a TLS peer that disconnects without sending close_notify.

Since v4.7.0, writing to a peer that has hung up raises a handleable error instead of terminating Fry with SIGPIPE.

Sharing and closing a connection

Workers may read, write, and close the same connection concurrently. Reads are serialized with other reads, and complete sends with other sends; a pending read does not prevent another worker from sending.

close releases blocked readers with an empty chunk and waits for active operations to finish before releasing the connection. For TLS, it attempts to send close_notify before closing. Closing through any holder also closes the connection for every other holder, including copies of the socket object. Later send, receive, or close calls raise an error containing socket is closed; copying the object does not create a new connection.

Server mode

Listening on a port

To start a socket in server mode, use bind(port), obtaining a ServerSocket object:

socket <- fat.socket

server = socket.bind(1234)
...

Accepting connections

• Call server.accept(wait) to accept client connections. If no connection appears within wait milliseconds, it returns null.
• Upon obtaining a ClientSocket from accept, you can interact with the client using receive, send, and close.

~ con = server.accept(5000)  # waits up to 5 seconds
con != null ? {
  msg = con.receive(256)
  ...
  con.send(Chunk("Hello, client!"))
  con.close
}

use wait of -1 for blocking until a new connection starts, use wait of 0 for non-blocking

Several workers may call accept on the same server socket. Each call keeps its own wait limit even if another worker accepts the available connection first. This limit covers waiting for a TCP connection; when TLS is enabled, the handshake below adds its own bounded wait.

SSL on the server

Before calling bind, use setSSL("cert.pem", "key.pem") to load a certificate and private key and enable SSL/TLS:

socket.setSSL("cert.pem", "key.pem")
server = socket.bind(443)

Since v4.7.0, an accepted connection must complete its TLS handshake within five seconds. The deadline is not extended by a peer sending bytes slowly. A failed or timed-out handshake closes that connection and makes accept return null.

Closing the server

Call server.close to stop accepting new connections. It releases workers already waiting in accept, which return null. Later accept or close calls through any holder of that server socket raise socket is closed. Client connections already returned by accept remain open and must be closed separately.

See also

• Async library
• HTTP library