@jimhoyd/urlcode 0.3.0

package/docs/YAML-REFERENCE.md

@@ -0,0 +1,328 @@
+# YAML field reference
+
+Generated from the bundled JSON Schema by `npm run docs:reference`. Required
+means required within its containing object, not that the object itself must be
+present. `routes.*` means a route path; other `*` markers mean user-selected
+keys. `[]` means an array item. Option rows describe union alternatives.
+
+Read the [YAML guide](YAML-GUIDE.md) for examples and [specification](SPECIFICATION.md)
+for semantic validation beyond JSON Schema. Exactly one handler is required per
+route; respond.text/respond.json are mutually exclusive. Runtime defaults include
+GET/HEAD, redirect 302, respond 200, default module export, and asset no-cache.
+Only Set-Cookie accepts response header arrays. This table does not imply all
+schema-valid combinations activate successfully.
+
+| Field | Type | Required | Schema constraints |
+|---|---|---|---|
+| `version` | constant | yes | const: "1" |
+| `routes` | object | yes | maxProperties: 100000 |
+| `routes.*` | object | no | unknown keys rejected |
+| `routes.*.methods` | array | no | default: ["GET","HEAD"]; minItems: 1; uniqueItems: true |
+| `routes.*.methods[]` | string | no | enum: ["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS"] |
+| `routes.*.enabled` | boolean | no | — |
+| `routes.*.expires` | string | no | — |
+| `routes.*.description` | string | no | maxLength: 1024 |
+| `routes.*.parameters` | array | no | maxItems: 64 |
+| `routes.*.parameters[]` | object | no | unknown keys rejected |
+| `routes.*.parameters[].name` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_-]*$" |
+| `routes.*.parameters[].in` | string | yes | enum: ["path","query","header"] |
+| `routes.*.parameters[].required` | boolean | no | — |
+| `routes.*.parameters[].schema` | object | yes | unknown keys rejected |
+| `routes.*.parameters[].schema.type` | string | yes | enum: ["string","integer","number","boolean","array"] |
+| `routes.*.parameters[].schema.enum` | array | no | minItems: 1; uniqueItems: true |
+| `routes.*.parameters[].schema.enum[]` | string / number / boolean | no | — |
+| `routes.*.parameters[].schema.default` | string / number / boolean / array | no | — |
+| `routes.*.parameters[].schema.default[]` | string / number / boolean | no | — |
+| `routes.*.parameters[].schema.minLength` | integer | no | minimum: 0; maximum: 8192 |
+| `routes.*.parameters[].schema.maxLength` | integer | no | minimum: 0; maximum: 8192 |
+| `routes.*.parameters[].schema.minimum` | number | no | — |
+| `routes.*.parameters[].schema.maximum` | number | no | — |
+| `routes.*.parameters[].schema.items` | object | no | unknown keys rejected |
+| `routes.*.parameters[].schema.items.type` | string | yes | enum: ["string","integer","number","boolean"] |
+| `routes.*.parameters[].schema.maxItems` | integer | no | minimum: 0; maximum: 100 |
+| `routes.*.redirect` | object | no | unknown keys rejected |
+| `routes.*.redirect.url` | string | yes | maxLength: 8192 |
+| `routes.*.redirect.status` | number | no | enum: [301,302,303,307,308] |
+| `routes.*.redirect.query` | object | no | unknown keys rejected |
+| `routes.*.redirect.query.pass` | one of the shapes below | no | — |
+| `routes.*.redirect.query.pass (option 1)` | constant | no | const: false |
+| `routes.*.redirect.query.pass (option 2)` | array | no | uniqueItems: true |
+| `routes.*.redirect.query.pass (option 2)[]` | string | no | — |
+| `routes.*.redirect.query.map` | object | no | — |
+| `routes.*.redirect.query.map.*` | object | no | unknown keys rejected |
+| `routes.*.redirect.query.map.*.from` | string | yes | enum: ["path","query","header"] |
+| `routes.*.redirect.query.map.*.name` | string | yes | — |
+| `routes.*.function` | object | no | unknown keys rejected |
+| `routes.*.function.source` | string | yes | maxLength: 1024 |
+| `routes.*.function.export` | string | no | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.function.args` | object | no | — |
+| `routes.*.function.args.*` | one of the shapes below | no | — |
+| `routes.*.function.args.* (option 1)` | string / number / boolean | no | — |
+| `routes.*.function.args.* (option 2)` | object | no | unknown keys rejected |
+| `routes.*.function.args.* (option 2).from` | string | yes | enum: ["path","query","header"] |
+| `routes.*.function.args.* (option 2).name` | string | yes | — |
+| `routes.*.function.args.* (option 3)` | object | no | unknown keys rejected |
+| `routes.*.function.args.* (option 3).env` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.function.args.* (option 4)` | object | no | unknown keys rejected |
+| `routes.*.function.args.* (option 4).secret` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.env` | object | no | — |
+| `routes.*.env.*` | one of the shapes below | no | — |
+| `routes.*.env.* (option 1)` | object | no | unknown keys rejected |
+| `routes.*.env.* (option 1).value` | string | yes | — |
+| `routes.*.env.* (option 2)` | object | no | unknown keys rejected |
+| `routes.*.env.* (option 2).env` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.secrets` | object | no | — |
+| `routes.*.secrets.*` | object | no | unknown keys rejected |
+| `routes.*.secrets.*.secret` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.page` | object | no | unknown keys rejected |
+| `routes.*.page.file` | string | yes | minLength: 1; maxLength: 1024 |
+| `routes.*.page.contentType` | string | no | maxLength: 128; pattern: "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$" |
+| `routes.*.page.cacheControl` | string | no | enum: ["no-cache","no-store","public, max-age=3600","public, max-age=31536000, immutable"] |
+| `routes.*.download` | object | no | unknown keys rejected |
+| `routes.*.download.file` | string | yes | minLength: 1; maxLength: 1024 |
+| `routes.*.download.contentType` | string | no | maxLength: 128; pattern: "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$" |
+| `routes.*.download.cacheControl` | string | no | enum: ["no-cache","no-store","public, max-age=3600","public, max-age=31536000, immutable"] |
+| `routes.*.download.filename` | string | no | minLength: 1; maxLength: 255 |
+| `routes.*.static` | object | no | unknown keys rejected |
+| `routes.*.static.directory` | string | yes | minLength: 1; maxLength: 1024 |
+| `routes.*.static.contentType` | string | no | maxLength: 128; pattern: "^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$" |
+| `routes.*.static.cacheControl` | string | no | enum: ["no-cache","no-store","public, max-age=3600","public, max-age=31536000, immutable"] |
+| `routes.*.static.index` | string | no | pattern: "^[A-Za-z0-9_-]+\\.html$" |
+| `routes.*.request` | object | no | unknown keys rejected |
+| `routes.*.request.body` | object | no | unknown keys rejected |
+| `routes.*.request.body.required` | boolean | no | — |
+| `routes.*.request.body.maxBytes` | integer | no | minimum: 0; maximum: 1048576 |
+| `routes.*.request.body.contentTypes` | array | no | minItems: 1; maxItems: 16; uniqueItems: true |
+| `routes.*.request.body.contentTypes[]` | string | no | pattern: "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$" |
+| `routes.*.request.body.format` | string | no | enum: ["text","json"] |
+| `routes.*.response` | object | no | unknown keys rejected |
+| `routes.*.response.headers` | object | no | maxProperties: 64 |
+| `routes.*.response.headers.*` | one of the shapes below | no | — |
+| `routes.*.response.headers.* (option 1)` | string | no | maxLength: 4096 |
+| `routes.*.response.headers.* (option 2)` | array | no | minItems: 1; maxItems: 16 |
+| `routes.*.response.headers.* (option 2)[]` | string | no | maxLength: 4096 |
+| `routes.*.respond` | object | no | unknown keys rejected |
+| `routes.*.respond.status` | integer | no | minimum: 200; maximum: 599 |
+| `routes.*.respond.text` | string | no | maxLength: 1048576 |
+| `routes.*.respond.json` | any JSON value | no | — |
+| `routes.*.middleware` | array | no | maxItems: 16 |
+| `routes.*.middleware[]` | object | no | unknown keys rejected |
+| `routes.*.middleware[].source` | string | yes | maxLength: 1024 |
+| `routes.*.middleware[].export` | string | no | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.link` | object | no | unknown keys rejected |
+| `routes.*.link.collection` | string | yes | pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" |
+| `routes.*.link.code` | object | yes | unknown keys rejected |
+| `routes.*.link.code.from` | constant | yes | const: "path" |
+| `routes.*.link.code.name` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.policies` | object | no | unknown keys rejected |
+| `routes.*.policies.profile` | string | no | pattern: "^[a-z][a-z0-9-]{0,63}$" |
+| `routes.*.policies.throttle` | one of the shapes below | no | — |
+| `routes.*.policies.throttle (option 1)` | constant | no | const: false |
+| `routes.*.policies.throttle (option 2)` | object | no | unknown keys rejected |
+| `routes.*.policies.throttle (option 2).quota` | integer | no | minimum: 1; maximum: 1000000 |
+| `routes.*.policies.throttle (option 2).window` | integer | no | minimum: 1; maximum: 86400 |
+| `routes.*.policies.throttle (option 2).partition` | string | no | enum: ["client","route","client-route"]; default: "client" |
+| `routes.*.policies.throttle (option 2).status` | integer | no | default: 429; minimum: 400; maximum: 599 |
+| `routes.*.policies.throttle (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `routes.*.policies.throttle (option 2).maxKeys` | integer | no | default: 100000; minimum: 1000; maximum: 10000000 |
+| `routes.*.policies.agents` | one of the shapes below | no | — |
+| `routes.*.policies.agents (option 1)` | constant | no | const: false |
+| `routes.*.policies.agents (option 2)` | object | no | unknown keys rejected |
+| `routes.*.policies.agents (option 2).deny` | array | no | maxItems: 32; uniqueItems: true |
+| `routes.*.policies.agents (option 2).deny[]` | string | no | minLength: 1; maxLength: 1024 |
+| `routes.*.policies.agents (option 2).allow` | array | no | maxItems: 32; uniqueItems: true |
+| `routes.*.policies.agents (option 2).allow[]` | string | no | minLength: 1; maxLength: 1024 |
+| `routes.*.policies.agents (option 2).denyPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `routes.*.policies.agents (option 2).denyPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `routes.*.policies.agents (option 2).allowPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `routes.*.policies.agents (option 2).allowPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `routes.*.policies.agents (option 2).denyEmpty` | boolean | no | default: false |
+| `routes.*.policies.agents (option 2).status` | integer | no | default: 403; minimum: 400; maximum: 599 |
+| `routes.*.policies.agents (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `routes.*.policies.security` | one of the shapes below | no | — |
+| `routes.*.policies.security (option 1)` | constant | no | const: false |
+| `routes.*.policies.security (option 2)` | object | no | unknown keys rejected |
+| `routes.*.policies.security (option 2).headers` | string | no | enum: ["oshp","oshp-no-csp","off"]; default: "oshp" |
+| `routes.*.policies.security (option 2).set` | object | no | maxProperties: 32 |
+| `routes.*.policies.security (option 2).set.*` | string | no | maxLength: 4096 |
+| `routes.*.policies.security (option 2).unset` | array | no | maxItems: 32; uniqueItems: true |
+| `routes.*.policies.security (option 2).unset[]` | string | no | minLength: 1; maxLength: 128 |
+| `routes.*.policies.compression` | one of the shapes below | no | — |
+| `routes.*.policies.compression (option 1)` | constant | no | const: false |
+| `routes.*.policies.compression (option 2)` | object | no | unknown keys rejected |
+| `routes.*.policies.compression (option 2).encodings` | array | no | default: ["br","gzip"]; minItems: 1; uniqueItems: true |
+| `routes.*.policies.compression (option 2).encodings[]` | string | no | enum: ["br","gzip","deflate","zstd"] |
+| `routes.*.policies.compression (option 2).minBytes` | integer | no | default: 1024; minimum: 0; maximum: 1048576 |
+| `routes.*.policies.compression (option 2).types` | array | no | maxItems: 64; uniqueItems: true |
+| `routes.*.policies.compression (option 2).types[]` | string | no | minLength: 1; maxLength: 128 |
+| `routes.*.policies.compression (option 2).level` | integer | no | minimum: 1; maximum: 11 |
+| `routes.*.policies.compression (option 2).allowWithSecrets` | boolean | no | default: false |
+| `routes.*.policies.cache` | one of the shapes below | no | — |
+| `routes.*.policies.cache (option 1)` | constant | no | const: false |
+| `routes.*.policies.cache (option 2)` | object | no | unknown keys rejected |
+| `routes.*.policies.cache (option 2).strategy` | string | no | enum: ["no-store","revalidate","public","immutable","swr","sie","micro","cdn-only","private"] |
+| `routes.*.policies.cache (option 2).maxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.policies.cache (option 2).staleWhileRevalidate` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.policies.cache (option 2).staleIfError` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.policies.cache (option 2).cdnMaxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `routes.*.policies.cache (option 2).originTtl` | integer | no | minimum: 0; maximum: 86400 |
+| `routes.*.policies.cache (option 2).vary` | array | no | maxItems: 8; uniqueItems: true |
+| `routes.*.policies.cache (option 2).vary[]` | string | no | minLength: 1; maxLength: 128 |
+| `routes.*.policies.cache (option 2).statuses` | array | no | maxItems: 16; uniqueItems: true |
+| `routes.*.policies.cache (option 2).statuses[]` | integer | no | minimum: 200; maximum: 599 |
+| `routes.*.policies.cache (option 2).maxBytes` | integer | no | minimum: 0; maximum: 16777216 |
+| `routes.*.policies.cache (option 2).maxEntries` | integer | no | minimum: 1; maximum: 1000000 |
+| `routes.*.policies.cache (option 2).force` | boolean | no | default: false |
+| `includes` | array | no | maxItems: 256; uniqueItems: true |
+| `includes[]` | string | no | maxLength: 1024 |
+| `dynamicLinks` | boolean | no | default: false |
+| `policies` | object | no | unknown keys rejected |
+| `policies.profile` | string | no | pattern: "^[a-z][a-z0-9-]{0,63}$" |
+| `policies.throttle` | one of the shapes below | no | — |
+| `policies.throttle (option 1)` | constant | no | const: false |
+| `policies.throttle (option 2)` | object | no | unknown keys rejected |
+| `policies.throttle (option 2).quota` | integer | no | minimum: 1; maximum: 1000000 |
+| `policies.throttle (option 2).window` | integer | no | minimum: 1; maximum: 86400 |
+| `policies.throttle (option 2).partition` | string | no | enum: ["client","route","client-route"]; default: "client" |
+| `policies.throttle (option 2).status` | integer | no | default: 429; minimum: 400; maximum: 599 |
+| `policies.throttle (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `policies.throttle (option 2).maxKeys` | integer | no | default: 100000; minimum: 1000; maximum: 10000000 |
+| `policies.agents` | one of the shapes below | no | — |
+| `policies.agents (option 1)` | constant | no | const: false |
+| `policies.agents (option 2)` | object | no | unknown keys rejected |
+| `policies.agents (option 2).deny` | array | no | maxItems: 32; uniqueItems: true |
+| `policies.agents (option 2).deny[]` | string | no | minLength: 1; maxLength: 1024 |
+| `policies.agents (option 2).allow` | array | no | maxItems: 32; uniqueItems: true |
+| `policies.agents (option 2).allow[]` | string | no | minLength: 1; maxLength: 1024 |
+| `policies.agents (option 2).denyPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `policies.agents (option 2).denyPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `policies.agents (option 2).allowPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `policies.agents (option 2).allowPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `policies.agents (option 2).denyEmpty` | boolean | no | default: false |
+| `policies.agents (option 2).status` | integer | no | default: 403; minimum: 400; maximum: 599 |
+| `policies.agents (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `policies.security` | one of the shapes below | no | — |
+| `policies.security (option 1)` | constant | no | const: false |
+| `policies.security (option 2)` | object | no | unknown keys rejected |
+| `policies.security (option 2).headers` | string | no | enum: ["oshp","oshp-no-csp","off"]; default: "oshp" |
+| `policies.security (option 2).set` | object | no | maxProperties: 32 |
+| `policies.security (option 2).set.*` | string | no | maxLength: 4096 |
+| `policies.security (option 2).unset` | array | no | maxItems: 32; uniqueItems: true |
+| `policies.security (option 2).unset[]` | string | no | minLength: 1; maxLength: 128 |
+| `policies.compression` | one of the shapes below | no | — |
+| `policies.compression (option 1)` | constant | no | const: false |
+| `policies.compression (option 2)` | object | no | unknown keys rejected |
+| `policies.compression (option 2).encodings` | array | no | default: ["br","gzip"]; minItems: 1; uniqueItems: true |
+| `policies.compression (option 2).encodings[]` | string | no | enum: ["br","gzip","deflate","zstd"] |
+| `policies.compression (option 2).minBytes` | integer | no | default: 1024; minimum: 0; maximum: 1048576 |
+| `policies.compression (option 2).types` | array | no | maxItems: 64; uniqueItems: true |
+| `policies.compression (option 2).types[]` | string | no | minLength: 1; maxLength: 128 |
+| `policies.compression (option 2).level` | integer | no | minimum: 1; maximum: 11 |
+| `policies.compression (option 2).allowWithSecrets` | boolean | no | default: false |
+| `policies.cache` | one of the shapes below | no | — |
+| `policies.cache (option 1)` | constant | no | const: false |
+| `policies.cache (option 2)` | object | no | unknown keys rejected |
+| `policies.cache (option 2).strategy` | string | no | enum: ["no-store","revalidate","public","immutable","swr","sie","micro","cdn-only","private"] |
+| `policies.cache (option 2).maxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `policies.cache (option 2).staleWhileRevalidate` | integer | no | minimum: 0; maximum: 31536000 |
+| `policies.cache (option 2).staleIfError` | integer | no | minimum: 0; maximum: 31536000 |
+| `policies.cache (option 2).cdnMaxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `policies.cache (option 2).originTtl` | integer | no | minimum: 0; maximum: 86400 |
+| `policies.cache (option 2).vary` | array | no | maxItems: 8; uniqueItems: true |
+| `policies.cache (option 2).vary[]` | string | no | minLength: 1; maxLength: 128 |
+| `policies.cache (option 2).statuses` | array | no | maxItems: 16; uniqueItems: true |
+| `policies.cache (option 2).statuses[]` | integer | no | minimum: 200; maximum: 599 |
+| `policies.cache (option 2).maxBytes` | integer | no | minimum: 0; maximum: 16777216 |
+| `policies.cache (option 2).maxEntries` | integer | no | minimum: 1; maximum: 1000000 |
+| `policies.cache (option 2).force` | boolean | no | default: false |
+| `profiles` | object | no | maxProperties: 32 |
+| `profiles.*` | object | no | unknown keys rejected |
+| `profiles.*.throttle` | one of the shapes below | no | — |
+| `profiles.*.throttle (option 1)` | constant | no | const: false |
+| `profiles.*.throttle (option 2)` | object | no | unknown keys rejected |
+| `profiles.*.throttle (option 2).quota` | integer | no | minimum: 1; maximum: 1000000 |
+| `profiles.*.throttle (option 2).window` | integer | no | minimum: 1; maximum: 86400 |
+| `profiles.*.throttle (option 2).partition` | string | no | enum: ["client","route","client-route"]; default: "client" |
+| `profiles.*.throttle (option 2).status` | integer | no | default: 429; minimum: 400; maximum: 599 |
+| `profiles.*.throttle (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `profiles.*.throttle (option 2).maxKeys` | integer | no | default: 100000; minimum: 1000; maximum: 10000000 |
+| `profiles.*.agents` | one of the shapes below | no | — |
+| `profiles.*.agents (option 1)` | constant | no | const: false |
+| `profiles.*.agents (option 2)` | object | no | unknown keys rejected |
+| `profiles.*.agents (option 2).deny` | array | no | maxItems: 32; uniqueItems: true |
+| `profiles.*.agents (option 2).deny[]` | string | no | minLength: 1; maxLength: 1024 |
+| `profiles.*.agents (option 2).allow` | array | no | maxItems: 32; uniqueItems: true |
+| `profiles.*.agents (option 2).allow[]` | string | no | minLength: 1; maxLength: 1024 |
+| `profiles.*.agents (option 2).denyPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `profiles.*.agents (option 2).denyPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `profiles.*.agents (option 2).allowPatterns` | array | no | maxItems: 256; uniqueItems: true |
+| `profiles.*.agents (option 2).allowPatterns[]` | string | no | minLength: 1; maxLength: 256 |
+| `profiles.*.agents (option 2).denyEmpty` | boolean | no | default: false |
+| `profiles.*.agents (option 2).status` | integer | no | default: 403; minimum: 400; maximum: 599 |
+| `profiles.*.agents (option 2).mode` | string | no | enum: ["enforce","report"]; default: "enforce" |
+| `profiles.*.security` | one of the shapes below | no | — |
+| `profiles.*.security (option 1)` | constant | no | const: false |
+| `profiles.*.security (option 2)` | object | no | unknown keys rejected |
+| `profiles.*.security (option 2).headers` | string | no | enum: ["oshp","oshp-no-csp","off"]; default: "oshp" |
+| `profiles.*.security (option 2).set` | object | no | maxProperties: 32 |
+| `profiles.*.security (option 2).set.*` | string | no | maxLength: 4096 |
+| `profiles.*.security (option 2).unset` | array | no | maxItems: 32; uniqueItems: true |
+| `profiles.*.security (option 2).unset[]` | string | no | minLength: 1; maxLength: 128 |
+| `profiles.*.compression` | one of the shapes below | no | — |
+| `profiles.*.compression (option 1)` | constant | no | const: false |
+| `profiles.*.compression (option 2)` | object | no | unknown keys rejected |
+| `profiles.*.compression (option 2).encodings` | array | no | default: ["br","gzip"]; minItems: 1; uniqueItems: true |
+| `profiles.*.compression (option 2).encodings[]` | string | no | enum: ["br","gzip","deflate","zstd"] |
+| `profiles.*.compression (option 2).minBytes` | integer | no | default: 1024; minimum: 0; maximum: 1048576 |
+| `profiles.*.compression (option 2).types` | array | no | maxItems: 64; uniqueItems: true |
+| `profiles.*.compression (option 2).types[]` | string | no | minLength: 1; maxLength: 128 |
+| `profiles.*.compression (option 2).level` | integer | no | minimum: 1; maximum: 11 |
+| `profiles.*.compression (option 2).allowWithSecrets` | boolean | no | default: false |
+| `profiles.*.cache` | one of the shapes below | no | — |
+| `profiles.*.cache (option 1)` | constant | no | const: false |
+| `profiles.*.cache (option 2)` | object | no | unknown keys rejected |
+| `profiles.*.cache (option 2).strategy` | string | no | enum: ["no-store","revalidate","public","immutable","swr","sie","micro","cdn-only","private"] |
+| `profiles.*.cache (option 2).maxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `profiles.*.cache (option 2).staleWhileRevalidate` | integer | no | minimum: 0; maximum: 31536000 |
+| `profiles.*.cache (option 2).staleIfError` | integer | no | minimum: 0; maximum: 31536000 |
+| `profiles.*.cache (option 2).cdnMaxAge` | integer | no | minimum: 0; maximum: 31536000 |
+| `profiles.*.cache (option 2).originTtl` | integer | no | minimum: 0; maximum: 86400 |
+| `profiles.*.cache (option 2).vary` | array | no | maxItems: 8; uniqueItems: true |
+| `profiles.*.cache (option 2).vary[]` | string | no | minLength: 1; maxLength: 128 |
+| `profiles.*.cache (option 2).statuses` | array | no | maxItems: 16; uniqueItems: true |
+| `profiles.*.cache (option 2).statuses[]` | integer | no | minimum: 200; maximum: 599 |
+| `profiles.*.cache (option 2).maxBytes` | integer | no | minimum: 0; maximum: 16777216 |
+| `profiles.*.cache (option 2).maxEntries` | integer | no | minimum: 1; maximum: 1000000 |
+| `profiles.*.cache (option 2).force` | boolean | no | default: false |
+| `site` | object | no | unknown keys rejected |
+| `site.robots` | object | no | unknown keys rejected |
+| `site.robots.disallow` | array | no | maxItems: 1024; uniqueItems: true |
+| `site.robots.disallow[]` | string | no | minLength: 1; maxLength: 2048 |
+| `site.robots.allow` | array | no | maxItems: 1024; uniqueItems: true |
+| `site.robots.allow[]` | string | no | minLength: 1; maxLength: 2048 |
+| `site.robots.sitemap` | boolean | no | — |
+| `site.robots.extra` | array | no | maxItems: 1024 |
+| `site.robots.extra[]` | string | no | maxLength: 2048 |
+| `site.sitemap` | one of the shapes below | no | — |
+| `site.sitemap (option 1)` | constant | no | const: true |
+| `site.sitemap (option 2)` | object | no | unknown keys rejected |
+| `site.sitemap (option 2).exclude` | array | no | maxItems: 1024; uniqueItems: true |
+| `site.sitemap (option 2).exclude[]` | string | no | minLength: 1; maxLength: 2048 |
+| `site.sitemap (option 2).changefreq` | string | no | enum: ["always","hourly","daily","weekly","monthly","yearly","never"] |
+| `site.sitemap (option 2).priority` | number | no | minimum: 0; maximum: 1 |
+| `site.favicon` | string | no | minLength: 1; maxLength: 1024 |
+| `site.securityTxt` | object | no | unknown keys rejected |
+| `site.securityTxt.contact` | array | yes | minItems: 1; maxItems: 64 |
+| `site.securityTxt.contact[]` | string | no | minLength: 1; maxLength: 2048 |
+| `site.securityTxt.expires` | string | yes | pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$" |
+| `site.securityTxt.policy` | array | no | maxItems: 64 |
+| `site.securityTxt.policy[]` | string | no | maxLength: 2048; pattern: "^https://" |
+| `site.securityTxt.acknowledgments` | array | no | maxItems: 64 |
+| `site.securityTxt.acknowledgments[]` | string | no | maxLength: 2048; pattern: "^https://" |
+| `site.securityTxt.preferredLanguages` | array | no | minItems: 1; maxItems: 64 |
+| `site.securityTxt.preferredLanguages[]` | string | no | minLength: 2; maxLength: 35 |
+| `site.securityTxt.canonical` | array | no | maxItems: 64 |
+| `site.securityTxt.canonical[]` | string | no | maxLength: 2048; pattern: "^https://" |
+| `site.securityTxt.encryption` | array | no | maxItems: 64 |
+| `site.securityTxt.encryption[]` | string | no | minLength: 1; maxLength: 2048 |
+| `site.llms` | string | no | minLength: 1; maxLength: 1024 |

package/docs/policies/agents.md

@@ -0,0 +1,182 @@
+# The `agents` policy
+
+Denies or reports requests by their `User-Agent`, before anything else runs.
+It is the cheapest refusal in the request chain (`agents`, then `throttle`,
+then the cache lookup), so a denied crawler never counts against a quota,
+never reaches the sandbox and never fills the origin cache.
+
+```yaml
+version: "1"
+policies:                        # project defaults, or per route under routes.<pattern>.policies
+  agents:
+    deny: [ai-crawlers]          # bundled list names, or project-relative .json files
+    allow: [monitoring]          # allow always wins over deny
+    denyPatterns: ["^curl/"]     # linear-time regex subset, matched case-insensitively
+    allowPatterns: ["^Mozilla/5\\.0 \\(compatible; Googlebot"]
+    denyEmpty: false             # deny a missing or blank User-Agent
+    status: 403                  # 400-599
+    mode: enforce                # enforce | report
+```
+
+The `hardened` profile sets `deny: [ai-crawlers]` with status 403. A route can
+override any key, or set `agents: false` to switch the policy off for itself.
+
+## Semantics
+
+- Matching is against the `User-Agent` request header only and is
+  case-insensitive. Nothing else about the request (address, path, other
+  headers) takes part.
+- Evaluation order: if any `allow` list or `allowPatterns` entry matches, the
+  request passes and nothing is logged. Otherwise the first `deny` list (in
+  the order written) or `denyPatterns` entry that matches denies it.
+- `urlcode audit`, `test` and `benchmark` send generated probes as
+  `Mozilla/5.0 (compatible; RouteProbe/0.1)`;
+  a fixture may set its own `user-agent` header. Upstream lists include
+  short unanchored names (the `ai-crawlers` list carries `Code`, which
+  matches any agent containing that word), so a custom allow pattern for
+  your own tooling is worth declaring before denying a whole list.
+- `denyEmpty: true` denies a request with no `User-Agent`, or one that is only
+  whitespace. Allow rules cannot match an empty header, so this always wins
+  for empty headers.
+- A denial answers `status` (default 403) with `content-type:
+  text/plain; charset=utf-8`, `cache-control: no-store` and the body
+  `Forbidden\n`. Response policies that also run at request time (cache,
+  compression) are skipped on the early response; `security` headers are
+  still applied.
+- Every denial is logged as `{ event: 'agents', route, list, outcome }`, where
+  `list` is the list name, the file path as written in YAML, `pattern` for
+  `denyPatterns`, or `empty` for `denyEmpty`. The raw header value is never
+  logged: a `User-Agent` is attacker-controlled text.
+- `mode: report` logs the same event with `outcome: 'reported'` and never
+  denies. Run a new deny list in report mode for a release, read the log, then
+  switch to `enforce`.
+
+## Allow before deny
+
+Broad deny lists without an explicit allow are the most common self-inflicted
+outage in this space. `crawlers` contains every search engine; `ai-crawlers`
+contains agents some operators want (for example `ChatGPT-User` or
+`Applebot-Extended` when a site chooses to appear in AI search). Keep an
+explicit `allow` or `allowPatterns` entry for the agents you depend on, and
+anchor it: `^Mozilla/5\.0 \(compatible; Googlebot` cannot be satisfied by a
+`Googlebot` token dropped in the middle of an unrelated string.
+
+Matching is string matching. A client can claim any `User-Agent`, and the
+genuine search crawlers publish the way to check a claim (reverse DNS for
+Googlebot, bingbot and Applebot; the IETF `web-bot-auth` HTTP Message
+Signature drafts for newer agents). That verification needs network calls and
+vendor data, so it belongs in a [host plugin](../SPIKE-EXTENSIONS.md) that
+runs after this policy, not in the runtime.
+
+## Bundled lists
+
+| Name | Contents | Upstream | Licence | Refresh |
+| --- | --- | --- | --- | --- |
+| `ai-crawlers` | every agent in `robots.json` (AI training, AI search and assistant crawlers) | [ai-robots-txt/ai.robots.txt](https://github.com/ai-robots-txt/ai.robots.txt) | MIT | pinned tag in `scripts/sync-agent-lists.ts` |
+| `crawlers` | every crawler, bot and automated client in `crawler-user-agents.json` | [monperrus/crawler-user-agents](https://github.com/monperrus/crawler-user-agents) | MIT (revisions after 2016-11-07 only) | same |
+| `seo` | `crawlers` entries tagged `seo` (backlink and rank trackers such as AhrefsBot, SemrushBot, MJ12bot) | derived from crawler-user-agents | MIT | same |
+| `monitoring` | `crawlers` entries tagged `monitoring` (UptimeRobot, Pingdom, StatusCake, ...) | derived from crawler-user-agents | MIT | same |
+
+Each list lives in `data/agents/<name>.json` as
+`{ name, description, source: { repository, url, license, tag, commit, file, fetchedAt }, entries }`
+with one entry per pattern: `{ name, pattern, source, sourceRevision, addedAt }`.
+The generated `data/agents/index.js` mirrors the `[name, pattern]` pairs so the
+policy module (which also runs inside the Cloudflare Worker) needs no
+filesystem. The upstream licences are reproduced verbatim under
+`data/agents/LICENSES/` and named in `NOTICE`, as Apache-2.0 section 4(d)
+requires. `urlcode audit` and the runtime's policy inventory report the list
+names, pattern counts and the pinned revision each list was built from, so a
+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 --check    # exit 1 when the committed files are stale
+```
+
+The script fetches each upstream at the tag and commit pinned in its `sources`
+table, normalises entries to the schema above (an ai.robots.txt agent name
+becomes an escaped literal pattern; a crawler-user-agents pattern is kept and
+named by its literal prefix), validates every pattern against the subset below
+(rewriting `{n,}` to `{n,64}`, and dropping and printing anything else),
+preserves `addedAt` from the previous file or the upstream `addition_date`, and
+writes the JSON lists, the index and the licence copies. To move to a newer
+upstream release, change the `tag` and `commit` pins and rerun; the revision
+appears in every entry and in the audit output. Refresh through an ordinary
+pull request so the list diff is reviewed like code. Behind an HTTPS proxy,
+set `NODE_USE_ENV_PROXY=1` so `fetch` honours `HTTPS_PROXY` and
+`NODE_EXTRA_CA_CERTS`.
+
+## Project lists
+
+`deny` and `allow` also accept a project-relative path ending in `.json`:
+
+```yaml
+policies:
+  agents:
+    deny: [agents/deny.json]
+```
+
+The file is either an array of entries or `{ "entries": [...] }`, each entry
+`{ "name": "curl", "pattern": "^curl/" }` (`name` optional; the other fields
+of the bundled schema are ignored). It must stay inside the project, hold at
+most 4096 entries and pass the same pattern validation as YAML patterns. The
+log names the path as written. The file is read once at activation; the
+Cloudflare build embeds its entries in the artifact so the Worker never reads a
+file.
+
+## The pattern subset
+
+Patterns in `denyPatterns`, `allowPatterns` and every list file are validated
+at activation. A pattern outside the subset fails activation with a
+`ConfigError` naming the route, the key and the reason, so a project cannot
+turn the matcher into a denial-of-service vector by editing YAML. Allowed:
+
+- anchors `^` and `$`; literals; `.`
+- escapes: `\d \w \s \D \W \S \b \B \t \n \r \f \v \0`, `\xHH`, `\uHHHH`, and
+  a backslash before any punctuation (`\.`, `\/`, `\(`, `\-`, ...)
+- character classes `[...]` and `[^...]` with ranges and the escapes above
+- groups `(...)` and `(?:...)`, and alternation `|`
+- quantifiers `*`, `+`, `?`, `{n}` and `{n,m}` with `m <= 64`, on a single
+  atom (a literal, escape, class or `.`); `?` may also follow a group that
+  contains no quantifier, for optional words such as `(?:bot)?`
+- at most 256 bytes
+
+Rejected: backreferences (`\1`, `\k<name>`), lookahead and lookbehind, named
+groups, unicode property escapes, `\c` control escapes, nested character
+classes, `{n,}` and bounds above 64, lazy or stacked quantifiers (`+?`, `**`),
+quantifiers on anchors, and `*`, `+` or `{n,m}` on a group (so `(a+)+` and
+`(ab)*` fail). Each list is compiled into one alternated `RegExp` with the `i`
+flag, so a request costs one pass per list rather than one per pattern.
+
+## robots.txt
+
+Denying an agent is not the same as asking it to stay away. Well-behaved
+crawlers read `/robots.txt` (RFC 9309) before fetching anything, and the AI
+crawlers in `ai-crawlers` are the ones that upstream tracks as respecting or
+ignoring it. Generate one from the same bundled list with
+[`site.robots`](../SITE.md) so the file and the policy cannot drift apart:
+
+```yaml
+site:
+  robots:
+    disallow: [ai-crawlers]
+policies:
+  agents:
+    deny: [ai-crawlers]
+```
+
+This serves `/robots.txt` with one `User-agent:` line per list entry followed
+by `Disallow: /`, then `User-agent: *` / `Allow: /`. A hand-written
+`/robots.txt` `respond` route still works and takes precedence over the
+generated one. The `agents` policy then enforces the same decision for clients
+that ignore the file.
+
+## Targets
+
+| Target | Support |
+| --- | --- |
+| self-hosted (`urlcode serve`) | native |
+| Vercel, AWS | native |
+| Cloudflare | compiled: the build validates the policy, embeds the effective configuration (and any project list entries) in the artifact, and the Worker compiles it at startup without filesystem access |

package/docs/policies/cache.md

@@ -0,0 +1,139 @@
+# `policies.cache`
+
+Named HTTP caching strategies, enforced on the host. A route picks one
+strategy from a fixed catalogue; every row is a pattern with a name outside
+this project and a defined header output, so a browser, a CDN and the
+runtime's own origin memory cache all read the same thing. Explicit fields
+(`maxAge`, `staleWhileRevalidate`, `staleIfError`, `cdnMaxAge`, `originTtl`)
+override what a strategy implies.
+
+```yaml
+policies:
+  cache: { strategy: revalidate }      # project default
+routes:
+  /feed:
+    function: { source: feed.mjs }
+    policies:
+      cache: { strategy: swr, maxAge: 30, staleWhileRevalidate: 300, vary: [Accept-Language] }
+```
+
+## Strategies
+
+| `strategy` | Emitted headers | Origin memory cache | Typical use |
+|---|---|---|---|
+| `no-store` | `Cache-Control: no-store` | off | personalized, secret-bearing |
+| `revalidate` | `Cache-Control: no-cache`, `ETag` (a strong SHA-256 tag is computed for results without one); answers `304` to `If-None-Match`, and to `If-Modified-Since` when the result carries `Last-Modified` | off | HTML, anything that must be fresh but is cheap to validate |
+| `public` | `Cache-Control: public, max-age=N` (`maxAge` required) | on only when `originTtl` > 0 | stable API answers, feeds |
+| `immutable` | `Cache-Control: public, max-age=31536000, immutable` (RFC 8246; `maxAge` overrides the year) | off | content-hashed URLs only; refused elsewhere unless `force: true` |
+| `swr` | `Cache-Control: public, max-age=N, stale-while-revalidate=M` (RFC 5861; both required) | on: fresh for `originTtl` (default `maxAge`), then stale served once | hot functions, link previews |
+| `sie` | as `swr` plus `stale-if-error=K` (`staleIfError` required; `staleWhileRevalidate` optional) | on, as `swr` | keep answering during an upstream failure (headers only at the origin; see below) |
+| `micro` | `Cache-Control: no-store` to clients | on: `originTtl` default 1 s, at most 5 s unless `force: true` | the NGINX micro-cache: absorb a thundering herd without changing what a browser sees |
+| `cdn-only` | `Cache-Control: no-store` plus `CDN-Cache-Control: max-age=N` (RFC 9213; `cdnMaxAge` required) | off | let the CDN cache while browsers do not |
+| `private` | `Cache-Control: private, max-age=N` (`maxAge` required) | off | per-user data a browser may keep |
+
+`immutable` accepts a route whose pattern has a segment with eight or more
+hex characters (`/app.3f2a9c1d.js`) or a parameter named like a digest
+(`{hash}`, `{digest}`, `{sha}`, `{version}`, `{build}`, `{rev}`,
+`{fingerprint}`). Anything else fails configuration with the route named
+unless `force: true`.
+
+## Who owns `Cache-Control`
+
+Explicit beats strategy, in this order:
+
+1. A `response.headers.cache-control` declared in YAML on the route is kept
+   as written; the strategy does not touch it.
+2. An asset handler's `cacheControl` (`page`, `download`, `static`) is kept
+   when the cache policy is only inherited from the project or a profile.
+   When the route itself declares `policies.cache`, the strategy overrides it.
+3. A handler result that already says `no-store` or `private` is kept and is
+   never stored: a personalized answer under a `public` route stays private.
+4. Otherwise the strategy's header replaces whatever the handler emitted.
+
+`Vary` is merged with the declared `vary` names (no duplicates, `*` left
+alone), for every strategy, so the origin key and the wire header agree.
+Compression adds `Accept-Encoding` to `Vary` after this policy.
+
+## Origin memory cache
+
+On for `swr`, `sie`, `micro`, and `public` with `originTtl` set. It is an
+origin-side micro-cache, so a client's own `Cache-Control: no-cache` or
+`max-age=0` request directive does not bypass it (RFC 9111 §5.2.1 lets an
+origin decide that); conditional and range requests do, as below. Rules:
+
+- Only `GET` and `HEAD` are looked up; only `GET` results are stored, and a
+  `HEAD` hit serves the `GET` entry's headers with an empty body and the
+  entry's `Content-Length`. A route whose `methods` exclude `GET` has the
+  origin cache off.
+- Only statuses in `statuses` (default `200, 301, 302, 404, 410`) are stored.
+- 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 (an asset route
+  keeps its own `304`, `412` and `206` answers).
+- Never stored: results carrying `Set-Cookie`; routes declaring `secrets`;
+  results whose handler `Cache-Control` says `private` or `no-store`; bodies
+  larger than `maxBytes` (default 1 MiB).
+- Key: route pattern, request path, query string and the values of the
+  declared `vary` request headers. The method is not part of the key so
+  `HEAD` shares the `GET` entry.
+- Hits carry `Age` (RFC 9111). No non-standard headers are added.
+- Concurrent misses for one key coalesce: the first request reaches the
+  handler, up to 64 others wait for its result, and any beyond that proceed
+  to the handler themselves. If the fill fails, waiters fall through to the
+  handler rather than receiving the error.
+- Bounds: `maxEntries` per route configuration (default 10000) and 64 MiB of
+  bodies across the whole runtime; the least recently used entry is evicted
+  first. The store belongs to one runtime instance and is dropped on close and
+  reload, so a deploy never serves the previous code's output.
+- Stored entries hold the handler's headers as they were after YAML
+  `response.headers` and this policy ran, before security headers and
+  compression. Those run again on every hit, so a hit is compressed and
+  hardened the same way as a miss. Bodies are stored uncompressed.
+
+### `swr` at the origin: stale served once, next request refreshes
+
+A policy has no handle to the route's handler, so it cannot revalidate in the
+background. The origin-side approximation is: a request that finds an entry
+past `originTtl` but within `staleWhileRevalidate` is answered from the stale
+entry immediately, and the entry is flagged so the next request for that key
+goes to the handler and replaces it. If that refresh fails the flag is
+cleared and the stale entry may be served once more, as long as it is within
+the window. Beyond `max-age + stale-while-revalidate` nothing is served from
+memory. Clients and CDNs that honour RFC 5861 do their own background
+revalidation from the emitted header.
+
+### `sie` limitation
+
+`stale-if-error` is header-only at the origin. Policies observe errors but
+cannot replace a thrown error with a result (the runtime rethrows), so a
+handler failure is not answered from a stale entry by this runtime. Downstream
+caches honouring RFC 5861 still serve stale on a 5xx. Origin-side
+stale-if-error needs the plugin API or a runtime change that lets a policy's
+error hook return a result.
+
+## Targets
+
+| Target | Support | Note |
+|---|---|---|
+| node | native | headers and origin cache per runtime instance |
+| vercel | native | headers; the origin cache is per function instance, so hit rates depend on instance reuse |
+| aws | native | headers; the origin cache is per Lambda instance |
+| cloudflare | refused | the Worker build has no policy runtime; activation fails with the route named |
+
+## Diagnostics
+
+`describe()` (in `urlcode test`, the readiness plan and plugin activation)
+reports `strategy`, the emitted `cacheControl` string (or `explicit response
+header` / `asset handler` when something else owns it), `cdnCacheControl`,
+`originTtl`, `staleWhileRevalidate`, `staleIfError`, `vary` and whether the
+origin cache is `on`.
+
+Log events, through the runtime's `log`:
+
+```json
+{ "event": "cache", "route": "/feed", "outcome": "hit" }
+```
+
+`outcome` is `hit`, `stale`, `miss` or `store`. The route is the configured
+pattern, never the request path or key.