@jimhoyd/urlcode 0.3.0

package/docs/policies/compression.md

@@ -0,0 +1,168 @@
+# Compression policy
+
+`policies.compression` negotiates a content coding (RFC 9110 §12.5.3) on the
+host, outside the sandbox, for every result a route produces: `respond`
+bodies, function results, asset responses, cache hits and early denials.
+It runs last in the response phase, after the cache store and the security
+headers, so every header it reads is final. Asset snapshots are compressed
+once at load and served by reference (the NGINX `gzip_static` / Caddy
+`precompressed` model); other bodies are compressed on the request path
+within a fixed size bound.
+
+## YAML
+
+```yaml
+version: "1"
+policies:
+  compression:
+    encodings: [br, gzip]     # preference order; br | gzip | deflate | zstd
+    minBytes: 1024            # bodies below this stay identity (default 1024)
+    types:                    # media types eligible; `type/*` wildcards allowed
+      - text/*
+      - application/json
+      - application/javascript
+      - application/xml
+      - image/svg+xml
+      - application/manifest+json
+      - application/ld+json
+    level: 6                  # 1–11, optional; mapped per codec (table below)
+    allowWithSecrets: false   # compress even where BREACH applies (default false)
+
+routes:
+  /api/report:
+    function: { source: functions/report.mjs }
+    secrets: { KEY: { secret: api-key } }
+    policies:
+      compression: { allowWithSecrets: true }   # route keys merge over project keys
+```
+
+`encodings`, `minBytes`, `types`, `level` and `allowWithSecrets` are the
+only keys; the list above is the default `types`. `zstd` is accepted only
+when the running Node exposes `zlib.zstdCompressSync` (Node 22.15+ / 23.8+);
+otherwise startup fails with the route named, rather than silently serving
+identity. YAML `response.headers` cannot set `Content-Encoding` (it is a
+runtime-owned header); this policy is the only thing that sets it.
+
+### Levels
+
+Without `level`, each codec uses a latency-leaning level for request-path
+bodies and a size-leaning level for asset variants that are computed once.
+With `level`, one number in YAML is mapped onto each codec's own scale and
+applies to both paths.
+
+| Coding | Dynamic default | Stored default | `level` mapping |
+|---|---|---|---|
+| `br` | quality 4 | quality 9 | `level` (1–11) |
+| `gzip` | 6 | 9 | `min(level, 9)` |
+| `deflate` | 6 | 9 | `min(level, 9)` |
+| `zstd` | 3 | 12 | `min(level × 2, 22)` |
+
+## Negotiation
+
+The `Accept-Encoding` field is parsed per RFC 9110: each coding carries a
+`q` weight (default 1, `q=0` means not acceptable), `*` supplies the weight
+of any coding not named, and a coding neither named nor covered by `*` is
+not acceptable. The acceptable coding in `encodings` with the highest weight
+wins; equal weights are broken by the order of `encodings`, so
+`Accept-Encoding: gzip, br` selects `br` when the project lists `br` first.
+When nothing in `encodings` is acceptable, including `identity;q=0` or
+`*;q=0`, the response is sent as identity; a 406 helps nobody.
+
+Every response whose media type is in `types` gets `Vary: Accept-Encoding`,
+merged into an existing `Vary` without duplication and preserved on 304 and
+206, so a shared cache keys the URL by the field even when this particular
+response was not compressed.
+
+## When compression is skipped
+
+The response is sent as identity, still with `Vary`, when any of these hold:
+
+- the status is 206 (a byte range of the identity representation), 304, 204
+  or 205, or the result already carries `Content-Encoding`;
+- `Cache-Control` contains `no-transform`;
+- the media type is not in `types`, or the body is below `minBytes`;
+- the request method is `HEAD` and the body has no precomputed variant (see
+  below);
+- the body exceeds 1 MiB and has no precomputed variant: a synchronous
+  compression of that size would hold the event loop for every other
+  request, so such bodies stay identity on the request path;
+- compressing did not shrink the body;
+- **BREACH:** the route declares `secrets`, or the response carries
+  `Set-Cookie`, unless `allowWithSecrets: true`.
+
+### BREACH rationale
+
+Compressing a body that mixes a secret (a session token, a CSRF token, an
+API key echoed into a page) with attacker-influenced input leaks the secret
+through the compressed length: an attacker who can make the victim's
+browser issue requests with chosen input measures which guesses shrink the
+response. The signal is only there when secret and input share a
+compressed body, so the policy refuses to compress exactly where a secret is
+plausible: a route that has been granted secrets, and any response that
+sets a cookie. `allowWithSecrets: true` is for routes whose bodies do not
+echo the secret (a route that uses a key to call an upstream API and returns
+public data); set it per route, not for the project.
+
+## ETag and HEAD
+
+RFC 9110 requires a strong validator to differ between representations, so
+an encoded body cannot carry the identity ETag unchanged. The policy handles
+the two paths differently:
+
+- **Precompressed assets** keep a strong ETag with the coding appended
+  inside the quotes: `"<sha256>-br"`, `"<sha256>-gz"`, `"<sha256>-df"`,
+  `"<sha256>-zs"`. The asset handler validates `If-None-Match` against the
+  identity tag; the policy validates the suffixed tag for the coding it
+  selected and answers 304 (with the suffixed ETag and `Vary`) when it
+  matches. A suffixed tag presented with a different `Accept-Encoding`
+  selects a different representation and gets a fresh 200. `If-Range` only
+  ever matches the identity tag, so a range request against a variant tag
+  gets the full identity body, as the RFC prescribes for a non-matching
+  validator.
+- **Dynamically compressed bodies** (functions, `respond`, middleware
+  results, cache hits) keep the handler's ETag but weakened: `W/"v1"`. Weak
+  comparison treats `W/"v1"` and `"v1"` as equal, so a client revalidating
+  with the weak tag gets the same 304 it would for identity, and a
+  handler's own `If-None-Match` logic keeps working. Nothing is appended,
+  because a dynamic body has no stable bytes for a strong tag to name.
+
+`HEAD` reports what `GET` would send when the answer is free: a
+precompressed asset answers `HEAD` with `Content-Encoding` and the variant's
+`Content-Length`. A dynamic body is not compressed for `HEAD` (it would pay
+the whole compression for one number) and reports the identity length,
+the same `Content-Length` its `GET` would carry uncompressed.
+
+## Precompression and memory bounds
+
+`compileAssets` runs before policies compile, so the policy, not the asset
+loader, computes variants: in `compile()` it walks the route's asset
+snapshot (one file for `page`/`download`, the whole tree for `static`) and
+compresses every file whose type is in `types` and whose size is at least
+`minBytes`, once per configured coding. A project without the policy pays
+nothing. Variants are stored on the immutable snapshot and replaced with it
+on reload. Bounds:
+
+- a variant at least as large as the original is dropped;
+- the aggregate of all variants across the runtime is capped at 64 MiB
+  (the same figure as the asset snapshot itself); beyond it, remaining
+  files are served identity or compressed on the request path when they
+  fit the 1 MiB dynamic bound;
+- a request for a stored variant costs one buffer reference, no copy.
+
+`urlcode audit` and `testPlan()` report `precompressed`, the number of
+variants a route holds, alongside `encodings`, `minBytes`, the count of
+`types` and `level`.
+
+## Per-target behavior
+
+| Target | Support | Notes |
+|---|---|---|
+| node | native | Negotiation, precompressed assets and dynamic compression as described. |
+| vercel | delegated | The platform compresses responses at its edge; the policy is accepted and dropped so one YAML serves every host. |
+| aws | delegated | CloudFront/API Gateway compression is configured on the platform; the policy is accepted and dropped. |
+| cloudflare | delegated | Workers responses are compressed by the Cloudflare edge; the build accepts and drops the policy. |
+
+A refusal is deliberate: the YAML stays portable and the difference is
+visible at build time rather than as a silent double compression. Remove
+the key, or set `compression: false` on the routes that use a profile which
+declares it, when deploying to those targets.

package/docs/policies/security.md

@@ -0,0 +1,160 @@
+# Security headers policy
+
+`policies.security` adds response security headers on the host, outside the
+sandbox, to every result a route produces: redirects, `respond` bodies,
+function results, asset responses, cache hits and early denials from the
+`agents` and `throttle` policies. Values are the OWASP Secure Headers
+Project best-practice recommendations (OSHP 2024 best practices,
+<https://owasp.org/www-project-secure-headers/>). The tables below are
+generated from the frozen `profiles` constant in `src/policies/security.ts`.
+
+## YAML
+
+```yaml
+version: "1"
+policies:
+  security:
+    headers: oshp            # oshp (default) | oshp-no-csp | off
+    set:                     # add or overwrite one header, verbatim
+      Content-Security-Policy-Report-Only: "default-src 'self'; report-to csp"
+      Clear-Site-Data: '"cache"'
+    unset:                   # drop a header the profile would emit
+      - Cross-Origin-Embedder-Policy
+routes:
+  /embed:
+    respond: { text: ok }
+    policies:
+      security: { headers: oshp-no-csp }   # route keys merge over project keys
+```
+
+`headers`, `set` and `unset` are the only keys. A route may also write
+`security: false` to disable the policy for that route.
+
+## Profile `oshp`
+
+| Header | Value |
+|---|---|
+| `strict-transport-security` | `max-age=31536000; includeSubDomains` |
+| `x-frame-options` | `deny` |
+| `x-permitted-cross-domain-policies` | `none` |
+| `referrer-policy` | `strict-origin-when-cross-origin` |
+| `content-security-policy` | `default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content` |
+| `cross-origin-embedder-policy` | `require-corp` |
+| `cross-origin-opener-policy` | `same-origin` |
+| `cross-origin-resource-policy` | `same-origin` |
+| `permissions-policy` | `accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()` |
+
+## Profile `oshp-no-csp`
+
+Identical to `oshp` without `Content-Security-Policy`.
+
+| Header | Value |
+|---|---|
+| `strict-transport-security` | `max-age=31536000; includeSubDomains` |
+| `x-frame-options` | `deny` |
+| `x-permitted-cross-domain-policies` | `none` |
+| `referrer-policy` | `strict-origin-when-cross-origin` |
+| `cross-origin-embedder-policy` | `require-corp` |
+| `cross-origin-opener-policy` | `same-origin` |
+| `cross-origin-resource-policy` | `same-origin` |
+| `permissions-policy` | `accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()` |
+
+## Profile `off`
+
+Emits nothing. `set` still applies, so `off` plus `set` is a hand-written
+header list.
+
+Not in any profile:
+
+- `X-Content-Type-Options: nosniff`: the runtime sets it on every response,
+  including errors, so the profile does not duplicate it.
+- `Cache-Control`: owned by the `cache` policy and the asset handlers;
+  `set` refuses it.
+- `Clear-Site-Data`: destructive by design, so only on explicit `set`.
+
+## Precedence
+
+1. Headers already on the result keep their value. YAML `response.headers`
+   are applied by the runtime before this policy runs, and a function or asset
+   handler sets its headers earlier still, so any of them beats the profile
+   header by header (`x-frame-options: sameorigin` on a route wins over the
+   profile's `deny`).
+2. `set` overwrites everything: the profile and an existing header of the
+   same name. Writing a header under `set` is explicit operator intent.
+3. `unset` removes a header from the profile by case-insensitive name. Naming
+   a header the selected profile does not emit is a configuration error that
+   names the route, so a typo cannot silently leave a header in place. The
+   check runs against the profile in effect on each route: a route that
+   switches to a profile without that header inherits the project `unset`
+   and must write `unset: []` to clear it.
+
+`set` names and values are validated at activation with the same rules the
+wire enforces (RFC 7230 token names, no control characters) and may not name a
+header the runtime or a handler owns (`content-length`, `content-type`,
+`location`, `etag`, `content-encoding`, `cache-control`, `set-cookie`,
+`x-request-id`, `x-content-type-options`, hop-by-hop headers), nor one
+another policy emits (`vary`, `ratelimit`, `ratelimit-policy`, `retry-after`,
+`age`). The static
+headers of one route are capped at 8 KiB so the response keeps room under the
+runtime's 16 KiB / 256-header limit; the error names the route.
+
+## Error responses
+
+Errors the runtime throws (404, 410, 413 and the rest) do not run the
+response phase, but they do get this policy: the matched route's effective
+profile when the error came after routing, otherwise the project-level one,
+on every host and in the Cloudflare Worker. The fixed error headers
+(`Content-Type`, `Cache-Control: no-store`, `Content-Length`, `X-Request-Id`,
+`X-Content-Type-Options`) are never replaced.
+
+## HSTS and the origin
+
+`Strict-Transport-Security` is emitted only when the request origin is
+`https:`. On the self-hosted server that is the `--origin` setting (or the
+`origin` option of `startServer`); the Worker uses the request URL. A
+browser ignores HSTS on a plain-text response, and a forwarded header such as
+`X-Forwarded-Proto` is client-controlled, so the runtime never infers the
+scheme from it. Behind a TLS-terminating proxy or tunnel, state
+`--origin https://your.host` and the header appears. Once emitted, HSTS
+commits the host to HTTPS for a year including subdomains: set the origin only
+when that is true.
+
+## CSP and pages with inline scripts
+
+The `oshp` CSP (`default-src 'self'`, no `unsafe-inline`) blocks inline
+`<script>` and `<style>` blocks and any third-party script. For a page that
+needs them, either use `oshp-no-csp` on that route, or keep the profile and
+trial a policy in report-only mode first:
+
+```yaml
+policies:
+  security:
+    headers: oshp-no-csp
+    set:
+      Content-Security-Policy-Report-Only: "default-src 'self'; script-src 'self' https://cdn.example; report-to csp"
+```
+
+Once the reports are clean, move the value to `Content-Security-Policy` under
+`set`, which overrides the profile value.
+
+## Targets
+
+| Target | Support | Notes |
+|---|---|---|
+| node | native | `--origin` decides HSTS |
+| vercel | native | origin from the adapter's public URL |
+| aws | native | origin from the adapter's public URL |
+| cloudflare | compiled | Validated at build; the Worker compiles the same module synchronously and emits identical headers. HSTS follows the request URL scheme. |
+
+## Interaction with other policies
+
+- `cache`: security headers are added after the cache store and on cache
+  hits, so a stored body never carries a stale profile; `Cache-Control` is
+  never touched.
+- `compression`: runs after this policy, so `Vary`/`Content-Encoding` are
+  unaffected and the size check above already includes the profile.
+- `agents` and `throttle`: their denials pass through this policy, so a 403
+  or 429 carries the same headers as a normal response.
+
+`urlcode audit` and `testPlan().policies` report, per route, the profile
+name, the header names it emits, and the `set` and `unset` names.

package/docs/policies/throttle.md

@@ -0,0 +1,103 @@
+# Throttle policy
+
+`policies.throttle` gives each client, route or client-route pair a request
+budget: `quota` requests per `window` seconds. The runtime counts requests in
+a sliding window (two fixed windows blended by elapsed time, the usual middle
+ground between a fixed window that bursts at its edges and a token bucket
+that is hard to explain in a header) and refuses the request that would
+exceed the budget before it reads a body or reaches the sandbox. Refused
+requests are not counted, so a retrying client cannot keep its own window
+from clearing.
+
+```yaml
+version: "1"
+policies:
+  throttle:
+    quota: 120          # requests
+    window: 60          # seconds
+    partition: client   # client | route | client-route  (default client)
+    status: 429         # 4xx or 5xx answered on refusal (default 429)
+    mode: enforce       # enforce | report               (default enforce)
+    maxKeys: 100000     # bounded counter table, LRU eviction
+
+routes:
+  /api/lookup/{id}:
+    function: { source: functions/lookup.mjs }
+    policies:
+      throttle: { quota: 10, window: 60 }   # tighter budget with its own counter
+```
+
+A route override that restates `quota` and `window` gets its own counters; a
+route that inherits the project budget shares the client's counter with every
+other route on the same budget. `throttle: false` on a route turns it off there.
+
+## Standards
+
+- [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585) status 429 by default;
+  any 4xx or 5xx `status` is accepted and the body is a short plain-text line.
+- [RFC 9110 `Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after),
+  integer seconds, on every refusal.
+- [IETF httpapi RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)
+  on every response, allowed or refused, in structured-field syntax:
+  `RateLimit-Policy: "default";q=<quota>;w=<window>` and
+  `RateLimit: "default";r=<remaining>;t=<seconds until reset>`.
+
+A refusal also carries `content-type: text/plain; charset=utf-8` and
+`cache-control: no-store` so no intermediary keeps it.
+
+## Targets
+
+| Target | `partition: route` | `client` / `client-route` |
+|---|---|---|
+| node (`urlcode serve`) | native | native |
+| vercel | native, per instance | refused at activation |
+| aws | native, per instance | refused at activation |
+| cloudflare | refused | refused |
+
+Counters live in the process. On serverless targets a route counter is at
+least an honest per-instance ceiling, while a client counter would silently
+become `quota × instances`, so those partitions are refused with the route
+named. The Cloudflare build refuses the policy; map the same `quota` and
+`window` to a provider rate rule instead.
+
+## Client identity
+
+`client` is the socket peer address. Behind a load balancer every request
+would share one address, so name the proxies allowed to speak for a client:
+`urlcode serve --trusted-proxies 10.0.0.0/8,::1`. Only then is
+`X-Forwarded-For` consulted, walking from the right past trusted hops. When no
+client can be resolved (a caller that passed none, an adapter without a peer)
+requests share a single bucket rather than escaping the budget; the policy
+inventory (`urlcode audit`, `testPlan().policies`) reports this as
+`unresolvedClient: "shared key"`.
+
+## Report before enforce
+
+Run a release with `mode: report`: headers are emitted and every request logs
+`{ event: "throttle", route, outcome: "allowed" | "exceeded", remaining }`
+(never the client address), but nothing is refused. Read the `exceeded` lines
+against real traffic, set `quota` from what you saw, then switch to `enforce`.
+In enforce mode only `exceeded` is logged.
+
+## What it does not do
+
+- No shared state across processes or instances. Two `urlcode serve`
+  processes behind one balancer each enforce the full budget. A host plugin
+  (`onRequest` returning a refusal, backed by whatever store you run) is the
+  place for a cluster-wide budget; see the plugin contract in
+  `docs/SPIKE-EXTENSIONS.md`.
+- No per-user or per-token keys. The partition is address or route; a token
+  bucket per API key is again a plugin.
+- Counters do not survive a reload: a new snapshot starts empty.
+- `maxKeys` bounds memory with least-recently-used eviction; an evicted key
+  starts fresh, so a table sized below the number of concurrent clients
+  under-counts rather than blocks.
+
+## Interaction with other policies
+
+Request order is agents, throttle, cache. A denied agent never touches a
+counter; a throttled request never reaches the cache lookup or the handler.
+Security headers and compression still apply to a refusal. A cache hit skips
+only the cache's own response hook, so a cached response still carries the
+client's `RateLimit` headers; the request was counted. A 405 is counted too
+and carries them.

package/examples/assets/.env.example

@@ -0,0 +1 @@
+# Add names and empty placeholders only. Put local values in ignored .env.local.

package/examples/assets/.gitattributes

@@ -0,0 +1,2 @@
+# Keep text assets and test fixtures byte-consistent across platforms.
+* text=auto eol=lf

package/examples/assets/Makefile

@@ -0,0 +1,30 @@
+.DEFAULT_GOAL := help
+
+# Install the runtime separately, or override: URLCODE='node /path/to/urlcode/src/cli.js'
+URLCODE ?= urlcode
+HOST ?= 127.0.0.1
+PORT ?= 3000
+
+.PHONY: help dev serve validate test doctor
+help:
+	@echo "make dev       Run this app with reload and .env.local"
+	@echo "make validate  Validate this app and its local bindings"
+	@echo "make test      Run this app's HTTP assertions"
+	@echo "make serve     Run a fixed snapshot, without local dotenv"
+	@echo "make doctor    Show runtime/platform details"
+	@echo "Options: PORT=3001 HOST=127.0.0.1 URLCODE=urlcode"
+
+dev:
+	$(URLCODE) dev --project . --host "$(HOST)" --port "$(PORT)"
+serve:
+	$(URLCODE) serve --project . --host "$(HOST)" --port "$(PORT)"
+validate:
+	$(URLCODE) validate --local --project .
+test:
+	$(URLCODE) test --project .
+doctor:
+	$(URLCODE) doctor
+
+.PHONY: routes audit benchmark
+routes audit benchmark:
+	$(URLCODE) $@ --project . $(ARGS)

package/examples/assets/README.md

@@ -0,0 +1,18 @@
+# Asset demonstration
+
+This is a runnable example, not a separate starter choice. From the runtime checkout:
+
+```sh
+make dev PROJECT=examples/assets
+# In another terminal:
+make test-project PROJECT=examples/assets
+```
+
+Try `/hello/Ada` for a function, `/go` for a redirect, `/about` for HTML,
+`/assets/example.txt` for a static file, and `/download` for an attachment.
+Assets live in `public/`; never put secrets there. See the
+[asset guide](../../docs/ASSETS.md) for MIME, caching and resource limits.
+
+To start your own small app, use `urlcode init ../my-links`. It creates one
+function route and one regular redirect. Add asset routes when you need them.
+URLCode is licensed under the Apache License 2.0.

package/examples/assets/functions/hello.mjs

@@ -0,0 +1,3 @@
+export default function hello(_request, { args, env }) {
+  return Response.json({ message: `${env.GREETING}, ${args.name}!` });
+}

package/examples/assets/gitignore.template

@@ -0,0 +1,7 @@
+.env
+.env.*
+!.env.example
+node_modules/
+.urlcode/
+.urlcode-edit-*/
+urlcode.yaml.lock

