Ecosystem
net
availableHTTP • Sockets • TLS • WebSocket
Networking
Overview
net is the low-level networking layer, similar in spirit to Python's urllib/socket modules. Fetch a URL with http_get, stand up a tiny HTTP server for tests, open a TCP socket for a custom protocol, or wrap it in TLS.
DNS resolution, WebSocket clients, SMTP for sending mail, and FTP for file transfer are included. Failures return net_error values with a kind and message instead of opaque exceptions, which makes retry logic easier to write.
- HTTP client & server
- TCP/UDP/TLS
- WebSocket
- Typed net errors
Import
import
import "net" |
Quick start
quick start
import "net" |
|
let resp = net.http_get("https://api.example.com/status") |
print(resp.status) |
print(resp.body) |
Capabilities
High-level overview of what net is for.
HTTP client & server
GET/POST/PUT/DELETE with headers and body on the client side. A minimal embedded server for local services and integration tests.
TCP/UDP/TLS sockets
Connect, listen, send, recv, building blocks for protocols that aren't HTTP. TLS layer for encrypted streams.
WebSocket
Client connection with send/receive on frames for real-time protocols.
DNS resolution
Resolve a hostname to addresses before you open a socket.
SMTP & FTP
Send email and transfer files, enough for scripts and ops automation, not a full mail stack.
Structured net_error
Timeouts, connection refused, and TLS failures surface as typed errors with a kind field you can branch on.
API reference
86 functions and methods in net. Grouped by category from the standard library docs.
Runtime modes
| Signature | Description |
|---|---|
| net_http_poll(server) | Yes (interpreter) |
| net_http_serve(server) | Yes (interpreter) |
| net_http_serve_async(server) | No - use `net_http_poll` instead |
URL utilities
| Signature | Description |
|---|---|
| net_url_parse(url) | Parse URL into components |
| net_url_encode(s) | Query-string encode (`a b` → `a+b`) |
| net_url_decode(s) | Query-string decode |
| net_url_join(base, ref) | Resolve relative URL |
| net_url_build(parts) | Build URL from parts object |
Parsed URL object (`net_url_parse`)
| Signature | Description |
|---|---|
| scheme | e.g. `"https"` |
| host | Hostname |
| port | Port (default for scheme if omitted) |
| path | Path component |
| query | Query without `?` |
| fragment | Fragment without `#` |
| user | Username |
| password | Password |
DNS
| Signature | Description |
|---|---|
| net_resolve(host, port) | Resolve host to addresses |
| net_hostname() | Local hostname (`HOSTNAME` / `COMPUTERNAME`, else `"localhost"`) |
DNS
| Signature | Description |
|---|---|
| ip | IP address |
| port | Port number |
| family | `"ipv4"` or `"ipv6"` |
HTTP client
| Signature | Description |
|---|---|
| net_http_get(url, opts?) | GET request |
| net_http_post(url, body, opts?) | POST with string body |
| net_http_put(url, body, opts?) | PUT |
| net_http_delete(url, opts?) | DELETE |
| net_http_patch(url, body, opts?) | PATCH |
| net_http_head(url, opts?) | HEAD |
| net_http_request(method, url, opts) | Arbitrary method |
| net_http_download(url, path, opts?) | GET and write body to file |
| net_response_field(resp, field) | Read a response field by name |
Response object
| Signature | Description |
|---|---|
| status | HTTP status code |
| ok | `true` when status is 200–299 |
| body | Response body as UTF-8 text |
| body_bytes | Raw response bytes |
| headers | Response headers (lowercase keys) |
| url | Final URL after redirects |
TCP client / server
| Signature | Description |
|---|---|
| net_tcp_socket() | Create unconnected TCP socket |
| net_tcp_connect(host, port) | Connect to remote host |
| net_tcp_bind(host, port) | Bind listener |
| net_tcp_listen(listener, backlog) | Mark listener ready (backlog accepted) |
| net_tcp_accept(listener) | Accept connection; returns new socket handle |
| net_tcp_send(sock, data) | Bytes written |
| net_tcp_recv(sock, n) | Read up to `n` bytes |
| net_tcp_close(handle) | Close socket or listener |
UDP
| Signature | Description |
|---|---|
| net_udp_socket() | Create UDP socket (ephemeral bind) |
| net_udp_bind(host, port) | Bind UDP socket |
| net_udp_send(sock, host, port, data) | Send datagram |
| net_udp_recv(sock, n) | Receive up to `n` bytes |
Timeouts
| Signature | Description |
|---|---|
| net_set_timeout(handle, ms) | Set read/write timeout; `ms < 0` clears timeout |
TLS
| Signature | Description |
|---|---|
| net_tls_connect(host, port, sni?) | One-shot TLS TCP connection (handle) |
| net_tls_wrap(tcp_handle, sni_host) | Upgrade existing TCP handle to TLS |
| net_tls_config(verify?, min_version?) | TLS config placeholder (verify flag) |
HTTP server
| Signature | Description |
|---|---|
| net_http_listen(port, host?) | Create server handle (default host `0.0.0.0`) |
| net_http_route(server, method, path, handler) | Per-route handler |
| net_http_on_request(server, handler) | Catch-all fallback handler |
| net_http_poll(server) | Process one pending request (non-blocking) |
| net_http_serve(server) | Blocking accept loop until `net_http_stop` |
| net_http_serve_async(server) | Background accept loop (no Niao handlers) |
| net_http_stop(server) | Signal server to stop |
| net_http_response(status, content_type, body) | Build handler response object |
| net_request_field(req, field) | Read request field |
Request object (passed to handler)
| Signature | Description |
|---|---|
| method | HTTP method |
| path | Path without query string |
| query | Query string without `?` |
| body | Body as UTF-8 text |
| body_bytes | Raw body bytes |
| headers | Request headers (lowercase keys) |
Response object (returned by handler)
| Signature | Description |
|---|---|
| status | HTTP status code |
| content_type | `Content-Type` header |
| body | Response body |
WebSocket (client)
| Signature | Description |
|---|---|
| net_ws_connect(url, opts?) | Client handshake (`ws://` or `wss://`) |
| net_ws_send(handle, message) | Send text or binary frame |
| net_ws_recv(handle) | Blocking receive; `nil` on close |
| net_ws_close(handle) | Close connection |
SMTP
| Signature | Description |
|---|---|
| net_smtp_send(host, port, from, to, subject, body, opts?) | Send plain-text email |
FTP
| Signature | Description |
|---|---|
| net_ftp_connect(host, port) | Connect to FTP server |
| net_ftp_login(handle, user, pass) | Authenticate |
| net_ftp_get(handle, remote) | Download file as string |
| net_ftp_put(handle, remote, content) | Upload string content |
| net_ftp_close(handle) | Quit and close |
Async background networking
| Signature | Description |
|---|---|
| net_async_http_get(url, opts?) | Background HTTP GET |
| net_async_tcp_connect(host, port) | Background TCP connect (returns socket handle) |
| net_task_done(task) | `true` when finished or cancelled |
| net_task_poll(task) | Result if done; `nil` if pending |
| net_task_wait(task) | Block until done, then return result |
| net_task_cancel(task) | Cancel pending task |
Notes
- For production HTTP APIs with routing and middleware, use ahiru instead of the bare net server.