Net.Socket
module Net.Socket
Process-owned TCP byte streams and listeners. All blocking operations return typed NetError values; close operations are idempotent.
using Net
using Net.Socket
let listener = TCP.listen(TCP.Endpoint.loopback(Port.from(0).try)).try
let address = listener.localAddress.try
let client = TCP.connect(address).try
client.sendAll("ping".to(Binary).try).try
listener.closemodule Net.Socket.TCP
connect
connect(endpoint: Endpoint) -> Result<TCPConnection, NetError>
connect(endpoint: Endpoint, options: ConnectOptions) -> Result<TCPConnection, NetError>Connects to a TCP endpoint with the backend's bounded connect deadline.
Returns a stream or Connect/Timeout
Examples
Connecting to a line-oriented local service
let endpoint = TCP.Endpoint.host("127.0.0.1", Port.from(9000).try)
let connection = TCP.connect(endpoint).trylisten
listen(endpoint: Endpoint) -> Result<TCPListener, NetError>
listen(endpoint: Endpoint, options: ListenOptions) -> Result<TCPListener, NetError>Binds and starts listening. Port zero selects an ephemeral local port.
Returns a listener or Connect
Examples
Giving each integration test its own free port
let listener = TCP.listen(TCP.Endpoint.loopback(Port.from(0).try)).try
let port = listener.localAddress.try.portsendAll
sendAll(connection: TCPConnection, data: Binary) -> Result<Integer, NetError>Sends every byte, retrying partial operating-system writes internally.
On failure, NetError.progress records how many bytes were accepted before the error. Do not blindly retry the whole payload when progress is present.
Examples
Sending one newline-delimited request
connection.sendAll("status\n".to(Binary).try).tryreceiveChunk
receiveChunk(connection: TCPConnection, limit: Integer, timeout: Duration) -> Result<Binary, NetError>Receives up to limit bytes; EOF is reported as Closed.
A successful result is one available chunk, not necessarily a complete application message. Use receiveExactly, receiveUntil, or receiveLine when the protocol supplies a boundary.
Examples
Reading up to 16 KiB from a streaming response
let chunk = connection.receiveChunk(16 * 1024).tryreceiveExactly
receiveExactly(connection: TCPConnection, count: Integer, timeout: Duration) -> Result<Binary, NetError>Receives exactly count bytes or returns a typed EOF/timeout failure.
Useful after a protocol header has declared the payload length.
Examples
Reading a four-byte frame header
let header = connection.receiveExactly(4).tryreceiveUntil
receiveUntil(connection: TCPConnection, delimiter: Binary, limit: Integer, timeout: Duration) -> Result<Binary, NetError>Receives through the first delimiter without exceeding limit bytes.
The delimiter is included in the returned bytes. An empty delimiter is a Parse error; reaching the bound first is a Limit error.
Examples
Read through the end of an HTTP header section
connection.receiveUntil("\r\n\r\n".to(Binary).try, 65536).tryreceiveLine
receiveLine(connection: TCPConnection, limit: Integer, timeout: Duration) -> Result<Binary, NetError>Receives through a newline without exceeding limit bytes.
The newline remains in the returned binary. Decode and trim only after a complete bounded line has been received.
Examples
Reading a response line with a defensive 8 KiB limit
let line = connection.receiveLine(8192).try.to(String).try.trimshutdownWrite
shutdownWrite(connection: TCPConnection) -> Result<Void, NetError>Half-closes the write side while leaving reads available.
accept
accept(listener: TCPListener, timeout: Duration) -> Result<TCPConnection, NetError>Waits for and returns the next connection accepted by the listener.
A timeout applies to this wait only; it does not become a read timeout on the returned connection.
Examples
Accepting one client in a small test server
let client = listener.accept(5.seconds).trylocalAddress
localAddress(connection: TCPConnection) -> Result<Endpoint, NetError>Returns the bound local endpoint, including an ephemeral assigned port.
peerAddress
peerAddress(connection: TCPConnection) -> Result<Endpoint, NetError>Returns the remote endpoint of a connected stream.
Examples
Recording the peer in an access log
let peer = connection.peerAddress.try
IO.printLine("accepted ${peer.host}:${peer.port.string}")type Plain
Marker for an unencrypted stream.
type TCPConnection
An opaque connected TCP stream.
type TCPListener
An opaque TCP listening socket.
record Endpoint
A host name or numeric address paired with a validated port.
Fields
hostStringportNet.Port
record ConnectOptions
Connection deadlines and operating-system socket policy.
Buffer values of zero leave sizing to the operating system. noDelay? disables Nagle's algorithm, which is usually right for request/response traffic; bulk-transfer protocols may prefer fewer, larger packets.
Fields
record ListenOptions
Listener queue and policy inherited by accepted connections.
backlog bounds connections waiting for accept. Buffer values of zero keep the platform defaults rather than requesting a particular byte size.
Fields
module Net.Socket.TCP.Endpoint
host
host(name: String, port: Net.Port) -> EndpointPairs a hostname or numeric address with a port.
Resolution happens when connecting, so this preserves name exactly as supplied rather than validating it as an IP.Address.
Returns the remote or listening endpoint
Examples
Connecting by hostname
TCP.Endpoint.host("cache.internal", Port.from(6379).try)any
any(port: Net.Port) -> EndpointBuilds an IPv4 wildcard endpoint for listening on every local interface.
Be deliberate with this in development: unlike loopback, it may expose the service to other machines on the network.
Returns an IPv4 wildcard listening endpoint
Examples
Exposing a production service on port 8080
TCP.Endpoint.any(Port.from(8080).try)loopback
loopback(port: Net.Port) -> EndpointBuilds an IPv4 loopback endpoint reachable only from this machine.
Port zero lets the operating system choose a free port, which is useful for tests; ask localAddress which port was assigned after listening.
Returns an IPv4 loopback endpoint
Examples
Starting an isolated test listener
TCP.Endpoint.loopback(Port.from(0).try)module Net.Socket.UDP
bind
bind(endpoint: Endpoint) -> Result<Socket, NetError>
bind(endpoint: Endpoint, options: BindOptions) -> Result<Socket, NetError>Binds a datagram socket. Port zero selects an ephemeral local port.
Examples
A local UDP echo test
let socket = UDP.bind(UDP.Endpoint.loopback(Port.from(0).try)).try
let endpoint = socket.localAddress.trysendTo
sendTo(socket: Socket, endpoint: Endpoint, data: Binary) -> Result<Integer, NetError>Sends one complete datagram and returns its byte count.
Datagram boundaries are preserved: one sendTo corresponds to one receiveFrom, unless the packet is lost by the network.
Examples
Sending a StatsD-style counter
socket.sendTo(collector, "orders:1|c".to(Binary).try).tryreceiveFrom
receiveFrom(socket: Socket, limit: Integer) -> Result<Datagram, NetError>Receives one datagram no larger than limit bytes.
Oversized packets fail with Limit instead of being silently truncated, so a caller never mistakes a prefix for a complete message.
Examples
Receiving and replying to one packet
let packet = socket.receiveFrom(4096).try
socket.sendTo(packet.source, packet.data).trylocalAddress
localAddress(socket: Socket) -> Result<Endpoint, NetError>Returns the bound endpoint, including an ephemeral assigned port.
type Socket
Connectionless datagrams. A receive limit rejects an oversized datagram instead of returning a silently truncated payload.
let socket = UDP.bind(UDP.Endpoint.loopback(Port.from(0).try)).try
let address = socket.localAddress.try
socket.sendTo(address, "hello".to(Binary).try).try
let packet = socket.receiveFrom(1024).try
socket.closeAn opaque bound datagram socket.
record Endpoint
A datagram address paired with a validated port.
Fields
hostStringportNet.Port
record Datagram
A received datagram and its source endpoint.
Reply to source rather than the socket's local address: UDP has no connection that remembers which peer sent the packet.
Fields
sourceEndpointdataBinary
record BindOptions
Curated socket policy. Broadcast is opt-in. The receive timeout applies to each receiveFrom call; multicast TTL is bounded to the IP hop-limit range.
Fields
module Net.Socket.UDP.Endpoint
host
host(name: String, port: Net.Port) -> EndpointPairs a hostname or numeric address with a UDP port.
Returns an endpoint using name exactly as supplied
Examples
Addressing a local metrics collector
UDP.Endpoint.host("metrics.internal", Port.from(8125).try)module Net.Socket.Unix
connect
connect(address: Address) -> Result<UnixConnection, NetError>
connect(address: Address, options: ConnectOptions) -> Result<UnixConnection, NetError>Connects to a filesystem-domain listener.
Unix sockets avoid opening a network port and are a good fit for two processes on the same machine, such as a CLI and its background daemon.
Examples
let daemon = Unix.connect(Unix.Address.path("/tmp/my-app.sock").try).trylisten
listen(address: Address) -> Result<UnixListener, NetError>
listen(address: Address, options: ListenOptions) -> Result<UnixListener, NetError>Binds a new path; an existing filesystem entry is never removed implicitly.
This conservative default protects regular files and also avoids taking over a socket that may still belong to a running service.
sendAll
sendAll(connection: UnixConnection, data: Binary) -> Result<Integer, NetError>Sends every byte and returns the count.
receiveChunk
receiveChunk(connection: UnixConnection, limit: Integer) -> Result<Binary, NetError>Receives one bounded chunk; EOF is Closed.
receiveExactly
receiveExactly(connection: UnixConnection, count: Integer) -> Result<Binary, NetError>Receives exactly count bytes or returns a typed EOF/timeout failure.
receiveUntil
receiveUntil(connection: UnixConnection, delimiter: Binary, limit: Integer) -> Result<Binary, NetError>Receives through delimiter, including it, within an explicit bound.
Examples
Read through the next newline
connection.receiveUntil("\n".to(Binary).try, 4096).tryreceiveLine
receiveLine(connection: UnixConnection, limit: Integer) -> Result<Binary, NetError>Receives through a newline without exceeding limit bytes.
shutdownWrite
shutdownWrite(connection: UnixConnection) -> Result<Void, NetError>Half-closes the write side while leaving reads available.
accept
accept(listener: UnixListener) -> Result<UnixConnection, NetError>Waits for and returns the next stream connection.
type UnixConnection
Filesystem-domain streams for local IPC. The listener owns and removes only the socket path it successfully created.
let address = Unix.Address.path("/tmp/my-service.sock").try
let listener = Unix.listen(address).try
let client = Unix.connect(address).try
listener.closeAn opaque connected filesystem-domain byte stream.
type UnixListener
An opaque filesystem-domain stream listener.
record Address
A validated absolute filesystem socket path.
Fields
pathString
Defined in other modules
record ConnectOptions
Connection and read deadlines for a local IPC client.
Fields
record ListenOptions
Listener queue, stale-socket policy, and per-operation deadlines.
removeStale? removes only a filesystem socket, never a regular file or directory that happens to occupy the requested path.
Fields
module Net.Socket.Unix.Address
path
path(value: String) -> Result<Address, NetError>Validates a nonempty absolute Unix-domain socket path.
Relative paths are rejected so ownership and cleanup always refer to one unambiguous filesystem entry.
Returns the address, or Parse
Examples
Addressing a per-user background service
Unix.Address.path("/tmp/my-app.sock").trymodule Net.Socket.TLS
connect
connect(endpoint: Net.Socket.TCP.Endpoint, config: ClientConfig) -> Result<TLSConnection, NetError>Opens a direct TLS connection with a bounded handshake deadline.
serverName drives both certificate hostname verification and SNI. Pass the DNS name from the URL, not an address it happened to resolve to.
Returns a TLS stream or typed failure
Examples
Opening a verified connection to an HTTPS origin
let endpoint = TCP.Endpoint.host("example.com", Port.from(443).try)
let connection = TLS.connect(endpoint, TLS.ClientConfig {
serverName: "example.com",
alpn: ["http/1.1"]
}).trysendAll
sendAll(connection: TLSConnection, data: Binary) -> Result<Integer, NetError>Sends every plaintext byte through the TLS stream.
receiveChunk
receiveChunk(connection: TLSConnection, limit: Integer) -> Result<Binary, NetError>Receives one decrypted chunk no larger than limit.
closed?
closed?(connection: TLSConnection) -> BoolReturns whether the TLS connection owner has stopped
type TLSConnection
TLS client streams. Certificate and hostname verification are enabled by default; disabling verification must be an explicit configuration choice.
let endpoint = TCP.Endpoint.host("example.test", Port.from(443).try)
let tls = TLS.connect(endpoint, TLS.ClientConfig {
serverName: "example.test"
}).try
tls.closeAn opaque verified or explicitly unverified TLS byte stream.
record ClientConfig
Client handshake policy. TLS 1.2/1.3 are enabled; verification defaults on.