Skip to content

stdlib.net

Networking Library

Generated from v0.60.1. 29 source files, 320 documented symbols.

address.xi

type Address

struct Address { family: Str; host: Str; port: Int } family is "ipv4", "ipv6" or "hostname"; port 0 means "no explicit port".

Field Type
family Str
host Str
port Int
fn address_parse(s: Str) -> Option[Address]

Parse a host:port address string into an Address. Parameters: s -- the address string ("example.com:8080", "127.0.0.1", "[::1]:53", "example.com"). Returns: Some(Address) when the string is well-formed (non-empty host and a valid port if present), None otherwise. Complexity: O(n). Pure.

fn address_host(s: Str) -> Str

Extract the host part of an address string. Parameters: s -- the address string. Returns: the host (without brackets for IPv6 literals), or "" when the string is not a valid address. Complexity: O(n). Pure.

fn address_port(s: Str) -> Int

Extract the port part of an address string. Parameters: s -- the address string. Returns: the port number (0 when absent), or 0 for an invalid address. Complexity: O(n). Pure.

  • Postcondition: result >= 0
fn address_is_ipv4(s: Str) -> Bool

Test if the host part of an address string is an IPv4 address. Parameters: s -- the address string. Returns: true when the string parses and its host is dotted-quad IPv4. Complexity: O(n). Pure.

fn address_is_ipv6(s: Str) -> Bool

Test if the host part of an address string is an IPv6 address. Parameters: s -- the address string. Returns: true when the string parses and its host is an IPv6 literal. Complexity: O(n). Pure.

fn address_is_valid(s: Str) -> Bool

Test if the address string is well-formed. Parameters: s -- the address string. Returns: true when parsing succeeds with a non-empty host and a valid port (0..65535) if one is present. Complexity: O(n). Pure.

cookie.xi

struct Cookie { name: Str; value: Str; domain: Str; path: Str; expires: Int; max_age: Int; secure: Bool; http_only: Bool; same_site: Str } expires is a unix timestamp (0 = session cookie); same_site is "Strict", "Lax" or "None" ("" when unset).

Field Type
name Str
value Str
domain Str
path Str
expires Int
max_age Int
secure Bool
http_only Bool
same_site Str
type CookieJar

struct CookieJar - an ordered collection of cookies.

Field Type
cookies Vec[Cookie]

Parse a request Cookie header into a cookie. Parameters: header -- the Cookie header value (e.g. "a=b; c=d"). Returns: Ok(Cookie) for the first name=value pair, Err when the header is empty or any segment is malformed. Complexity: O(n). Pure.

Parse a Set-Cookie header into a cookie. Parameters: header -- the Set-Cookie header value (e.g. "a=b; Path=/; HttpOnly; Max-Age=3600; SameSite=Strict"). Returns: Ok(Cookie) with attributes applied, Err when the name=value pair is missing or malformed. Complexity: O(n). Pure.

Serialize a cookie into Cookie header form ("name=value"). Parameters: c -- the cookie. Returns: the "name=value" string. Complexity: O(1). Pure.

Create an empty cookie jar. Returns: a jar holding no cookies. Complexity: O(1). Pure.

Store a cookie in the jar, replacing an existing cookie with the same name, domain and path. Parameters: jar -- the mutable jar; c -- the cookie to store. Returns: Unit. Complexity: O(n) with n = jar size. Pure.

Fetch a cookie by name for a url. Parameters: jar -- the jar; name -- the cookie name; url -- the request url. Returns: Some(Cookie) for the first matching cookie, None otherwise. Complexity: O(n) with n = jar size. Pure.

Test if a cookie applies to a url (domain match, path match and not expired). Parameters: c -- the cookie; url -- the request url. Returns: true when the cookie applies. Complexity: O(n). Pure.

Count cookies held in the jar. Parameters: jar -- the jar. Returns: the number of cookies. Complexity: O(1). Pure.

  • Postcondition: result >= 0

Test if the cookie expires within the given number of seconds. Parameters: c -- the cookie; seconds -- the window in seconds. Returns: true when the cookie has an expiry and it falls at or before now + seconds (already-expired cookies count as expiring). Complexity: O(1). Pure.

RFC 6265 domain-match test. Parameters: domain -- the cookie's Domain attribute; host -- the request host. Returns: true when host equals domain or is a subdomain of domain. Complexity: O(n). Pure.

RFC 6265 path-match test. Parameters: path -- the cookie's Path attribute; request_path -- the request path. Returns: true when request_path matches the cookie path. Complexity: O(n). Pure.

dns.xi

fn dns_parse_ipv4(s: Str) -> Option[Vec[UInt8]]

dns_parse_ipv4 parses "a.b.c.d" into 4 bytes, or None on invalid input. Delegates to the canonical xiom.net.ip4 (dedup wave, 2026-09-16; parity proven in p_dns_parity). The Option/Result translation binds the parsed value to a named local first (R28 workaround: .value on a temporary aggregate payload is corrupt).

fn dns_ipv4_to_str(octets: &Vec[UInt8]) -> Option[Str]

dns_ipv4_to_str formats 4 bytes as "a.b.c.d", or None if the length is not 4. Delegates to the canonical xiom.net.ip4.

fn dns_parse_ipv6(s: Str) -> Option[Vec[UInt8]]

dns_parse_ipv6 parses a full-form IPv6 address (8 hex groups) or a compressed form with a single "::" into 16 bytes. Returns None on invalid input. Delegates to the canonical xiom.net.ip6 (parity proven in p_dns_parity).

fn dns_ipv6_to_str(bytes: &Vec[UInt8]) -> Option[Str]

dns_ipv6_to_str formats 16 bytes as a full-form IPv6 address (8 groups, no "::" compression). Delegates to the canonical xiom.net.ip6 (same full-form convention; parity proven in p_dns_parity).

fn dns_parse_record_line(line: Str) -> Option[(Str, Str, Str)]

dns_parse_record_line parses a presentation-format zone record line such as "example.com. 3600 IN A 93.184.216.34" into (name, type, rdata).

fn dns_is_valid_hostname(name: Str) -> Bool

dns_is_valid_hostname validates a hostname: labels of [A-Za-z0-9-] with no leading/trailing hyphen, 1-63 chars each, total length <= 253, at least one label, and no empty labels. A single trailing dot is allowed.

fn dns_reverse_ipv4(octets: &Vec[UInt8]) -> Option[Str]

dns_reverse_ipv4 formats 4 bytes as the in-addr.arpa reverse name, or None if the length is not 4.

fn dns_well_known_port(service: Str) -> Option[Int]

dns_well_known_port maps a well-known service name to its default port, or None for unknown services.

ftp.xi

fn ftp_default_port() -> Int

ftp_default_port returns the default FTP control port (21). Complexity: O(1). Pure.

  • Postcondition: result == 21
fn ftp_command_user(user: Str) -> Str

ftp_command_user formats a USER command. Complexity: O(1). Pure.

fn ftp_command_pass(pass: Str) -> Str

ftp_command_pass formats a PASS command. Complexity: O(1). Pure.

fn ftp_command_retr(path: Str) -> Str

ftp_command_retr formats a RETR command for a remote path. Complexity: O(1). Pure.

fn ftp_command_stor(path: Str) -> Str

ftp_command_stor formats a STOR command for a remote path. Complexity: O(1). Pure.

fn ftp_command_list(path: Str) -> Str

ftp_command_list formats a LIST command with an optional path. Complexity: O(1). Pure.

fn ftp_command_quit() -> Str

ftp_command_quit formats a QUIT command. Complexity: O(1). Pure.

fn ftp_command_cwd(dir: Str) -> Str

ftp_command_cwd formats a CWD command. Complexity: O(1). Pure.

fn ftp_command_type(kind: Str) -> Str

ftp_command_type formats a TYPE command (A or I). Complexity: O(1). Pure.

fn ftp_parse_reply(line: Str) -> Option[(Int, Str)]

ftp_parse_reply parses an FTP reply line like "220 Ready" into (code, text). Returns None if the line does not start with a 3-digit code. Complexity: O(1). Pure.

fn ftp_reply_is_success(code: Int) -> Bool

ftp_reply_is_success returns true for 2xx replies. Complexity: O(1). Pure.

  • Postcondition: result == (code >= 200 && code < 300)
fn ftp_reply_is_positive_preliminary(code: Int) -> Bool

ftp_reply_is_positive_preliminary returns true for 1xx replies. Complexity: O(1). Pure.

  • Postcondition: result == (code >= 100 && code < 200)

