API reference

Everything an app reaches through const spider = @import("spider");, by the name it writes.

These pages are generated from the comments in Spider's source code each time the site is built, so they describe the code as it is. A name that is public only for Spider's own files is not listed.

Ctx and Response

• spider.Ctx: The request, and what builds the response: every handler receives a *Ctx.
• spider.NextFn: What a middleware calls to let the request go on.
• spider.MiddlewareFn: A middleware: fn (*spider.Ctx, spider.NextFn) !spider.Response.
• spider.ErrorHandler: The function given to server.onError.
• spider.Response: What a handler returns; built by c.json, c.view, c.redirect and the like.
• spider.DownloadOptions: Options of c.download(bytes, .{ .filename = …, .content_type = … }).
• spider.content_types: Content types for downloads: .xlsx, .csv, .pdf, .binary.
• spider.statusForError: The HTTP status an error gets by default: error.NotFound is 404, and so on.

Server

• spider.app: Builds the server of an app: var server = spider.app(.{});.
• spider.appWithConfig: The same server, with the config given in code instead of spider.config.zig.
• spider.Server: The server type spider.app returns; its methods register routes and middlewares, and listen() runs it.
• spider.ListenOptions: The argument of server.listen: .port and .host, both optional.
• spider.Job: A periodic task of a feature's jobs; spider.every builds one.
• spider.every: A job for a feature's jobs: spider.every(60_000, run) calls run once a minute.
• spider.Boot: What a feature's boot() receives: an allocator and the server's Io.
• spider.StaticConfig: Where static files are served from.
• spider.static: Static file serving; the server uses it by itself for the static_dir of the config.
• spider.health: The handlers behind /up and /_spider/health, which spider.app registers.

Modules and migrations

• spider.module: Declares a module: pub const spider_module = spider.module(.{ .name, .version, .spider, ... }), checked at compile time. Mounted with server.mountModules(.{ ... }).
• spider.Manifest: What a module declares about itself (M.spider_module.manifest).
• spider.ModuleEnv: The environment variables a module declares in its manifest (.env).
• spider.Migration: One database migration, a module's or the app's own: .{ .name = "0001_init", .sql = @embedFile(...) }.
• spider.Check: Given to a module's check(c) before the server starts: c.fail(...), c.env(...).
• spider.ModuleReport: The modules' checks (server.check): report.ok(), report.write(w).
• spider.ModuleProblem: One problem in a ModuleReport: the module and the message.

Group and routes

• spider.Group: The routes of one feature under one prefix: what a feature's routes.build() returns.

Path, Form, Loaded

• spider.Path: Handler parameter: a :name segment of the route, converted. id: spider.Path(i64, "id").
• spider.Form: Handler parameter: the submitted form as a struct. form: spider.Form(Input).
• spider.Loaded: Handler parameter: the resource the route's spider.resourcePolicy loaded.

Config

• spider.Config: The app's settings: what spider.config.zig declares (port, host, directories, timeouts, limits).
• spider.Env: The value of Config.env: .development, .production or .testing. Nothing in Spider reads it today.

env

• spider.env: Environment variables, with .env loaded: spider.env.getOr("NAME", "default").

Template and RawHtml

• spider.Template: A template parsed from text, for rendering outside a request (an email body, a file): Template.init(allocator, text), then render(data, allocator). Inside a handler, c.view is the usual way.
• spider.RawHtml: Trusted markup for templates: { expr } escapes everything else.

Forms and uploads

• spider.multipart: multipart/form-data parsing: the fields and the uploaded files of a form. Handlers use c.parseMultipart.
• spider.MultipartData: The parsed parts of a multipart body: what c.parseMultipart returns.
• spider.UploadedFile: One uploaded file of a multipart body: its name, content type and bytes.

Policies and roles

• spider.rbac: The checks behind a route's .roles, .org_roles, .authenticated and .policy, as middlewares.
• spider.policy: A named access rule for a route: .policy = spider.policy("post_owner", isPostOwner) with fn isPostOwner(c: *spider.Ctx) !bool. See modules/rbac.zig.
• spider.Policy: What spider.policy and spider.resourcePolicy return: the value of a route's .policy.
• spider.resourcePolicy: A policy that loads the route's resource (404 when missing), checks it, and hands it to the handler (spider.Loaded(T) / c.loaded(T)).
• spider.policySet: The rules about one kind of resource in one place (Laravel Policy / Pundit): Set.route(.update) for routes, Set.can(c, .update, x) in handlers.

