Skip to content

std::net

TCP connections. net.dial opens a connection, and net.listen with net.serve handles the connections that arrive, each as a task of a supervisor, as http.serve handles requests. A connection is read and written through std::io’s streams:

conn = net.dial("example.com:7")?

_ = Writer.write_text(Connection.writer(conn), "ping\n")

reply = Reader.read_line(Connection.reader(conn))

Connection.close(conn)

Dialing runs under the context in force, and a connection’s reads and writes stop when the task that opened it is cancelled. std::tls runs TLS over the same Connection.

Import with import std::net.

struct Connection
    handle: http_host.Conn
end

An open network connection: TCP, or TLS over TCP.

fn reader(conn: Connection) -> Reader

type function on Connection

What the peer sends, as a stream. The same reader each call.

fn writer(conn: Connection) -> Writer

type function on Connection

What goes to the peer: each write is sent as it is made.

fn close(conn: Connection) -> Unit

type function on Connection

Closes both directions. A read or write after it fails.

fn close_write(conn: Connection) -> Unit

type function on Connection

Closes the sending direction, so the peer reads the end of its input, while this side can still read.

fn local_address(conn: Connection) -> String

type function on Connection

This side’s address, host:port.

fn remote_address(conn: Connection) -> String

type function on Connection

The peer’s address, host:port.

fn set_deadline(conn: Connection, at: Maybe<Instant>) -> Unit

type function on Connection

Reads and writes past at fail with a timeout; None clears it.

fn set_read_deadline(conn: Connection, at: Maybe<Instant>) -> Unit

type function on Connection

fn set_write_deadline(conn: Connection, at: Maybe<Instant>) -> Unit

type function on Connection

fn close_read(conn: Connection) -> Unit

type function on Connection

Closes the receiving direction of a TCP connection.

fn set_no_delay(conn: Connection, on: Bool) -> Unit

type function on Connection

Whether small writes go out at once (True, Go’s default) or wait to be combined (Nagle’s algorithm).

fn set_linger(conn: Connection, wait: Maybe<Duration>) -> Unit

type function on Connection

How long close waits to send what is unsent: None is the system’s default, zero discards it.

fn set_keep_alive(conn: Connection, keep_alive: KeepAlive) -> Unit

type function on Connection

The connection’s keep-alive probes.

fn is_multipath(conn: Connection) -> Bool

type function on Connection

Whether the connection runs Multipath TCP.

fn of_handle(handle: http_host.Conn) -> Connection

type function on Connection

For std::tls: the connection a handle holds.

fn handle_of(conn: Connection) -> http_host.Conn

type function on Connection

For std::tls: the handle a connection holds.

impl Debug for Connection

fn inspect(value: Connection) -> String

impl Debug.inspect

struct KeepAlive
    enabled: Bool = True
    idle: Maybe<Duration> = None
    interval: Maybe<Duration> = None
    count: Maybe<Int> = None
end

TCP keep-alive probes on a connection.

impl Debug for KeepAlive

fn inspect(value: KeepAlive) -> String

impl Debug.inspect

struct DialOptions
    timeout: Maybe<Duration> = None
    keep_alive: KeepAlive = KeepAlive{}
    local_address: Maybe<String> = None
    fallback_delay: Maybe<Duration> = None
    multipath: Bool = False
end

How dial connects. A timeout past about 292 years, the longest wait the clock counts, never fires.

impl Debug for DialOptions

fn inspect(value: DialOptions) -> String

impl Debug.inspect

struct ListenOptions
    keep_alive: KeepAlive = KeepAlive{}
    multipath: Bool = False
end

How listen binds.

impl Debug for ListenOptions

fn inspect(value: ListenOptions) -> String

impl Debug.inspect

enum Error
    Refused { address: String }
    Unreachable { address: String }
    Reset { address: String }
    AddressInUse { address: String }
    Timeout { address: String }
    Closed
    InvalidAddress { address: String, reason: String }
    Dns { host: String, reason: String, server: Maybe<String>, not_found: Bool }
    Other { op: String, address: String, reason: String }
    Tls { error: tls.Error }
end

Why a connection could not be made or used.

Variants

  • Refused

    Nothing listens at address.

  • Reset

    The peer closed the connection under a read or write.

  • Timeout

    A deadline passed: the context’s, an option’s or the connection’s.

  • Closed

    The listener or connection is closed, or the task waiting was stopped.

  • InvalidAddress

    An address that does not parse.

  • Dns

    A name the resolver could not resolve.

  • Other

    Any other failure of op (dial, listen, lookup) on address.

fn from_parts(parts: List<String>) -> Error

type function on Error

The error for the parts a crossing returns: a net variant, or a tls.Error’s.