package/examples/assets/public/about.html

@@ -0,0 +1,2 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>URLCode</title><h1>URLs that run code</h1><p>Try <a href="/hello/Ada">your function</a> or <a href="/download">download the guide</a>.</html>

package/examples/assets/public/assets/example.txt

@@ -0,0 +1 @@
+A native static asset.

package/examples/assets/public/guide.txt

@@ -0,0 +1 @@
+URLCode: URLs that run code.

package/examples/assets/tests/requests.json

@@ -0,0 +1,44 @@
+[
+  {
+    "path": "/go",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/"
+    }
+  },
+  {
+    "path": "/hello/Ada",
+    "status": 200,
+    "expectBody": "{\"message\":\"Hello, Ada!\"}"
+  },
+  {
+    "path": "/hello/Ada",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/missing",
+    "status": 404
+  },
+  {
+    "path": "/about",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8"
+    }
+  },
+  {
+    "path": "/download",
+    "status": 200,
+    "expectHeaders": {
+      "content-disposition": "attachment; filename=urlcode-guide.txt"
+    },
+    "expectBody": "URLCode: URLs that run code.\n"
+  },
+  {
+    "path": "/assets/example.txt",
+    "status": 200,
+    "expectBody": "A native static asset.\n"
+  }
+]

package/examples/assets/urlcode.yaml

