Standard library

import std/file
import std/http
import std/http/websocket
import std/io
import std/net

fn handle(req: http.Request) -> http.Response {
    if req.path == "/chat" {
        using ws = websocket.accept(req) catch {
            _ => return http.response(400, "")
        }
        let m = websocket.receive(ws) catch {
            _ => return http.upgraded()
        }
        websocket.send_text(ws, str(m.data)) catch {
            _ => {}
        }
        return http.upgraded()
    }
    http.response(200, file.read_text("index.html") catch "missing")
}

fn main() ! io.Error {
    let client = http.client().with_bearer_token("token").with_timeout(5000).build()
    let page = client.get("https://example.com/") catch {
        _ => return
    }
    using l = net.listen("", 8080)?
    http.serve(l, handle)?
}

import std/<name> loads a standard library module. The library is compiled into low, and the project root is not searched for it.

Every module except std/math and std/sql/sqlite talks to the kernel through raw syscalls. std/math calls libm and std/sql/sqlite calls libsqlite3 through extern blocks. A library is linked only when reachable code calls it, so a program stays static unless it calls one of their C functions.

Resource ownership

Every standard library resource that must be disposed of is a droppable owner bound with using. defer is for work that is not disposal: unlocking a lock, signalling a channel, restoring ambient state and logging.

• An owner keeps the resource's name (file.File, net.Conn, net.Listener, net.Socket, tls.Session, http.Connection, websocket.Socket, process.Child, cancel.Registration, pipe.Reader, pipe.Writer, sqlite.Database, sql.Connection, cdp.Browser, otel.Sdk) and holds its view in a public handle field. Its drop closes through the handle.
• A view is named <Owner>Handle: FileHandle, ConnHandle, ListenerHandle, SocketHandle, SessionHandle, ChildHandle, RegistrationHandle, ReaderHandle, WriterHandle, DatabaseHandle, ConnectionHandle, BrowserHandle and SdkHandle. SocketHandle names the view in both net and websocket. A view is a copyable struct, or a pointer to the shared state when that state is mutable, so closures capture it, slices, channels, optionals and pointer-held structs store it, and spawn takes it. A view never closes anything on its own.
• Operations a caller uses directly take the owner and borrow it: net.read(c, buf). Operations that run after ownership has moved elsewhere (green threads, io.Stream closures, pools, callbacks) take the view and end in _on: net.read_on(h, buf), net.stream_on(h), net.close_on(h). A function that returns a view without an owner ends in _handle: net.accept_handle, tls.client_handle, cdp.launch_handle. adopt(h) makes an owner from a view. detach(mut owner) gives up an owner's responsibility so a function that opened a resource and wrapped it can return the wrapper.
• Closing is explicit and idempotent from the owner, the view and the stream, and the drop after an explicit close does nothing. The closed state lives in the shared view. Descriptor-based views share an io.Guard: every operation enters it, retire marks it closed and wakes blocked operations, and the last operation to leave closes the descriptors. A view used after its owner closed fails with NotConnected and never reaches a reused descriptor. The SQL drivers fail with sql.Error.Closed and cdp with cdp.Error.Closed.
• io.Stream is a view whose close closes everything beneath it. In tls.client(net.stream(c), config), closing the session closes the connection, and the connection's own drop does nothing.
• A droppable cannot be stored in a pointer, slice, map, channel, optional or enum variant, captured by a closure or passed to spawn, so long-lived and shared state holds views. The HTTP client's idle connections, its HTTP/2 connections and the reaper's deadlines hold ConnHandle and io.Stream views and close them explicitly with the _on operations. A green thread that should own a resource receives its view and binds the owner itself: http.serve accepts with net.accept_handle, and each spawned connection thread runs using c = net.adopt(h). Pump threads that only use a resource take its view and leave it to its owner. A scope that opens a resource for a wrapper it returns binds it with using var and calls detach, as tls.dial does.
• A process.Child that was not waited for is killed and reaped when released. A pipe.Reader or pipe.Writer completes when released, so a peer never waits on an abandoned end.

Networking

• Sockets are non-blocking. An operation that would block waits with wait_readable or wait_writable, so a green thread waiting on the network never holds an OS thread the collector must wait for. Every connection holds a duplicate descriptor for its write side, so one green thread can read while another writes.
• A timeout spawns a green thread that sleeps and shuts the socket down if the operation is still waiting. The waiting operation then fails with TimedOut.
• A connection counts the reads and writes in progress. Closing it shuts it down, which wakes any green thread still waiting while the descriptor stays registered. The last operation to finish closes the descriptors, so a descriptor number is never reused under a waiting operation. Reads and writes after close fail with NotConnected, and closing twice does nothing.
• serve runs each connection on its own green thread.
• Cancellation is cooperative. A token runs its callbacks and closes its channel once, so code stops blocking work by closing what it waits on: net.close wakes a waiting read or write, process.kill ends a child, and select takes <-cancel.done(t).
• An HTTP/1.1 handler without an Upgrade header runs on the connection's green thread while one spawned watcher reads ahead into the request reader. End of input or a read error cancels the request's token, and the response is still written. Requests read ahead are served in order afterwards. An HTTP/2 stream's token is cancelled when the client resets it or the connection ends. Every request's token is cancelled once its handler returns.
• A client request with a token arms its deadline even without a timeout. Cancelling the token fires the deadline, which shuts down the connection the request is using and wakes the request from waiting on a pooled connection or an HTTP/2 stream.
• A server speaks HTTP/1.1 and HTTP/2 on the same port. A connection that opens with the HTTP/2 preface is served as HTTP/2; any other is HTTP/1.1 with keep-alive, pipelining, chunked bodies and Expect: 100-continue. Over TLS, ALPN offers h2 and http/1.1 and the same detection applies. The h2c upgrade from HTTP/1.1, deprecated by RFC 9113, is not offered.
• HTTP/2 covers framing, HPACK with its dynamic table and Huffman decoding, stream multiplexing, flow control in both directions, SETTINGS, PING, RST_STREAM, GOAWAY and CONTINUATION, and the request validation of RFC 9113 section 8. A reader green thread feeds frames to the connection, each request's handler runs on its own green thread, and the connection selects over frames and finished responses, so every write happens on one green thread. The encoder uses the static table and literals without Huffman coding. It passes h2spec except the test sending a garbage preface, which the shared port reads as an HTTP/1.1 request. A handler's Response.trailers are sent as a final HEADERS frame over HTTP/2; HTTP/1.1 responses carry none.
• A handler that returns status 101 owns the connection: the server writes nothing more and closes it once the handler returns. http.upgraded() is that response, returned after a WebSocket session.
• Request.connection is the buffered reader of an HTTP/1.1 connection. websocket.accept writes the handshake to it and reads frames from it. A WebSocket server requires masked client frames, answers pings, reassembles fragments, checks UTF-8 in text messages, limits messages to 16 MB and echoes a close frame.
• http.client() returns a Builder[Client] value whose with_* functions return updated copies. build makes a *Client that any number of green threads share. c.request(method, url) copies the client's settings into a Builder[Response], so headers, authentication, timeouts, redirects, retries, version and decompression can be overridden per request. The type parameter only selects whether build or send applies.
• HTTP/1.1 client connections: a request takes an idle keep-alive connection from a pool keyed by scheme, host and port, dials a new one while the host is under its limit, or queues for one. A sweeper green thread expires idle connections. A pooled connection that fails before any response byte is retried once on a fresh one.
• HTTP/2 client connections: over TLS the client offers h2 and http/1.1 by ALPN and keeps one HTTP/2 connection per host. A reader green thread decodes frames into per-stream queues, request green threads wait on their stream, flow control credits windows as bodies are consumed, and SETTINGS, PING, RST_STREAM, GOAWAY and the peer's stream limit are honoured. with_prior_knowledge(true) speaks HTTP/2 to http:// URLs without negotiation (h2c), keeping one connection per host as over TLS.
• One reaper green thread per client enforces whole-request deadlines by shutting down an expired HTTP/1.1 exchange. HTTP/2 waits select on the deadline and reset the stream.
• Redirects switch 301, 302 and 303 to GET without a body, keep the method and body on 307 and 308, resolve relative locations and drop Authorization and Cookie across origins.
• Responses are decoded from gzip, deflate (zlib or raw), Brotli and Zstandard as they stream, and chunked bodies are read and sent. An optional RFC 6265 cookie jar is shared by the client.
• Retries apply to connection failures and, for idempotent methods, to transport errors and 429, 502, 503 and 504, with exponential backoff that respects Retry-After.
• Servers set TCP_NODELAY so separate HEADERS and DATA writes are not held back by delayed acknowledgements.
• Response.trailers holds the trailer fields of chunked HTTP/1.1 bodies and of HTTP/2 responses.
• Request and response bodies are limited to 64 MB.

Processes

• process.start builds the path, arguments, environment and pipes before fork, so the child runs only straight-line syscalls: setpgid for a new group, dup2 onto descriptors 0 to 2, chdir and execve. Every descriptor the standard library opens is close-on-exec, so the child inherits only its three streams. A child's pipes are streams over guarded descriptors, so closing one twice or using it after it closed fails with NotConnected and never reaches a reused descriptor.
• A failed chdir or execve writes its errno to a close-on-exec pipe, which the parent reads before returning. The read sees end of file once execve succeeds; otherwise the parent reaps the child and fails with that errno.
• The parent's pipe ends are non-blocking and wait through the scheduler, as sockets do; the child's ends stay blocking. wait waits for the process's pidfd to become readable, then reaps it with waitid and remembers the result. kill signals through the pidfd, or the whole group when the command asked for one.
• signal.notify installs a handler with rt_sigaction. The handler is a short block of machine code in a mapped page: it writes the signal number to a non-blocking pipe and returns through rt_sigreturn. The runtime gives every OS thread an alternate signal stack, so the handler runs on whichever thread receives the signal. A forwarding green thread reads the pipe with wait_readable and sends to the signals channel, which holds 16 and drops repeats while full. Another notify for the same signal replaces the handler. Dropping a Watch restores the saved dispositions and unmaps the page. raise signals the calling thread, so its handler has run when raise returns; send is process-directed and unordered against other threads.
• watch.next reads every event an inotify read returns and queues them. With recursive set, new and moved-in directories are watched before the batch that reports them is returned. stop wakes a parked next by adding and removing a watch on /, which makes the descriptor readable. The kernel merges identical consecutive events it has not yet delivered.

Resilience

• retry.delay is the capped exponential backoff and jittered applies the chosen jitter to it. next calls the observer, waits through the policy's sleeper or sleep, and stops at the attempt limit, the deadline or a cancelled token.
• A Bucket keeps its balance as an integer in units of one token over per nanoseconds, so refills are exact and a wait is the ceiling of the deficit over the rate. reserve consumes and returns the wait. wait sleeps that long and refunds if cancelled.
• Group.do runs the function outside its lock, removes the key and stores the result before waking the waiters. It matches the key by call identity, so a forget followed by a new call is not disturbed.

Text

• diff.unified merges hunks whose gap is at most twice the context, omits a count of 1 in a hunk header and writes \ No newline at end of file, as GNU diff -u does. The edit script is minimal.
• number.format_bytes shows one decimal below 10 and rounds half to even on exact integers. parse_bytes reads k and kb as 1000 and ki and kib as 1024, and fails with OutOfRange on overflow or TooPrecise beyond 18 fraction digits. si rounds on the exact decimal expansion of the f64.
• naming.words splits at case, acronym and digit boundaries and keeps combining marks attached to their letter, so HTTPServerID2 is http server id 2.