header.xi

fn header_get(headers: &Vec[(Str, Str)], name: Str) -> Option[Str]

Fetch the first value for a header name (case-insensitive). Parameters: headers -- the header list; name -- the header name. Returns: Some(first value) when present, None otherwise. Complexity: O(n) with n = header count. Pure.

fn header_set(headers: &mut Vec[(Str, Str)], name: Str, value: Str)

Set a header, replacing any existing entry with the same name (case-insensitive); the new entry keeps the caller's spelling. Parameters: headers -- the mutable header list; name -- the header name; value -- the header value. Returns: Unit. Complexity: O(n) with n = header count. Pure.

fn header_remove(headers: &mut Vec[(Str, Str)], name: Str) -> Bool

Remove all entries for a header name (case-insensitive). Parameters: headers -- the mutable header list; name -- the header name. Returns: true when at least one entry was removed. Complexity: O(n) with n = header count. Pure.

fn header_contains(headers: &Vec[(Str, Str)], name: Str) -> Bool

Test if a header name is present (case-insensitive). Parameters: headers -- the header list; name -- the header name. Returns: true when at least one entry matches. Complexity: O(n) with n = header count. Pure.

fn header_parse_line(line: Str) -> Option[(Str, Str)]

Parse one "Name: value" line into a (name, value) pair. Parameters: line -- a single header line (may include a trailing CRLF). Returns: Some((name, value)) for a well-formed line, None otherwise. The name is preserved verbatim; the value is trimmed. Complexity: O(n). Pure.

fn header_serialize(headers: &Vec[(Str, Str)]) -> Str

Serialize headers into "Name: value" lines. Parameters: headers -- the header list. Returns: the concatenated header block; each line ends with CRLF. Complexity: O(n) with n = header count. Pure.

http.xi

type HttpResponse

type HttpResponse - an HTTP response: status code (Int), headers, and raw body bytes.

Field Type
status Int
headers Vec[(Str, Str)]
body Vec[UInt8]

Derives: Clone

fn http_status_text(code: Int) -> Str

http_status_text returns the standard reason phrase for a status code, or "Unknown" for codes not in the table. Complexity: O(1).

fn http_request_line(method: Str, target: Str) -> Str

http_request_line builds the request line for a method and target, e.g. http_request_line("GET", "/") == "GET / HTTP/1.1". Complexity: O(1). Pure.

fn http_build_request(method: Str, url_str: Str, headers: &Vec[(Str, Str)], body: &Vec[UInt8]) -> Result[Str, Str]

http_build_request builds a full HTTP/1.1 request text from a parsed URL, method, headers, and body. Used by the client and exposed for callers that want to send raw requests themselves.

fn http_response_status(raw: Str) -> Option[Int]

http_response_status extracts the HTTP status code from a raw response without allocating a full response value. Returns None if the status line is malformed. Complexity: O(1). Pure.

fn http_parse_response_headers(raw: Str) -> Vec[(Str, Str)]

http_parse_response_headers extracts the (name, value) header pairs from a raw HTTP response block (everything after the status line and before the blank line). Complexity: O(n). Pure.

fn http_parse_response(raw: Str) -> Result[HttpResponse, Str]

http_parse_response parses a raw HTTP/1.1 response into an HttpResponse. Invalid input returns Err. Complexity: O(n). Pure.

fn http_status_code(resp: &HttpResponse) -> Int

http_status_code returns the HTTP status code of a response. Complexity: O(1). Pure.

fn http_header(resp: &HttpResponse, name: Str) -> Option[Str]

http_header returns the value of a named response header (matched case-insensitively), or None if absent. Complexity: O(h). Pure.

fn http_body_text(resp: &HttpResponse) -> Str

http_body_text decodes the response body bytes as UTF-8 text. Complexity: O(n). Pure.

fn http_url_encode(s: Str) -> Str

http_url_encode percent-encodes a string for use in a URL. Complexity: O(n). Pure.

fn http_url_decode(s: Str) -> Result[Str, Str]

http_url_decode percent-decodes a URL-encoded string. Returns Err on truncated or invalid escapes. Complexity: O(n). Pure.

fn http_get(url: Str) -> Result[HttpResponse, Str]

http_get performs an HTTP GET request and returns the response. Complexity: network I/O.

fn http_post(url: Str, body: &Vec[UInt8]) -> Result[HttpResponse, Str]

http_post performs an HTTP POST with a raw byte body. Complexity: network I/O.

fn http_put(url: Str, body: &Vec[UInt8]) -> Result[HttpResponse, Str]

http_put performs an HTTP PUT with a raw byte body. Complexity: network I/O.

fn http_delete(url: Str) -> Result[HttpResponse, Str]

http_delete performs an HTTP DELETE request. Complexity: network I/O.

fn http_head(url: Str) -> Result[HttpResponse, Str]

http_head performs an HTTP HEAD request. Complexity: network I/O.

fn http_patch(url: Str, body: &Vec[UInt8]) -> Result[HttpResponse, Str]

http_patch performs an HTTP PATCH with a raw byte body. Complexity: network I/O.

fn http_get_text(url: Str) -> Result[Str, Str]

http_get_text performs an HTTP GET and returns the response body decoded as text. Complexity: network I/O.

fn http_get_bytes(url: Str) -> Result[Vec[UInt8], Str]

http_get_bytes performs an HTTP GET and returns the raw body bytes. Complexity: network I/O.

fn http_redirect_follow(url: Str, max: Int) -> Result[HttpResponse, Str]

http_redirect_follow follows up to max HTTP redirects (301/302/303/ 307/308) before returning the final response. Complexity: network I/O.

fn http_request(method: Str, url: Str, headers: &Vec[(Str, Str)], body: &Vec[UInt8]) -> Result[HttpResponse, Str]

http_request performs a generic HTTP request; each tuple in headers is a (name, value) header pair. Complexity: network I/O.

https.xi

fn https_default_port() -> Int

https_default_port returns the default HTTPS port (443). Complexity: O(1). Pure.

fn https_request_line(method: Str, target: Str) -> Str

https_request_line builds the request line for a method and target, e.g. https_request_line("GET", "/") == "GET / HTTP/1.1". Complexity: O(1). Pure.

fn https_build_request(method: Str, url_str: Str, headers: &Vec[(Str, Str)], body: &Vec[UInt8]) -> Result[Str, Str]

https_build_request builds a full HTTPS request text from a URL, method, headers, and body. The Host header carries the explicit port only when it differs from 443. Complexity: O(n). Pure.

fn https_status_text(code: Int) -> Str

https_status_text returns the standard reason phrase for a status code, or "Unknown" for codes not in the table. Complexity: O(1).

fn https_response_status(raw: Str) -> Option[Int]

https_response_status extracts the HTTP status code from a raw response. Returns None if malformed. Complexity: O(1). Pure.

fn https_parse_response_headers(raw: Str) -> Vec[(Str, Str)]

https_parse_response_headers extracts the (name, value) header pairs from a raw response block. Complexity: O(n). Pure.

fn https_url_encode(s: Str) -> Str

https_url_encode percent-encodes a string for use in a URL. Complexity: O(n). Pure.

fn https_url_decode(s: Str) -> Result[Str, Str]

https_url_decode percent-decodes a URL-encoded string. Complexity: O(n). Pure.

ip.xi

enum IpAddr

type IpAddr - an IP address enum: V4 holding four octets, V6 holding eight 16-bit parts.

  • V4(octets: Vec[UInt8])
  • V6(parts: Vec[UInt16])
fn ipv4_parse(s: Str) -> Option[Vec[UInt8]]

Parse a dotted-quad IPv4 string into four octets. Parameters: s -- the address string. Returns: Some(four octets) for a valid address, None otherwise. Complexity: O(n). Pure.

fn ipv4_to_string(octets: &Vec[UInt8]) -> Str

Format four octets as a dotted-quad IPv4 string. Parameters: octets -- at least four octets (only the first four are used). Returns: the "a.b.c.d" representation, or "" for an undersized vector. Complexity: O(1). Pure.

fn ipv6_parse(s: Str) -> Option[Vec[UInt16]]

Parse an IPv6 string (full form or single "::" compression) into eight 16-bit groups. Parameters: s -- the address string. Returns: Some(eight groups) for a valid address, None otherwise. Complexity: O(n). Pure.

fn ipv6_to_string(parts: &Vec[UInt16]) -> Str

