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.
Exports
Section titled “Exports”struct Connection
Section titled “struct Connection”struct Connection handle: http_host.Conn end
An open network connection: TCP, or TLS over TCP.
Connection.reader
Section titled “Connection.reader”fn reader(conn: Connection) -> Reader
type function on Connection
What the peer sends, as a stream. The same reader each call.
Connection.writer
Section titled “Connection.writer”fn writer(conn: Connection) -> Writer
type function on Connection
What goes to the peer: each write is sent as it is made.
Connection.close
Section titled “Connection.close”fn close(conn: Connection) -> Unit
type function on Connection
Closes both directions. A read or write after it fails.
Connection.close_write
Section titled “Connection.close_write”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.
Connection.local_address
Section titled “Connection.local_address”fn local_address(conn: Connection) -> String
type function on Connection
This side’s address, host:port.
Connection.remote_address
Section titled “Connection.remote_address”fn remote_address(conn: Connection) -> String
type function on Connection
The peer’s address, host:port.
Connection.set_deadline
Section titled “Connection.set_deadline”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.
Connection.set_read_deadline
Section titled “Connection.set_read_deadline”fn set_read_deadline(conn: Connection, at: Maybe<Instant>) -> Unit
type function on Connection
Connection.set_write_deadline
Section titled “Connection.set_write_deadline”fn set_write_deadline(conn: Connection, at: Maybe<Instant>) -> Unit
type function on Connection
Connection.close_read
Section titled “Connection.close_read”fn close_read(conn: Connection) -> Unit
type function on Connection
Closes the receiving direction of a TCP connection.
Connection.set_no_delay
Section titled “Connection.set_no_delay”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).
Connection.set_linger
Section titled “Connection.set_linger”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.
Connection.set_keep_alive
Section titled “Connection.set_keep_alive”fn set_keep_alive(conn: Connection, keep_alive: KeepAlive) -> Unit
type function on Connection
The connection’s keep-alive probes.
Connection.is_multipath
Section titled “Connection.is_multipath”fn is_multipath(conn: Connection) -> Bool
type function on Connection
Whether the connection runs Multipath TCP.
Connection.of_handle
Section titled “Connection.of_handle”fn of_handle(handle: http_host.Conn) -> Connection
type function on Connection
For std::tls: the connection a handle holds.
Connection.handle_of
Section titled “Connection.handle_of”fn handle_of(conn: Connection) -> http_host.Conn
type function on Connection
For std::tls: the handle a connection holds.
Connection.inspect
Section titled “Connection.inspect”impl Debug for Connection
fn inspect(value: Connection) -> String
impl Debug.inspect
struct KeepAlive
Section titled “struct KeepAlive”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.
KeepAlive.inspect
Section titled “KeepAlive.inspect”impl Debug for KeepAlive
fn inspect(value: KeepAlive) -> String
impl Debug.inspect
struct DialOptions
Section titled “struct DialOptions”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.
DialOptions.inspect
Section titled “DialOptions.inspect”impl Debug for DialOptions
fn inspect(value: DialOptions) -> String
impl Debug.inspect
struct ListenOptions
Section titled “struct ListenOptions”struct ListenOptions keep_alive: KeepAlive = KeepAlive{} multipath: Bool = False end
How listen binds.
ListenOptions.inspect
Section titled “ListenOptions.inspect”impl Debug for ListenOptions
fn inspect(value: ListenOptions) -> String
impl Debug.inspect
enum Error
Section titled “enum Error”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
-
RefusedNothing listens at
address. -
ResetThe peer closed the connection under a read or write.
-
TimeoutA deadline passed: the context’s, an option’s or the connection’s.
-
ClosedThe listener or connection is closed, or the task waiting was stopped.
-
InvalidAddressAn address that does not parse.
-
DnsA name the resolver could not resolve.
-
OtherAny other failure of
op(dial,listen,lookup) onaddress.
Error.from_parts
Section titled “Error.from_parts”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.
Error.of_tls
Section titled “Error.of_tls”fn of_tls(error: tls.Error) -> Error
type function on Error
A TLS failure as a net error.
Error.is_timeout
Section titled “Error.is_timeout”fn is_timeout(error: Error) -> Bool
type function on Error
Whether the error is a timeout, as Go’s Timeout() returns.
Error.to_string
Section titled “Error.to_string”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"
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal
net.dial
Section titled “net.dial”fn dial(address: String, options: DialOptions = DialOptions{}) -> Result<Connection, Error>
A TCP connection to address, host:port.
net.nanos
Section titled “net.nanos”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.
net.pipe
Section titled “net.pipe”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"
net.split_host_port
Section titled “net.split_host_port”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"))
net.join_host_port
Section titled “net.join_host_port”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
Section titled “struct Mx”struct Mx host: String preference: Int end
A mail exchanger a domain names.
Mx.inspect
Section titled “Mx.inspect”impl Debug for Mx
fn inspect(value: Mx) -> String
impl Debug.inspect
struct Srv
Section titled “struct Srv”struct Srv target: String port: Int priority: Int weight: Int end
A service location a domain names.
Srv.inspect
Section titled “Srv.inspect”impl Debug for Srv
fn inspect(value: Srv) -> String
impl Debug.inspect
net.lookup_host
Section titled “net.lookup_host”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.
net.lookup_ip
Section titled “net.lookup_ip”fn lookup_ip(host: String) -> Result<List<String>, Error>
The IP addresses of host.
net.lookup_address
Section titled “net.lookup_address”fn lookup_address(ip: String) -> Result<List<String>, Error>
The names that map to the address ip.
net.lookup_cname
Section titled “net.lookup_cname”fn lookup_cname(host: String) -> Result<String, Error>
The canonical name of host.
net.lookup_ns
Section titled “net.lookup_ns”fn lookup_ns(domain: String) -> Result<List<String>, Error>
The name servers of domain.
net.lookup_txt
Section titled “net.lookup_txt”fn lookup_txt(domain: String) -> Result<List<String>, Error>
The TXT records of domain.
net.lookup_mx
Section titled “net.lookup_mx”fn lookup_mx(domain: String) -> Result<List<Mx>, Error>
The mail exchangers of domain, most preferred first.
net.lookup_port
Section titled “net.lookup_port”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.
net.lookup_srv
Section titled “net.lookup_srv”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
Section titled “struct Listener”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.
Listener.address
Section titled “Listener.address”fn address(listener: Listener) -> String
type function on Listener
The address it is bound to, with the port it picked for port 0.
Listener.accept
Section titled “Listener.accept”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.
Listener.set_deadline
Section titled “Listener.set_deadline”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.
Listener.close
Section titled “Listener.close”fn close(listener: Listener) -> Unit
type function on Listener
Stops listening. A connection already accepted stays open.
Listener.of_handle
Section titled “Listener.of_handle”fn of_handle(handle: http_host.TcpListener) -> Listener
type function on Listener
For std::tls: the listener a handle holds.
Listener.handle_of
Section titled “Listener.handle_of”fn handle_of(listener: Listener) -> http_host.TcpListener
type function on Listener
For std::tls: the handle a listener holds.
Listener.inspect
Section titled “Listener.inspect”impl Debug for Listener
fn inspect(value: Listener) -> String
impl Debug.inspect
net.listen
Section titled “net.listen”fn listen(address: String, options: ListenOptions = ListenOptions{}) -> Result<Listener, Error>
Binds address, host:port; port 0 picks a free one.
net.serve
Section titled “net.serve”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.