Time

• Each concept is its own type: Timestamp is a point on the UTC timeline; Date, TimeOfDay and DateTime are civil values with no zone; Zoned is a timestamp seen through a zone; Duration is exact elapsed time; Span is a calendar amount. Types never convert silently.
• Fields are private and constructors validate, so a Date cannot hold February 30. Months are 1 to 12, and Month and Weekday are enums. Nothing rolls over: date.of(2026, 2, 30) fails with Invalid, and the clamping forms are named (clamped, plus_months).
• Calendar arithmetic and elapsed arithmetic are separate. A Duration moves a Timestamp or Zoned by elapsed time. A Span moves a Date, DateTime or Zoned by calendar units: a month after January 31 is the last day of February, and a day after a spring-forward midnight is the next civil day although it is 23 hours long. until and since take a Diff, add whole years, then months, to the start without passing the end, then count the rest.
• Only zone.local reads the host zone. A civil time in a daylight saving gap or overlap needs a Disambiguation. In an overlap, Compatible and Earlier pick the first occurrence and Later the second. In a gap, Compatible and Later move forward by the gap and Earlier back. Reject fails with Skipped or Ambiguous. zoned.start_of_day is the first instant of the civil day, correct where midnight does not exist.
• Zones come from TZif versions 1 to 4, using the 64-bit body from version 2, with the footer's POSIX TZ rule applying after the last transition. Before the first transition the first standard-time type applies. The rules cover Jn, zero-based n and Mm.w.d days and transition times from -167 to 167 hours, so negative daylight saving (Dublin, Casablanca), half-hour shifts (Lord Howe) and skipped days (Apia) work.
• Parsing is strict ISO 8601, RFC 3339 and RFC 9557: T, t or a space separates date and time, a fraction has 1 to 9 digits, :60 reads as :59, and a civil type rejects an offset. A written offset that disagrees with a bracketed zone is OffsetConflict unless an OffsetPolicy says which wins. Every parse error is Syntax(at) with the byte offset of the first bad character, or a value error naming the field.
• The supported range is 0001-01-01 to 9999-12-31 for a Timestamp and years -9999 to 9999 for a Date. Leap seconds are not modelled. Plain arithmetic panics on overflow; the try_ forms return an optional.
• Month and weekday names are English. pattern.Names and humanize.Words carry other languages.

Browser automation

• cdp.launch finds chromium, chromium-browser, google-chrome-stable or google-chrome on PATH unless given an executable, and creates a profile with file.temp_dir. It starts the browser headless in its own process group with --remote-debugging-port=0, standard input and output discarded and standard error piped. A green thread reads standard error until the DevTools listening on line, which gives the WebSocket address, and keeps draining it so the browser never blocks on a full pipe. shutdown closes the WebSocket, kills the process group, reaps the browser and removes the profile.
• Commands carry an id and, for a session, its sessionId. A pump green thread routes replies to the waiting call and sends every other message to the events channel. Sends are serialised and a call waits at most 30 seconds. Once the socket closes, every waiting call fails with Closed and the events channel closes.
• open_page creates a browser context that is disposed on detach, denies downloads in it, and turns on auto-attach with waitForDebuggerOnStart and flat sessions, so every page, frame and worker target pauses on creation. The first page in the context is the opened page; any other page in it, such as a popup, is closed before it runs. Every other target in the context gets Fetch.enable for all URLs, Network.enable, auto-attach for its own children and, for pages, Network.setBypassServiceWorker, and only then resumes, so no request escapes interception. Each paused request is passed to Handlers.request on its own green thread and continued or failed with its verdict. Responses and failed loads are reported with their URL.
• Cancellation is the caller's: let h = b.handle and cancel.on_cancel(t, fn() { cdp.shutdown_on(h) }) end everything the browser was doing.

TLS

• TLS 1.3 (RFC 8446) and TLS 1.2 (RFC 5246), client and server. Config.min_version and Config.max_version, written with tls12() and tls13(), bound the versions and default to 1.2 through 1.3. A client offers its range through supported_versions, and a server answers with the highest version both support. Session.handle.version holds the result.
• Downgrade protection: a server that supports 1.3 ends a 1.2 ServerHello random with the RFC 8446 downgrade sentinel; a client that offered 1.3 aborts with illegal_parameter when it sees either sentinel; a server refuses TLS_FALLBACK_SCSV below its highest version with inappropriate_fallback.
• Config.cipher_suites lists suites in preference order, and a server takes the first of its own list that the client offers. Session.handle.cipher_suite holds the IANA code and Session.handle.suite the AEAD and hash.
• TLS 1.3 has TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256 and TLS_AES_256_GCM_SHA384. TLS 1.2 has ECDHE with ECDSA or RSA authentication and AES-128-GCM with SHA-256, ChaCha20-Poly1305 with SHA-256 or AES-256-GCM with SHA-384, AEAD only: GCM records carry the 64-bit sequence number as their explicit nonce, and ChaCha20-Poly1305 records use the RFC 7905 nonce.
• TLS 1.3 key exchange offers the hybrid post-quantum group X25519MLKEM768 first, then X25519, P-256 and P-384. A client sends key shares for X25519MLKEM768 and X25519. A server picks the first group of its own order that the client supports, answering with a HelloRetryRequest when the client sent no share for it, so a client that supports X25519MLKEM768 always gets it. TLS 1.2 uses the first of X25519, P-256 and P-384 in the server's order that the client lists, and a server with an ECDSA certificate also requires the client to list the certificate's curve (RFC 8422).
• Servers sign with ECDSA P-256 or P-384, RSA-PSS, RSA PKCS#1 v1.5 in TLS 1.2, or Ed25519, with keys loaded from PEM (load_certificates, load_key). TLS 1.2 ECDSA signature schemes name only the hash, so either curve signs with SHA-256 or SHA-384. Clients verify the chain against Config.roots, or the system roots when that is empty, and check the host name against the certificate's subject alternative names. They verify CertificateVerify or ServerKeyExchange with any offered scheme the certificate allows and, in TLS 1.2, the suite's authentication.
• TLS 1.2 requires the extended master secret (RFC 7627) on both sides. A client requires the secure renegotiation indication (RFC 5746), a server echoes it when the client sends it, and both refuse renegotiation with a no_renegotiation warning.
• ALPN, SNI, KeyUpdate in TLS 1.3 and close_notify are supported. Session tickets are ignored, so there is no resumption or 0-RTT. Servers do not request client certificates; a client answers a CertificateRequest with an empty Certificate.
• Records hold at most 2^14 bytes of plaintext, and a peer's ciphertext may add 256 bytes in TLS 1.3 or 2048 in TLS 1.2. A record or handshake error sends its fatal alert, such as bad_record_mac, record_overflow, unexpected_message or decode_error, and leaves the session unusable.
• A session's read and write sides are independent, with a write lock, so different green threads can read and write it.

