Skip to content

README.md

Latest commit

 

History

History
140 lines (108 loc) · 5.46 KB

README.md

File metadata and controls

140 lines (108 loc) · 5.46 KB

Virtual Modules

Virtual modules are native Zig APIs exposed to handlers as import { ... } from "zigttp:*". Calls have zero interpretation overhead, carry effect annotations the compiler reads for handler property classification, and feed contract extraction for runtime sandboxing.

The modules are grouped by role. Each page documents exports, compile-time proof interactions, runtime failures, and related modules. The implementation registry is packages/zigts/src/builtin_modules.zig; public module specs live under packages/modules/module-specs/.

Security

Trust boundary: input validation, credential handling, cryptographic primitives.

  • zigttp:auth - JWT signing/verification, Bearer parsing, webhook signatures, constant-time comparison.
  • zigttp:crypto - SHA-256, HMAC-SHA256, base64 encode/decode.
  • zigttp:validate - JSON Schema registry with validateJson / validateObject / coerceJson.
  • zigttp:decode - schema-backed ingress (decodeJson / decodeForm / decodeQuery).

Data

Persistent or quasi-persistent state.

  • zigttp:cache - in-process key-value cache with TTL and LRU.
  • zigttp:sql - registered SQLite queries with build-time schema validation.
  • zigttp:ratelimit - sliding-window rate limiting backed by the cache layer.

Net

Inbound and outbound traffic across process boundaries.

  • zigttp:fetch - web-standard outbound HTTP with optional durable replay.
  • zigttp:service - named internal service-to-service calls resolved via system.json.
  • zigttp:websocket - WebSocket protocol termination with rooms, attachments, and codec auto-replies.

HTTP

HTTP-shaped utilities with no transport of their own.

  • zigttp:router - pattern-matching router with captured params.
  • zigttp:http - cookies, content negotiation, content-type parsing, CORS headers.
  • zigttp:url - URL parsing, query string handling, percent-encoding.

Workflow

Control-flow primitives: durable runs, pipe guards, scoped cleanup, structured concurrency.

  • zigttp:durable - crash-safe execution with write-ahead oplog, timers, and signals.
  • zigttp:compose - compile-time handler composition with guard() and the pipe operator.
  • zigttp:scope - structured lifecycle management with deterministic LIFO cleanup.
  • zigttp:io - parallel() and race() for overlapping outbound I/O without async.

Platform

Runtime primitives with no domain coupling.

  • zigttp:env - environment variable access (literal keys feed runtime sandboxing).
  • zigttp:id - UUID v4, ULID, nanoid.
  • zigttp:log - structured line-delimited JSON logging to stderr.
  • zigttp:text - HTML escape, slugify, truncate, mask.
  • zigttp:time - ISO 8601 / HTTP date formatting, Unix-ms arithmetic.

Type-only Module

zigttp:types is a type-only import surface for proof annotations. It is stripped before runtime and does not appear in the native module registry. Use it for Spec<...> handler obligations and the helper-level Proof<...> / Effects<...> capsules:

import type { Spec, Proof, Effects } from "zigttp:types";

See ../typescript.md for the supported property and capability vocabularies.

Effect classification

Every export carries an effect annotation used for handler property classification:

  • Read: env, cacheGet, cacheStats, id/*, websocket.deserializeAttachment, websocket.getWebSockets, and websocket.roomFromPath.
  • Write: cacheSet, cacheDelete, cacheIncr, sqlExec, fetch, serviceCall, parallel, race, scope, using, ensure, every durable export, websocket.send, websocket.close, websocket.serializeAttachment, websocket.setAutoResponse, log/*, and ratelimit/*.
  • None: auth/*, crypto/*, decode/*, validate/*, compose/*, platform/text, platform/time, http/*, url/*, router/*, sql, sqlOne, and sqlMany.

For internal capability governance, see ../internals/capabilities.md.

Runtime Requirements

Most modules work without extra flags. Modules that cross a process, disk, or durability boundary need runtime configuration:

Module Runtime Requirement
zigttp:env Proven literal env vars are checked at startup unless --no-env-check is passed.
zigttp:sql Start with --sqlite <FILE> for query execution. Use -Dsql-schema=<schema.sql> or --sql-schema during checks for schema validation.
zigttp:fetch Start with --outbound-http or --outbound-host <host>. Durable fetch also needs --durable <DIR>.
zigttp:service Start with --system <FILE> or set "system" in zigttp.json.
zigttp:durable Start with --durable <DIR>.
zigttp:websocket Run through the server/WebSocket gateway; no standalone compile flag is enough.
zigttp:log Writes structured lines to stderr. Do not log raw secrets or credentials.

zigttp doctor checks the project manifest, entry file, runtime template, test fixture, and configured static/system paths before you start the dev loop.