@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/docs/links/setup.md

@@ -0,0 +1,135 @@
+# Dynamic links: Setup: requirements, YAML and the example
+
+Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
+
+## Node build requirement
+
+Live links need a Node build carrying the patched SQLite WAL fix: SQLite 3.51.3
+or newer, 3.50.7 or 3.44.6. Node bundles SQLite, so this is a property of the
+build, not something you can install separately, and some current releases on a
+supported Node line ship an unpatched version. Run `urlcode doctor` and check
+`liveLinks`; activation fails closed and names the detected version when the
+build is unsuitable. Everything except live links works on any supported Node.
+
+Available in URLCode 0.1.0. Define a stable route once; create, update and delete
+short-code records while `serve` keeps running. No YAML rewrite, route snapshot
+rebuild, Git commit or public-server restart is needed for record changes.
+
+This first adapter uses optional SQLite storage on one host. Multiple processes
+on that host can share it. No database is required for ordinary YAML-defined
+routes. Network filesystems, multi-host replication and serverless ephemeral disks
+are not supported by this adapter. SQLite WAL requires processes on the same
+host; see [SQLite WAL](https://www.sqlite.org/wal.html).
+
+## Behavior in YAML, data outside Git
+
+```yaml
+version: "1"
+dynamicLinks: true
+routes:
+  /r/{code}:
+    parameters:
+      - name: code
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 128}
+    link:
+      collection: links
+      code: {from: path, name: code}
+```
+
+`link` is a seventh primary handler, exclusive with `function`, `redirect`,
+`respond`, `page`, `static` and `download`. Its `code` is a declared path-input
+reference. `collection` is a logical name, not a filesystem path. GET and HEAD
+are supported; normal route precedence, lifecycle and input validation apply.
+An exact YAML route can intentionally shadow a stored code's URL.
+
+The operator binds `links` to a database outside the project. YAML cannot choose
+a database file or grant itself storage. The built-in public binding opens it
+read-only. It performs an indexed database lookup for each request, with no
+application cache or negative cache. Requests starting after an acknowledged
+mutation can see it immediately; an already-running request can finish with an
+older result. Browser/proxy caches remain outside that guarantee.
+
+Missing or disabled record: 404. Expired record: 410. Unavailable/overloaded
+store: 503. Invalid code syntax: 404 after route input validation. Redirects
+default to 302 and no-store. Query strings are not forwarded. A record's URL is
+literal HTTP(S), with no embedded credentials, control characters or interpolation.
+It is a redirect, not a server-side fetch. The store does not verify destination
+ownership, safety or availability; application abuse prevention remains necessary.
+
+## Run the included example
+
+From the runtime checkout, choose a private data directory **outside the app**.
+Its parent directory must already exist. The following POSIX-shell example uses
+an operator-created directory; on Windows use an absolute local drive path.
+
+```sh
+mkdir -p ../urlcode-data
+URLCODE_DATA="$(cd ../urlcode-data && pwd)"
+node src/cli.ts links init --store "$URLCODE_DATA/links.sqlite"
+node src/cli.ts links create --store "$URLCODE_DATA/links.sqlite" \
+  --code demo --destination https://example.com/demo
+node src/cli.ts serve --project examples/live-links \
+  --link-store "links=$URLCODE_DATA/links.sqlite" --port 3000
+```
+
+Open `/r/demo`. In a second terminal, run another `links create` with an unused
+code against the same absolute file; its URL works immediately. Omit `--code`
+to generate a cryptographically random 16-character base64url code. Codes allow
+1–128 letters, digits, underscores and hyphens; collection names begin with a
+letter and contain at most 64 letters/digits/underscores/hyphens.
+
+The CLI defaults to collection `links`; specify `--collection` to manage another.
+Serving currently accepts one `--link-store collection=/absolute/file` binding;
+embedded applications may supply multiple adapters. Commands do not copy records
+into YAML or create route definitions automatically.
+
+## Explicit project opt-in
+
+Only the entry `urlcode.yaml` may set `dynamicLinks: true`. It defaults to false;
+the starter writes `dynamicLinks: false` explicitly. Included route files cannot
+set or override it. Any `link` handler, including a disabled route, or runtime
+link-store binding requires the opt-in. This flag means live stored-link records,
+not parameterized redirects, custom functions, middleware or development reload.
+
+`validate`, `routes`, `audit` and `scaffold` reports expose `dynamicLinks` as a
+boolean. Enabling it grants no storage access to guest code and starts no
+management endpoint. The operator still supplies the external store binding;
+management remains a separate authenticated service. Standalone `links` CRUD/API
+commands operate the operator's store independently of this public-runtime flag.
+
+Migration: existing live-link projects must add `dynamicLinks: true` to their
+entry file. Refresh revision-pinned function policies for those projects using
+the normal operator review flow; enabling the capability changes the approval
+digest. Projects that omit it or explicitly set false retain their prior digest.
+To disable, remove `link` declarations and serving-store bindings, then set false
+and validate/redeploy. Editing the flag alone does not stop an already running
+production process or management API. Invalid reloads retain the last-good state.
+
+## Middleware, sandbox and tests
+
+Middleware may wrap a successful link response; the usual native metadata/body
+rules apply. Lookup/missing/disabled/expiry errors happen before middleware. The
+handler does not make database objects available to guest code. Functions still
+have no filesystem, SQL, fetch, storage broker or management token capability.
+Link changes do not alter configuration/source digests or invalidate unrelated
+function-binding grants. Changing YAML still does.
+
+`routes` and `audit --expect-routes` count definitions, not stored records. Link
+routes require explicit successful GET/HEAD fixtures; there is no assumed fixture
+for live data. Seed a disposable test database, then pass `--link-store` to
+validate/test/audit/benchmark. Do not run mutation tests against production.
+
+```sh
+node src/cli.ts test --project examples/live-links --link-store links=/absolute/test-links.sqlite
+node src/cli.ts audit --project examples/live-links --link-store links=/absolute/test-links.sqlite --expect-routes 2
+```
+
+The example expects `demo -> https://example.com/demo` and an unused `not-created`
+code. Tests cover create/update/delete visibility without reload, persistence,
+concurrent conflicts, expiry/disabled semantics, scope, public/admin separation,
+body/token boundaries, overload and acknowledged writes after abrupt writer exit.
+Production durability, sustained load and recovery drills still require validation
+on your actual storage. General application state, WebRTC sessions, user-account
+APIs and arbitrary runtime code registration remain separate future work.

package/docs/policies/agents.md

@@ -91,7 +91,7 @@ deploy carries a known list version and a rollback rolls the list back too.
 ### Refreshing
 
 ```sh
-node scripts/sync-agent-lists.ts            # fetch pinned upstreams, validate, write data/agents/
+node scripts/sync-agent-lists.ts            # fetch pinned upstreams, validate, write data/agents/ (also: npm run sync:agents)
 node scripts/sync-agent-lists.ts --check    # exit 1 when the committed files are stale
 ```
 

package/docs/policies/contract.md

@@ -0,0 +1,52 @@
+# Policies: The policy contract and your own patterns
+
+Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
+
+## The policy contract in TypeScript
+
+The policies are modules of one shape, `PolicyModule<Config, State>` in
+`src/types.ts`: `targets`, `compile`, `onRequest`, `onResponse`, optional
+`onError`, `describe` and `close`. `@jimhoyd/urlcode/policies` exports that type with
+`PolicyRequest`, `PolicyContext`, `PolicyChain`, `PolicyShared` and
+`PolicyRegistry` (the five built-ins keyed by name), and the declarations ship
+with the package. A per-policy configuration is typed as the YAML it accepts,
+and a `profiles` layer may hold a partial one:
+
+```ts
+import { registry, targets, type PolicyRegistry, type PolicyRequest } from '@jimhoyd/urlcode/policies';
+
+const throttle: PolicyRegistry['throttle'] = registry.throttle;   // PolicyModule<ThrottleConfig, ThrottleState>
+const support = throttle.targets({ quota: 120, window: 60, partition: 'client', status: 429 });  // per-target support for this config
+console.log(support.vercel, support.cloudflare);
+function inspect(request: PolicyRequest): void { console.log(request.route, request.client, targets); }
+```
+
+The registry is read-only: a project cannot add a policy from YAML, and an
+operator adds behavior through [plugins](../PLUGINS.md), not by editing it.
+
+## Supplying your own patterns
+
+The runtime ships mechanisms and one named profile, not an opinion about who
+should be blocked. Ways to express your own:
+
+- **Custom profiles.** Define any number under `profiles` and select one per
+  project or per route. Profiles are plain data and travel with the YAML.
+- **Per-route overrides.** Any key can be tightened, replaced or set to
+  `false` on a route.
+- **Own agent lists.** `agents.deny` and `agents.allow` accept bundled list
+  names and project-relative `.json` files in the same schema, so a list you
+  do not want to redistribute stays yours. `denyPatterns`/`allowPatterns`
+  take a bounded, linear-time pattern subset. See [agents](agents.md).
+- **Header by header.** `security.set` adds or overrides a header and wins over
+  the profile, YAML `response.headers` and handler output; `security.unset`
+  drops one the profile would emit. Headers the runtime or a handler owns
+  (`content-type`, `cache-control`, `set-cookie`, `etag`, `location`, and the
+  rest listed in `src/policies/security.ts`) cannot be `set`.
+  See [security](security.md).
+- **Explicit cache fields.** A strategy sets defaults; `maxAge`,
+  `staleWhileRevalidate`, `staleIfError`, `cdnMaxAge`, `originTtl`, `vary`,
+  `statuses`, `maxBytes` and `maxEntries` override what it implies.
+  See [cache](cache.md).
+- **Plugins.** Verified-bot checks, shared-store throttling, purge endpoints
+  and anything vendor-specific are host code an operator passes in;
+  see [plugins](../PLUGINS.md).

package/docs/policies/hardened.md

@@ -0,0 +1,56 @@
+# Policies: The built-in `hardened` profile and hardening guidance
+
+Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
+
+## The built-in `hardened` profile
+
+`policies.profile: hardened` expands to the following and nothing else, so it
+can be read in one place and overridden key by key. This is
+`builtinProfiles.hardened` in `src/policies.ts`:
+
+```yaml
+policies:
+  security: { headers: oshp }
+  agents: { deny: [ai-crawlers], status: 403 }
+  throttle: { quota: 120, window: 60, partition: client, status: 429 }
+  compression: { encodings: [br, gzip], minBytes: 1024 }
+  cache: { strategy: revalidate }
+```
+
+The numbers are starting points chosen to be safe for a single small instance;
+they are not tuned for any workload and not a security assessment of your
+deployment. Note what the profile implies per target: on Vercel and AWS it
+refuses activation as written, because `throttle.partition: client` is
+refused there; set `throttle: false` (or `partition: route`) at the project
+or route level. `compression` is delegated to the platform. On Cloudflare
+only `agents` and `security` survive and `compression` is delegated, so the
+profile must also drop `throttle` and `cache` there.
+There is no `strict` profile: anything stricter is a per-project decision.
+
+## Hardened configuration guidance
+
+Advice, not defaults, condensed from the spike's section 6.
+
+1. **Network and edge first.** Volumetric protection, TLS termination and
+   per-client connection budgets stay with the provider or the reverse proxy.
+   Runtime policies are a second layer, never the first.
+2. **Ingress to origin.** Bind privately; allow only the proxy's addresses;
+   pass `--trusted-proxies` so `client` partitioning sees the real peer.
+3. **Request policies.** Agents before throttle: denials are cheaper than
+   counting. Start throttle in `mode: report` for a release to see real
+   quotas in the headers and logs, then switch to `enforce`.
+4. **Allow before deny.** Keep an explicit allow for the crawlers you need
+   indexed; a broad deny without one is the common self-inflicted outage.
+5. **Route contract.** Exact methods, `request.body` limits and `expires` on
+   campaign routes still do most of the work.
+6. **Response policies.** Security headers on every route; compression only
+   on listed types and never on secret-bearing responses (the BREACH class of
+   attack, which is why compression is skipped where a route declares secrets
+   unless `allowWithSecrets` says otherwise); caching only with a strategy
+   whose semantics you can state, `immutable` only on content-hashed paths,
+   `no-store` everywhere else.
+7. **Lists as pinned data.** Bundled agent lists ship with the release, so a
+   rollback rolls the list back too.
+8. **Read the table.** Check `urlcode routes` on each target you deploy to;
+   the same YAML is refused where it cannot be enforced, and that is the
+   point.

package/docs/policies/interoperability.md

@@ -0,0 +1,169 @@
+# Policies: Interoperability between policies
+
+Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
+
+## Interoperability
+
+Every pair of policies, and every policy against the runtime's own responses,
+was reviewed by reading the code and by exercising a server. The rules below
+are the ones the current code enforces; where a combination misbehaves, the
+rule says so and names what to do instead.
+
+### Cannot coexist
+
+Hard conflicts: the runtime refuses activation, or the combination produces
+a wrong answer today.
+
+- **Origin cache and conditional or range requests.** A request carrying
+  `If-None-Match`, `If-Modified-Since`, `If-Match`, `If-Unmodified-Since` or
+  `Range` is never answered from the origin cache: a stored entry is a full
+  `200` representation and the handler owns validators and ranges, so such
+  requests always reach it and get the handler's `304`, `412` or `206`.
+  Unconditional requests are served from the entry.
+- **`security.unset` and a route that switches profile.** `unset` is
+  validated against the profile in effect on that route. A project-level
+  `unset` merges into a route that names a profile without that header
+  (`headers: off`, or `oshp-no-csp` with `unset: [Content-Security-Policy]`)
+  and activation fails with `unset names "...", which the off profile does
+  not emit`. Write `unset: []` on that route: a route key replaces the whole
+  array.
+- **`security.set` of `Cache-Control`, `Content-Encoding`, `ETag`,
+  `Content-Type`, `Set-Cookie`, `Location` and the other reserved names** is
+  refused at activation (`is owned by the runtime or handler`). `Vary`,
+  `RateLimit`, `RateLimit-Policy`, `Retry-After` and `Age` are reserved for
+  the same reason: the cache and throttle policies own them, and a `set` of
+  any of the five is refused at activation with the route named. Declare
+  `vary` on the cache policy instead.
+- **`agents.denyEmpty`, `throttle` and the generated probes.** `urlcode
+  audit`, `urlcode test` and `urlcode benchmark` send generated probes as
+  `Mozilla/5.0 (compatible; RouteProbe/0.1)`,
+  so `denyEmpty` does not fail them; a deny pattern that matches that string
+  would. A tight `throttle` fails an audit once the probes exceed `quota`
+  (the audit runs from one address, so a `static` tree with more files than
+  the quota trips it): keep the quota at least the number of generated cases
+  or run the audit in `mode: report`.
+- **`hardened` on Vercel and AWS** is refused as written, because
+  `throttle.partition: client` cannot be honoured there; **on Cloudflare**
+  the build refuses `throttle` and `cache`. Override the offending keys with
+  `false` or `partition: route` as [the `hardened` page](hardened.md) describes.
+- **`compression.encodings: [zstd]` on a Node without `zlib.zstdCompressSync`**
+  fails activation with the route named rather than serving identity.
+
+### Coexist with defined precedence
+
+Pairs that work, with the rule the code applies.
+
+- **Request order is `agents`, `throttle`, cache lookup.** A denied agent is
+  never counted and never looked up; a throttled request is never looked up.
+  An agent on an `allow` list passes `agents` and is still throttled. An
+  `agents` denial and a `throttle` refusal both pass through the cache
+  policy's response hook (they carry no flight, so nothing is stored) and
+  pick up its declared `vary` names, then security headers, then
+  `Vary: Accept-Encoding` from compression; their bodies are below `minBytes`
+  so they are never encoded.
+- **Cache hit and the response phase.** A hit skips only the cache's own
+  response hook: it still carries the client's `RateLimit` headers (the
+  request was counted), the security profile, and is compressed on the way
+  out. Stored entries are the handler's bytes and headers after YAML
+  `response.headers` and the cache policy ran, before throttle, security and
+  compression: bodies are stored uncompressed and encoded again on every hit,
+  and a `RateLimit` value is never stored. A cache hit on an asset serves the
+  same snapshot buffer, so a precompressed variant is used for `GET` and
+  reported at the variant's length for `HEAD`, exactly as when uncached.
+- **Cache `Vary` and compression `Vary`.** The cache merges its declared
+  `vary` names first; compression appends `Accept-Encoding` without
+  duplicating it and leaves a `Vary: *` alone. The origin key uses only the
+  cache's names: because bodies are stored uncompressed, `Accept-Encoding` is
+  not part of the key and need not be.
+- **ETags across `cache` and `compression`.** `revalidate` keeps a handler or
+  asset `ETag` and computes a strong SHA-256 tag for a `200` without one.
+  Compression then weakens a dynamically encoded body's tag (`W/"..."`) and
+  suffixes a precompressed asset's (`"...-gz"`). Revalidation works in every
+  combination: the cache's `304` compares weakly, the asset handler compares
+  weakly against the identity tag, and compression answers `304` for a
+  suffixed tag it produced. The `304` that `revalidate` produces keeps
+  `Content-Type`, so compression adds `Vary: Accept-Encoding` to it as it
+  does to the asset handler's own `304`.
+- **Who owns `Cache-Control`.** YAML `response.headers` first, then an asset
+  handler's `cacheControl` when the cache policy is only inherited, then a
+  handler's `private` or `no-store`, then the strategy; `security.set` cannot
+  name it. A `no-store` or `private` handler answer is never stored whatever
+  the strategy says.
+- **Security headers and everything else.** Profile headers fill gaps only:
+  YAML `response.headers`, function, asset, redirect and early-denial headers
+  keep their values. `set` overrides all of them. `Strict-Transport-Security`
+  needs an `https` origin. The profile is applied on cache hits and on early
+  denials (including a plugin short-circuit), on the self-hosted server and
+  in the Worker alike.
+- **Compression and secrets or cookies.** A route with `secrets` or a
+  response with `Set-Cookie` is sent as identity (still with `Vary`) unless
+  `allowWithSecrets: true`. A route with `secrets` also never enters the
+  origin cache, so the two policies agree on what a secret-bearing route is.
+- **Throttle and the 405.** The request phase runs before the method check,
+  so a request that ends as `405` was counted, and the `405` passes through
+  the response phase: it carries the `RateLimit` headers, the security
+  profile and plugin `onResponse` rewrites. Nothing stores it.
+- **Plugins and policies.** `onRequest` runs before every policy; a
+  short-circuit result skips `agents`, `throttle` and the cache lookup
+  (nothing is counted, matched or stored) and skips the cache store and the
+  throttle headers, then receives security headers and compression, then
+  every plugin's `onResponse`. On a thrown error the policies' `onError`
+  hooks run first (in the order the policies were declared) and then plugin
+  `onError` hooks in reverse. Only the cache policy has an error hook today
+  and it never returns a fallback (`stale-if-error` is header-only); if a
+  future policy did, that fallback would pass through the response phase and
+  every plugin `onResponse`, and plugin `onError` would not run for that
+  request.
+- **Reload.** Every reload builds a new runtime with fresh shared state:
+  throttle counters start empty and the origin cache and precompressed
+  variants are rebuilt; a client mid-window gets a fresh budget. The plugin
+  objects are the ones the operator passed and persist across reloads:
+  `onActivate` runs for the new runtime before `onClose` runs for the old,
+  so a plugin's own state (a shared-store connection, a `WeakMap`) survives a
+  reload unless its `onClose` discards it. A plugin whose `onActivate`
+  throws makes the reload fail and the old runtime keeps serving.
+- **Merge edge cases.** A route `profile` that lacks a key the project layer
+  had leaves that key in force (layers merge, they do not replace); `false`
+  at the project level followed by an object at the route level re-enables
+  the policy with the route's object alone, so it must be complete
+  (`throttle` needs `quota` and `window`); a custom profile named like a
+  built-in shadows it everywhere.
+- **Memory bounds add up.** Per runtime: 64 MiB of asset snapshot, up to
+  64 MiB of precompressed variants, up to 64 MiB of origin-cache bodies (a
+  stored asset references the snapshot buffer rather than copying it, but
+  is counted against the cache budget), and the throttle table at the
+  largest `maxKeys` (100,000 keys by default). Two routes serving the same
+  file compress it separately and both count. During a reload both
+  generations exist at once. [Capacity](../CAPACITY.md) states the asset,
+  throttle and cache figures; the precompressed budget belongs in that table
+  too.
+- **Cloudflare.** The artifact carries the effective `agents` and `security`
+  configuration per route, with the entries of any project list file
+  embedded under the reference as written in YAML (no filesystem path); a
+  route-level `agents: false` leaves the artifact without that key. The
+  Worker runs `agents` on the request and `security` on the response, so an
+  early denial carries the profile exactly as on the self-hosted server.
+
+### Not covered by policies
+
+- **Every error the runtime throws** (404 for no match, disabled route or
+  missing link, 410, 400/413/415 from body checks, 502/503/504 from the
+  sandbox or a link store) bypasses the response phase: no `Vary`, no
+  `RateLimit`, no compression, no plugin `onResponse`, on every target.
+  What they do get is the `security` policy: the matched route's effective
+  profile when the error came after routing (so a route with
+  `security: false` answers its 410 bare), otherwise the project-level
+  profile, including a host-side error such as an oversized body or shed
+  admission and the Worker's own 404. The runtime's fixed headers
+  (`Content-Type`, `Cache-Control: no-store`, `Content-Length`,
+  `X-Request-Id`, `X-Content-Type-Options`) can never be replaced by it.
+  Plugins keep `onError` for observation; a policy error hook may answer with
+  a fallback, and none does today.
+- **The audit's probes** share one address and one `User-Agent`, so they do
+  not exercise `agents` or `throttle` the way real traffic does;
+  the policy table in `testPlan().policies` is the audit's evidence for
+  those two.
+- **`stale-if-error` at the origin**: header-only, as the
+  [cache page](cache.md) states.
+- **Cross-instance state**: counters and the cache are per runtime on every
+  target; a shared budget or a shared cache is a plugin.