Derived serialization

std/serde defines a Writer and a Reader, structs of closures through which values are written and read. For every concrete type the compiler derives a function that writes a value to a Writer, a function that reads it from a Reader, and a Schema describing it:

• Booleans, integers, floats and strings map to their primitives; []u8 to binary; slices to sequences; maps to maps with keys written as text; optionals to null or the value; pointers to their target.
• A struct is a map from field names to values, and every field takes part, private ones included. Reading skips unknown keys, uses a field's default when its key is missing, treats a missing optional field as none, and fails with Missing otherwise.
• An enum variant without fields is its name. One with labelled fields is a single-key map from its name to a map of its fields, and one with positional fields maps its name to a sequence.
• A schema records each type's kind, name, fields with whether they are required, and variants. A struct or enum reached again through a pointer while it is being described becomes a Ref to its name.

std/json, std/orm and std/web are built on these. T.field, where T is a struct type, is a serde.Field[T, F] holding the field's name and index, so a function can take a field of a given struct with a given type.

Data

• json.Reader tokenizes UTF-8 bytes like .NET's Utf8JsonReader, strictly per RFC 8259, with a depth limit of 64. It returns strings without copying unless they contain escapes. Numbers are parsed as integers or correctly rounded floats.
• json.serialize_with and json.deserialize_with take Options for indentation, naming (Unchanged, CamelCase, SnakeCase, PascalCase), maximum depth and omit_none. Naming applies to field names and to variant names in both directions; a variant name read back is matched in PascalCase. With omit_none, a field whose value is none is left out instead of written as null. Binary data is base64; non-finite floats are written as null.
• std/cbor decodes RFC 8949 items into Values: every major type, indefinite-length strings, arrays and maps, tags, simple values, and half, single and double floats, which become f64. Indefinite-length items arrive as their definite equivalents. Text must be valid UTF-8 and map keys must be distinct. These fail with Malformed: truncated input, reserved additional information, a stray break, indefinite integers or tags, mixed or nested string chunks, a two-byte simple value below 32, data after the item, and a declared length that exceeds the remaining input (checked before anything is allocated). Nesting deeper than Options.max_depth, or a string, array or map longer than max_length, fails with TooLarge. decode_first returns the first item and its length so a caller can continue after it. encode writes the deterministic encoding of §4.2.1: shortest heads, definite lengths, map entries sorted by the bytes of their encoded keys, and floats in the shortest of half, single or double that keeps the value, with NaN as f97e00. diagnostic writes the notation of §8. serialize and deserialize bind types through serde with []u8 as byte strings, structs and variants as maps with text keys, and none as null; reading looks through tags and accepts integer map keys as their decimal text.
• std/webauthn produces options JSON in the shape py_webauthn's options_to_json writes, with base64url challenges, user ids and credential ids, pubKeyCredParams defaulting to EdDSA, ES256 and RS256, and attestation none.
  • verify_registration takes the credential JSON a browser's PublicKeyCredential gives in base64url, with or without padding. It checks that id is the base64url of rawId, that type is public-key, that clientDataJSON has type webauthn.create, the expected challenge (compared in constant time) and the origin. It then decodes the attestation object and checks the RP ID hash, user presence, user verification when required, and attested credential data. It parses the COSE key, accepts only the none format with an empty statement, and rejects a backup state without backup eligibility. It returns the credential id, the COSE key bytes exactly as the authenticator wrote them, and the sign count.
  • verify_authentication makes the same client data and authenticator data checks for webauthn.get. It rejects a sign count that is not greater than the stored one unless both are zero. It verifies the signature over authenticatorData followed by SHA-256 of clientDataJSON with the stored key: ES256 as DER ECDSA on P-256, EdDSA as Ed25519 and RS256 as PKCS#1 v1.5 with SHA-256.
  • Each failure is its own Error variant.
