@jimhoyd/urlcode 0.3.0

package/dist/policies/cache.js

@@ -0,0 +1,297 @@
+import { createHash } from 'node:crypto';
+import { assert, ConfigError } from '../errors.js';
+                                                                     
+                                                                                                                
+
+// Named HTTP caching strategies (RFC 9111) chosen from a fixed catalogue so a
+// browser, a CDN and this runtime's own origin cache read the same headers
+// the same way. Each strategy names a pattern known outside this project:
+// RFC 5861 stale-while-revalidate / stale-if-error, RFC 8246 immutable,
+// RFC 9213 CDN-Cache-Control, the NGINX micro-cache. Explicit fields override
+// what the strategy implies; the strategy never overrides explicit YAML
+// response headers. The origin cache is one per runtime, bounded by entries
+// and bytes, and dropped with the runtime, so a reload starts empty.
+export const name = 'cache';
+export const phases                    = ['request','response'];
+
+                                                                                                                             
+                              
+                                                                                                                                    
+                                                                                                
+ 
+/** A stored 200 representation: the result minus its body and headers, which are kept separately. */
+                                                                                                                                                             
+/** The in-flight fill for one key; waiters share its promise up to MAX_WAITERS. */
+                                                                                                                                                             
+/** The one origin cache per runtime, shared by every route with an origin-caching strategy. */
+                                                                                                                                                  
+                             
+                                                                                                                                                             
+                                                                                                           
+                                                                             
+                                                                                                                 
+ 
+                                   
+                                                                                                      
+                                                                                 
+ 
+
+const strategies                    = ['no-store','revalidate','public','immutable','swr','sie','micro','cdn-only','private'];
+const DEFAULT_STATUSES = [200,301,302,404,410];
+const DEFAULT_MAX_BYTES = 1048576;      // per entry
+const DEFAULT_MAX_ENTRIES = 10000;
+const STORE_BYTES = 64 * 1024 * 1024;   // per runtime, all routes together
+const MAX_WAITERS = 64;                 // coalesced requests per in-flight key
+const YEAR = 31536000;
+const MICRO_MAX = 5;
+const hashedSegment = /[0-9a-f]{8,}/i;
+const hashedParameter = /^\{[^}]*(?:hash|digest|sha|fingerprint|rev|version|build)[^}]*\}$/i;
+
+// Per-instance memory: honest on node, per-instance on serverless (documented),
+// impossible in a Worker that has no policy runtime at all.
+export function targets()                                    { return { node:'native', vercel:'native', aws:'native', cloudflare:'refused' }; }
+
+function lower(list           )           { return list.map(v => String(v).trim().toLowerCase()).filter(Boolean); }
+function header(headers              , key        )                     {
+  const found = headers.find(([k]) => String(k).toLowerCase() === key);
+  return found ? found[1] : undefined;
+}
+function without(headers              , ...keys          )               { return headers.filter(([k]) => !keys.includes(String(k).toLowerCase())); }
+function directive(value                    , token        )          { return new RegExp(`(?:^|,)\\s*${token}\\s*(?:=|,|$)`, 'i').test(value || ''); }
+
+export async function compile(config             , { route, shared }               )                      {
+  assert(config && typeof config === 'object', `policies.${name} on ${route.pattern} must be an object`);
+  const { strategy, maxAge, staleWhileRevalidate, staleIfError, cdnMaxAge, force = false } = config;
+  const where = `on ${route.pattern}`;
+  assert(strategies.includes(strategy), `policies.${name}.strategy ${where} must be one of ${strategies.join(', ')}`);
+  const seconds = (value                    , key        , required         )                     => {
+    if (value === undefined) { if (required) throw new ConfigError(`policies.${name}.${key} ${where} is required by strategy ${strategy}`); return undefined; }
+    assert(Number.isInteger(value) && value >= 0, `policies.${name}.${key} ${where} must be a non-negative integer of seconds`);
+    return value;
+  };
+  const vary = lower(config.vary ?? []);
+  assert(vary.length <= 8 && new Set(vary).size === vary.length && vary.every(v => /^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(v)), `policies.${name}.vary ${where} must list at most 8 distinct header names`);
+  const statuses = config.statuses ?? DEFAULT_STATUSES;
+  assert(Array.isArray(statuses) && statuses.every(s => Number.isInteger(s) && s >= 200 && s <= 599), `policies.${name}.statuses ${where} must list HTTP statuses`);
+  const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES, maxEntries = config.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  assert(Number.isInteger(maxBytes) && maxBytes >= 0, `policies.${name}.maxBytes ${where} must be a non-negative integer`);
+  assert(Number.isInteger(maxEntries) && maxEntries >= 1, `policies.${name}.maxEntries ${where} must be a positive integer`);
+
+  // What the strategy implies, then what the fields override. `age` is
+  // required (so defined) for public, private, swr and sie, `swr` for swr:
+  // seconds() has thrown otherwise, which is what the `!` below rest on.
+  let cacheControl = '', cdnCacheControl                    , fresh = 0, stale = 0, origin = false;
+  const age = seconds(maxAge, 'maxAge', ['public','private','swr','sie'].includes(strategy));
+  const swr = seconds(staleWhileRevalidate, 'staleWhileRevalidate', strategy === 'swr');
+  const sie = seconds(staleIfError, 'staleIfError', strategy === 'sie');
+  const cdn = seconds(cdnMaxAge, 'cdnMaxAge', strategy === 'cdn-only');
+  let originTtl = seconds(config.originTtl, 'originTtl', false);
+  switch (strategy) {
+    case 'no-store': cacheControl = 'no-store'; break;
+    case 'revalidate': cacheControl = 'no-cache'; break;
+    case 'public': cacheControl = `public, max-age=${age}`; origin = (originTtl ?? 0) > 0; fresh = originTtl ?? 0; break;
+    case 'private': cacheControl = `private, max-age=${age}`; break;
+    case 'immutable': {
+      const hashed = route.pattern.split('/').some(part => hashedSegment.test(part) || hashedParameter.test(part));
+      if (!hashed && !force) throw new ConfigError(`${route.pattern} declares policies.${name} strategy immutable on a path without a content hash; add a hashed segment or force: true`);
+      cacheControl = `public, max-age=${age ?? YEAR}, immutable`; break;
+    }
+    case 'swr': cacheControl = `public, max-age=${age}, stale-while-revalidate=${swr}`; origin = true; fresh = originTtl ?? age ; stale = swr ; break;
+    case 'sie':
+      cacheControl = `public, max-age=${age}${swr !== undefined ? `, stale-while-revalidate=${swr}` : ''}, stale-if-error=${sie}`;
+      origin = true; fresh = originTtl ?? age ; stale = swr ?? 0; break;
+    case 'micro':
+      originTtl ??= 1;
+      if (originTtl > MICRO_MAX && !force) throw new ConfigError(`policies.${name}.originTtl ${where} exceeds ${MICRO_MAX} seconds for strategy micro; use public or set force: true`);
+      cacheControl = 'no-store'; origin = originTtl > 0; fresh = originTtl; break;
+    case 'cdn-only': cacheControl = 'no-store'; cdnCacheControl = `max-age=${cdn}`; break;
+  }
+  // A route bound to secrets never enters the origin cache, whatever it says.
+  const secrets = Object.keys(route.secrets || {}).length > 0;
+  if (secrets || !(route.methods || ['GET','HEAD']).includes('GET')) origin = false;
+  const store = shared.cache ||= { entries: new Map(), pending: new Map(), bytes: 0, maxBytes: STORE_BYTES, now: shared.now || Date.now };
+  return {
+    strategy, cacheControl, cdnCacheControl, vary, statuses: new Set(statuses), maxBytes, maxEntries,
+    origin, freshMs: fresh * 1000, staleMs: stale * 1000, originTtl: origin ? fresh : null, staleIfError: sie ?? null,
+    route: route.pattern, secrets, log: shared.log, store,
+    // Who owns Cache-Control on this route: explicit YAML headers always,
+    // an asset handler's cacheControl unless the route itself names a policy.
+    yamlCacheControl: (route.responseHeaders || []).some(([k]) => k === 'cache-control'),
+    inheritedAsset: Boolean(route.asset) && !route.policies?.cache,
+    inflight: new WeakMap(),
+  };
+}
+
+// Key: route pattern, path, query and the values of the declared Vary
+// headers. HEAD shares the GET entry (only GET results are stored), so the
+// method is not part of the key.
+function keyFor(state            , req               )         {
+  const varied = state.vary.map(h => req.headers.get(h) ?? '').join('\u0001');
+  return `${state.route}\u0000${req.path}\u0000${req.query?.toString?.() ?? ''}\u0000${varied}`;
+}
+function log(state            , outcome        )       {
+  try { state.log?.({ event: 'cache', route: state.route, outcome }); } catch { /* logging never changes the outcome */ }
+}
+function touch(store            , key        , entry            )       {
+  store.entries.delete(key); store.entries.set(key, entry);
+}
+function served(entry            , ageMs        )                {
+  const headers               = [...without(entry.headers, 'age'), ['age', String(Math.max(0, Math.floor(ageMs / 1000)))]];
+  // The body stays attached on HEAD, as the asset handler does: the response
+  // writer drops it, and a later policy can still pick the encoded variant.
+  return { ...entry.result, headers, contentLength: entry.body.length, body: entry.body };
+}
+
+const conditional = ['if-none-match','if-modified-since','if-match','if-unmodified-since','range'];
+export async function onRequest(state            , req               )                                     {
+  if (!state.origin || req.secrets || (req.method !== 'GET' && req.method !== 'HEAD')) return undefined;
+  // A stored entry is a full 200 representation; the handler owns validators
+  // and ranges, so a conditional or partial request always reaches it.
+  if (conditional.some(name => req.headers.has(name))) return undefined;
+  const { store } = state, now = store.now(), key = keyFor(state, req);
+  const entry = store.entries.get(key);
+  if (entry) {
+    const age = now - entry.storedAt;
+    if (age < state.freshMs) { touch(store, key, entry); log(state, 'hit'); return served(entry, age); }
+    // Stale within the window: answer now and let the next request refresh.
+    // A policy has no handle to the handler, so this is the origin-side
+    // approximation of background revalidation; the flag makes it one-shot.
+    if (age < state.freshMs + state.staleMs && !entry.revalidating) { entry.revalidating = true; log(state, 'stale'); return served(entry, age); }
+  }
+  // Miss: the first request for a key reaches the handler; concurrent ones
+  // wait for its result up to a bounded count, beyond which they proceed.
+  const pending = store.pending.get(key);
+  if (pending && pending.waiters < MAX_WAITERS) {
+    pending.waiters++;
+    let stored                   ;
+    try { stored = await pending.promise; } catch { stored = null; }
+    if (stored) { log(state, 'hit'); return served(stored, store.now() - stored.storedAt); }
+    return undefined;
+  }
+  if (!pending && req.method === 'GET') {
+    let resolve                    , reject                   ;
+    const promise = new Promise                   ((res, rej) => { resolve = res; reject = rej; });
+    const flight         = { waiters: 0, promise, resolve, reject };
+    flight.promise.catch(() => {});
+    store.pending.set(key, flight);
+    state.inflight.set(req, { key, flight });
+  }
+  log(state, 'miss');
+  return undefined;
+}
+
+function mergeVary(headers              , names          )               {
+  if (!names.length) return headers;
+  const index = headers.findIndex(([k]) => String(k).toLowerCase() === 'vary');
+  const present = index < 0 ? [] : headers[index] [1].split(',').map(v => v.trim()).filter(Boolean);
+  if (present.includes('*')) return headers;
+  const seen = new Set(present.map(v => v.toLowerCase()));
+  const merged = [...present, ...names.filter(n => !seen.has(n))];
+  if (index < 0) return [...headers, ['vary', merged.join(', ')]];
+  const out = [...headers]; out[index] = [headers[index] [0], merged.join(', ')]; return out;
+}
+function noneMatch(value        , etag        )          {
+  const strip = (tag        )         => tag.trim().replace(/^W\//, '');
+  return value.split(',').some(tag => tag.trim() === '*' || strip(tag) === strip(etag));
+}
+function bodyOf(result               )         { return result.body ? (Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body)) : Buffer.alloc(0); }
+
+// Conditional requests for results the handler did not validate itself:
+// assets answer 304 before this phase, so only 200 results are examined.
+function revalidate(state            , req               , result               )                {
+  if (result.status !== 200 || (req.method !== 'GET' && req.method !== 'HEAD')) return result;
+  let headers = result.headers, etag = header(headers, 'etag');
+  if (!etag) {
+    // A strong validator over the representation. A HEAD answer without a
+    // body (a function's) has nothing to hash and gets no validator, rather
+    // than one that would disagree with GET.
+    const body = bodyOf(result);
+    if (req.method === 'HEAD' && !body.length) return result;
+    etag = '"' + createHash('sha256').update(body).digest('hex') + '"'; headers = [...headers, ['etag', etag]];
+  }
+  const none = req.headers.get('if-none-match'), modified = header(headers, 'last-modified');
+  const since = req.headers.get('if-modified-since');
+  const matched = none ? noneMatch(none, etag) : Boolean(modified && since && Date.parse(modified) <= Date.parse(since));
+  if (!matched) return { ...result, headers };
+  // Content-Type stays so a later policy can still see what varied (RFC 9110 §15.4.5).
+  const kept = new Set(['etag','cache-control','cdn-cache-control','vary','last-modified','content-location','expires','date','content-type']);
+  const { contentLength: _length, ...rest } = result;
+  return { ...rest, status: 304, headers: headers.filter(([k]) => kept.has(String(k).toLowerCase())), body: Buffer.alloc(0) };
+}
+
+function evict(store            , maxEntries        )       {
+  while (store.entries.size > maxEntries || store.bytes > store.maxBytes) {
+    const [key, oldest] = store.entries.entries().next().value ;
+    store.entries.delete(key); store.bytes -= oldest.body.length;
+  }
+}
+
+export function onResponse(state            , req               , result               )                {
+  const flight = state.inflight.get(req);
+  if (flight) state.inflight.delete(req);
+  const handlerControl = header(result.headers, 'cache-control');
+  // Explicit beats strategy: YAML headers, an inherited policy over an asset
+  // handler's own cacheControl, and a handler that asked for private or
+  // no-store (a personalized answer under a public route stays private).
+  const restrictive = directive(handlerControl, 'no-store') || directive(handlerControl, 'private');
+  const owned = !state.yamlCacheControl && !state.inheritedAsset && !restrictive;
+  let headers = result.headers;
+  if (owned) {
+    headers = [...without(headers, 'cache-control', 'cdn-cache-control'), ['cache-control', state.cacheControl]];
+    if (state.cdnCacheControl) headers.push(['cdn-cache-control', state.cdnCacheControl]);
+  }
+  // Only responses the cache could hold vary on the declared headers; a
+  // refusal produced ahead of the handler keeps its own headers.
+  if (flight || state.statuses.has(result.status)) headers = mergeVary(headers, state.vary);
+  let out                = { ...result, headers };
+  if (state.strategy === 'revalidate') out = revalidate(state, req, out);
+  if (!flight) return out;
+  // Store decision for the request that reached the handler; waiters are
+  // released either way, with the entry or with nothing.
+  const { store } = state, body = bodyOf(out);
+  const storable = !req.secrets && state.statuses.has(out.status) && !restrictive && body.length <= state.maxBytes
+    && !out.headers.some(([k]) => String(k).toLowerCase() === 'set-cookie');
+  let entry                    = null;
+  if (storable) {
+    const previous = store.entries.get(flight.key);
+    if (previous) { store.entries.delete(flight.key); store.bytes -= previous.body.length; }
+    const { body: _body, headers: _headers, ...rest } = out;
+    entry = { result: rest, headers: without(out.headers, 'age'), body, storedAt: store.now(), revalidating: false };
+    store.entries.set(flight.key, entry); store.bytes += body.length;
+    evict(store, state.maxEntries);
+    log(state, 'store');
+  }
+  store.pending.delete(flight.key);
+  flight.flight.resolve(entry);
+  return out;
+}
+
+export function onError(state            , req               , _error          )       {
+  const flight = state.inflight.get(req);
+  if (!flight) return;
+  state.inflight.delete(req);
+  state.store.pending.delete(flight.key);
+  flight.flight.reject(new Error('cache fill failed'));
+  // A stale entry that failed to refresh may be served once more.
+  const entry = state.store.entries.get(flight.key);
+  if (entry) entry.revalidating = false;
+}
+
+export function describe(state            )                   {
+  const summary                   = { strategy: state.strategy, cacheControl: state.cacheControl, origin: state.origin, originTtl: state.originTtl, vary: state.vary };
+  if (state.cdnCacheControl) summary.cdnCacheControl = state.cdnCacheControl;
+  if (state.staleMs) summary.staleWhileRevalidate = state.staleMs / 1000;
+  if (state.staleIfError !== null) summary.staleIfError = state.staleIfError;
+  if (state.yamlCacheControl) summary.cacheControl = 'explicit response header';
+  else if (state.inheritedAsset) summary.cacheControl = 'asset handler';
+  if (state.secrets) summary.origin = false;
+  return summary;
+}
+
+export async function close(shared                          )                {
+  const store = shared?.cache;
+  if (!store) return;
+  for (const flight of store.pending.values()) flight.reject(new Error('runtime closed'));
+  store.pending.clear(); store.entries.clear(); store.bytes = 0;
+  delete shared.cache;
+}