fn of_tls(error: tls.Error) -> Error

type function on Error

A TLS failure as a net error.

fn is_timeout(error: Error) -> Bool

type function on Error

Whether the error is a timeout, as Go’s Timeout() returns.

impl Display for Error

fn to_string(error: Error) -> String

impl Display.to_string

assert "${Error.Refused{address: "a:1"}}" == "connection refused by a:1"

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal

fn dial(address: String, options: DialOptions = DialOptions{}) -> Result<Connection, Error>

A TCP connection to address, host:port.

fn nanos(d: Maybe<Duration>) -> Int

For std::tls: a timeout in nanoseconds, 0 for None, held to the longest wait the clock counts, about 292 years either way: a longer timeout waits that long, so it never fires.

fn pipe() -> (Connection, Connection)

Two connections joined in memory, each end’s writes the other’s reads, with no buffer: Go’s net.Pipe. For tests of code that talks over a connection.

(a, b) = net.pipe()
_ = Connection.close(a)
assert Connection.remote_address(b) == "pipe"
fn split_host_port(address: String) -> Result<(String, String), Error>

Splits host:port (or [host]:port) into its host and port: Go’s SplitHostPort.

assert net.split_host_port("[::1]:80") == Ok(("::1", "80"))
fn join_host_port(host: String, port: String) -> String

Joins a host and port into an address, bracketing an IPv6 host: Go’s JoinHostPort.

assert net.join_host_port("::1", "80") == "[::1]:80"
struct Mx
    host: String
    preference: Int
end

A mail exchanger a domain names.

impl Debug for Mx

fn inspect(value: Mx) -> String

impl Debug.inspect

struct Srv
    target: String
    port: Int
    priority: Int
    weight: Int
end

A service location a domain names.

impl Debug for Srv

fn inspect(value: Srv) -> String

impl Debug.inspect

fn lookup_host(host: String) -> Result<List<String>, Error>

The addresses of host, as the system resolver returns.

assert net.lookup_host("localhost")
|> Result.map(fn xs -> Iter.any_match(xs, fn a -> a == "127.0.0.1" or a == "::1")) == Ok(True)

Not run here: this example opens network connections, which a browser cannot do. nomi test runs it.

fn lookup_ip(host: String) -> Result<List<String>, Error>

The IP addresses of host.

fn lookup_address(ip: String) -> Result<List<String>, Error>

The names that map to the address ip.

fn lookup_cname(host: String) -> Result<String, Error>

The canonical name of host.

fn lookup_ns(domain: String) -> Result<List<String>, Error>

The name servers of domain.

fn lookup_txt(domain: String) -> Result<List<String>, Error>

The TXT records of domain.

fn lookup_mx(domain: String) -> Result<List<Mx>, Error>

The mail exchangers of domain, most preferred first.

fn lookup_port(service: String) -> Result<Int, Error>

The port number of a TCP service name, such as "http".

assert net.lookup_port("http") == Ok(80)

Not run here: this example opens network connections, which a browser cannot do. nomi test runs it.

fn lookup_srv(service: String, protocol: String, domain: String) -> Result<(String, List<Srv>), Error>

The SRV records for _service._protocol.domain, with the canonical name they were found under.

struct Listener
    handle: http_host.TcpListener
end

A listening socket. Close it with Listener.close; a program that is shutting down closes every listener when its supervisors start draining.

fn address(listener: Listener) -> String

type function on Listener

The address it is bound to, with the port it picked for port 0.

fn accept(listener: Listener) -> Result<Connection, Error>

type function on Listener

The next connection. Error.Closed once the listener is closed or the calling task is stopped.

fn set_deadline(listener: Listener, at: Maybe<Instant>) -> Unit

type function on Listener

An accept still waiting at at fails with Error.Timeout; None clears it.

fn close(listener: Listener) -> Unit

type function on Listener

Stops listening. A connection already accepted stays open.

fn of_handle(handle: http_host.TcpListener) -> Listener

type function on Listener

For std::tls: the listener a handle holds.

fn handle_of(listener: Listener) -> http_host.TcpListener

type function on Listener

For std::tls: the handle a listener holds.

impl Debug for Listener

fn inspect(value: Listener) -> String

impl Debug.inspect

fn listen(address: String, options: ListenOptions = ListenOptions{}) -> Result<Listener, Error>

Binds address, host:port; port 0 picks a free one.

fn serve(listener: Listener, handler: (Connection) -> Unit, supervisor: Supervisor) -> Unit

Handles each connection listener accepts with handler, each as a task of supervisor, and closes the connection when the handler returns. Returns when the listener is closed or the calling task is stopped, as at shutdown, after closing the listener.