Format eight 16-bit parts as a full-form IPv6 string (no "::" compression, leading zeros elided). Parameters: parts -- exactly eight 16-bit groups. Returns: the colon-separated string, or "" for a vector of the wrong size. Complexity: O(8). Pure.

fn ip_parse(s: Str) -> Option[IpAddr]

Parse an IPv4 or IPv6 string into an IpAddr. Parameters: s -- the address string. Returns: Some(IpAddr) for a valid address, None otherwise. Complexity: O(n). Pure.

fn ip_is_loopback(s: Str) -> Bool

Returns true for loopback addresses (127.0.0.0/8, ::1). Parameters: s -- the address string. Returns: true when the address parses and is loopback. Complexity: O(n). Pure.

fn ip_is_private(s: Str) -> Bool

Returns true for private-use ranges (10/8, 172.16/12, 192.168/16, fc00::/7). Parameters: s -- the address string. Returns: true when the address parses and is private-use. Complexity: O(n). Pure.

Returns true for link-local ranges (169.254/16, fe80::/10). Parameters: s -- the address string. Returns: true when the address parses and is link-local. Complexity: O(n). Pure.

fn ip_is_multicast(s: Str) -> Bool

Returns true for multicast ranges (224.0.0.0/4, ff00::/8). Parameters: s -- the address string. Returns: true when the address parses and is multicast. Complexity: O(n). Pure.

fn ip_is_unspecified(s: Str) -> Bool

Returns true for the all-zero address (0.0.0.0, ::). Parameters: s -- the address string. Returns: true when the address parses and is all zero. Complexity: O(n). Pure.

fn ip_masked(s: Str, prefix: Int) -> Str

Apply a CIDR prefix mask to an address and return the masked address string. Parameters: s -- the address string; prefix -- the prefix length (0..32 for IPv4, 0..128 for IPv6). Returns: the masked address, or "" for invalid input or an out-of-range prefix. Complexity: O(n). Pure.

fn ip_in_subnet(ip: Str, subnet: Str) -> Bool

Test whether ip falls inside a CIDR subnet ("192.168.1.0/24" or "2001:db8::/32"). Parameters: ip -- the address string; subnet -- "address/prefix". Returns: true when the masked addresses are equal. Complexity: O(n). Pure.

fn ip_expand(s: Str) -> Str

Expand an IPv6 string to the full eight-part form with zero padding. Parameters: s -- the address string. Returns: the "0000:0000:...:0000" form, or "" for invalid input. IPv4 input is returned unchanged. Complexity: O(n). Pure.

fn ip_compress(s: Str) -> Str

Compress an IPv6 string using "::" and leading-zero elision. Parameters: s -- the address string. Returns: the canonical compressed form, or "" for invalid input. IPv4 input is returned unchanged. Complexity: O(n). Pure.

fn ip_octets(s: Str) -> Vec[Int]

Split an IPv4 string into its numeric octets. Parameters: s -- the address string. Returns: four octets for a valid address, an empty vector otherwise. Complexity: O(n). Pure.

ip4.xi

fn ip4_parse(s: Str) -> Result[Vec[UInt8], Str]

ip4_parse parses a dotted-quad IPv4 string into four octets. Invalid input (wrong segment count, non-numeric, or out-of-range octets) returns Err. Complexity: O(n). Pure.

fn ip4_validate(s: Str) -> Bool

ip4_validate returns true if s is a valid dotted-quad IPv4 address. Complexity: O(n). Pure.

fn ip4_to_str(octets: &Vec[UInt8]) -> Result[Str, Str]

ip4_to_str formats four octets as a dotted-quad string. Returns Err if octets.len() is not 4. Complexity: O(1). Pure.

fn ip4_octets(s: Str) -> Vec[Int]

ip4_octets splits a dotted-quad IPv4 string into its four numeric octets as Int. Invalid input returns an empty vector. Pure.

fn ip4_is_loopback(s: Str) -> Bool

ip4_is_loopback returns true for 127.0.0.0/8. Complexity: O(n). Pure.

fn ip4_is_private(s: Str) -> Bool

ip4_is_private returns true for RFC 1918 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). Complexity: O(n). Pure.

ip4_is_link_local returns true for 169.254.0.0/16. Complexity: O(n). Pure.

fn ip4_is_multicast(s: Str) -> Bool

ip4_is_multicast returns true for 224.0.0.0/4. Complexity: O(n). Pure.

fn ip4_is_unspecified(s: Str) -> Bool

ip4_is_unspecified returns true for 0.0.0.0. Complexity: O(n). Pure.

fn ip4_is_broadcast(s: Str) -> Bool

ip4_is_broadcast returns true for 255.255.255.255. Complexity: O(n). Pure.

ip6.xi

fn ip6_parse(s: Str) -> Result[Vec[UInt8], Str]

ip6_parse parses an IPv6 string (full form or with a single "::" compression) into 16 bytes. Invalid input returns Err. Complexity: O(n). Pure.

fn ip6_validate(s: Str) -> Bool

ip6_validate returns true if s is a valid IPv6 address. Complexity: O(n). Pure.

fn ip6_to_str(bytes: &Vec[UInt8]) -> Result[Str, Str]

ip6_to_str formats 16 bytes as a full-form IPv6 address (eight 16-bit groups, no "::" compression). Returns Err if the length is not 16. Complexity: O(n). Pure.

fn ip6_expand(s: Str) -> Result[Str, Str]

ip6_expand returns the full eight-group form of an IPv6 string, expanding "::" and zero-padding each group to four hex digits. Returns Err on invalid input. Complexity: O(n). Pure.

fn ip6_is_loopback(s: Str) -> Bool

ip6_is_loopback returns true for ::1. Complexity: O(n). Pure.

fn ip6_is_unspecified(s: Str) -> Bool

ip6_is_unspecified returns true for :: Complexity: O(n). Pure.

fn ip6_is_multicast(s: Str) -> Bool

ip6_is_multicast returns true for ff00::/8. Complexity: O(n). Pure.

ip6_is_link_local returns true for fe80::/10. Complexity: O(n). Pure.

jwt.xi

type Jwt

struct Jwt { header: Str; payload: Str; signature: Str }

Field Type
header Str
payload Str
signature Str
fn jwt_base64url_encode(data: &Vec[UInt8]) -> Str

Base64url encode bytes without padding. Parameters: data -- the bytes to encode. Returns: the unpadded URL-safe base64 string. Complexity: O(n). Pure.

fn jwt_base64url_decode(s: Str) -> Result[Vec[UInt8], Str]

Decode an unpadded base64url string back to bytes. Parameters: s -- the encoded string (padding optional). Returns: Ok(bytes) on success, Err for an invalid character. Complexity: O(n). Pure.

fn jwt_alg_supported(alg: Str) -> Bool

Test if an algorithm is supported. Parameters: alg -- the algorithm name. Returns: true for "HS256" and "none". Complexity: O(1). Pure.

fn jwt_encode(header: Str, payload: Str, secret: Str, alg: Str) -> Result[Str, Str]

Build a signed JWT string. Parameters: header -- the JSON header (e.g. "{\"alg\":\"HS256\",\"typ\":\"JWT\"}"); payload -- the JSON claims; secret -- the HMAC secret; alg -- "HS256" or "none". Returns: Ok("header.payload.signature") on success, Err for an unsupported algorithm. Complexity: O(n). Pure.

fn jwt_sign_b64(header_b64: Str, payload_b64: Str, secret: Str, alg: Str) -> Result[Str, Str]

Sign base64url parts and append the signature. Parameters: header_b64 -- the encoded header; payload_b64 -- the encoded payload; secret -- the HMAC secret; alg -- "HS256" or "none". Returns: Ok("header.payload.signature") on success, Err for an unsupported algorithm. Complexity: O(n). Pure.

fn jwt_decode(token: Str) -> Result[Jwt, Str]

Split a JWT into header, payload, and signature. Parameters: token -- the full JWT string. Returns: Ok(Jwt) with exactly three dot-separated parts, Err otherwise. Complexity: O(n). Pure.

fn jwt_verify(token: Str, secret: Str) -> Bool

Verify a JWT signature with the given secret. Parameters: token -- the JWT string; secret -- the HMAC secret. Returns: true when the structure is valid and (for HS256) the signature matches; "none" tokens verify only when the signature part is empty. Complexity: O(n). Pure.

fn jwt_expired(token: Str, now: Int) -> Bool

