std/net

Types

Net

@unsafeGuarantee(Copy, Send, Sync)
pub type Net

Network access, obtained from host.net(). Safety: a stateless capability marker; every call it makes is independent, so sharing or duplicating it is free.

Net.http

pub fn Net.http(self) -> Http

HTTP client with a 10 second timeout per request.

Net.connect

pub fn Net.connect(self, host: String, port: Int) -> Conn!

Connects to host:port over IPv4, refusing a port outside 0..65535; no timeout (unlike Http.post, this call blocks until the OS gives up or a peer answers).

Net.listen

pub fn Net.listen(self, host: String, port: Int) -> Listener!

Binds host:port (SO_REUSEADDR set) and starts listening; a modest, fixed backlog, matching the rest of std/net's lack of tuning knobs. family is forced to AF_INET (2) so SockAddrIn's fixed layout matches what the kernel later hands back from getsockname.

Http

@unsafeGuarantee(Copy, Send, Sync)
pub type Http

HTTP client, obtained from Net.http(). Safety: holds no per-client state; each request is independent, so sharing or duplicating the handle is free.

Http.post

pub fn Http.post(self, url: String, body: String) -> Response!

Sends body in a POST request to url over plain HTTP/1.1 (https is refused); a [v6]:port IPv6 literal is accepted, but a user:pass@ authority and any control character or space in the host or path are rejected, since either could inject extra headers or a second request. The 10 second timeout bounds each connect, send and receive, not the whole request; the status line is read as bytes, so a non-UTF-8 reason phrase is not an Err.

Response

pub type Response = {
    pub status Int
}

Result of an HTTP request.

Failure

pub type Failure = {
    pub text String
}

Error from an HTTP request.

Failure.message

pub fn Failure.message(self) -> String

The failure text.

Conn

pub type Conn = resource {
    // private fields omitted
}

TCP connection; read/write match std/io's Reader/Writer shape.

Conn.read

pub fn Conn.read(mut self, into: &mut Array[u8], max: usize) -> usize!

Reads up to max bytes into into; 0 with no error is end of input, matching std/io's Reader (POSIX read semantics).

Conn.write

pub fn Conn.write(mut self, data: Bytes) -> usize!

Writes data; may send fewer bytes than given, matching send(2) and std/io's Writer (writeAll loops for the rest).

Conn.pollRead

pub fn Conn.pollRead(mut self, into: &mut Array[u8], max: usize) -> usize?!

Reads like read without blocking, or None when no input is ready yet; Some(0) is end of input. The connection stays non-blocking.

Conn.pollWrite

pub fn Conn.pollWrite(mut self, data: Bytes) -> usize?!

Writes like write without blocking, or None when the send buffer is full. The connection stays non-blocking.

Conn.close

pub fn Conn.close(move self) -> Void!

Nothing to flush for a socket; the drop closes it, as File.close's does.

Conn.drop

pub fn Conn.drop(move self)

Closes the connection when it goes out of scope, ignoring errors.

Bodiless unlike File.drop: the VM runs a resource's real lowered body on an implicit drop even when an accelerator exists for it, so a body here would hit the unsupported extern(C) close on the first Conn ever dropped without an explicit close().

Listener

pub type Listener = resource {
    // private fields omitted
}

TCP listening socket, from Net.listen.

Listener.accept

pub fn Listener.accept(mut self) -> Conn!

Accepts the next incoming connection, blocking until one arrives.

Listener.port

pub fn Listener.port(self) -> Int

The local port bound, or 0 when it cannot be read; lets a caller bind port 0 and learn which port the OS picked.

Listener.pollAccept

pub fn Listener.pollAccept(mut self) -> Conn?!

Accepts a waiting connection without blocking, or None when none is waiting; the listener and the accepted connection stay non-blocking.

Listener.drop

pub fn Listener.drop(move self)

Closes the listening socket when it goes out of scope, ignoring errors; see Conn.drop for why this is bodiless.