session

• spider.session: Login sessions for an app's own users: a signed cookie (or bearer token), start, end, middleware().

password

• spider.password: Password hashing for an app's own users (argon2id): hash, verify.

auth (HS256 tokens)

• spider.auth: Tokens signed with a secret of the app (HS256) and the cookie helpers around them. For a login with the app's own users, spider.session is the ready-made one.

pg (PostgreSQL)

• spider.pg: PostgreSQL: init, query, queryOne, queryExecute, begin. Opt-in with -Dpg=true.

sqlite

• spider.sqlite: SQLite: init, query, queryOne, queryExecute, begin. Opt-in with -Dsqlite=true.

Hub, Sse, Ws

• spider.Hub: The connected SSE or WebSocket clients, and what sends to them: emit, emitTo a channel, broadcast.
• spider.Ws: One WebSocket connection, as its handler sees it: next() reads a message, send writes one.
• spider.Sse: One Server-Sent Events stream, as its handler sees it.

http_client

• spider.http_client: The HTTP client: get, post, put, patch, delete, head, or a Client that keeps connections.
• spider.http_client_mtls: HTTP requests that present a client certificate (mutual TLS).

mail

• spider.mail: Sending mail through a provider's HTTP API (Brevo, Resend, Postmark) — see modules/mail/mail.zig.

push (Web Push)

• spider.push: Web Push notifications to browsers (VAPID).

Middlewares

• spider.logger: Middleware that logs one line per request: server.use(spider.logger).
• spider.loggerWith: Request logger with options (quiet paths, stream opens) — see modules/logger.zig.
• spider.logFn: std.log function with UTC timestamps: pub const std_options: std.Options = .{ .logFn = spider.logFn };
• spider.gzip: Middleware that compresses response bodies of 1024 bytes or more for clients that accept gzip.
• spider.forceHttps: spider.forceHttps(.{ .default_base_url = "https://example.com" }): a middleware that redirects plain HTTP to HTTPS behind a TLS proxy (honors route .allow_http).
• spider.ForceHttpsOptions: Options of spider.forceHttps.
• spider.varyHtmx: Middleware that adds Vary: HX-Request to HTML responses.
• spider.errorHandler: spider.errorHandler(.{}): a ready-made onError that answers JSON, an htmx toast or a page (see modules/errors.zig).
• spider.markAuthMiddleware: Tells Spider that mw authenticates requests (an app's own session middleware); Spider's providers mark theirs. See modules/auth_marker.zig.
• spider.ErrorHandlerOptions: Options of spider.errorHandler.
• spider.dbgRequest: Middleware that prints each request (method, target, headers and body) to stderr, for debugging.
• spider.dbgResponse: Middleware that prints each response (status, headers and body) to stderr, for debugging.

testing

• spider.testing: Test helpers for apps: start (requests against the running app), expectRoutes, expectConventions, expectAllTestsDiscovered.
• spider.conventions: App conventions checked by spider check and testing.expectConventions().

zmd (Markdown)

• spider.zmd: Markdown to HTML: spider.zmd.parse(arena, text, .{}). What the author typed is escaped.

keycloak

• spider.keycloak: Authentication through a Keycloak realm: the login, callback and refresh handlers, and the middleware that checks the token.

jwks

• spider.jwks: Checks tokens signed by an identity provider, with the keys it publishes (JWKS).

google

• spider.google: Sign-in with Google (OAuth): login sends the visitor to Google, callback checks the answer and returns their profile.

clerk

• spider.clerk: Authentication through Clerk.

r2 (object storage)

• spider.r2: Cloudflare R2 (S3-compatible) object storage: put, get, delete, presigned URLs. Opt-in with -Dr2=true.

qrcode

• spider.qrcode: QR code generation. Opt-in with -Dqrcode=true.

xlsx

• spider.xlsx: Excel .xlsx files, written and read — opt-in with -Dxlsx=true (see modules/xlsx/README.md).

version

• spider.version: The version of this Spider (std.SemanticVersion): spider.version.minor.

migrating

• spider.migrating: Whether this run is spider migrate (SPIDER_MIGRATE set): listen() then applies the migrations and returns without serving. An app whose main() does work before listen() that migrating does not need (an identity provider, a cache) migrates first and returns: