Net

TCP listeners and connections.

withListener, accept, and withClient open a socket for the length of a callback and close it on every exit; source and sink adapt a connection to Reader and Writer. Libraries that manage a connection’s lifetime themselves, as the HTTP client does, use the unscoped operations and pools. Reads on one connection serialize, as do whole writes, so tasks may share it; closing interrupts a blocked read or write and makes later operations fail.

Every call performs Network. runSystem is its default and reaches the OS; a custom handler can answer the same operations without sockets, using withProvider to create listeners, connections, and pools of its own. Sockets belong to the runner that opened them, which rejects those of any other runner and closes its remaining sockets when it exits.

Accepts, reads, and writes take a Cancel. The Async variants pass the task’s lifetime: when the task is cancelled during the call, the system runner closes the listener or connection to interrupt it, and the variant then stops the task as cancelled rather than raising a network error. Other calls pass uncancellable; cancelling their task does not close anything.

Cancel

type CancelSource

Whether a blocking operation may be interrupted, and by which task lifetime. A value obtained in one task keeps naming that task’s lifetime; once that lifetime has ended it reads as cancelled.

Connection

type ConnectionSource

A connected socket. It cannot be forged, inspected, or compared.

Endpoint

type Endpoint =    { host : String    , port : Int    , timeoutMs : Int    , security : Security    }Source

Where and how to connect.

Fields

host

host : StringSource

The host name or address.

port

port : IntSource

The TCP port.

timeoutMs

timeoutMs : IntSource

The connection limit in milliseconds; 0 leaves it to the system.

security

security : SecuritySource

Plain TCP or TLS.

Instances:

Eq Endpoint
Show Endpoint

Error

type Error =    { kind : Kind    , address : String    , message : String    }Source

A structured network failure.

Fields

kind

kind : KindSource

What went wrong.

address

address : StringSource

The endpoint of the failed operation, when one is known.

message

message : StringSource

The system’s description.

Instances:

Eq Error
Show Error

Kind

type Kind    = ConnectionRefused    | ConnectionReset    | AddressInUse    | TimedOut    | OtherSource

The kinds of network failure a program can act on portably.

Constructors

ConnectionRefused

ConnectionRefused : KindSource

Nothing accepted the connection at the address.

ConnectionReset

ConnectionReset : KindSource

The peer reset the connection.

AddressInUse

AddressInUse : KindSource

The port is already bound.

Other

Other : KindSource

Any other failure, including use of a closed, foreign, or retired resource.

TimedOut

TimedOut : KindSource

An operation exceeded its time limit or deadline.

Instances:

Eq Kind
Show Kind

Listener

type ListenerSource

A listening socket. It cannot be forged, inspected, or compared.

Pool

type PoolSource

Idle client connections kept per endpoint, shared safely between tasks. Connections leased from a pool belong to the pool’s runner.

Provider

type ProviderSource

The identity of one handler’s listeners, connections, and pools. A custom handler gets a fresh one from withProvider; comparing a resource’s provider tells its own resources apart from those of other runners.

Security

type Security    = Plain    | Tls (Maybe String)Source

How a connection is secured.

Constructors

Plain

Plain : SecuritySource

Plain TCP.

Tls

Tls : Maybe String -> SecuritySource

TLS, verifying the server certificate for the host against the system roots plus those in the PEM file, when one is given. The host is also sent for SNI. The connection then carries plaintext like any other.

Instances:

Eq Security
Show Security

Network

effect NetworkSource

Listeners, connections, and pools. Every operation is public so custom handlers can interpret the complete boundary.

Operations

listen

listen : Int ->{Network} Result Error ListenerSource

Listens on the port at every address; port 0 picks a free one.

stopListener

stopListener : Listener ->{Network} Result Error ()Source

Closes the listener, interrupting a blocked accept. Stopping it again does nothing.

listenerStopped

listenerStopped : Listener ->{Network} BoolSource

Whether the listener is closed, or is not usable by this runner.

acceptConnection

acceptConnection : Listener -> Cancel ->{Network} Result Error ConnectionSource

Waits for one client. Cancellation closes the listener.

connect

connect : Endpoint ->{Network} Result Error ConnectionSource

Connects to the endpoint.

closeConnection

closeConnection : Connection ->{Network} Result Error ()Source

Closes the connection, interrupting blocked reads and writes. Closing it again does nothing.

readConnectionBytes

readConnectionBytes : Connection -> Int -> Cancel ->{Network} Result Error BytesSource

Up to count bytes once any arrive, at most 64 KiB, or empty bytes at the end of the stream. Cancellation closes the connection.

writeConnectionBytes

writeConnectionBytes : Connection -> Bytes -> Cancel ->{Network} Result Error ()Source

