Config

On this page:

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.

`spider.Config`

zig

pub const Config = struct

The settings of an app. spider.app() reads them from the config constant of the project's spider.config.zig (the defaults below when the project has no such file); spider.appWithConfig(.{...}) takes them in code.

zig

// spider.config.zig
const spider = @import("spider");

pub const config = spider.Config{
    .views_dir = "./src",
    .port = 3000,
    .host = "0.0.0.0",
};

Fields

port: u16 = 3000: Port listen() binds when nothing else names one. spider dev --port, the .port given to listen() and the PORT variable (environment or .env) come first, in that order. Default 3000.
host: []const u8 = "127.0.0.1": Address listen() binds; the .host given to listen() replaces it. The default, "127.0.0.1", accepts local connections only: use "0.0.0.0" to accept connections from other machines (a container).
views_dir: ?[]const u8 = "./views": Directory searched, with its subdirectories, for the templates (.html, .md) that c.view() renders when they are read from disk: a view named "posts/index" is <views_dir>/posts/index.html or, in the layout of a generated app, <views_dir>/features/posts/views/index.html. Default "./views" (a generated app sets "./src"). null: c.view() fails with error.ViewsNotConfigured, embedded templates or not.
layout: ?[]const u8 = "layout": Deprecated: nothing reads it, and it will be removed in a future release. A template names its layout itself, with extends "layout". Remove the line from spider.config.zig.
static_dir: ?[]const u8 = "./public": Directory served as static files at "/" (before routing and before any middleware: always public). null: no static files. server.staticDir() / staticAt() override it. Default "./public".
static_max_file_bytes: usize = 10 * 1024 * 1024: The largest static file served, in bytes. A file is read whole into memory for each request, so raise it with care; bigger files belong in object storage or behind the proxy. Default: 10 MiB.
env: Env = .development: Deprecated: nothing reads it (it changes no behaviour), and it will be removed in a future release. Remove the line from spider.config.zig; what differs between environments goes in the .env files (SPIDER_ENV picks .env.<name>).
workers: ?usize = null: Accept threads of the threaded I/O backend (null: one per CPU). Ignored by the zio backend.
keepalive_timeout_ms: u32 = 120_000: Connection deadlines (ms, 0 = off), enforced by the connection watchdog so idle or stalled clients can't hold file descriptors forever. None applies while a handler runs, so SSE/WebSocket streams and slow handlers are unaffected.
header_timeout_ms: u32 = 30_000: From the first byte of a request to its complete head (slowloris). Milliseconds, 0 = off. Default: 30 s.
body_timeout_ms: u32 = 60_000: Longest silence while receiving a request body; restarts on every chunk, so a slow but steady upload is never cut. When it passes, the request is answered 400 and the connection closed. Milliseconds, 0 = off. Default: 60 s.
max_body_bytes: u64 = 10 * 1024 * 1024: Largest request body accepted, in bytes. With a Content-Length, a bigger one is answered 413 before anything is read or allocated; a chunked body, which declares no length, is answered 413 as soon as it passes the limit. The connection is then closed. Uploads that go straight to object storage (presigned URLs) never reach it; raise it for apps that take files through the app. Default: 10 MiB.
origin_check: @import("../core/origin.zig").Policy = .{}: Cross-site request check, on by default: a state-changing request a browser sends from another site (CSRF) or a cross-site WebSocket upgrade gets 403 before routing. Non-browser clients (webhooks, servers) aren't affected. See core/origin.zig; add trusted_origins or exempt_paths for legitimate cross-site posts, .enabled = false to turn it off.
trusted_proxies: []const []const u8 = &.{}: Reverse proxies whose X-Forwarded-For is believed by Ctx.clientIp(): CIDRs or addresses, e.g. &.{"10.0.0.0/8", "172.16.0.0/12"} for a proxy on a private network. Empty (the default): the header is ignored.
sse_allowed_origins: []const []const u8 = &.{}: Other sites whose pages may read this app's SSE streams, as origins ("https://app.example.com": scheme, host and port, no path). A stream answers a listed origin with Access-Control-Allow-Origin naming it. Empty (the default): only the app's own pages. &.{"*"} lets any site read them: only for streams with nothing private in them.
stream_write_timeout_ms: u32 = 10_000: Longest a server push to an SSE/WebSocket client may stay blocked (its socket buffer full: the client stopped reading). The connection is then closed, so the client reconnects instead of silently missing events, and a stuck client can't hold up delivery to everyone else. Milliseconds, 0 = off. Default: 10 s.
dev_reload: ?bool = null: Browser reload for spider dev (modules/dev_reload.zig): a script added to HTML pages plus /_spider/dev.js and /_spider/dev. null (the default): on when SPIDER_DEV is set, which spider dev does for the app it runs. Never on in a release build.
require_route_access: bool = false: Every route must declare who may call it (.public, .authenticated, .roles, .org_roles or .policy, directly or through its group's defaults()); listen() refuses to start otherwise (error.RouteAccessUndeclared) and names the routes that don't. Turns "forgot the RBAC" into a boot error. Routes that take no config (ws(), wsInterval(), plain sse()) count as not declaring. Default false. Also server.requireRouteAccess().

`spider.Env`

zig

pub const Env = enum

The value of Config.env.

Values

development
production
testing