• std/orm builds queries from conditions over field references, such as orm.filter(orm.from(users), orm.ge(User.age, 18)), and type-checks them against the field. It renders them for Postgres or SQL Server, maps rows onto structs, stores nested values as JSON columns, creates tables from types with an identity key named id, and returns generated keys from inserts.
• sql.Value holds dates as days since 1970-01-01, times as microseconds since midnight, timestamps as microseconds since 1970-01-01 UTC, infinite dates and timestamps as the i64 maximum and minimum, and UUIDs as 16 bytes. A connection serves one green thread at a time; a call made while another is running fails with Busy. orm.transaction rolls back on any error from its body and fails with that error.
• std/sql/postgres authenticates with SCRAM-SHA-256, MD5 or cleartext. It uses the simple protocol for statements without parameters and the extended protocol with a 64-entry prepared statement cache otherwise, streams each in batches of 512 rows, reads results as text decoded by type OID, and keeps a connection usable after a server error. A timeout sends a CancelRequest and closes the connection. connect_tls upgrades with SSLRequest and std/tls.
• std/sql/sqlserver speaks TDS 7.4 with SQL authentication.
  • Prelogin offers no encryption to connect and full encryption to connect_tls. connect_tls runs the std/tls handshake inside PRELOGIN packets and unwraps the packets the server keeps sending around TLS records. LOGIN7 announces UTF-8 support.
  • Statements without parameters go as SQL batches. With parameters they go to sp_executesql as @p1..@pN declared as bigint, float, bit, decimal(38, s), nvarchar, varbinary, uniqueidentifier, date, time(7), datetime2(7) or datetimeoffset(7), with NULL sent as nvarchar(4000). Every request carries the transaction descriptor, and begin, commit and rollback use transaction manager requests.
  • Results decode every fixed, nullable, decimal, money, date and time, GUID, character, binary, long-value, text, image, XML, sql_variant and user-defined type. GUIDs become RFC 4122 byte order. Single-byte text decodes through its collation's UTF-8 flag or as Windows-1252. Row counts sum the DONE and DONEINPROC counts.
  • each streams rows as they arrive, and stopping early sends an ATTENTION and reads until the server acknowledges it. A server error below severity 20 leaves the connection usable. A per-connection watchdog sends an ATTENTION and closes the stream when one read waits longer than the timeout, and the call fails with Timeout.
• std/toml parses into ordered tables and applies every rule of TOML 1.0.0, including the restrictions on redefining tables through headers, dotted keys, inline tables and arrays of tables. It agrees with Python's tomllib on the toml-test suite. Errors carry a line and column. encode writes plain values first and then [table] and [[array]] sections. serialize and deserialize bind types through serde, reading date-times as RFC 3339 text.
• std/yaml parses YAML 1.2.2 into ordered node trees and agrees with the yaml-test-suite on every case's event stream and JSON equivalent.
  • A scanner modelled on libyaml tokenizes the whole stream, tracking indentation, implicit keys, JSON-like adjacent values and the YAML 1.2 tab rules, with 32-byte vector scans over plain scalars and simd.find_byte_str for comment and line ends. Token text is a view into the source.
  • A recursive-descent parser turns tokens into Events with resolved tags, and a composer builds Nodes carrying line, column, tag, anchor and style.
  • Plain scalars resolve with the core schema. !!str, !!int, !!float, !!bool, !!null and !!binary are checked against their content; other tags stay on the node. Aliases share their anchored node. Options.max_nodes bounds the tree with every alias expanded, failing with TooManyNodes, and max_depth bounds nesting. Duplicate scalar keys are an error.
  • encode writes block style, quotes a scalar only when it would read back differently (including YAML 1.1 booleans, numbers and dates), writes multi-line text as literal blocks, and anchors any node reached more than once. serialize and deserialize bind types through serde, with []u8 as !!binary.
• std/otel keeps the provider in the green thread's context slot as an immutable Context of the active span, baggage, a suppression flag and the SDK.
  • spawn copies the slot, so a child green thread's spans parent to the spawning span. install and setup_from_env return a droppable Sdk that shuts down when released and put the SdkHandle into the calling green thread's slot, reaching the green threads it spawns afterwards. Programs install at the top of main. Every API call checks the slot first and returns a no-op value without allocating when no SDK is present.
  • Timestamps and durations come from time.now_nanos and time.monotonic. Span and trace ids come from a std/rand generator behind a lock. Samplers are always on, always off, trace-id ratio on the low 63 bits, and parent-based.
  • Batch processors for spans and logs queue to a bounded channel with a non-blocking send that counts drops. A worker green thread exports when a batch fills, when the delay passes, and on flush or shutdown.
  • Metric instruments aggregate per attribute set, keyed by a canonical encoding of the sorted attributes, in one stream per reader, capped at 2000 series plus an otel.metric.overflow series. Readers collect cumulatively or as deltas, periodically or on demand.
  • Exporters encode OTLP once through a writer that emits protobuf through std/protobuf or the OTLP JSON mapping, and send with the context suppressed.
  • OTLP/HTTP posts, optionally gzipped, retrying 429, 502, 503 and 504 with jittered exponential backoff and Retry-After.
  • OTLP/gRPC makes unary Export calls on opentelemetry.proto.collector.{trace,metrics,logs}.v1 over the pooled client's HTTP/2 connection, with h2c prior knowledge for http://. The message carries the 5-byte gRPC prefix, optionally gzipped under grpc-encoding, with te: trailers and grpc-timeout. The result is grpc-status from the trailers or, in a trailers-only response, the headers. CANCELLED, DEADLINE_EXCEEDED, ABORTED, OUT_OF_RANGE, UNAVAILABLE and DATA_LOSS are retried. RESOURCE_EXHAUSTED is retried only when grpc-status-details-bin carries a RetryInfo, whose delay replaces the backoff.
  • setup_from_env reads the standard OTEL_* variables. OTEL_EXPORTER_OTLP_PROTOCOL=grpc selects gRPC, defaulting to http://localhost:4317.