Writes all the bytes. Cancellation closes the connection.

setReadDeadline

setReadDeadline : Connection -> Int ->{Network} Result Error ()Source

Makes reads fail once millis milliseconds from now have passed; zero or less clears the deadline.

setWriteDeadline

setWriteDeadline : Connection -> Int ->{Network} Result Error ()Source

Makes writes fail once millis milliseconds from now have passed; zero or less clears the deadline.

newPool

newPool : Int -> Int ->{Network} PoolSource

A pool of at most maxIdle idle connections per endpoint, each kept idleMillis milliseconds.

poolConnect

poolConnect : Pool -> Endpoint -> Bool ->{Network} Result Error ConnectionSource

Leases an idle connection to the endpoint, unless fresh, or connects a new one.

poolRelease

poolRelease : Connection -> Bool ->{Network} Result Error ()Source

Ends a lease: a reusable connection returns to its pool, anything else closes. Releasing again does nothing.

connectionReused

connectionReused : Connection ->{Network} BoolSource

Whether a leased connection came from the pool rather than a new connection.

closePool

closePool : Pool ->{Network} Result Error ()Source

Closes the pool’s idle connections; leases still out close on release.

accept

accept : Listener -> (Connection ->{Fail Error, Network, e} a) ->{Fail Error, Network, e} aSource

Waits for one client, runs action with its connection, and closes it on every exit.

acceptAsync

acceptAsync : Listener -> (Connection ->{Fail Error, Async, Network, e} a) ->{Fail Error, Async, Network, e} aSource

accept in a task: cancelling the waiting task closes the listener and stops the task.

connectionFor

connectionFor : Provider -> String -> Int -> ConnectionSource

A connection owned by the provider, labelled with its peer address.

connectionKey

connectionKey : Provider -> Connection -> Result Error IntSource

The backend key of a connection this provider created, checked like listenerKey.

endpoint

endpoint : String -> Int -> EndpointSource

A plain endpoint with no timeout of its own.

import Net

(Net.endpoint "localhost" 80).security == Net.Plain

isCancelled

isCancelled : Cancel -> BoolSource

Whether the operation’s task has been cancelled at this moment. A custom handler may poll it while it would otherwise wait.

listenerFor

listenerFor : Provider -> Int -> ListenerSource

A listener owned by the provider, for the handler’s own backend key. The handler decides which keys are open and must not reuse one within a provider, or a closed resource would become valid again. The same holds for connections and pools.

listenerKey

listenerKey : Provider -> Listener -> Result Error IntSource

The backend key of a listener this provider created. Any other listener, including a system one, answers foreign listener; after the provider exits, closed provider. Both are Other errors.

poolFor

poolFor : Provider -> Int -> PoolSource

A pool owned by the provider.

poolKey

poolKey : Provider -> Pool -> Result Error IntSource

The backend key of a pool this provider created, checked like listenerKey.

runSystem

runSystem : (() ->{Network, e} a) ->{IO, e} aSource

Interprets Network through the OS under a fresh provider. Scoped sockets close before their callbacks leave; remaining listeners, connections, and pools close when the runner exits, ignoring close failures. A task that outlives the runner gets closed provider errors rather than OS access.

sink

sink : Connection -> Sink {Fail Error, Network}Source

The connection as a byte sink that writes each chunk completely. It does not close the connection.

sinkAsync

sinkAsync : Connection ->{Async} Sink {Fail Error, Async, Network}Source

sink in a task: cancelling a task blocked in a write closes the connection and stops the task.

source

source : Connection -> Source {Fail Error, Network}Source

The connection as a byte source, answering at most 8192 bytes per pull once any arrive. It does not close the connection.

sourceAsync

sourceAsync : Connection ->{Async} Source {Fail Error, Async, Network}Source

source in a task: cancelling a task blocked in a read closes the connection and stops the task.

taskCancel

taskCancel : () ->{Async} CancelSource

The current task’s lifetime: cancelling the task interrupts the operation.

uncancellable

uncancellable : CancelSource

An operation that cancellation never interrupts.

withClient

withClient : String -> Int -> (Connection ->{Fail Error, Network, e} a) ->{Fail Error, Network, e} aSource

Connects to host and port over plain TCP, runs action with the connection, and closes it on every exit.

withListener

withListener : Int -> (Listener ->{Fail Error, Network, e} a) ->{Fail Error, Network, e} aSource

Listens on port at every address, runs action with the listener, and closes it on every exit.

withProvider

withProvider : (Provider ->{e} a) ->{e} aSource

Gives a custom handler a fresh provider and retires it on every exit of action. Resources created under it, including any the result carries, then answer closed provider.