Seq Standard Library Reference

This document covers:

• Built-in Operations - primitives implemented in the runtime
• Standard Library Modules - Seq code included via include std:<module>

Table of Contents

Built-in Operations

• I/O Operations
• Command-line Arguments
• File Operations
• Type Conversions
• Integer Arithmetic
• Integer Comparison
• Boolean Operations
• Bitwise Operations
• Stack Operations
• Control Flow
• Concurrency
• Channel Operations
• Networking — net.tcp.*
• Networking — net.udp.*
• Networking — net.dns.*
• Networking — net.tls.*
• Networking — Socket type
• OS Operations
• Terminal Operations
• String Operations
• Encoding Operations
• Crypto Operations
• Networking — net.http.* (HTTP client)
• Regular Expressions
• Compression
• Variant Operations
• List Operations
• Map Operations
• Float Arithmetic
• Float Comparison
• Float Math
• Test Framework
• Time Operations
• Serialization
• Stack Introspection

Standard Library Modules

• std:json
• std:yaml
• std:http
• std:list
• std:map
• std:imath
• std:fmath
• std:zipper
• std:signal
• std:son
• std:stack-utils

I/O Operations

Command-line Arguments

File Operations

Directory Operations

Type Conversions

Integer Arithmetic

Division and Modulo Behavior

Division and modulo operations return a result and a success flag:

• Success (true): Operation completed normally, result is valid
• Failure (false): Division by zero, result is 0

Overflow handling: INT_MIN / -1 uses wrapping semantics and returns INT_MIN with success=true. This matches Forth/Factor behavior and avoids undefined behavior.

10 3 i./     # ( -- 3 true )   Normal division
10 0 i./     # ( -- 0 false )  Division by zero
-9223372036854775808 -1 i./  # ( -- -9223372036854775808 true )  Wrapping

Integer Comparison

Boolean Operations

Bitwise Operations

Stack Operations

Control Flow

Concurrency

Channel Operations

Networking — net.tcp.*

All TCP operations return a Bool success flag for error handling. The fd slot is typed as Socket (a phantom over Int) — net.tcp.write will not accept an arbitrary integer.

Note on net.tcp.local-port and Socket id aliasing. Listeners and connected streams live in separate registries that each start their id sequence at 0, so the same Socket integer can refer to different resources depending on which registry holds it. Dispatch for local-port (and for close) is streams-first, then listeners. The practical implication: if you intend to read a listener’s local port, call net.tcp.local-port on it before allocating any connected streams (or stash the result eagerly), otherwise an id that aliases between the two registries will return the stream’s port. Tracked as a broader follow-up; in the meantime treat Socket ids as resource-local, not globally unique.

net.tcp.connect resolves the hostname through net.dns.resolve — the lookup runs on the DNS worker pool, not the may carrier, and tries each returned address in order until one connects (or all fail). IP literals work as hostnames (they round-trip through getaddrinfo without touching DNS). Bool is false on resolution failure, every-address-failed, invalid port (must be 1..65535), or socket-registry exhaustion.

Connect timeout. Each connect attempt is bounded by a default 10s deadline. A peer that silently drops SYNs surfaces as a connect failure in seconds, not the kernel’s full SYN timeout (~60–130s on Linux). Override per-process with SEQ_TCP_CONNECT_TIMEOUT_MS (read once on first use; setting 0 falls back to the default). The bound applies per address — a multi-IP fallback that walks dead addresses sees N × timeout total wall time before giving up.

Known limitation — no happy-eyeballs. Addresses are tried in resolver order. If AAAA (IPv6) points somewhere unreachable on a misconfigured network, the connect-timeout fires per address before falling back to A (IPv4). RFC 8305 happy-eyeballs would parallelise this; it’s a planned follow-up.

"example.com" 443 net.tcp.connect
[ # ( socket )
  "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n" over net.tcp.write drop
  dup net.tcp.read
  [ io.write-line ]
  [ drop "read failed" io.write-line ]
  if
  net.tcp.close drop
]
[ drop "connect failed" io.write-line ]
if

Networking — net.udp.*