• std/http sits below std/otel in the import graph, so the hook runs through the context slot. otel.Context declares an http.Ambient as its first field, and std/http reads the slot as *http.Ambient, which relies on struct fields being laid out in declaration order. install sets the ambient Observer and suppressed clears it; std/http does nothing when it is absent.
  • http.serve and serve_tls open a server span per request over HTTP/1.1 and HTTP/2, with the parent extracted from traceparent and client.address from Request.remote, and record http.server.request.duration. std/web adopts that span, adds http.route and renames it to the method and route; it opens its own span only when its handler runs outside http.serve.
  • The client opens a CLIENT span named after the method for each attempt sent, redirects and retries included. Each span is under the caller's span, with http.request.resend_count from the second attempt. The client injects traceparent, tracestate and baggage into that attempt, sets url.full without userinfo, and ends the span when the body is delivered or the attempt fails, with error.type the status from 400 or the http.Error variant. It records http.client.request.duration.
  • std/sql/postgres and std/sql/sqlserver wrap their connections with instrument_sql. std/orm opens client spans with the operation and table; a nested database span merges into the outer one, so an ORM query produces one span.
• std/protobuf writes and reads the protobuf wire format without code generation. An Encoder appends into a buffer that doubles as needed. Signed integers sign-extend to ten bytes and sint64 zigzag-encodes. begin_message returns a mark and end_message measures the body, shifts it right by the size of its length varint and writes the length, so nested messages need neither a second buffer nor padded lengths. Output matches protoc --encode byte for byte. A Decoder walks fields in order as number, wire type, integer value and a view of the payload. It rejects truncated or overlong varints, lengths past the end, field 0 and wire types 6 and 7 with Malformed, and groups with Unsupported. The as_* readers check the wire type and the unpack_* readers accept packed and single encodings.
• std/xml reads XML 1.0 (fifth edition) with Namespaces from UTF-8, UTF-16 with a byte order mark, ISO-8859-1 or US-ASCII, converting to UTF-8 and normalising line endings first.
  • xml.Reader is a pull reader: next returns one token and position its line and column. Names arrive with namespaces resolved and are interned in a per-reader table. Text, CDATA, comments and attribute values are views into the input unless a reference or normalisation forces a copy, and 32-byte vector scans find the bytes that end them. The reader enforces well-formedness and the namespace constraints and agrees with libxml2 on what it accepts.
  • The internal subset is parsed. General entities expand, including markup, with recursion detection, a nesting limit of 40 and a total of 1 MiB plus eight times the input. Attribute-list declarations supply defaults and normalise tokenised types. External entities are never fetched and parameter entities are not expanded.
  • xml.parse builds an Element tree of owned strings with attribute, child, children, text and find. xml.Writer escapes text and attributes, splits CDATA around ]]>, writes namespace declarations and indents element-only content. serialize_value and deserialize bind types through serde, mapping fields to attributes or child elements by local name, repeated elements to slices, and xsi:nil to none.
• Pipes block through channels. A writer flushing more than the pause threshold waits until the reader brings the unconsumed bytes below the resume threshold, or until the reader itself waits for more data, so a message larger than the thresholds cannot deadlock the pipe.
• pool.open stores ConnectionHandle views, so one connection serves a lease at a time and the pool, not the owner, closes it. Idle and lifetime limits are checked on acquire, release and prune against clock.monotonic, and a release hands the connection to the oldest waiter. A lease marks its connection broken on Connect, Authentication, Closed, Timeout or Protocol errors, and the pool closes it. A transaction left open at release is rolled back.
• migrate.up refuses any applied migration whose checksum differs (Drift), a pending version below the highest applied one (OutOfOrder) and duplicate or non-ascending versions. The lock is BEGIN IMMEDIATE on SQLite, pg_advisory_lock on PostgreSQL and sp_getapplock on SQL Server, and each migration re-checks inside its transaction that it is not yet recorded. In a text migration a statement ends at a line ending in ;, and -- +begin to -- +end keeps a block with several ; as one statement.

Unicode

• std/unicode reads tables generated by cmd/tablegen unicode from UnicodeData.txt, CaseFolding.txt and DerivedNormalizationProps.txt of Unicode 16.0.0, the version Python's unicodedata reports, and agrees with it on every code point.
• The tables are embedded binary files. A two-level trie of 64-entry blocks covers code points below U+2FA40 and gives 0 above. It maps each code point to a 16-bit record id. Each record holds the canonical combining class and 16-bit offsets and lengths into a pool of u32 code points for the full canonical decomposition, the full compatibility decomposition and the C and F case folding.
• Hangul syllables decompose and compose algorithmically. Decomposition is followed by a stable canonical reordering by combining class. Composition binary-searches a sorted table of primary composites, leaving out Full_Composition_Exclusion. ASCII input returns at once, or lowercased by casefold and search_key.
• search_key(s) equals Python's ''.join(c for c in unicodedata.normalize('NFKD', s.casefold()) if not unicodedata.combining(c)). It skips reordering, since every reordered character is dropped.

HTML

• std/html tokenizes UTF-8 HTML following the WHATWG tokenization states. It builds no tree and never fails. Tag and attribute names are lowercased in ASCII, attribute values may be double-quoted, single-quoted or unquoted, a repeated attribute keeps its first value, and a tag cut off by the end of input is dropped.
• A start tag for script, style, xmp, iframe, noembed or noframes switches to raw text, and one for title or textarea to escapable raw text, until the matching end tag in any case. plaintext takes the rest of the input. The script-data double-escape states are not implemented, and noscript is tokenized as when scripting is disabled.
• Comments end at --> or --!>, with <!--> and <!---> empty. <?...>, <!...> other than comments and doctypes, <![CDATA[...]]> and </ followed by a non-letter become comments, and </> is skipped. Doctype carries the lowercased name and the optional public and system identifiers.
• Character references are decoded in text, escapable raw text and attribute values. Named references match the longest name against the full WHATWG table of 2,231 names, generated by cmd/tablegen entities and embedded, including the names valid without a semicolon. Decimal and hexadecimal references work with or without a semicolon. Zero, surrogates and values above U+10FFFF become U+FFFD, and 0x80 to 0x9F map through Windows-1252. Inside an attribute, a match without a semicolon that is followed by = or a letter or digit stays literal. Text without references is a view into the input.
• The tokens match Python's html.parser except where it departs from WHATWG: duplicate attributes, processing instructions and CDATA as comments, raw text after <script/>, and control-character references.

