Sets the active state every connection starts in. Defaults to Once.

builder
|> tup.active_state(Count(10))

The most bytes one read hands to your handler. Erlang’s default is about 9 KB.

A larger buffer means fewer and bigger Incoming messages which pays off when clients send a lot of data. It costs the memory on every connection so provide careful values.

builder
|> tup.buffer_size(65_536)

How many connections are open right now. Returns Error(Nil) when no server is running under name.

tup.connection_count(name)
// -> Ok(12)

Keeps the connection open and carries state into the next message.

fn handler(_connection, count, message) {
  case message {
    Incoming(_data) -> tup.continue(count + 1)
    User(_message) -> tup.continue(count)
  }
}

Describes a socket error as text.

case tup.send(connection, data) {
  Ok(Nil) -> Nil
  Error(error) -> io.println(describe_socket_error(error))
}

Formats an endpoint as text: the address and port of a TCP endpoint or the path of a Unix one.

tup.endpoint_to_string(TcpEndpoint(Ipv4(127, 0, 0, 1), 3000))
// -> "127.0.0.1:3000"

Listen only on IPv6. IPv4 clients are refused.

Starting fails when the address is an IPv4 or a unix socket path.

Wait for every connection to finish when the server shuts down, however long that takes. A connection that never finishes keeps the shutdown from ever completing, so only use this when every handler is sure to return.

builder
|> tup.infinite_shutdown_timeout

Formats an address as text.

tup.ip_address_to_string(Ipv4(127, 0, 0, 1))
// -> "127.0.0.1"

The endpoint the named server listens on, with the port the system picked when the server was started on port 0. Waits up to timeout milliseconds for the listener to answer.

Returns Error(Nil) when no server runs under name, when it is suspended or when the listener does not answer in time.

let name = process.new_name("tup")
let assert Ok(_started) =
  builder
  |> tup.listening(on: Tcp(interface: "127.0.0.1", port: 0))
  |> tup.named(name)
  |> tup.start

tup.listen_endpoint(name, within: 1000)
// -> Ok(TcpEndpoint(Ipv4(127, 0, 0, 1), 54321))

Sets where the server listens. Defaults to TCP on 127.0.0.1 port 3000.

builder
|> tup.listening(on: Tcp(interface: "0.0.0.0", port: 8080))

The server’s end of a connection.

tup.local(connection)
// -> TcpEndpoint(Ipv4(127, 0, 0, 1), 3000)

Registers the started server under name. listen_endpoint, suspend, resume and connection_count look the server up by it.

let name = process.new_name("tup")

builder
|> tup.named(name)

Creates a builder from the callbacks every connection runs.

on_init runs once the connection is accepted. It receives the connection and a selector and returns the initial state together with the selector user messages are received on.

handler runs for every Message and returns what the connection does next.

on_close runs once the connection has ended.

By default the server listens on 127.0.0.1 port 3000 over plain TCP, starts every connection in the Once active state, runs 20 acceptors and gives connections 15 seconds to finish on shutdown. Each of these can be changed with the builder function.

tup.new(
  on_init: fn(_connection, selector) { #(0, selector) },
  handler: fn(connection, count, message) {
    case message {
      Incoming(data) -> {
        let _ = tup.send(connection, bytes_tree.from_bit_array(data))
        tup.continue(count + 1)
      }
      User(_message) -> tup.continue(count)
    }
  },
  on_close: fn(_count) { Nil },
)

Sets a callback that runs in every open connection when the server shuts down, ahead of on_close and within the shutdown timeout. Nothing runs by default.

builder
|> tup.on_shutdown(fn(connection, _state) {
  let _ = tup.send(connection, bytes_tree.from_string("bye\n"))
  Nil
})

The client’s end of a connection.

tup.peer(connection)
// -> TcpEndpoint(Ipv4(192, 168, 1, 20), 51234)

How many acceptors wait for connections at once. Defaults to 20. Must be greater than zero.

builder
|> tup.pool_size(100)

Open the listen socket again and start accepting connections after suspend. With port 0 the system picks a new port.

Returns Error(Nil) when no server is running under name or when the socket can’t be opened again, for example because another program took the port while the server was suspended.

tup.resume(name)
// -> Ok(Nil)

Sends data to the client. Returns the socket error when the write fails.

tup.send(connection, bytes_tree.from_string("hello\n"))
// -> Ok(Nil)

Sets how session tickets are issued. Defaults to Stateless.

tls(certificate)
|> tup.session_tickets(NoTickets)

How long each connection gets to finish when the server shuts down before it is killed. A connection still running at the deadline is killed without on_shutdown or on_close completing. Defaults to 15 seconds. Must not be negative.

builder
|> tup.shutdown_timeout(5000)

The transport and the socket behind a connection.

let #(transport, socket) = tup.socket(connection)
socket.send(transport, socket, data)

Starts the server linked to the calling process.

Fails with actor.InitFailed when a setting is out of range, a certificate, key or trust store cannot be read or holds nothing, an ALPN protocol is malformed, or name is already registered. A listen socket that cannot be opened comes back as an Error as well, instead of crashing the caller.

let assert Ok(_started) = tup.start(builder)
process.sleep_forever()

Closes the connection.

case message {
  Incoming(<<"quit\n">>) -> tup.stop()
  _message -> tup.continue(state)
}

Closes the connection and exits abnormally with reason.

tup.stop_abnormal("client sent an invalid frame")

A child specification that runs the server under a supervisor.

static_supervisor.new(static_supervisor.OneForOne)
|> static_supervisor.add(tup.supervised(builder))
|> static_supervisor.start

Stop accepting connections and close the listen socket. Connections that are already open keep running.

While suspended the new clients are refused and listen_endpoint returns Error(Nil).

Returns Error(Nil) when no server is running under the name.

let assert Ok(Nil) = tup.suspend(name)

tup.listen_endpoint(name, within: 1000)
// -> Error(Nil)

Creates TLS settings around certificate. By default the clients are not asked for a certificate, no ALPN protocols are offered and session tickets are stateless. Every TLS server speaks TLS 1.2 and 1.3, applies its own cipher order and refuses client renegotiation.

tup.tls(tup.Disk(cert: "priv/cert.pem", key: "priv/key.pem"))

Extracts the IPv4 address inside an IPv4 mapped IPv6 address.

tup.unmap_ipv4(Ipv6(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x0001))
// -> Ipv4(127, 0, 0, 1)

Asks clients for a certificate and verifies it against a trust store.

tup.tls(tup.Disk(cert: "priv/cert.pem", key: "priv/key.pem"))
|> tup.verifying_clients(on: tup.Required(trusting: tup.TrustDisk("priv/ca.pem")))

Sets the socket’s active state from now on. Has no effect on a stop.

tup.continue(state)
|> tup.with_active_state(Count(10))

Sets the ALPN protocols the server offers, most preferred first. Each must be 1 to 255 bytes long. Duplicates are dropped.

tls(certificate)
|> with_alpn(["h2", "http/1.1"])

Sets the selector the connection receives user messages on from now on. Has no effect on a stop.

let selector =
  process.new_selector()
  |> process.select(subject)

tup.continue(state)
|> tup.with_selector(selector)

Wraps every connection in TLS with the given settings.

builder
|> tup.with_tls(tup.tls(tup.Disk(cert: "priv/cert.pem", key: "priv/key.pem")))