Datagram-oriented; sockets are Socket handles. Every word ends with a success Bool on top so callers can [ ... ] [ ... ] if.

net.udp.send-to host resolution. Hostnames in the host argument are resolved through net.dns.resolve — the may-aware DNS worker pool — so the carrier thread does not park on a blocking getaddrinfo. IP literals work without DNS round-trip. If resolution returns multiple addresses (e.g. localhost → ::1, 127.0.0.1) the addresses are tried in order; the first send_to that doesn’t error wins, which transparently handles the case of a v4-only socket reached through a name that resolves v6-first.

Note: for UDP, send_to returning OK means the kernel accepted the datagram for the chosen address family — it does not confirm peer receipt. The multi-address walk therefore catches local-side errors (address-family mismatch, route-not-found) but cannot detect an unreachable peer past the first successful queue.

Networking — net.dns.*

Hostname resolution offloaded to a dedicated OS-thread pool so may carriers never park on getaddrinfo. A small TTL cache (60s, max 256 entries) collapses fanout to the same host. Inherits all platform-correct resolution behaviour (/etc/hosts, systemd-resolved, VPN/corp DNS, mDNS) from libc.

The list contains IP-string representations ("127.0.0.1", "::1", …). IP literals fast-path through getaddrinfo without touching DNS.

Worker count is configurable via SEQ_DNS_WORKERS (default 8, max 64). SEQ_DNS_WORKERS=0 is treated as unset and falls back to the default — disabling the pool makes no architectural sense since the syscall has to run somewhere off the may carrier.

Fanout collapsing. Both sequential and concurrent fanout collapse to a single getaddrinfo. The TTL cache catches the sequential case. An in-flight map keyed by hostname catches the concurrent case: when N strands race to resolve the same uncached host, the first to arrive enqueues exactly one worker job and the others attach to the in-flight entry. When the worker returns it writes the cache and fans the result out to every attached strand.

IP-literal fast path. Callers that go through net.dns.resolve indirectly (via net.tcp.connect, net.udp.send-to, or the HTTP client’s SSRF validator) bypass the worker pool entirely when the host string is an IP literal — dns::resolve_to_ips parses the literal and returns it directly. The pool round-trip is reserved for actual DNS work.

"api.example.com" net.dns.resolve
[ "first IP: " io.write list.first
  [ io.write-line ] [ drop "no addresses" io.write-line ] if ]
[ "resolution failed" io.write-line ]
if

Networking — net.tls.*

TLS client upgrade for an already-connected Socket. The handshake runs eagerly inside the builtin (via rustls::ClientConnection::complete_io over the underlying may-aware TCP stream) so transport errors, bad certificates, hostname mismatches, and any other TLS-layer failure surface as (0, false) — matching every other fallible networking word. After a successful upgrade, the existing net.tcp.read / net.tcp.write / net.tcp.close operate on the returned Socket transparently — the runtime dispatches reads and writes through rustls. Trust roots come from webpki-roots.

Handshake timeout. Each individual read/write inside the rustls handshake is bounded by a default 10s deadline. A peer that accepts the TCP connection but goes silent mid-handshake surfaces as a handshake failure within that bound, rather than parking the strand indefinitely. Override with SEQ_TLS_HANDSHAKE_TIMEOUT_MS. (The per-IO budget applies to each round of the handshake, not the entire exchange — a slow but progressing handshake completes; a stalled one fails.)

Known limitations (v1):

• net.tcp.close on a TLS socket is a hard close. The underlying TCP stream is dropped without first sending the TLS close_notify alert (RFC 5246 expects clients to send it). Modern servers tolerate truncation; some older stacks log it as a truncation-attack indicator. A graceful-shutdown variant is a planned follow-up.
• IP-literal hostnames syntactically work but almost always fail validation. ServerName::try_from parses "1.2.3.4" cleanly, but cert validation against an IP requires the peer cert to carry that IP in a SubjectAltName entry — vanishingly rare for public-internet certs. Use a DNS name unless you control the peer cert.
• No client-certificate authentication (mTLS). A with_no_client_auth() config is used unconditionally. mTLS is a planned follow-up.
• No caller-side ALPN selection. Whatever rustls defaults negotiate (typically h2 / http/1.1 if the peer offers them) is what you get; there’s no way to ask for or reject a specific protocol.
• No peer-certificate or cipher inspection from Seq. Once the handshake succeeds, only the upgraded Socket is exposed — the negotiated suite, peer cert chain, SNI accepted, etc., are not surfaced.
• No session resumption knobs. rustls’s default in-process session cache applies; there’s no Seq-level control.

