Skip to the content.

network

import "network" as network

TCP sockets, TLS client sockets and an HTTP/HTTPS client.

HTTP client

network.http provides get, post, put, del and request:

import "network" expose http

let resp = http.get("https://isotope.wbell.dev/")
term.log(resp.status, resp.ok())   # 200 true
term.log(resp.headers.value_get("Content-Type"))
let body = resp.text()

URLs can use http:// or https:// and may include a port (http://localhost:8080/api).

Function Description
http.get(url, headers=null, ...) send a GET request
http.post(url, body=null, headers=null, ...) send a POST request
http.put(url, body=null, headers=null, ...) send a PUT request
http.del(url, headers=null, ...) send a DELETE request
http.request(method, url, headers=null, body=null, ...) send a request with any method

Every function also accepts these keyword arguments:

Argument Default Description
verify_peer true verify the server’s TLS certificate
ca_path null path to a CA certificate bundle to verify against
timeout_ms 30000 how long to wait for data
max_header_size 65536 maximum response header size in bytes
auto_close true close the connection once the body has been read

headers is a dictionary. body may be a string, a buffer, a multipart_form (see below), or any iterable that yields buffers. A Content-Length header is added automatically for strings, buffers and forms, and Connection: close is sent unless you set Connection yourself.

import "network" expose http
import "json" as json

let resp = http.post(
    "https://example.com/api/items",
    body = json.stringify({name: "widget"}),
    headers = {"Content-Type": "application/json"},
)

Responses

Member Description
status the status code, e.g. 404
status_text the reason phrase, e.g. "Not Found"
headers a dictionary of response headers (names as sent by the server)
ok() true for a 2xx status
text() the whole body as a string
json() the body parsed as JSON
bytes() the whole body as a buffer
content_length() the Content-Length header as a number, or null
chunk() the next chunk of the body as a buffer, or null at the end
close() close the connection early

A response is also iterable, yielding the body in buffer chunks. This lets you stream large downloads to disk without holding them in memory:

import "network" expose http
import "file" expose open

let resp = http.get("https://isotope.wbell.dev/")
let out = open("page.html", "wb")
for (chunk in resp) out.write(chunk)
out.close()

The body can only be read once.

Network errors throw network.HTTPError (for timeouts and broken responses), network.SocketError (when the connection fails) or network.TLSError. A non-2xx status does not throw; check ok() or status.

Multipart forms

network.multipart_form builds a multipart/form-data body, for example for file uploads. File contents are streamed from disk while sending, not loaded into memory:

import "network" expose http, multipart_form
import "file" expose open

let form = multipart_form()
form.field("name", "Ada")
form.file("avatar", "photo.jpg", open("photo.jpg", "rb"))

let resp = http.post(
    "https://example.com/upload",
    body = form,
    headers = {"Content-Type": form.content_type()},
)

form.file(field_name, filename, file, content_type=null) takes ownership of the open file and closes it once it has been sent. If content_type is omitted, it is guessed from the file name’s extension. Pass the form’s content_type() (which includes the boundary) as the Content-Type header.

TCP

Servers: network.tcp(port)

Listens on port on all interfaces. accept() waits for a client and returns a connection:

import "network" as network

let server = network.tcp(8080)
while (true) do
    let conn = server.accept()
    let message = conn.recv_string(1024)
    conn.send_string("Received: " + message)
    conn.close()

Clients: network.tcp_client(host, port)

import "network" as network

let client = network.tcp_client("localhost", 8080)
client.send_string("Hello!")
term.log(client.recv_string(1024))
client.close()

Socket methods

Connections returned by accept() and clients created with tcp_client share these methods:

Method Description
send(buffer) send bytes; returns the number sent
send_string(string) send a string; returns the number of bytes sent
recv(buffer) receive into buffer; returns the number of bytes received (0 when the other side has closed)
recv_string(size) receive up to size bytes and return them as a string
peek(buffer) like recv, but leaves the data in the socket
poll(want_read, want_write, timeout_ms) wait until the socket is ready (see below)
set_nonblocking(enable) make operations return immediately instead of waiting
set_opt(option, value) set a socket option (see below)
close() close the socket

Servers support accept(), poll, set_nonblocking, set_opt and close().

Connection failures throw network.SocketError:

import "network" as network

try network.tcp_client("127.0.0.1", 1)
catch (network.SocketError as e) term.log(e.message)   # failed to connect to 127.0.0.1:1

Polling

poll(want_read, want_write, timeout_ms) waits until the socket is ready, and returns a bitmask of network.NET_POLL_READ (1) and network.NET_POLL_WRITE (2). It returns 0 if the timeout expired and -1 on error. A timeout of -1 waits forever.

let ready = client.poll(true, false, 1000)
if (ready > 0) term.log(client.recv_string(1024))
else if (ready == 0) term.log("timed out")

Socket options

Constant Meaning
network.NET_OPT_KEEPALIVE enable TCP keepalive
network.NET_OPT_NODELAY disable Nagle’s algorithm
network.NET_OPT_REUSEADDR allow reusing the address
network.NET_OPT_RCVTIMEO receive timeout
network.NET_OPT_SNDTIMEO send timeout
client.set_opt(network.NET_OPT_NODELAY, true)

TLS

network.tls_client(host, port, verify_peer=true, ca_path=null) opens an encrypted connection. It supports send, send_string, recv, recv_string, poll and close. network.TLS_SUPPORTED is false if the interpreter was built without TLS support, in which case creating a TLS client throws network.TLSError.

Next