Regular expressions

• std/regex compiles a pattern once into a program for a Pike VM, a Thompson NFA simulation that carries capture slots per thread, so matching takes time linear in the input times the program size and never backtracks.
• A Regex keeps two pools of idle machines: one without capture slots for is_match, one with them for find, full_match and the scans. Each machine owns its thread queues, capture slots and scratch. A call takes an idle machine under a lock, builds one when none is idle, and puts it back when it finishes. A compiled value is therefore shared freely between green threads, and a callback that matches with the same Regex during replace_all gets its own machine. A Match copies its slots out of the machine.
• Syntax: literals; escapes \n \t \r \f \v \a, \xhh, \uhhhh, \Uhhhhhhhh and escaped punctuation; .; classes with ranges, negation and \d \w \s \D \W \S inside; \d \w \s \D \W \S \b \B \A \Z \z; ^ and $; capturing groups, (?:...), inline flags (?i), (?m), (?s), (?-i) and scoped (?i:...); alternation; *, +, ?, {m}, {m,}, {,n} and {m,n} with lazy forms. A { that does not form a valid count is a literal. Inline flags apply to the rest of the enclosing group.
• Input is UTF-8 matched by code point; offsets are bytes. \d, \w, \s, \b and case folding are ASCII. . excludes only \n unless dot_all is set. Without multiline, $ matches at the end or before a final \n; with it, ^ and $ match at every line boundary.
• Matching is leftmost-first, as in Python and RE2, and results agree with Python's re under re.ASCII. find_all, replace_all and split follow Python 3.7: an empty match is allowed right after a non-empty one, and after an empty match the next one may start at the same offset only if it is not empty. split does not include group text. split_n splits at most max times; a negative max splits everywhere.
• Repeat counts are limited to 10000 and programs to 100,000 instructions. Invalid patterns fail with Invalid(at, message), at the byte offset Python reports. Backreferences, lookaround, named groups and possessive quantifiers are rejected.
• regex.generated("pattern") is a Regex built at compile time, like .NET's [GeneratedRegex]. The pattern must be a string literal; flags are written inline. An invalid pattern is a compile error at the literal, invalid regex at byte N: message, with the offset and message compile would fail with. The result is used through the same functions as a compiled Regex and matches identically.
• internal/regex holds a Go copy of the parser and assembler, held to the Low one by running the std_regex_errors fixture's patterns through it. The checker turns each distinct literal into Low functions named __regex_ and the FNV-1a hash of the pattern, parsed with the prelude's privileges and added to std/regex, so they reach its private types.
• A Regex carries an Engine of thread-start, step and skip functions with the queue size. compile fills it with the Pike VM. The generated engine keeps the VM's queues, priorities and capture slots but replaces interpretation with code per instruction:
  • One function per instruction that starts a thread, follows a consumed character or joins two epsilon paths, each guarded by the queue's sparse set. The remaining jumps, splits, saves and assertions are inlined into it.
  • Characters and classes of up to four ranges compare inline in the step, which dispatches on the program counter by binary search. Larger classes get a binary-search function.
  • When no empty match is possible from the start, a skip function moves past ASCII bytes that cannot begin a match before a thread starts.
  • Programs over 2000 instructions are compiled at run time by compile instead, so call depth stays bounded.

Compression

• DEFLATE, zlib and gzip decode stored, fixed and dynamic blocks with two-level lookup tables, check Adler-32, CRC-32, ISIZE and the gzip header CRC, and read concatenated gzip members. The encoder uses greedy matching at levels 1 to 3 and lazy matching at 4 to 9 over a hash chain on a 32 KB window, choosing dynamic, fixed or stored encoding per block. flush emits a sync flush so streamed output is decodable as it arrives.
• xz decodes multiple blocks and streams, the none, CRC32, CRC64 and SHA-256 checks, LZMA2 chunks with their resets, and the delta filter; other filters fail with Unsupported. The encoder writes LZMA2 with a hash-chain match finder and lazy parsing, a dictionary from 256 KiB to 64 MiB by level, and raw chunks where compression does not pay.
• std/compress/zstd and std/compress/lz4 each offer compress(data, level), decompress(data, limit), a streaming decode(reader, sink, limit) that passes output to the sink one block at a time, and a streaming Encoder with encode, flush and finish.
  • The zstd decoder handles every block and literal type, 1- and 4-stream Huffman literals, all four FSE table modes, repeat offsets, skippable and concatenated frames, and the content checksum. Its history grows with real output up to the smaller of the window and the remaining limit, so large windows never allocate what the header claims up front.
  • The zstd encoder finds matches with two hash chains keyed on 8-byte and 4- or 5-byte prefixes, with depth and lazy evaluation set by the level. It Huffman-codes literals, picks predefined, RLE or custom FSE tables per block by estimated cost, and falls back to raw or RLE blocks.
  • The LZ4 decoder accepts linked and independent blocks, block and content checksums, content sizes and skippable frames. The encoder writes linked 64 KB blocks with a content checksum.
  • Dictionaries and LZ4 frames with magic number 0x184C2102 fail with Unsupported.
• std/compress/brotli has the same API as zstd and LZ4.
  • The decoder handles compressed, uncompressed and metadata meta-blocks, block switching for literals, commands and distances, all four literal context modes, context maps with run-length coding and inverse move-to-front, distance postfix and direct parameters, the static dictionary with all 121 transforms, and windows of 10 to 24 bits. Output collects in a ring buffer that starts at 64 KB and doubles up to the window, and reaches the sink at the end of each meta-block, when the ring wraps, and before each blocking read. The 122,784-byte dictionary is embedded from dictionary.bin.
  • The encoder writes uncompressed meta-blocks at level 0. Levels 1 to 11 run hash chains of depth 2^(level-1) with lazy matching from level 4 and checks against the four recent distances and their neighbours, writing 256 KB meta-blocks with Huffman-coded commands and distances. From level 5 they model literals in UTF-8 context mode with up to 3·level-11 clustered trees. A block that would grow is stored. flush ends the meta-block and pads with an empty metadata block so everything sent decodes.
• std/bits holds a growable Set over []u64 words. Counts use a SWAR popcount, and scans (next_set, next_clear, min, max, rank, select_at, members) step a word at a time.
• std/bits/roaring holds Roaring, a set of u32 split into 65536-value chunks keyed by the high 16 bits. Each chunk is a sorted []u16 array of up to 4096 values, a 1024-word bitmap, or a list of runs. Arrays and bitmaps convert at 4096 values; ranges create runs, and unions and intersections of runs stay runs. Every container tracks its cardinality, so cardinality is constant time. Set operations come as new-set and in-place _with forms, working word by word on bitmaps and by galloping merge on arrays. run_optimize picks the smallest form per container by the Go library's rule. serialize and deserialize implement the portable Roaring format byte for byte as Go roaring/v2 writes it, rejecting any inconsistent length, ordering or cardinality with Malformed.
• std/image holds an Image of width, height, Format (Gray8, GrayAlpha8, Rgb8, Rgba8, Gray16, Rgba16, 16-bit samples big-endian), stride and pixel bytes.
  • Pixels read and write as 8-bit Rgba, with operations converting through 16-bit intermediates. get outside the image is transparent black and set there does nothing. Operations convert formats, crop, flip, rotate, apply EXIF orientation, fill rectangles, composite straight alpha, premultiply and unpremultiply, and resize separably on premultiplied values with nearest, bilinear, Catmull-Rom bicubic or Lanczos-3 filters.
  • decode picks a codec by signature and rejects images over 2^26 pixels; decode_limited takes another limit.
  • PNG decodes every colour type, bit depth and Adam7, checks every CRC, and encodes with per-row adaptive filtering.
  • JPEG decodes baseline and progressive scans with restart markers, any sampling, grayscale and Adobe CMYK/YCCK, with libjpeg's integer IDCT and fancy upsampling, so output matches libjpeg byte for byte. It encodes baseline 4:2:0 with the standard tables scaled by quality.
  • GIF decodes 87a and 89a and composites every frame by disposal method in decode_gif_frames. It encodes one frame with a given or median-cut palette.
  • BMP covers 1 to 32 bits, RLE, bitfields and every header version, and encodes 24 or 32 bits.
  • QOI decodes and encodes.
  • WebP decodes lossless VP8L with every transform, the colour cache and meta prefix codes. Lossy VP8, alpha chunks and animation fail with Unsupported.
• Every codec has buffer functions, a streaming decoder that pulls from an io.Reader, pushes output to a sink and fails with TooLarge past a caller's limit, and a streaming encoder.

Web

• web.app() holds routes and middleware. get, post, put, patch, del and route add handlers for paths with :name parameters and a trailing *. group makes a sub-application with a prefix and more middleware, and mount adds its routes back. An unknown path is a 404 and a known path with another method a 405 with Allow.
• endpoint[Req, Res] and query_endpoint[Res] read a JSON body into Req, call a handler returning Res ! web.Problem, and write the result as JSON or the problem as application/problem+json. Their schemas describe the operation in the OpenAPI document that openapi serves, along with path parameters and each route's security schemes.
• Middleware is a struct of a run closure and an optional security scheme. api_key, basic and bearer authenticate requests and set Context.user. sessions keeps a map in a cookie sealed with AES-256-GCM, with the cookie name as associated data and an expiry inside. csrf requires the session's token in X-CSRF-Token on unsafe methods. require_session, cors, logger and compress complete the set; compress picks Zstandard, Brotli or gzip, in that order, from what Accept-Encoding allows.
• jwt verifies bearer tokens against a key set with std/crypto/jose. oidc does the same for an OpenID Connect issuer: it reads the discovery document and the JWKS, refreshes them hourly, and refreshes early, at most once a minute, when a token names a key it does not know. oidc_login adds a sign-in route that redirects to the issuer with state, nonce and a PKCE S256 challenge kept in the session, and a callback route that checks the state, exchanges the code, verifies the ID token and its nonce, and hands the claims to the application.
• A handler streams a body by returning a Response with stream set to a chan[[]u8] and closing it at the end. The server writes each chunk as it arrives, cancels req.token when the stream ends, the client disconnects or a write fails, and drops the stream for HEAD and bodiless statuses. Response compression skips streamed responses.
• sse.stream sets text/event-stream, no-cache and x-accel-buffering: no, flushes every event, sends a : keepalive comment every 15 seconds unless keepalive is 0, and stops when req.token is cancelled. Emitter.send returns false after the client has gone. sse.format removes CR and LF from id and event and NUL from id.
• web.static decodes each path segment and answers 400 for .., an embedded separator, NUL or a bad escape, and 404 for dotfiles, non-regular files and any file whose real path leaves the root. A directory without a trailing slash is redirected, and a directory serves index.html or an optional listing. precompressed picks .br then .gz by Accept-Encoding. A multi-range or malformed Range gives the whole file. Files stream in 64 KiB chunks.