"example.com" 443 net.tcp.connect
[ # ( socket )
  "example.com" net.tls.client
  [ # ( socket )
    "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n" over net.tcp.write drop
    dup net.tcp.read
    [ io.write-line ]
    [ drop "read failed" io.write-line ]
    if
    net.tcp.close drop
  ]
  [ drop "TLS handshake failed" io.write-line ]
  if
]
[ drop "connect failed" io.write-line ]
if

Networking — Socket type

Socket is a compile-time-only nominal wrapper over the Int file descriptor; the runtime representation stays Value::Int(fd). This means the type checker rejects 42 net.tcp.write. Two escape hatches exist for FFI / debugging:

OS Operations

Terminal Operations

String Operations

Encoding Operations

Crypto Operations

Networking — net.http.* (HTTP client)

The HTTP client lives under net.http.*. The std:http stdlib module provides server-side response/parsing helpers (http-ok, http-request-path, …) and is unrelated.

The client is hand-rolled HTTP/1.1 over the may-aware TCP and TLS primitives (see net.tcp.connect, net.tls.client). Every IO step yields the strand cooperatively; the request never parks the carrier thread. Hostname resolution and SSRF validation run through the net.dns.* worker pool, so there is exactly one getaddrinfo per request and it runs off the may carrier.

Response Map shape:

• "status" (Int): HTTP status code, or 0 on connection-level error.
• "body" (String): response body as raw bytes (byte-clean — binary downloads round-trip intact; decode as text yourself if you expected text).
• "ok" (Bool): true iff status is in 200..300.
• "error" (String): error message; present only on failure.

Connection pool. Keep-alive connections are pooled by (scheme, host, port) between requests. A second net.http.get against the same origin skips the TCP and TLS handshakes when an idle entry is available. Defaults:

• 8 idle connections per (scheme, host, port)
• 30s idle timeout
• 256 idle connections globally
• MRU checkout (freshest pooled connection used first)
• Non-blocking half-closed peek on reuse: if the peer FIN’d the socket while it sat idle, the entry is dropped and a fresh connection is dialled.

SSRF protection. Requests are blocked when the URL’s host resolves to a loopback (127.0.0.0/8, ::1), private (10/8, 172.16/12, 192.168/16), link-local (169.254/16, including cloud metadata endpoints), or unique-local (fc00::/7) IP. Schemes outside http/https are rejected. The check runs against the addresses the DNS layer already returned — no second resolution on the carrier.

v1 limitations:

• No redirect following. A 3xx response is returned to the caller as-is, with Location available in the body or via your own header parser.
• No automatic decompression. The client sends Accept-Encoding: identity. If you want gzip transfer, set up your own request and decompress with compress.gunzip.
• Per-IO request/response timeout (default 30s). Each individual read/write inside the wire layer (request send, response header read, every chunk read for chunked transfers, every read for EOF-framed bodies) is bounded by this deadline. A peer that goes silent mid-response — no bytes for timeout — surfaces as a wire error within the bound. Override with SEQ_HTTP_REQUEST_TIMEOUT_MS. The deadline is per-IO, not total: a peer that drips one byte every timeout − ε keeps each read under budget and so isn’t caught by this bound — practically, the residual exposure is capped at MAX_BODY_SIZE (10 MB) reads × timeout. A total-time deadline is a planned follow-up; today the per-IO bound covers the “goes fully silent” hazard, not the slow-trickle-but-progressing one.
• No custom request headers. Only Host, User-Agent, Accept, Accept-Encoding, Connection, and (for POST/PUT) Content-Type + Content-Length are sent. Content-Type rejects control characters in the value to prevent header injection. A header-bag API is a planned follow-up.
• No client certificate auth, ALPN selection, or peer-cert inspection. Inherited from net.tls.client.
• POST is not auto-retried on transient transport failure; GET/PUT/DELETE are (idempotent per RFC 9110). A POST that fails mid-flight surfaces as a connection error.

Regular Expressions

All regex operations return a Bool success flag (false for invalid regex).

Compression

Variant Operations

List Operations

Map Operations

Float Arithmetic

Float Comparison

Float Math

NaN/Infinity propagate per IEEE 754 — no (value Bool) flag. e.g. f.sqrt of a negative returns NaN; f.ln 0.0 returns -Infinity.

Roots / powers

Exponential / logarithmic

Trigonometric (radians)

Rounding

Constants

Test Framework

Time Operations

Serialization

Stack Introspection

Standard Library Modules

These modules are included with include std:<module-name>.

std:json - JSON Parsing

JSON parsing and serialization implemented in Seq.

include std:json

"hello" json-string json-serialize io.write-line  # "hello"
"{\"name\":\"bob\"}" json-parse drop json-serialize io.write-line

Value Constructors

Builders

Type Predicates

Extractors

Parsing & Serialization

std:yaml - YAML Parsing

YAML parsing for configuration files and data.

include std:yaml

"name: hello\nport: 8080" yaml-parse drop yaml-serialize io.write-line

Supports: key-value pairs, nested objects (indentation), strings, numbers, booleans, null, comments.

std:http - HTTP Response Helpers

Helper functions for building HTTP servers.

include std:http

"Hello, World!" http-ok   # Returns full HTTP 200 response
request http-request-path # Extract path from request

Response Building

Request Parsing

std:list - List Utilities

Convenient words for building lists.

include std:list

list-of 1 lv 2 lv 3 lv  # Build [1, 2, 3]

std:map - Map Utilities

No additional utilities beyond the built-in Map Operations.

std:imath - Integer Math

Common mathematical operations for integers.

include std:imath

-5 abs            # 5
48 18 gcd         # 6
15 0 100 clamp    # 15

For modulo and power, use the i.modulo and i.pow builtins directly (( Int Int -- Int Bool ) — see the Integer Arithmetic section above).

std:fmath - Float Math

Common mathematical operations for floats.

include std:fmath

-3.14 f.abs       # 3.14
2.5 3.7 f.max     # 3.7
1.5 f.square      # 2.25

For sqrt, trig, exp/log, rounding, and constants (f.pi, f.e, f.tau), see the Float Math builtin section above — those are always available without an include.

std:zipper - Functional List Zipper

A zipper provides O(1) cursor movement and “editing” of immutable lists by maintaining a focus element with left and right context.

include std:zipper

list-of 1 lv 2 lv 3 lv 4 lv 5 lv
zipper.from-list
zipper.right zipper.right   # focus is now 3
zipper.focus                # get current element (3)
10 zipper.set               # replace focus with 10
zipper.to-list              # [1, 2, 10, 4, 5]

Construction

Navigation

Query

Modification

std:signal - Signal Handling

Unix signal handling with a safe, flag-based API.

include std:signal

signal.trap-shutdown  # Trap SIGINT and SIGTERM

: server-loop ( -- )
  signal.shutdown-requested? if
    "Shutting down..." io.write-line
  else
    handle-request
    server-loop
  then
;

Signal Constants (builtins)

Convenience Words

std:son - Seq Object Notation Helpers

Convenience module that re-exports std:map and std:list, providing all the builder words needed for SON data construction.

include std:son

map-of "host" "localhost" kv "port" 8080 kv
list-of 1 lv 2 lv 3 lv

Including std:son gives you map-of, kv, list-of, and lv.

Security warning: SON files are executable Seq code. Only load SON from trusted sources.

std:stack-utils - Stack Utilities

Common stack operations built from primitives.

include std:stack-utils

1 2 3 2drop  # Stack: 1

Built-in operations: 152 total. Standard library modules provide additional functionality.