package/docs/policies/operations.md

@@ -0,0 +1,45 @@
+# Policies: Client identity, inventory and logging
+
+Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
+
+## Client identity and `--trusted-proxies`
+
+`throttle` partitions by `client`. On the self-hosted server the client is the
+socket peer unless `urlcode serve --trusted-proxies 10.0.0.0/8,fd00::/8`
+names the addresses allowed to speak for a client. Then `X-Forwarded-For` is
+walked from the right, skipping trusted hops, and the first untrusted address is
+the client; a chain made only of trusted proxies yields its leftmost entry, and
+a malformed entry is skipped. A forwarded header from a peer
+outside the trusted set is ignored, as is a request carrying more than one
+`X-Forwarded-For` field. Ranges are IPv4 or IPv6 CIDRs (at most 256);
+IPv4-mapped IPv6 peers match IPv4 ranges. `startServer({ trustedProxies })`
+takes the same list.
+
+A request whose client cannot be resolved (an adapter without a peer, an
+embedding caller that passes none) shares one bucket rather than being exempt,
+so a misconfigured proxy fails closed. The throttle summary in
+`testPlan().policies` records this as `unresolvedClient: "shared key"`. The runtime still
+never trusts forwarded headers for its public origin; set `--origin`
+explicitly, as [resilience](../RESILIENCE.md) already requires.
+
+## What `routes` and `audit` report
+
+`urlcode routes` prints the inventory with a `policies` array per route naming
+the policies effective on it (`testPlan().inventory[].policies`) and the full
+`policies` map. The embedding API and a plugin's `onActivate` see
+`testPlan().policies`, a map from route pattern to each policy's summary with
+its `target` value (`native`, `compiled` or `delegated`), the per-route
+capability table the portability rule calls for. `urlcode audit` prints the
+same table under `policies` and, with `--compliance`, checks the declared
+configuration against standards-referenced rules; see
+[compliance](../COMPLIANCE.md). `urlcode doctor` lists the policy names this
+runtime knows.
+
+## Logging
+
+Policies log through the runtime's request log with one-line events:
+`{ event: 'throttle', route, outcome: 'exceeded' | 'allowed', remaining }`,
+`{ event: 'agents', route, list, outcome: 'denied' | 'reported' }` and the
+cache events described on the [cache page](cache.md). Events name the
+configured route pattern and the list or strategy, never a client address, a
+User-Agent string or request text. A logging failure never changes a response.