Test if the exp claim is before the given time. Parameters: token -- the JWT string; now -- the reference unix timestamp. Returns: true when the token has an exp claim at or before now, false when there is no exp claim or the token is malformed. Complexity: O(n). Pure.

fn jwt_claims(token: Str) -> Result[Str, Str]

Extract the payload claims as JSON. Parameters: token -- the JWT string. Returns: Ok(decoded payload) on success, Err for a malformed token or an invalid base64url payload. Complexity: O(n). Pure.

mime.xi

type MimeType

struct MimeType { kind: Str; subtype: Str; params: Vec[(Str, Str)] } NOTE: the frozen spec documents params: Map[Str, Str]. The compiler cannot construct/return a struct containing a Map field (hangs/0xC0000005, see probe in agent_net2); the main-type field is named kind because the reserved word type is unreadable at call sites (P001) and breaks cross-module resolution. Params are stored as ordered (name, value) pairs.

Field Type
subtype Str
params Vec[(Str, Str)]
kind Str

struct Link { href: Str; rel: Str; title: Str; kind: Str }

Field Type
href Str
rel Str
title Str
kind Str
fn mime_parse(s: Str) -> Result[MimeType, Str]

Parse a MIME type string into its parts. Parameters: s -- the MIME type (e.g. "text/html; charset=utf-8"). Returns: Ok(MimeType) with a lowercased type/subtype and parsed parameters (in declaration order); Err for a missing slash or an empty type. Complexity: O(n). Pure.

fn mime_type_of(path: Str) -> Str

Guess the MIME type from a file extension. Parameters: path -- the file path. Returns: the MIME type (lowercase) or "application/octet-stream". Complexity: O(1). Pure.

fn mime_extension_of(mime: Str) -> Str

Guess a file extension for a MIME type. Parameters: mime -- the MIME type (lowercase). Returns: the extension without the leading dot, or "" when unknown. Complexity: O(1). Pure.

fn mime_matches(pattern: Str, mime: Str) -> Bool

Wildcard pattern match against a MIME type. Parameters: pattern -- e.g. "text/", "application/json" or "/*"; mime -- the actual MIME type. Returns: true when the pattern matches. Complexity: O(n). Pure.

fn mime_is_text(mime: Str) -> Bool