@@ -0,0 +1,27 @@
+version: "1"
+routes:
+  /hello/{name}:
+    parameters:
+      - name: name
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 80}
+    function:
+      source: functions/hello.mjs
+      args:
+        name: {from: path, name: name}
+    env:
+      GREETING: {value: Hello}
+  /go:
+    redirect:
+      url: https://example.com
+  /about:
+    page:
+      file: public/about.html
+  /assets/*:
+    static:
+      directory: public/assets
+  /download:
+    download:
+      file: public/guide.txt
+      filename: urlcode-guide.txt

package/examples/aws/README.md

@@ -0,0 +1,13 @@
+# URLCode on AWS Lambda
+
+A native-handler project served by a Lambda Function URL. See
+[the adapter guide](../../docs/AWS.md) for what is and is not supported.
+
+```sh
+urlcode test --project .     # the same assertions run locally
+sam deploy --guided
+```
+
+`handler.mjs` serves the project with `createLambdaHandler`. The deployment
+package must contain the project files the routes read: the entry YAML, any
+includes, and every page, download and static directory.

package/examples/aws/handler.mjs

@@ -0,0 +1,5 @@
+// Lambda entry point. The runtime activates once per execution environment and
+// is reused across warm invocations.
+import { createLambdaHandler } from '@jimhoyd/urlcode/aws';
+
+export const handler = createLambdaHandler({ project: process.env.LAMBDA_TASK_ROOT ?? process.cwd() });

package/examples/aws/public/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>URLCode on Lambda</title>
+<body><h1>URLCode on Lambda</h1><p>Native handlers served by the runtime adapter.</p></body>

package/examples/aws/public/notes.txt

@@ -0,0 +1 @@
+Served by the static handler through the Lambda adapter.

package/examples/aws/template.yaml

@@ -0,0 +1,33 @@
+# Minimal SAM template: a Function URL in front of the adapter. An API Gateway
+# HTTP API works the same way; a REST API does not, because payload format 1.0
+# cannot preserve the original request encoding.
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Resources:
+  UrlcodeFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.handler
+      Runtime: nodejs22.x
+      MemorySize: 512
+      Timeout: 10
+      FunctionUrlConfig:
+        AuthType: NONE
+      Environment:
+        Variables:
+          # The public origin, so generated URLs name the domain a visitor used.
+          URLCODE_PUBLIC_HOST: !Ref PublicHost
+          # Paste the output of `urlcode permissions` only if routes declare
+          # env or secret bindings.
+          # URLCODE_POLICY: '{"version":1,...}'
+
+Parameters:
+  PublicHost:
+    Type: String
+    Default: ''
+    Description: Public hostname without scheme, e.g. links.example.
+
+Outputs:
+  FunctionUrl:
+    Value: !GetAtt UrlcodeFunctionUrl.FunctionUrl

package/examples/aws/tests/requests.json

@@ -0,0 +1,9 @@
+[
+  {"path": "/go", "status": 302, "expectHeaders": {"location": "https://example.com/target"}},
+  {"path": "/u/42", "status": 302, "expectHeaders": {"location": "https://example.com/users/42"}},
+  {"path": "/u/42", "method": "HEAD", "status": 302, "expectHeaders": {"location": "https://example.com/users/42"}, "expectBody": ""},
+  {"path": "/health", "status": 200, "expectBody": "{\"ok\":true}"},
+  {"path": "/", "status": 200, "expectHeaders": {"content-type": "text/html; charset=utf-8"}},
+  {"path": "/files/notes.txt", "status": 200, "expectHeaders": {"content-type": "text/plain; charset=utf-8"}},
+  {"path": "/nothing-here", "status": 404}
+]