package/dist/policies/compression.js

@@ -0,0 +1,187 @@
+import zlib from 'node:zlib';
+import { assert, ConfigError } from '../errors.js';
+                                                                     
+                                                                                                                             
+
+// Content-coding negotiation (RFC 9110 §12.5.3) enforced on the host. Runs
+// last in the response phase so every header it reads (Content-Type,
+// Cache-Control, Set-Cookie, ETag) is final. Two paths:
+//   assets   variants are computed once in compile() and served by reference
+//            with a strong, suffixed ETag (the NGINX gzip_static model);
+//   dynamic  bodies up to 1 MiB are compressed synchronously on the request
+//            path with a weakened ETag; larger bodies are sent as identity so
+//            the event loop is never held for a single response.
+export const name = 'compression';
+export const phases                    = ['response'];
+
+                                                        
+                                                                                                                                            
+                                                    
+                                   
+                                                                                                                                 
+                                                                                            
+ 
+                                                                                                                                             
+                                                                                                                                      
+
+const DYNAMIC_LIMIT = 1048576;              // bytes; above this a body is never compressed on the request path
+const PRECOMPRESSED_BUDGET = 64 * 1024 * 1024; // aggregate bytes of asset variants per runtime
+const DEFAULT_TYPES = ['text/*','application/json','application/javascript','application/xml','image/svg+xml','application/manifest+json','application/ld+json'];
+const SUFFIX                         = { br:'-br', gzip:'-gz', deflate:'-df', zstd:'-zs' };
+const BODYLESS = new Set([204,205,304]);
+
+// Codec table. `dynamic` levels favour latency, `stored` levels favour size
+// because they are paid once at load. An explicit `level` (1–11) is mapped
+// onto each codec's own scale so one number in YAML means "more" everywhere.
+const codecs                        = {
+  br: { dynamic: 4, stored: 9, map: level => level,
+    compress: (body, quality) => zlib.brotliCompressSync(body, { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: quality, [zlib.constants.BROTLI_PARAM_SIZE_HINT]: body.length } }) },
+  gzip: { dynamic: 6, stored: 9, map: level => Math.min(level, 9), compress: (body, level) => zlib.gzipSync(body, { level }) },
+  deflate: { dynamic: 6, stored: 9, map: level => Math.min(level, 9), compress: (body, level) => zlib.deflateSync(body, { level }) },
+  zstd: { dynamic: 3, stored: 12, map: level => Math.min(level * 2, 22),
+    compress: (body, level) => zlib.zstdCompressSync(body, { params: { [zlib.constants.ZSTD_c_compressionLevel]: level } }) },
+};
+export const zstdAvailable = typeof zlib.zstdCompressSync === 'function';
+const isCoding = (value         )                  => typeof value === 'string' && Object.hasOwn(codecs, value);
+
+export function targets()                                    { return { node:'native', vercel:'delegated', aws:'delegated', cloudflare:'delegated' }; }
+
+function typeMatcher(types          )                                          {
+  const exact = new Set        (), prefixes           = [];
+  for (const raw of types) {
+    const type = raw.toLowerCase().trim();
+    assert(/^[\w.+-]+\/(?:\*|[\w.+-]+)$/.test(type), `policies.${name}.types entry "${raw}" is not a media type`);
+    if (type.endsWith('/*')) prefixes.push(type.slice(0, -1)); else exact.add(type);
+  }
+  return header => {
+    const type = (header || '').split(';')[0] .trim().toLowerCase();
+    return type ? exact.has(type) || prefixes.some(prefix => type.startsWith(prefix)) : false;
+  };
+}
+function eligibleAssets(asset                                        )          {
+  if (!asset) return [];
+  return asset instanceof Map ? [...asset.values()] : [asset];
+}
+
+export async function compile(config                   , { route, shared }               )                            {
+  assert(config && typeof config === 'object', `policies.${name} on ${route.pattern} must be an object`);
+  const encodings = config.encodings ?? ['br','gzip'];
+  assert(Array.isArray(encodings) && encodings.length && encodings.every(isCoding), `policies.${name}.encodings on ${route.pattern} must list br, gzip, deflate or zstd`);
+  if (encodings.includes('zstd') && !zstdAvailable) throw new ConfigError(`${route.pattern} declares policies.${name}.encodings zstd, which node:zlib on Node ${process.version} does not provide`);
+  const minBytes = config.minBytes ?? 1024;
+  assert(Number.isInteger(minBytes) && minBytes >= 0, `policies.${name}.minBytes on ${route.pattern} must be a non-negative integer`);
+  const types = config.types ?? DEFAULT_TYPES;
+  assert(Array.isArray(types) && types.length, `policies.${name}.types on ${route.pattern} must be a non-empty array`);
+  const level = config.level;
+  assert(level === undefined || (Number.isInteger(level) && level >= 1 && level <= 11), `policies.${name}.level on ${route.pattern} must be 1–11`);
+  const levels                                  = {};
+  for (const coding of encodings) {
+    const codec = codecs[coding];
+    levels[coding] = level === undefined ? { dynamic: codec.dynamic, stored: codec.stored } : { dynamic: codec.map(level), stored: codec.map(level) };
+  }
+  const state                   = { encodings, minBytes, types, matches: typeMatcher(types), level: level ?? null, levels, allowWithSecrets: config.allowWithSecrets === true, precompressed: 0 };
+  // Asset snapshots are immutable until the next reload, so their variants are
+  // computed here, once, and bounded: a variant that does not shrink the file
+  // is dropped and the aggregate across the runtime stops at the budget.
+  shared.compressionBytes ??= 0;
+  for (const asset of eligibleAssets(route.asset)) {
+    if (asset.body.length < minBytes || !state.matches(asset.type)) continue;
+    const encoded = asset.encoded ??= {};
+    for (const coding of encodings) {
+      if (encoded[coding] || shared.compressionBytes >= PRECOMPRESSED_BUDGET) continue;
+      const variant = codecs[coding].compress(asset.body, levels[coding] .stored);
+      if (variant.length >= asset.body.length || shared.compressionBytes + variant.length > PRECOMPRESSED_BUDGET) continue;
+      encoded[coding] = variant;
+      shared.compressionBytes += variant.length; state.precompressed++;
+    }
+  }
+  return state;
+}
+
+// RFC 9110 §12.5.3: pick the acceptable coding with the highest weight; the
+// project's `encodings` order breaks ties. A coding absent from the field is
+// acceptable only through `*`; identity is the fallback whenever nothing else
+// is acceptable, including `identity;q=0` (sending 406 helps nobody).
+export function negotiate                  (acceptEncoding                           , encodings              )           {
+  if (acceptEncoding == null) return null;
+  const weights = new Map                ();
+  for (const member of acceptEncoding.split(',')) {
+    const [token = '', ...params] = member.split(';');
+    const coding = token.trim().toLowerCase();
+    if (!coding) continue;
+    let q = 1;
+    for (const param of params) {
+      const [key, value] = param.split('=');
+      if (key?.trim().toLowerCase() === 'q') { q = Number.parseFloat(value ); if (!Number.isFinite(q)) q = 0; }
+    }
+    if (!weights.has(coding)) weights.set(coding, Math.min(Math.max(q, 0), 1));
+  }
+  const star = weights.get('*') ?? 0;
+  let best           = null, bestQ = 0;
+  for (const coding of encodings) {
+    const q = weights.has(coding) ? weights.get(coding)  : star;
+    if (q > bestQ) { best = coding; bestQ = q; }
+  }
+  return best;
+}
+
+function header(headers              , key        )                     {
+  const found = headers.find(([k]) => k.toLowerCase() === key);
+  return found ? found[1] : undefined;
+}
+function withVary(headers              )               {
+  const index = headers.findIndex(([k]) => k.toLowerCase() === 'vary');
+  if (index < 0) return [...headers, ['vary','Accept-Encoding']];
+  const values = headers[index] [1].split(',').map(v => v.trim()).filter(Boolean);
+  if (values.some(v => v === '*' || v.toLowerCase() === 'accept-encoding')) return headers;
+  const out = [...headers]; out[index] = [headers[index] [0], [...values,'Accept-Encoding'].join(', ')];
+  return out;
+}
+function etagFor(headers              , coding        , strong         )               {
+  const value = header(headers, 'etag');
+  if (!value) return headers;
+  const tagged = strong ? value.replace(/"$/, SUFFIX[coding] + '"') : value.startsWith('W/') ? value : 'W/' + value;
+  return headers.map(([k,v]) => k.toLowerCase() === 'etag' ? [k,tagged] : [k,v]);
+}
+function noneMatch(value        , etag        )          {
+  return value.split(',').some(tag => { const t = tag.trim(); return t === '*' || t.replace(/^W\//,'') === etag.replace(/^W\//,''); });
+}
+
+export function onResponse(state                  , request               , result             )                {
+  const { status } = result;
+  if (BODYLESS.has(status) && status !== 304) return result;
+  const headers = result.headers;
+  if (header(headers, 'content-encoding') || !state.matches(header(headers, 'content-type'))) return result;
+  // The representation can vary from here on, whatever this response does.
+  const varied              = { ...result, headers: withVary(headers) };
+  if (status === 304 || status === 206) return varied;
+  if (/(?:^|,)\s*no-transform\s*(?:,|$)/i.test(header(headers, 'cache-control') || '')) return varied;
+  if (!state.allowWithSecrets && (request.secrets || headers.some(([k]) => k.toLowerCase() === 'set-cookie'))) return varied;
+  const body = result.body ? (Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body)) : Buffer.alloc(0);
+  if (body.length < state.minBytes) return varied;
+  const coding = negotiate(request.headers.get('accept-encoding'), state.encodings);
+  if (!coding) return varied;
+  const asset = result.asset;
+  const stored = asset?.encoded?.[coding] && (asset.body === result.body || (request.method === 'HEAD' && result.asset === asset)) && status === 200 ? asset.encoded[coding] : undefined;
+  let encoded        , strong         ;
+  if (stored) { encoded = stored; strong = true; }
+  else {
+    // Dynamic bodies: HEAD would pay the whole compression for a number, and
+    // large bodies would stall every other request, so both stay identity.
+    if (request.method === 'HEAD' || body.length > DYNAMIC_LIMIT) return varied;
+    encoded = codecs[coding].compress(body, state.levels[coding] .dynamic);
+    if (encoded.length >= body.length) return varied;
+    strong = false;
+  }
+  const out              = { ...varied, headers: [...etagFor(varied.headers, coding, strong).filter(([k]) => k.toLowerCase() !== 'content-encoding'), ['content-encoding', coding]] };
+  // The asset handler validated If-None-Match against the identity tag; the
+  // suffixed tag of an encoded variant is this module's to validate.
+  const etag = header(out.headers, 'etag'), revalidate = request.headers.get('if-none-match');
+  if (strong && etag && revalidate && noneMatch(revalidate, etag)) { const { contentLength: _length, ...rest } = out; return { ...rest, status: 304, body: Buffer.alloc(0) }; }
+  return { ...out, body: encoded, contentLength: encoded.length };
+}
+
+export function describe(state                  )                         {
+  return { encodings: state.encodings, minBytes: state.minBytes, types: state.types.length, level: state.level, precompressed: state.precompressed };
+}
+export async function close(shared                          )                { if (shared) shared.compressionBytes = 0; }

package/dist/policies/throttle.js

@@ -0,0 +1,131 @@
+import { assert } from '../errors.js';
+                                                                     
+                                                                                                                
+
+// Sliding-window request budget, expressed in the vocabulary of the IETF
+// httpapi RateLimit-Policy / RateLimit fields (draft-ietf-httpapi-
+// ratelimit-headers) so a NGINX limit_req or a CDN rule can restate the
+// same numbers. Two fixed windows are blended by elapsed fraction: cheaper
+// than a log, smoother than a fixed window, and the reset time stays
+// explainable in a header. Counters are per runtime, never per process
+// group; multi-instance sharing is a plugin concern.
+export const name = 'throttle';
+export const phases                    = ['request','response'];
+                                                            
+                                                                                                                                                        
+                                                                    
+/** The one counter table per runtime, shared by every route that declares a throttle. */
+                                                                                               
+                                                     
+                                
+                                                                                                                    
+                                                                                                
+ 
+                                                                                                                                                                   
+const partitions                    = ['client','route','client-route'];
+const bodies                         = { 429: 'Too many requests\n', 503: 'Service unavailable\n' };
+
+// Per-instance counters are only honest where one instance sees the whole
+// route; serverless targets fan a client across instances, so a client
+// budget there would silently be quota × instances.
+export function targets(config                          = {})                                    {
+  const perRoute = config.partition === 'route';
+  return { node: 'native', vercel: perRoute ? 'native' : 'refused', aws: perRoute ? 'native' : 'refused', cloudflare: 'refused' };
+}
+
+export async function compile(config                , { route, shared }               )                         {
+  assert(config && typeof config === 'object', `policies.${name} on ${route.pattern} must be an object`);
+  const { quota, window, partition = 'client', status = 429, mode = 'enforce', maxKeys = 100000 } = config;
+  assert(Number.isInteger(quota) && quota >= 1, `policies.${name}.quota on ${route.pattern} must be a positive integer`);
+  assert(Number.isInteger(window) && window >= 1, `policies.${name}.window on ${route.pattern} must be a positive integer of seconds`);
+  assert(partitions.includes(partition), `policies.${name}.partition on ${route.pattern} must be one of ${partitions.join(', ')}`);
+  assert(Number.isInteger(status) && status >= 400 && status <= 599, `policies.${name}.status on ${route.pattern} must be a 4xx or 5xx status`);
+  assert(mode === 'enforce' || mode === 'report', `policies.${name}.mode on ${route.pattern} must be enforce or report`);
+  assert(Number.isInteger(maxKeys) && maxKeys >= 1, `policies.${name}.maxKeys on ${route.pattern} must be a positive integer`);
+  // One table per runtime so a client budget spans routes that share a
+  // policy; the widest maxKeys wins because the table is common.
+  const table = shared.throttle ||= { keys: new Map(), maxKeys: 0, now: shared.now || Date.now };
+  table.maxKeys = Math.max(table.maxKeys, maxKeys);
+  return { quota, window, windowMs: window * 1000, partition, status, mode, route: route.pattern, table, log: shared.log, pending: new WeakMap() };
+}
+
+// Key by what the partition names, scoped to the budget itself so routes
+// that restate the same quota share one client counter while a route that
+// overrides it gets its own. An unresolved client (a caller that gave none,
+// or an adapter without a peer) shares one bucket rather than being exempt,
+// so a misconfigured proxy fails closed instead of open.
+function keyFor(state               , req               )         {
+  const client = req.client ?? 'shared';
+  const budget = `${state.quota}/${state.window}`;
+  if (state.partition === 'route') return `${budget}|route|${req.route}`;
+  if (state.partition === 'client') return `${budget}|client|${client}`;
+  return `${budget}|client-route|${client}|${req.route}`;
+}
+
+function touch(state               , key        )        {
+  const { keys, maxKeys } = state.table;
+  let entry = keys.get(key);
+  if (entry) keys.delete(key); else entry = { start: 0, current: 0, previous: 0 };
+  keys.set(key, entry);
+  // Map preserves insertion order, so re-inserting on access makes the first
+  // key the least recently used.
+  while (keys.size > maxKeys) keys.delete(keys.keys().next().value );
+  return entry;
+}
+
+// Roll the fixed windows forward, then weigh the previous one by how much of
+// it still overlaps a window ending now.
+function observe(state               , entry       , now        )                                  {
+  const start = now - (now % state.windowMs);
+  if (start !== entry.start) {
+    entry.previous = start - entry.start === state.windowMs ? entry.current : 0;
+    entry.current = 0; entry.start = start;
+  }
+  const elapsed = (now - start) / state.windowMs;
+  return { used: entry.previous * (1 - elapsed) + entry.current, reset: Math.max(1, Math.ceil((start + state.windowMs - now) / 1000)) };
+}
+
+function headersFor(state               , { remaining, reset }        )               {
+  return [['ratelimit-policy', `"default";q=${state.quota};w=${state.window}`], ['ratelimit', `"default";r=${remaining};t=${reset}`]];
+}
+
+function withHeaders(result               , added              )                {
+  const names = new Set(added.map(([n]) => n));
+  return { ...result, headers: [...result.headers.filter(([n]) => !names.has(String(n).toLowerCase())), ...added] };
+}
+
+export async function onRequest(state               , req               )                                     {
+  const now = state.table.now();
+  const entry = touch(state, keyFor(state, req));
+  const { used, reset } = observe(state, entry, now);
+  const exceeded = used + 1 > state.quota;
+  // A refused request is not counted: it did no work, and counting it would
+  // let a retry loop keep its own window from ever clearing.
+  if (!exceeded || state.mode === 'report') entry.current++;
+  const remaining = Math.max(0, Math.floor(state.quota - used - (exceeded ? 0 : 1)));
+  const budget = { remaining, reset };
+  if (exceeded || state.mode === 'report') {
+    try { state.log?.({ event: 'throttle', route: state.route, outcome: exceeded ? 'exceeded' : 'allowed', remaining }); } catch { /* logging never changes the outcome */ }
+  }
+  if (!exceeded || state.mode === 'report') { state.pending.set(req, budget); return undefined; }
+  // The runtime skips the response phase of request-phase modules for an
+  // early result, so the refusal must carry its own headers.
+  return withHeaders({ status: state.status, headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store'], ['retry-after', String(reset)]],
+    body: Buffer.from(bodies[state.status] || 'Request refused\n') }, headersFor(state, budget));
+}
+
+export function onResponse(state               , req               , result               )                {
+  const budget = state.pending.get(req);
+  return budget ? withHeaders(result, headersFor(state, budget)) : result;
+}
+
+export function describe(state               )                      {
+  const summary                      = { quota: state.quota, window: state.window, partition: state.partition, mode: state.mode, status: state.status };
+  if (state.partition !== 'route') summary.unresolvedClient = 'shared key';
+  return summary;
+}
+
+export async function close(shared              )                {
+  shared.throttle?.keys.clear();
+  delete shared.throttle;
+}