Appearance
std/net
From the spec
This page is spec/std/net.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).
TCP and TLS sockets for programs on the server runtime: clients, listeners and STARTTLS, what a protocol such as SMTP needs (core/crates/weft-check/src/std/net.weft declares it; the server runtime implements it on its I/O threads, server.md). It is an I/O module: a package that imports it has the net capability (docs/packages.md), and sandboxed user code can't import it (sandbox.md). HTTP is std/http's.
weft
import { connect } from "std/net"
let smtp = try await connect({ host: "mail.example.com", port: 587 })
try await smtp.readLine() // 220 mail.example.com ESMTP
try await smtp.write("EHLO app.example.com\r\n")
// … read the replies up to the line starting `250 `
try await smtp.write("STARTTLS\r\n")
try await smtp.readLine() // 220 go ahead
try await smtp.startTls() // the certificate is checked for mail.example.com
try await smtp.write("EHLO app.example.com\r\n") // over TLS from here onConnecting
connect(options): Task<Socket ! NetError>, with ConnectOptions = { host, port, tls?, timeout? }:
tls:trueorTlsOptionsto start with TLS.timeout: ms for connecting and for each handshake, read and write (30,000; 0 for none).
TlsOptions = { serverName?, ca? }. Certificates are always checked, and no option turns that off: against the web's root certificates, or only the PEM certificates in ca (a private CA). serverName is the name sent (SNI) and the name the certificate must be for, by default the host connected to.
Sockets
Socket | |
|---|---|
remote, local | the peer's address and this end's, as host:port |
read(): Task<Bytes? ! NetError> | the next bytes as they arrive, null at the end |
readLine(): Task<string? ! NetError> | the next line without its \n or \r\n (UTF-8, malformed bytes as U+FFFD), null at the end; a last line with no line end is a line. A line past 1 MiB fails with Protocol |
write(data: Bytes | string): Task<void ! NetError> | sends data (text as UTF-8), settling once it is written |
startTls(options?: TlsOptions): Task<void ! NetError> | upgrades the connection to TLS as a client |
secure(): boolean | whether the connection is over TLS |
close(): Task<void> | closes it; a read in flight gives null, and later operations fail with Closed |
A read and a write can overlap. Two reads, or two writes, can't: overlapping them is a bug and panics (await each). read and readLine share one buffer, so they can be mixed.
STARTTLS. startTls fails with Protocol when the peer has sent anything not yet read. Bytes that arrive before the handshake didn't come over TLS, and treating them as if they had is the STARTTLS command injection attack. A handshake that fails closes the connection.
Listening
listen(options): Task<Listener ! NetError>, with ListenOptions = { host?, port, timeout? }: host defaults to 127.0.0.1, port 0 picks a free port, and timeout is the accepted sockets' (none by default). Listener = { host, port, accept(): Task<Socket? ! NetError>, close() }: accept gives the next connection, and null once the listener is closed. Accepted sockets are plain TCP.
Errors
NetError { code, message }, code (NetCode) one of:
code | |
|---|---|
Refused | nothing listens there |
Dns | the name doesn't resolve |
Timeout | timeout passed |
Closed | the connection was reset or is closed |
Tls | the handshake failed: a certificate that doesn't check out, the wrong name, no shared protocol |
Protocol | the peer broke the protocol: data ahead of a TLS upgrade, a line past 1 MiB |
AddressInUse | the port is taken |
PermissionDenied | the system doesn't allow it |
Other | anything else, in message |
Not yet: TLS on the listening side, client certificates, UDP.