package/docs/yaml/assets.md

@@ -0,0 +1,36 @@
+# YAML guide: Pages, static folders and downloads
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 10. Pages, static folders, downloads and MIME
+
+```yaml
+  /about:
+    page:
+      file: public/about.html
+      cacheControl: no-cache
+  /assets/*:
+    static:
+      directory: public/assets
+      index: index.html
+      cacheControl: public, max-age=3600
+  /download:
+    download:
+      file: public/guide.txt
+      filename: urlcode-guide.txt
+      contentType: text/plain
+      cacheControl: no-store
+```
+
+All files must exist. MIME is detected by extension, not content sniffing; unknown
+extensions become application/octet-stream. `contentType` overrides detection
+without MIME parameters. An override on a static mount affects all its files.
+The download name defaults to the source basename. `index` is opt-in and only
+applies to slash-terminated requests. No automatic slash redirect or SPA fallback.
+
+Cache choices: `no-cache` (asset default), `no-store`, `public, max-age=3600`,
+`public, max-age=31536000, immutable`. Reserve immutable caching for versioned
+URLs. GET/HEAD, ETag/date validation and single byte ranges are supported.
+Files stay snapshotted until reload/restart. See [assets](../ASSETS.md) for complete
+conditional/range semantics and publication safety. Files are limited to 16 MiB
+each and 64 MiB total unique bytes per snapshot.

package/docs/yaml/conditions.md

@@ -0,0 +1,20 @@
+# YAML guide: Enable, disable and expire
+
+Snippets are entries under `routes:` unless stated otherwise; the [guide index](../YAML-GUIDE.md) lists every page.
+
+## 11. Enable, disable and expire
+
+```yaml
+  /paused:
+    enabled: false
+    redirect: {url: 'https://example.com/'}
+  /campaign:
+    description: A scheduled end, no scheduled start
+    expires: "2030-01-01T00:00:00Z"
+    redirect: {url: 'https://example.com/'}
+```
+
+Quote timestamps so they remain strings. Disabled routes return 404; expired
+routes return 410. Expiry is an absolute UTC timestamp, not a TTL. There is no
+start-time scheduler. `description` is authoring metadata. Changing YAML activates
+through dev reload or production restart/deployment; it is not an HTTP mutation.