Test if a MIME type is text-based. Parameters: mime -- the MIME type. Returns: true for text/*, application/json, application/xml and related. Complexity: O(1). Pure.

fn mime_is_image(mime: Str) -> Bool

Test if a MIME type is an image. Parameters: mime -- the MIME type. Returns: true for image/ and image/x- types. Complexity: O(1). Pure.

fn mime_is_audio(mime: Str) -> Bool

Test if a MIME type is audio. Parameters: mime -- the MIME type. Returns: true for audio/* types. Complexity: O(1). Pure.

fn mime_is_video(mime: Str) -> Bool

Test if a MIME type is video. Parameters: mime -- the MIME type. Returns: true for video/* types. Complexity: O(1). Pure.

fn mime_is_application(mime: Str) -> Bool

Test if a MIME type is an application type. Parameters: mime -- the MIME type. Returns: true for application/* types. Complexity: O(1). Pure.

fn charset_detect(data: &Vec[UInt8]) -> Str

Guess the character encoding of a byte buffer. Parameters: data -- the bytes to inspect. Returns: "utf-8", "utf-16le", "utf-16be", "utf-32le", "utf-32be", "ascii" or "binary". Complexity: O(n). Pure.

fn charset_normalize(s: Str, charset: Str) -> Result[Str, Str]

Re-encode a string into a target charset. Parameters: s -- the input string (already UTF-8); charset -- the requested target charset. Returns: Ok(s) for UTF-8/ASCII targets (XIOM strings are always UTF-8), Err for unsupported targets. Complexity: O(1). Pure.

fn etag_new(content: &Vec[UInt8]) -> Str

Compute a quoted etag for a byte buffer (SHA-256 hex). Parameters: content -- the bytes to hash. Returns: the quoted etag, e.g. "\"a1b2c3...\"". Complexity: O(n). Pure.

fn etag_matches(etag: Str, if_none_match: Str) -> Bool

Test an etag against an If-None-Match header. Parameters: etag -- the entity tag (quoted); if_none_match -- the header value (a comma-separated list, optionally W/ prefixed). Returns: true when any list entry matches (including "*"). Complexity: O(n). Pure.

fn accept_parse(header: Str) -> Vec[(Str, Int)]

Parse an Accept header into mime pattern and q pairs. Parameters: header -- the Accept header value. Returns: the (pattern, q*1000) entries; malformed entries are skipped. Complexity: O(n). Pure.

fn accept_q_value(header: Str, mime: Str) -> Int

Look up the q value of a MIME type in an Accept header. Parameters: header -- the Accept header value; mime -- the actual MIME type. Returns: the highest matching q (scaled by 1000), or 0 when absent. Complexity: O(n). Pure.

fn accept_negotiate(header: Str, available: &Vec[Str]) -> Option[Str]

Pick the best available MIME type for an Accept header. Parameters: header -- the Accept header value; available -- the candidate MIME types. Returns: Some(best) when a match with q > 0 exists, None otherwise. Complexity: O(n-m). Pure.

Parse a Link header into typed links. Parameters: header -- the Link header value (e.g. "https://a.com; rel=\"next\"; title=\"Next\""). Returns: the parsed links; malformed entries are skipped. Complexity: O(n). Pure.

Find the href of a link with the given rel. Parameters: links -- the parsed links; rel -- the relation type. Returns: Some(href) for the first matching link, None otherwise. Complexity: O(n). Pure.

multipart.xi

type Part

struct Part { name: Str; filename: Str; content_type: Str; data: Vec[UInt8] }

Field Type
name Str
filename Str
content_type Str
data Vec[UInt8]
fn multipart_part(name: Str, value: Str) -> Part

Build a plain text field part. Parameters: name -- the field name; value -- the field value. Returns: a Part with no filename or content type. Complexity: O(n). Pure.

fn multipart_part_file(name: Str, filename: Str, content_type: Str, data: &Vec[UInt8]) -> Part

Build a file field part. Parameters: name -- the field name; filename -- the client file name; content_type -- the file's MIME type; data -- the file bytes. Returns: a Part carrying the file metadata and bytes. Complexity: O(n). Pure.

fn multipart_build(parts: &Vec[Part], boundary: Str) -> Vec[UInt8]

Serialize parts into a multipart body. Parameters: parts -- the parts to serialize; boundary -- the boundary string. Returns: the multipart/form-data body bytes. Complexity: O(n). Pure.

fn multipart_parse(body: &Vec[UInt8], boundary: Str) -> Result[Vec[Part], Str]

Split a multipart body into parts. Parameters: body -- the multipart body bytes; boundary -- the boundary string. Returns: Ok(parts) on success, Err when the body has no boundary markers or is malformed. Complexity: O(n). Pure.

fn multipart_boundary_new() -> Str

Generate a random boundary string. Returns: a boundary of the form "----xiomboundary". Complexity: O(1). Pure (timestamp-based uniqueness).

fn multipart_content_type(boundary: Str) -> Str

Build the Content-Type header value for a boundary. Parameters: boundary -- the boundary string. Returns: "multipart/form-data; boundary=". Complexity: O(1). Pure.

net.xi

type TcpStream

=== TCP ===

Field Type
fd Int

Derives: Clone

type TcpListener

Listening TCP socket handle.

Field Type
fd Int

Derives: Clone

type NetError

Network error with a message and an OS error code.

Field Type
message Str
code Int

fn tcp_connect(host: Str, port: Int) -> Result[TcpStream, NetError]

Connect to host:port; Err with the OS message.

  • Precondition: host.len() > 0
  • Precondition: port > 0 && port <= 65535

fn tcp_listen(host: Str, port: Int) -> Result[TcpListener, NetError]

Bind and listen on host:port; Err on failure.

  • Precondition: host.len() > 0
  • Precondition: port > 0 && port <= 65535

fn read(self: Self, buf: &mut Vec[UInt8]) -> Result[Int, NetError]

Read up to buffer capacity; Ok(bytes, 0 at EOF) or Err.

  • Precondition: true

fn write(self: Self, data: &Vec[UInt8]) -> Result[Int, NetError]

Write bytes; Ok(bytes written) or Err.

  • Precondition: true

fn close(self: Self) -> Result[Unit, NetError]

Close the stream; Err on failure.

fn accept(self: Self) -> Result[(TcpStream, Str), NetError]

Accept a connection; Ok((stream, peer address)) or Err.

  • Precondition: true

type NetHttpResponse

=== HTTP === NOTE: named NetHttpResponse to keep the bare type leaf distinct from xiom.net.http.HttpResponse (R44 same-leaf struct collision; both used to inject as %struct.HttpResponse and clobbered each other's fields).

Field Type
status Int
body Str

Derives: Clone

fn http_get(url: Str) -> Result[NetHttpResponse, NetError]

HTTP GET; Ok parsed response or Err (transport or parse).

  • Precondition: url.len() > 0

fn http_post(url: Str, body: Str) -> Result[NetHttpResponse, NetError]

HTTP POST with a body; Ok parsed response or Err.

type UdpSocket

=== UDP ===

Field Type
fd Int

fn udp_bind(host: Str, port: Int) -> Result[UdpSocket, NetError]

Bind a UDP socket to host:port; Err on failure.

fn send_to(self: Self, data: &Vec[UInt8], addr: Str, port: Int) -> Result[Int, NetError]

Send a datagram to addr:port; Ok(bytes) or Err.

  • Precondition: true

fn recv_from(self: Self, buf: &mut Vec[UInt8]) -> Result[(Int, Str, Int), NetError]

Receive a datagram; Ok((bytes, peer address, port)) or Err.

  • Precondition: true

fn close(self: Self) -> Result[Unit, NetError]

Close the socket; Err on failure.

fn resolve_host(hostname: Str) -> Result[Vec[Str], NetError]

=== DNS ===

  • Precondition: true

fn local_addr(port: Int) -> Result[Str, NetError]

Local address for binding to port; Err on failure.

  • Precondition: true

type UrlParts

=== URL parsing ===

Field Type
scheme Str
host Str
port Int
path Str
query Str
fragment Str

fn parse_url(url: Str) -> Result[UrlParts, NetError]

Split a URL into scheme/host/port/path; Err on malformed input.

enum HttpMethod

=== HTTP methods ===

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS

fn http_get_str(url: Str) -> Result[Str, NetError]

Performs an HTTP GET request and returns the response body as a string. Complexity: network I/O. Thread-safe: no shared state.

fn http_post_str(url: Str, body: Str) -> Result[Str, NetError]

Performs an HTTP POST request and returns the response body as a string. Complexity: network I/O. Thread-safe: no shared state.

fn http_status(url: Str) -> Option[Int]

Performs an HTTP GET request and returns only the status code, or None on error. Complexity: network I/O.

fn tcp_connect_str(host: Str, port: Int) -> Result[TcpStream, NetError]

Alias for tcp_connect. Connects to a TCP server at host:port. Complexity: network I/O.

fn is_valid_ipv4(s: Str) -> Bool

Returns true if s is a valid IPv4 address (e.g. "192.168.1.1"). Delegates to the canonical xiom.net.ip4 (parity proven in p_netip_parity). Complexity: O(n). Pure, no side effects.

fn is_valid_port(p: Int) -> Bool

Returns true if p is a valid TCP/UDP port number (1-65535). Complexity: O(1). Pure.

  • Postcondition: result == (p > 0 && p <= 65535)

fn url_parse_scheme(url: Str) -> Option[Str]

Extracts the scheme from a URL (e.g. "https" from "https://example.com"). Returns None if the URL is malformed. Complexity: O(n). Pure.

fn url_parse_host(url: Str) -> Option[Str]

Extracts the host from a URL (e.g. "example.com" from "https://example.com/path"). Returns None if the URL is malformed. Complexity: O(n). Pure.

fn url_parse_path(url: Str) -> Option[Str]

Extracts the path from a URL (e.g. "/path" from "https://example.com/path"). Returns None if the URL is malformed. Complexity: O(n). Pure.

fn url_parse_port(url: Str) -> Option[Int]

Extracts the port from a URL (e.g. 8080 from "https://example.com:8080/path"). Returns None if the URL is malformed or has no explicit port. Complexity: O(n). Pure.

fn dns_lookup(host: Str) -> Result[Vec[Str], NetError]

Resolves a hostname to a list of IP addresses. Delegates to resolve_host. Complexity: DNS network I/O.

ntp.xi

type NtpPacket

struct NtpPacket { li: Int; vn: Int; mode: Int; stratum: Int; poll: Int; precision: Int; root_delay: Float64; root_dispersion: Float64; ref_id: Int; ref_timestamp: Int; origin_timestamp: Int; recv_timestamp: Int; transmit_timestamp: Int } Timestamps are 64-bit NTP era timestamps (seconds since 1900-01-01).

Field Type
li Int
vn Int
mode Int
stratum Int
poll Int
precision Int
root_delay Float64
root_dispersion Float64
ref_id Int
ref_timestamp Int
origin_timestamp Int
recv_timestamp Int
transmit_timestamp Int
fn ntp_packet_new() -> NtpPacket

Build a client request packet with the current transmit time. Returns: an NtpPacket with LI=0, VN=4, Mode=3 (client), a zeroed header and the transmit timestamp set to the current NTP time. Complexity: O(1). Pure.

fn ntp_packet_to_bytes(p: NtpPacket) -> Vec[UInt8]

Serialize an NTP packet to 48 bytes (RFC 5905 wire format). Parameters: p -- the packet. Returns: the 48-byte big-endian packet. Complexity: O(1). Pure.

fn ntp_packet_from_bytes(data: &Vec[UInt8]) -> Result[NtpPacket, Str]

Parse a 48-byte NTP packet. Parameters: data -- at least 48 bytes of packet data. Returns: Ok(NtpPacket) for a readable packet, Err when too short. Complexity: O(1). Pure.

fn ntp_validate(p: NtpPacket) -> Bool

Sanity-check a received packet. Parameters: p -- the packet. Returns: true when the version is 1..4, the mode is 1..7 (reserved 0 excluded) and the transmit timestamp is non-zero. Complexity: O(1). Pure.

fn ntp_offset(packet: NtpPacket, local_t0: Int, local_t1: Int) -> Float64

Compute the clock offset in seconds (RFC 5905: (T2 - T1) + (T3 - T4)) / 2. Parameters: packet -- the server reply; local_t0 -- the client transmit time (unix seconds); local_t1 -- the client receive time (unix seconds). Returns: the offset in seconds (positive = local clock is behind). Complexity: O(1). Pure.

fn ntp_roundtrip(packet: NtpPacket, local_t0: Int, local_t1: Int) -> Float64

Compute the roundtrip delay in seconds (RFC 5905: (T4 - T1) - (T3 - T2)). Parameters: packet -- the server reply; local_t0 -- the client transmit time (unix seconds); local_t1 -- the client receive time (unix seconds). Returns: the roundtrip delay in seconds. Complexity: O(1). Pure.

fn ntp_request(server: Str) -> Result[NtpPacket, Str]

Send an NTP request and read the reply packet. NOT IMPLEMENTED: requires a UDP socket layer that the pure stdlib does not expose. Use ntp_packet_new / ntp_packet_to_bytes / ntp_packet_from_bytes for offline encode/decode. Returns: Err("ntp_request: UDP sockets not available in the pure stdlib").

fn ntp_sync_time(server: Str) -> Result[Int, Str]

Fetch the server time as a unix timestamp. NOT IMPLEMENTED: requires the UDP socket layer (see ntp_request). Returns: Err("ntp_sync_time: UDP sockets not available in the pure stdlib").

fn sntp_request(server: Str) -> Result[Int, Str]

One-shot SNTP client returning a unix timestamp. NOT IMPLEMENTED: requires the UDP socket layer (see ntp_request). Returns: Err("sntp_request: UDP sockets not available in the pure stdlib").

ping.xi

type PingStats

struct PingStats { sent: Int; received: Int; min_ms: Int; avg_ms: Int; max_ms: Int }

Field Type
sent Int
received Int
min_ms Int
avg_ms Int
max_ms Int
fn icmp_checksum(data: &Vec[UInt8]) -> UInt16

Compute the ICMP header checksum (RFC 1071 one's-complement sum). Parameters: data -- the packet bytes (the checksum field should be zero). Returns: the 16-bit checksum. Complexity: O(n). Pure.

fn ping_send_echo(host: Str, id: Int, seq: Int, payload: &Vec[UInt8]) -> Result[Int, Str]

Send one ICMP echo request. NOT IMPLEMENTED: requires raw sockets (ICMP) that the pure stdlib does not expose. Returns: Err("ping_send_echo: raw sockets not available in the pure stdlib").

fn ping_recv_echo(timeout_ms: Int) -> Result[(Int, Int, Int), Str]

Wait for one echo reply. NOT IMPLEMENTED: requires raw sockets (ICMP) that the pure stdlib does not expose. Returns: Err("ping_recv_echo: raw sockets not available in the pure stdlib").

fn ping_once(host: Str, timeout_ms: Int) -> Result[Int, Str]

Send one echo and return the round-trip time in milliseconds. NOT IMPLEMENTED: requires raw sockets (see ping_send_echo). Returns: Err("ping_once: raw sockets not available in the pure stdlib").

fn ping(host: Str, timeout_ms: Int) -> Result[PingStats, Str]

Run a ping burst and return aggregate stats. NOT IMPLEMENTED: requires raw sockets (see ping_send_echo). Returns: Err("ping: raw sockets not available in the pure stdlib").

fn traceroute_hop(host: Str, ttl: Int, timeout_ms: Int) -> Result[Str, Str]

Probe a single hop and return its address. NOT IMPLEMENTED: requires raw sockets (see ping_send_echo). Returns: Err("traceroute_hop: raw sockets not available in the pure stdlib").

fn traceroute(host: Str, max_hops: Int, timeout_ms: Int) -> Result[Vec[Str], Str]

Trace the route to a host by hop. NOT IMPLEMENTED: requires raw sockets (see ping_send_echo). Returns: Err("traceroute: raw sockets not available in the pure stdlib").

proto.xi

fn jsonrpc_request(id: Int, method: Str, params_json: Str) -> Str

jsonrpc_request builds a JSON-RPC 2.0 request object. The params value is embedded verbatim as pre-serialized JSON.

fn jsonrpc_success(id: Int, result_json: Str) -> Str

jsonrpc_success builds a JSON-RPC 2.0 success response. The result value is embedded verbatim as pre-serialized JSON.

fn jsonrpc_error(id: Int, code: Int, message: Str) -> Str

jsonrpc_error builds a JSON-RPC 2.0 error response.

fn sse_format_event(event: Str, data: Str) -> Str

sse_format_event formats an SSE event with an "event:" line followed by "data:" lines and a terminating blank line.

fn sse_format_data(data: Str) -> Str

sse_format_data formats a single SSE data message with a terminating blank line.

fn http_header_parse(headers: Str) -> Vec[(Str, Str)]

http_header_parse parses a block of "Name: value" lines (one per line, '\r' tolerated) into (name, value) pairs. Blank lines are skipped.

fn http_header_get(headers: Vec[(Str, Str)], name: Str) -> Option[Str]

http_header_get finds the value for a header name in a parsed header list, matching case-insensitively and returning the first match.

fn basic_auth_header(username: Str, password: Str) -> Str

basic_auth_header builds a "Basic " Authorization header value.

fn bearer_auth_header(token: Str) -> Str

bearer_auth_header builds a "Bearer " Authorization header value.

fn http_status_text(code: Int) -> Str

http_status_text maps an HTTP status code to its standard reason phrase, or "Unknown" for codes not in the table.

server.xi

fn server_default_port() -> Int

server_default_port returns the default HTTP server port (80). Complexity: O(1). Pure.

fn server_parse_request_line(line: Str) -> Option[(Str, Str, Str)]

server_parse_request_line parses an HTTP request line like "GET /path HTTP/1.1" into (method, target, version). Returns None if the line does not contain three space-separated tokens. Complexity: O(n). Pure.

fn server_build_status_line(code: Int) -> Str

server_build_status_line builds a status line like "HTTP/1.1 200 OK". Complexity: O(1). Pure.

fn server_build_response(code: Int, body: Str) -> Str

server_build_response builds a minimal HTTP/1.1 response with a text/plain body. Complexity: O(n). Pure.

fn server_build_response_headers(code: Int, headers: &Vec[(Str, Str)], body: Str) -> Str

server_build_response_headers builds an HTTP/1.1 response with custom (name, value) header pairs and a text body. Complexity: O(n). Pure.

fn server_status_text(code: Int) -> Str

server_status_text returns the standard reason phrase for a status code, or "Unknown" for codes not in the table. Complexity: O(1).

smtp.xi

fn smtp_default_port() -> Int

smtp_default_port returns the default SMTP port (25). Complexity: O(1). Pure.

fn smtp_command_helo(host: Str) -> Str

smtp_command_helo formats a HELO command. Complexity: O(1). Pure.

fn smtp_command_ehlo(host: Str) -> Str

smtp_command_ehlo formats an EHLO command. Complexity: O(1). Pure.

fn smtp_command_mail_from(addr: Str) -> Str

smtp_command_mail_from formats a MAIL FROM command with an address. Complexity: O(1). Pure.

fn smtp_command_rcpt_to(addr: Str) -> Str

smtp_command_rcpt_to formats a RCPT TO command with an address. Complexity: O(1). Pure.

fn smtp_command_data() -> Str

smtp_command_data formats a DATA command. Complexity: O(1). Pure.

fn smtp_command_quit() -> Str

smtp_command_quit formats a QUIT command. Complexity: O(1). Pure.

fn smtp_command_noop() -> Str

smtp_command_noop formats a NOOP command. Complexity: O(1). Pure.

fn smtp_command_rset() -> Str

smtp_command_rset formats a RSET command. Complexity: O(1). Pure.

fn smtp_command_auth_login() -> Str

smtp_command_auth_login formats an AUTH LOGIN command. Complexity: O(1). Pure.

fn smtp_body_end() -> Str

smtp_body_end formats the end-of-data marker (dot on its own line). Complexity: O(1). Pure.

fn smtp_parse_reply(line: Str) -> Option[(Int, Str)]

smtp_parse_reply parses an SMTP reply line like "250 OK" into (code, text). Returns None if the line does not start with a 3-digit code. Complexity: O(1). Pure.

fn smtp_reply_is_success(code: Int) -> Bool

smtp_reply_is_success returns true for 2xx replies. Complexity: O(1). Pure.

socket.xi

fn socket_tcp() -> Result[Int, Str]

socket_tcp creates a TCP socket and returns its fd, or Err. Complexity: O(1) syscall.

fn socket_udp() -> Result[Int, Str]

socket_udp creates a UDP socket and returns its fd, or Err. Complexity: O(1) syscall.

fn socket_bind(fd: Int, addr: Str, port: Int) -> Result[Unit, Str]

socket_bind binds a socket to addr:port. The runtime binds to the given port on the wildcard address; the addr string is validated for non-emptiness. Complexity: O(1) syscall.

fn socket_listen(fd: Int, backlog: Int) -> Result[Unit, Str]

socket_listen marks a bound TCP socket as listening. Complexity: O(1) syscall.

fn socket_accept(fd: Int) -> Result[Int, Str]

socket_accept accepts a connection and returns the new socket fd. Complexity: O(1) blocking syscall.

fn socket_connect(fd: Int, addr: Str, port: Int) -> Result[Unit, Str]

socket_connect connects a socket to a remote addr:port. Complexity: O(1) syscall.

fn socket_send(fd: Int, data: &Vec[UInt8]) -> Result[Int, Str]

socket_send sends bytes on a socket; returns the count written. Complexity: O(n) syscall.

fn socket_recv(fd: Int, max: Int) -> Result[Vec[UInt8], Str]

socket_recv receives up to max bytes; returns the bytes received. Complexity: O(n) blocking syscall.

fn socket_send_to(fd: Int, data: &Vec[UInt8], addr: Str, port: Int) -> Result[Int, Str]

socket_send_to sends a datagram to addr:port; returns the count written. Complexity: O(n) syscall.

fn socket_recv_from(fd: Int, max: Int) -> Result[(Vec[UInt8], Str, Int), Str]

socket_recv_from receives a datagram; the tuple is (data, peer_addr, peer_port). Complexity: O(n) blocking syscall.

fn socket_close(fd: Int)

socket_close closes a socket, releasing the fd. Complexity: O(1) syscall.

fn socket_set_timeout(fd: Int, ms: Int) -> Result[Unit, Str]

socket_set_timeout sets the receive timeout in milliseconds. The runtime does not expose SO_RCVTIMEO; always returns a documented Err.

fn socket_set_nonblocking(fd: Int, on: Bool) -> Result[Unit, Str]

socket_set_nonblocking enables or disables non-blocking mode. The runtime does not expose FIONBIO/O_NONBLOCK; always returns a documented Err.

fn socket_shutdown(fd: Int, how: Int) -> Result[Unit, Str]

socket_shutdown shuts down reading, writing, or both per how (0 = receive, 1 = send, 2 = both). The runtime does not expose shutdown(); always returns a documented Err.

fn socket_peer_addr(fd: Int) -> Result[(Str, Int), Str]

socket_peer_addr returns the connected peer address. The runtime does not expose getpeername(); always returns a documented Err.

fn socket_local_addr(fd: Int) -> Result[(Str, Int), Str]

socket_local_addr returns the bound local address. The runtime does not expose getsockname(); always returns a documented Err.

fn socket_available(fd: Int) -> Int

socket_available returns the number of bytes currently readable without blocking. The runtime does not expose FIONREAD; returns 0.

fn socket_reuse_addr(fd: Int, on: Bool) -> Result[Unit, Str]

socket_reuse_addr enables or disables SO_REUSEADDR. The runtime does not expose setsockopt(); always returns a documented Err.

sse.xi

type SseConnection

struct SseConnection { socket: TcpStream; url: Str; open: Bool }

Field Type
socket net.TcpStream
url Str
open Bool
type SseEvent

struct SseEvent { id: Str; event: Str; data: Str; retry: Int }

Field Type
id Str
event Str
data Str
retry Int
fn sse_parse_event(chunk: Str) -> Result[SseEvent, Str]

Parse one raw event chunk. Parameters: chunk -- a raw event block (a sequence of "field: value" lines ending with a blank line). Returns: Ok(SseEvent) for a well-formed chunk, Err for an empty chunk. Complexity: O(n). Pure.

fn sse_event_id(e: SseEvent) -> Option[Str]

Return the event id field. Parameters: e -- the event. Returns: Some(id) when the id is non-empty, None otherwise. Complexity: O(1). Pure.

fn sse_event_data(e: SseEvent) -> Str

Return the event data field. Parameters: e -- the event. Returns: the data field (possibly ""). Complexity: O(1). Pure.

fn sse_connect(url: Str) -> Result[SseConnection, Str]

Open a text/event-stream connection. NOT IMPLEMENTED: requires a live TCP connection that the pure stdlib does not manage. Returns: Err("sse_connect: TCP connections not available in the pure stdlib").

fn sse_connect_headers(url: Str, headers: &Vec[(Str, Str)]) -> Result[SseConnection, Str]

Connect with custom request headers. NOT IMPLEMENTED: requires a live TCP connection (see sse_connect). Returns: Err("sse_connect_headers: TCP connections not available in the pure stdlib").

fn sse_read_event(conn: SseConnection) -> Result[SseEvent, Str]

Read and parse the next event. NOT IMPLEMENTED: requires a live connection (see sse_connect). Returns: Err("sse_read_event: connection not available in the pure stdlib").

fn sse_close(conn: SseConnection)

Close the event stream connection. NO-OP: no live connection exists in the pure stdlib.

fn sse_read_events(conn: SseConnection, out: &mut Vec[SseEvent]) -> Int

Drain available events into out and return the count. NOT IMPLEMENTED: requires a live connection (see sse_connect). Always returns 0 with the output vector untouched.

tcp.xi

fn tcp_validate_port(p: Int) -> Bool

tcp_validate_port returns true if p is a valid TCP port (1-65535). Complexity: O(1). Pure.

fn tcp_is_valid_port(p: Int) -> Bool

tcp_is_valid_port is an alias for tcp_validate_port. Complexity: O(1). Pure.

fn tcp_parse_endpoint(s: Str) -> Option[(Str, Int)]

tcp_parse_endpoint splits a "host:port" string into (host, port). Returns None if no colon or a malformed port is present. The host may be empty (an empty host string is rejected). Complexity: O(n). Pure.

fn tcp_format_endpoint(host: Str, port: Int) -> Str

tcp_format_endpoint builds a "host:port" string. Complexity: O(1). Pure.

tls.xi

fn tls_default_port() -> Int

tls_default_port returns the default TLS port (443). Complexity: O(1). Pure.

fn tls_version_name(version: Int) -> Str

tls_version_name maps a TLS version code point to its name. Recognised values: 0x0301 TLSv1.0, 0x0302 TLSv1.1, 0x0303 TLSv1.2, 0x0304 TLSv1.3. Unknown values return "unknown". Complexity: O(1).

fn tls_handshake_type_name(t: Int) -> Str

tls_handshake_type_name maps a TLS handshake message type to its name. Complexity: O(1).

fn tls_alert_name(code: Int) -> Str

tls_alert_name maps a TLS alert description to its name per RFC 5246 and RFC 8446. Complexity: O(1).

fn tls_cipher_suite_name(code: Int) -> Str

tls_cipher_suite_name maps a TLS cipher suite code to a human-readable name for the most common suites, or "unknown" (0x0000- 0xFFFF, two-byte IANA code). Complexity: O(1).

tls_helper.xi

fn der_length_decode(data: &Vec[UInt8], pos: Int) -> Result[(Int, Int), Str]

Read a DER length at pos. Parameters: data -- the DER bytes; pos -- the position of the length octet. Returns: Ok((length, bytes_consumed)) for short and long forms; Err for indefinite lengths or truncated input. Complexity: O(1). Pure.

fn asn1_read_oid(data: &Vec[UInt8], pos: Int) -> Result[(Vec[Int], Int), Str]

Read an ASN.1 object identifier at pos. Parameters: data -- the DER bytes; pos -- the position of the OID tag. Returns: Ok((oid components, next_pos)) on success, Err on malformed input. Complexity: O(n). Pure.

fn cert_fingerprint_sha256(der: &Vec[UInt8]) -> Vec[UInt8]

SHA-256 fingerprint of a DER certificate. Parameters: der -- the certificate DER bytes. Returns: the 32-byte SHA-256 digest. Complexity: O(n). Pure.

fn cert_fingerprint_sha1(der: &Vec[UInt8]) -> Vec[UInt8]

SHA-1 fingerprint of a DER certificate. NOT AVAILABLE: xiom.crypto does not provide SHA-1. Returns an empty vector. Complexity: O(1). Pure.

fn cert_validity_dates(der: &Vec[UInt8]) -> Result[(Str, Str), Str]

Certificate validity period. Parameters: der -- the certificate DER bytes. Returns: Ok((not_before, not_after)) as ASN.1 time strings, Err when the structure cannot be parsed. Complexity: O(n). Pure.

fn cert_subject_cn(der: &Vec[UInt8]) -> Result[Str, Str]

The common name of the certificate subject. Parameters: der -- the certificate DER bytes. Returns: Ok(CN) on success, Err when unparseable or missing. Complexity: O(n). Pure.

fn cert_issuer_cn(der: &Vec[UInt8]) -> Result[Str, Str]

The common name of the certificate issuer. Parameters: der -- the certificate DER bytes. Returns: Ok(CN) on success, Err when unparseable or missing. Complexity: O(n). Pure.

fn cert_public_key_info(der: &Vec[UInt8]) -> Result[(Str, Int), Str]

Public key metadata for a certificate. Parameters: der -- the certificate DER bytes. Returns: Ok((algorithm, bits)) on success, Err when unparseable. Complexity: O(n). Pure.

fn cert_is_self_signed(der: &Vec[UInt8]) -> Bool

True when subject equals issuer (by common name comparison). Parameters: der -- the certificate DER bytes. Returns: true when both subject and issuer CNs parse and match; false otherwise (including unparseable input). Complexity: O(n). Pure.

fn pem_encode(der: &Vec[UInt8], label: Str) -> Str

Wrap DER bytes in a PEM armor with the given label. Parameters: der -- the DER bytes; label -- the PEM label (e.g. "CERTIFICATE"). Returns: the PEM string with 64-column base64 lines. Complexity: O(n). Pure.

fn pem_decode(pem: Str) -> Result[Vec[UInt8], Str]

Strip PEM armor and return the DER bytes. Parameters: pem -- the PEM string. Returns: Ok(DER bytes) on success, Err when no matching block is found. Complexity: O(n). Pure.

fn pem_parse_certificates(pem: Str) -> Result[Vec[Vec[UInt8]], Str]

Extract every certificate block from a PEM string. Parameters: pem -- the PEM string. Returns: Ok(the DER bytes of each CERTIFICATE block) on success, Err when no certificate block is present. Complexity: O(n). Pure.

udp.xi

fn udp_validate_port(p: Int) -> Bool

udp_validate_port returns true if p is a valid UDP port (1-65535). Complexity: O(1). Pure.

fn udp_is_valid_port(p: Int) -> Bool

udp_is_valid_port is an alias for udp_validate_port. Complexity: O(1). Pure.

fn udp_parse_endpoint(s: Str) -> Option[(Str, Int)]

udp_parse_endpoint splits a "host:port" string into (host, port). Returns None if no colon or a malformed port is present. Complexity: O(n). Pure.

fn udp_format_endpoint(host: Str, port: Int) -> Str

udp_format_endpoint builds a "host:port" string. Complexity: O(1). Pure.

unix.xi

type UnixSocket

struct UnixSocket { fd: Int; path: Str; listening: Bool }

Field Type
fd Int
path Str
listening Bool
fn unix_connect(path: Str) -> Result[UnixSocket, Str]

Connect to a listening unix socket. NOT IMPLEMENTED: requires the AF_UNIX socket layer (not available in the pure stdlib). Returns: Err("unix_connect: AF_UNIX sockets not available in the pure stdlib").

fn unix_listen(path: Str) -> Result[UnixSocket, Str]

Create a listening socket on a path. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_listen: AF_UNIX sockets not available in the pure stdlib").

fn unix_accept(sock: UnixSocket) -> Result[UnixSocket, Str]

Accept an incoming connection. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_accept: AF_UNIX sockets not available in the pure stdlib").

fn unix_send(sock: UnixSocket, data: &Vec[UInt8]) -> Result[Int, Str]

Write bytes to a socket. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_send: AF_UNIX sockets not available in the pure stdlib").

fn unix_recv(sock: UnixSocket, max: Int) -> Result[Vec[UInt8], Str]

Read up to max bytes from a socket. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_recv: AF_UNIX sockets not available in the pure stdlib").

fn unix_close(sock: UnixSocket)

Close a socket and its fd. NO-OP: no live sockets exist in the pure stdlib.

fn unix_bind(path: Str) -> Result[UnixSocket, Str]

Bind a socket to a path. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_bind: AF_UNIX sockets not available in the pure stdlib").

fn unix_connect_timeout(path: Str, timeout_ms: Int) -> Result[UnixSocket, Str]

Connect with a timeout. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_connect_timeout: AF_UNIX sockets not available in the pure stdlib").

fn unix_socketpair() -> Result[(UnixSocket, UnixSocket), Str]

Create an anonymous connected pair. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_socketpair: AF_UNIX sockets not available in the pure stdlib").

fn unix_peer_credentials(sock: UnixSocket) -> Result[(Int, Int, Int), Str]

Read the peer pid, uid, and gid. NOT IMPLEMENTED: requires the AF_UNIX socket layer (see unix_connect). Returns: Err("unix_peer_credentials: AF_UNIX sockets not available in the pure stdlib").

url.xi

fn url_parse(url: Str) -> Result[UrlParts, Str]

url_parse parses a URL into its scheme/host/port/path/query/fragment components. Userinfo (user:pass@) is skipped.

fn url_decode_component(s: Str) -> Result[Str, Str]

url_decode_component percent-decodes %XX sequences. '+' is left as-is (component semantics -- '+' is only a space in form-encoding).

fn url_encode_component(s: Str) -> Result[Str, Str]

url_encode_component percent-encodes everything except the unreserved characters A-Z a-z 0-9 - _ . ~ (reuses xiom.encoding.percent_encode).

fn url_query_parse(query: Str) -> Vec[(Str, Str)]

url_query_parse splits a query string on '&' and each pair on the first '=', percent-decoding both sides and converting '+' to a space (application/x-www-form-urlencoded semantics).

fn url_query_build(pairs: Vec[(Str, Str)]) -> Str

url_query_build joins key/value pairs as k=v separated by '&', applying component encoding to both keys and values.

fn url_normalize(url: Str) -> Result[Str, Str]

url_normalize lowercases the scheme and host, strips the default port, and removes dot segments from the path. Query and fragment are kept.

fn url_is_absolute(url: Str) -> Bool

url_is_absolute returns true if the URL carries a scheme (a ':' before any '/').

fn url_join(base: Str, relative: Str) -> Result[Str, Str]

url_join resolves a relative reference against a base URL (RFC 3986 S5.3 merge), then normalizes dot segments. If the reference carries its own scheme it is returned unchanged.

websocket.xi

type WsFrame

struct WsFrame { opcode: Int; fin: Bool; masked: Bool; payload: Vec[UInt8] }

Field Type
opcode Int
fin Bool
masked Bool
payload Vec[UInt8]

Derives: Clone

type WsConnection

struct WsConnection { socket: TcpStream; key: Str; open: Bool }

Field Type
fd Int
key Str
open Bool
fn ws_handshake_request(host: Str, path: Str, key: Str) -> Str

ws_handshake_request builds a client upgrade request for the given host, path, and Sec-WebSocket-Key value. Complexity: O(1). Pure.

fn ws_accept_key(key: Str) -> Str

ws_accept_key computes the Sec-WebSocket-Accept value for a client key per RFC 6455: base64(SHA-1(key + GUID)). Complexity: O(n).

fn ws_handshake_verify(response: Str, key: Str) -> Bool

ws_handshake_verify checks a server upgrade response against the client key: the status line must be 101 and the Sec-WebSocket-Accept header must match the computed accept value. Complexity: O(n). Pure.

fn ws_frame_encode(opcode: Int, payload: &Vec[UInt8], mask: Bool) -> Vec[UInt8]

ws_frame_encode serializes one WebSocket frame. When mask is true a random-looking client mask (derived from payload length) is applied. Complexity: O(n). Pure.

fn ws_frame_decode(frame: &Vec[UInt8]) -> Result[WsFrame, Str]

ws_frame_decode parses one WebSocket frame from bytes. Returns Err on truncated or invalid input. Complexity: O(n). Pure.

fn ws_random_key() -> Str

ws_random_key generates a Sec-WebSocket-Key value (base64 of 16 bytes) for use in client handshakes. Deterministic derivation from the current time keeps the module free of external RNG state.

fn ws_parse_url(url: Str) -> Result[(Str, Int, Str), Str]

ws_parse_url splits a ws:// or wss:// URL into host, port, and path. The port is the explicit port when present, otherwise the scheme default. Returns Err for malformed input. Complexity: O(n). Pure.

fn ws_connect(url: Str) -> Result[WsConnection, Str]

ws_connect opens a WebSocket connection to a ws:// or wss:// URL, performing the client handshake. TLS (wss) is not supported by the runtime socket layer; use ws://. Complexity: network I/O.

fn ws_send(conn: &WsConnection, text: Str) -> Result[Unit, Str]

ws_send sends a text message over an open connection. Complexity: network I/O.

fn ws_send_binary(conn: &WsConnection, data: &Vec[UInt8]) -> Result[Unit, Str]

ws_send_binary sends a binary message over an open connection. Complexity: network I/O.

fn ws_recv(conn: &WsConnection) -> Result[WsFrame, Str]

ws_recv receives the next frame from the connection. Complexity: network I/O.

fn ws_close(conn: &WsConnection, code: Int)

ws_close sends a close frame and tears down the connection. Complexity: network I/O.

fn ws_ping(conn: &WsConnection)

ws_ping sends a ping frame. Complexity: network I/O.

fn ws_pong(conn: &WsConnection)

ws_pong sends a pong frame. Complexity: network I/O.

ws.xi

fn ws_default_port(scheme: Str) -> Int

ws_default_port returns the default port for a ws scheme ("ws" -> 80, "wss" -> 443, anything else -> 80). Complexity: O(1). Pure.

fn ws_parse_url(url: Str) -> Result[(Str, Int, Str), Str]

ws_parse_url splits a ws:// or wss:// URL into (host, port, path). The port is the explicit port from the URL when present, otherwise the scheme default. Returns Err for malformed input. Complexity: O(n).

fn ws_build_url(scheme: Str, host: Str, port: Int, path: Str) -> Str

ws_build_url builds a ws:// or wss:// URL from host, port, and path. When port matches the scheme default it is omitted. Complexity: O(1).

fn ws_is_ws_url(url: Str) -> Bool

ws_is_ws_url returns true if url starts with ws://. Complexity: O(n). Pure.

fn ws_is_wss_url(url: Str) -> Bool

ws_is_wss_url returns true if url starts with wss://. Complexity: O(n). Pure.