@jimhoyd/urlcode 0.3.0

package/dist/observability.js

@@ -0,0 +1,242 @@
+import { assert } from './errors.js';
+
+// Operator observability: the catalogue of events the runtime emits, a sink
+// that fans each event out to operator observers, in-process counters and a
+// Prometheus renderer. Observers mirror host plugins (src/plugins.js): they
+// are passed by the embedding application, never named in YAML, and run in
+// the host process with the host's privileges.
+//
+//   { name, version, onEvent(event)?, onMetrics(snapshot)?, onClose()? }
+//
+// Every field an event may carry is listed here. Nothing carries a request
+// URL, query string, header, body, client address, User-Agent string, binding
+// or secret; `route` is always the configured pattern.
+export const events = Object.freeze({
+  request: Object.freeze(['event', 'requestId', 'status', 'durationMs', 'method', 'route']),
+  reload: Object.freeze(['event', 'status', 'version', 'routes']),
+  watch: Object.freeze(['event', 'status']),
+  function_worker: Object.freeze(['event', 'status', 'slot', 'attempt', 'delayMs']),
+  link_store_worker: Object.freeze(['event', 'status', 'readOnly', 'attempt', 'delayMs']),
+  link_request: Object.freeze(['event', 'requestId', 'collection', 'route', 'code', 'method', 'status', 'outcome', 'durationMs']),
+  link_observer: Object.freeze(['event', 'status', 'reason', 'dropped', 'queued', 'delivered', 'failed', 'timedOut', 'closed']),
+  logs_dropped: Object.freeze(['event', 'count']),
+  observer: Object.freeze(['event', 'status', 'name']),
+  management_request: Object.freeze(['event', 'timestamp', 'requestId', 'collection', 'action', 'authenticated', 'principal', 'status', 'outcome', 'durationMs']),
+  throttle: Object.freeze(['event', 'route', 'outcome', 'remaining']),
+  agents: Object.freeze(['event', 'route', 'list', 'outcome']),
+  cache: Object.freeze(['event', 'route', 'outcome']),
+  listening: Object.freeze(['event', 'address', 'port', 'mode', 'origin']),
+});
+
+/** One log record: a flat object whose `event` key names the kind (see `events`). */
+                                                    
+                           
+                                
+                                          
+                                                 
+                      
+ 
+/** What the event does not say: the route when the request log is minimal, and whether this was a probe. */
+                                                                  
+                                       
+                                                                                                          
+                                  
+                                                           
+                                                                                            
+                                                                       
+                                                                                                                   
+                                                                                              
+                                                          
+                                                                      
+                                                                            
+                                                     
+                           
+ 
+                          
+                                                        
+                                              
+                           
+                        
+                                                             
+ 
+/** The log sink the runtime writes to: callable like a logger, with the counters and observers hanging off it. */
+                                                                                        
+                                                                          
+                                                                   
+  
+
+const hookNames = ['onEvent', 'onMetrics', 'onClose']         ;
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function validateObservers(observers          = [])             {
+  assert(Array.isArray(observers) && observers.length <= 32, 'Observers must be an array of at most 32 entries');
+  const seen = new Set        ();
+  for (const candidate of observers             ) {
+    assert(candidate && typeof candidate === 'object', 'Observer must be an object');
+    const observer = candidate                     ; // trust boundary: operator code, checked field by field
+    assert(typeof observer.name === 'string' && namePattern.test(observer.name), 'Observer name must be lowercase kebab-case');
+    assert(!seen.has(observer.name), `Duplicate observer "${observer.name}"`); seen.add(observer.name);
+    assert(typeof observer.version === 'string' && observer.version.length <= 64, `Observer "${observer.name}" needs a version string`);
+    for (const hook of hookNames) assert(observer[hook] === undefined || typeof observer[hook] === 'function', `Observer "${observer.name}" hook ${hook} must be a function`);
+    assert(hookNames.some(hook => observer[hook]), `Observer "${observer.name}" declares no hooks`);
+  }
+  return observers              ; // every entry was just checked
+}
+
+export const SNAPSHOT_VERSION = 1;
+const statusClasses = ['2xx', '3xx', '4xx', '5xx'];
+const MAX_ROUTES = 10000;
+const outcomes = {
+  throttle: ['allowed', 'exceeded'],
+  agents: ['denied', 'reported'],
+  cache: ['hit', 'stale', 'miss', 'store'],
+  link_request: ['completed', 'aborted', 'missing', 'disabled', 'expired', 'invalid_code', 'invalid_record', 'unavailable'],
+};
+const zeroed = (keys          )           => Object.fromEntries(keys.map(key => [key, 0]));
+
+// Counters and gauges derived from the events that pass through a sink, plus
+// the few facts only the server knows (admission, shedding). Numbers only; the
+// only keyed series is per configured route pattern, capped so a reviewed but
+// large configuration cannot grow it without bound.
+export function createMetrics()          {
+  const started = Date.now();
+  const requests                            = { total: 0, byStatusClass: zeroed(statusClasses), inFlight: 0, byRoute: Object.create(null)             };
+  const health                  = { total: 0, byStatusClass: zeroed(statusClasses), inFlight: 0 };
+  const shed = { requests: 0, health: 0 };
+  const reloads = { ok: 0, rejected: 0 };
+  const watch = { failed: 0 };
+  const functionWorkers = { started: 0, restarts: 0 };
+  const linkStoreWorkers = { started: 0, restarts: 0 };
+  const policies = { throttle: zeroed(outcomes.throttle), agents: zeroed(outcomes.agents), cache: zeroed(outcomes.cache) };
+  const linkRequests = zeroed(outcomes.link_request);
+  const linkObserver = { failed: 0, dropped: 0 };
+  let logsDropped = 0, observerErrors = 0;
+  const count = (table          , key         )       => { if (typeof key === 'string' && Object.hasOwn(table, key)) table[key] ++; };
+  function countRequest(target                 , status         , route         )       {
+    target.total++;
+    const cls = `${Math.floor(Number(status) / 100)}xx`;
+    if (Object.hasOwn(target.byStatusClass, cls)) target.byStatusClass[cls] ++;
+    if (route && target.byRoute) {
+      const key = String(route);
+      if (Object.hasOwn(target.byRoute, key)) target.byRoute[key] ++;
+      else if (Object.keys(target.byRoute).length < MAX_ROUTES) target.byRoute[key] = 1;
+    }
+  }
+  return {
+    // `context` carries what the event does not: the route when the request
+    // log is minimal, and whether this was a probe.
+    record(event, context = {}) {
+      if (!event || typeof event !== 'object') return;
+      const record = event                 ; // any object is read as a record; unknown keys are ignored
+      switch (record.event) {
+        case 'request': countRequest(context.probe ? health : requests, record.status, context.probe ? null : (record.route ?? context.route)); break;
+        case 'reload': count(reloads, record.status); break;
+        case 'watch': if (record.status === 'failed') watch.failed++; break;
+        case 'function_worker': if (record.status === 'restarting') functionWorkers.restarts++; else if (record.status === 'started') functionWorkers.started++; break;
+        case 'link_store_worker': if (record.status === 'restarting') linkStoreWorkers.restarts++; else if (record.status === 'started') linkStoreWorkers.started++; break;
+        case 'throttle': case 'agents': case 'cache': count(policies[record.event], record.outcome); break;
+        case 'link_request': count(linkRequests, record.outcome); break;
+        case 'link_observer': if (record.status === 'failed') linkObserver.failed++; else if (record.status === 'dropped' || record.status === 'closed') linkObserver.dropped = Math.max(linkObserver.dropped, Number(record.dropped) || 0); break;
+        case 'logs_dropped': logsDropped += Number(record.count) || 0; break;
+        case 'observer': if (record.status === 'failed') observerErrors++; break;
+        default: break;
+      }
+    },
+    inFlight(kind, delta) { if (kind === 'health') health.inFlight += delta; else requests.inFlight += delta; },
+    shed(kind) { shed[kind === 'health' ? 'health' : 'requests']++; },
+    observerError() { observerErrors++; },
+    snapshot(extra = {}) {
+      return {
+        version: SNAPSHOT_VERSION,
+        uptimeSeconds: Math.round((Date.now() - started) / 1000),
+        rssBytes: process.memoryUsage.rss(),
+        requests: { total: requests.total, byStatusClass: { ...requests.byStatusClass }, inFlight: requests.inFlight, byRoute: { ...requests.byRoute } },
+        health: { total: health.total, byStatusClass: { ...health.byStatusClass }, inFlight: health.inFlight },
+        shed: { ...shed },
+        reloads: { ...reloads },
+        watch: { ...watch },
+        functionWorkers: { ...functionWorkers, healthySlots: 0, slots: 0 },
+        linkStoreWorkers: { ...linkStoreWorkers },
+        policies: { throttle: { ...policies.throttle }, agents: { ...policies.agents }, cache: { ...policies.cache } },
+        linkRequests: { ...linkRequests },
+        linkObserver: { ...linkObserver },
+        logsDropped,
+        observers: { errors: observerErrors },
+        ...extra,
+      };
+    },
+  };
+}
+
+// Fan-out to the default sink first, then each observer in array order. An
+// observer that throws is counted and reported to the default sink only, so a
+// bad observer can neither fail a request nor recurse through the others.
+export function createObserverSink(observers          = [], fallbackLog                                 = () => {}, metrics          = createMetrics())               {
+  const checked = validateObservers(observers);
+  const report = (event               )       => { try { fallbackLog(event); } catch { /* Logging cannot fail requests. */ } };
+  const settle = (result         , observer          )       => {
+    if (result && typeof (result                        ).then === 'function') (result                        ).then(undefined, () => sink.fail(observer));
+  };
+  const sink               = Object.assign((event               , context                )       => {
+    metrics.record(event, context);
+    report(event);
+    for (const observer of checked) {
+      if (!observer.onEvent) continue;
+      try { settle(observer.onEvent(event), observer); } catch { sink.fail(observer); }
+    }
+  }, {
+    fail(observer          )       { metrics.observerError(); report({ event: 'observer', status: 'failed', name: observer.name }); },
+    metrics,
+    observers: checked,
+    publish(snapshot                 )       {
+      for (const observer of checked) {
+        if (!observer.onMetrics) continue;
+        try { settle(observer.onMetrics(snapshot), observer); } catch { sink.fail(observer); }
+      }
+    },
+    async close()                {
+      for (let i = checked.length - 1; i >= 0; i--) { try { await checked[i] .onClose?.(); } catch { sink.fail(checked[i] ); } }
+    },
+  });
+  return sink;
+}
+
+// Prometheus text exposition, version 0.0.4. Labels are limited to
+// status_class, route (a configured pattern) and outcome (a fixed vocabulary).
+const escapeLabel = (value         )         => String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+                                                
+export function renderPrometheus(snapshot                          )         {
+  const lines           = [];
+  const metric = (name        , type        , help        , samples          )       => {
+    lines.push(`# HELP urlcode_${name} ${help}`, `# TYPE urlcode_${name} ${type}`);
+    for (const [labels, value] of samples) {
+      const label = Object.entries(labels || {}).map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(',');
+      lines.push(`urlcode_${name}${label ? `{${label}}` : ''} ${typeof value === 'number' && Number.isFinite(value) ? value : 0}`);
+    }
+  };
+  const byKey = (table                      , label        )           => Object.entries(table || {}).map(([key, value]) => [{ [label]: key }, value]);
+  metric('requests_total', 'counter', 'Application requests answered since start, by status class.', byKey(snapshot.requests?.byStatusClass, 'status_class'));
+  metric('route_requests_total', 'counter', 'Application requests answered since start, by configured route pattern.', byKey(snapshot.requests?.byRoute, 'route'));
+  metric('requests_in_flight', 'gauge', 'Application requests currently admitted.', [[{}, snapshot.requests?.inFlight]]);
+  metric('health_requests_total', 'counter', 'Probe and metrics requests answered since start, by status class.', byKey(snapshot.health?.byStatusClass, 'status_class'));
+  metric('health_requests_in_flight', 'gauge', 'Probe and metrics requests currently admitted.', [[{}, snapshot.health?.inFlight]]);
+  metric('shed_total', 'counter', 'Requests refused with 503 because an admission budget was full.', byKey(snapshot.shed, 'outcome'));
+  metric('reloads_total', 'counter', 'Configuration reloads since start.', byKey(snapshot.reloads, 'outcome'));
+  metric('watch_failures_total', 'counter', 'Development watcher failures.', [[{}, snapshot.watch?.failed]]);
+  metric('function_worker_restarts_total', 'counter', 'Function worker replacements scheduled.', [[{}, snapshot.functionWorkers?.restarts]]);
+  metric('function_worker_healthy_slots', 'gauge', 'Function worker slots ready to serve.', [[{}, snapshot.functionWorkers?.healthySlots]]);
+  metric('function_worker_slots', 'gauge', 'Function worker slots configured.', [[{}, snapshot.functionWorkers?.slots]]);
+  metric('link_store_worker_restarts_total', 'counter', 'Link-store worker replacements scheduled.', [[{}, snapshot.linkStoreWorkers?.restarts]]);
+  metric('throttle_total', 'counter', 'Throttle policy decisions.', byKey(snapshot.policies?.throttle, 'outcome'));
+  metric('agents_total', 'counter', 'Agents policy decisions.', byKey(snapshot.policies?.agents, 'outcome'));
+  metric('cache_total', 'counter', 'Cache policy outcomes.', byKey(snapshot.policies?.cache, 'outcome'));
+  metric('link_requests_total', 'counter', 'Dynamic link requests by outcome.', byKey(snapshot.linkRequests, 'outcome'));
+  metric('link_observer_failures_total', 'counter', 'Link event collector failures.', [[{}, snapshot.linkObserver?.failed]]);
+  metric('link_observer_dropped_total', 'counter', 'Link events dropped under overload.', [[{}, snapshot.linkObserver?.dropped]]);
+  metric('logs_dropped_total', 'counter', 'Log records the JSON logger shed.', [[{}, snapshot.logsDropped]]);
+  metric('observer_errors_total', 'counter', 'Observer hooks that threw or rejected.', [[{}, snapshot.observers?.errors]]);
+  metric('uptime_seconds', 'gauge', 'Seconds since the process started serving.', [[{}, snapshot.uptimeSeconds]]);
+  metric('process_rss_bytes', 'gauge', 'Resident set size of the process.', [[{}, snapshot.rssBytes]]);
+  metric('metrics_snapshot_version', 'gauge', 'Version of the metrics snapshot shape.', [[{}, snapshot.version]]);
+  return lines.join('\n') + '\n';
+}

package/dist/plugins.js

@@ -0,0 +1,74 @@
+import { assert, ConfigError } from './errors.js';
+import { targets as knownTargets } from './policies.js';
+                                                        
+                                                                      
+                                                                      
+                                                                    
+
+// Operator-supplied host plugins. They are not part of the project format: an
+// application passes them to startServer/createRuntime, so the YAML stays
+// portable and the trust boundary stays with the operator. Same hook names as
+// first-party policies, so both are tested through one seam.
+//
+//   { name, version, targets: ['node', …],
+//     onActivate(runtime)?, onRequest(req)?, onResponse(req, result)?,
+//     onError(req, error)?, onClose()? }
+//
+// onRequest may return a result to short-circuit; onResponse returns the
+// result to send. No hook can reach the guest, extend a deadline or read
+// bindings: the request object carries none of those.
+/** What onActivate receives: the started runtime's public facts, never its handlers. */
+                                                                                                      
+                         
+                                                       
+                                                            
+                                                                                                                   
+                                                                                                                                           
+                                                                         
+                                   
+ 
+const hookNames = ['onActivate','onRequest','onResponse','onError','onClose']         ;
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function validatePlugins(plugins          = [], target         = 'node')           {
+  assert(Array.isArray(plugins) && plugins.length <= 32, 'Plugins must be an array of at most 32 entries');
+  const seen = new Set        ();
+  for (const candidate of plugins             ) {
+    assert(candidate && typeof candidate === 'object', 'Plugin must be an object');
+    const plugin = candidate                   ; // trust boundary: operator code, checked field by field
+    assert(typeof plugin.name === 'string' && namePattern.test(plugin.name), 'Plugin name must be lowercase kebab-case');
+    assert(!seen.has(plugin.name), `Duplicate plugin "${plugin.name}"`); seen.add(plugin.name);
+    assert(typeof plugin.version === 'string' && plugin.version.length <= 64, `Plugin "${plugin.name}" needs a version string`);
+    assert(Array.isArray(plugin.targets) && plugin.targets.every(t => (knownTargets                     ).includes(t)), `Plugin "${plugin.name}" must list its supported targets`);
+    if (!(plugin.targets            ).includes(target)) throw new ConfigError(`Plugin "${plugin.name}" does not support the ${target} target`);
+    for (const hook of hookNames) assert(plugin[hook] === undefined || typeof plugin[hook] === 'function', `Plugin "${plugin.name}" hook ${hook} must be a function`);
+    assert(hookNames.some(hook => plugin[hook]), `Plugin "${plugin.name}" declares no hooks`);
+  }
+  return plugins            ; // every entry was just checked
+}
+
+export async function activatePlugins(plugins          , runtime               )                {
+  for (const plugin of plugins) await plugin.onActivate?.(runtime);
+}
+
+export async function pluginsRequest(plugins          , request               )                                     {
+  for (const plugin of plugins) {
+    const early = await plugin.onRequest?.(request);
+    if (early) return early;
+  }
+  return undefined;
+}
+
+// Reverse order, so the plugin that saw the request first sees the response last.
+export async function pluginsResponse(plugins          , request               , result               )                         {
+  for (let i = plugins.length - 1; i >= 0; i--) result = (await plugins[i] .onResponse?.(request, result)) ?? result;
+  return result;
+}
+
+export async function pluginsError(plugins          , request               , error         )                {
+  for (let i = plugins.length - 1; i >= 0; i--) { try { await plugins[i] .onError?.(request, error); } catch { /* an observer cannot change the outcome */ } }
+}
+
+export async function closePlugins(plugins          )                {
+  for (let i = plugins.length - 1; i >= 0; i--) { try { await plugins[i] .onClose?.(); } catch { /* best effort */ } }
+}

package/dist/policies/agents.js

@@ -0,0 +1,248 @@
+import { assert, ConfigError } from '../errors.js';
+import { lists as bundled } from '../../data/agents/index.js';
+                                                         
+
+// User-Agent policy. Contract in src/policies.ts. This module also runs inside
+// the Cloudflare Worker, so it has no Node imports and never touches the
+// filesystem: bundled lists arrive through the generated data/agents/index.js
+// and project-relative list files arrive already loaded (src/agent-lists.ts
+// on Node, or a `resolved` map the build step attaches for the Worker).
+export const name = 'agents';
+export const phases                    = ['request'];
+export function targets()                                        { return { node:'native', vercel:'native', aws:'native', cloudflare:'compiled' }; }
+
+                                                              
+                               
+                                                                    
+                                                                                       
+                                                                                 
+                                          
+ 
+                                                    
+                                                                                                                     
+                                                                       
+                                                                                      
+                                                                                                 
+                              
+                                                                                
+                                                                                           
+                                                                       
+ 
+                                    
+                                                                                                    
+                                                                                         
+ 
+                             
+
+export const bundledLists = Object.freeze(Object.keys(bundled));
+export const MAX_PATTERN_BYTES = 256;
+export const MAX_REPEAT = 64;
+
+// The pattern subset: anchors, literals, `.`, escapes, character classes,
+// groups, alternation, and quantifiers on a single atom only. Nothing here
+// can make a backtracking engine super-linear on the input: no backreferences,
+// no lookaround, no quantifier on a group that itself repeats, no unbounded
+// counted repetition. A pattern outside the subset is a ConfigError, so a
+// project cannot turn the matcher into a ReDoS vector by editing YAML.
+const escapeClass = /^[dDwWsSbBtnrfv0]$/;
+export function validatePattern(pattern         )                     {
+  if (typeof pattern !== 'string' || !pattern.length) return 'pattern must be a non-empty string';
+  if (new TextEncoder().encode(pattern).length > MAX_PATTERN_BYTES) return `pattern exceeds ${MAX_PATTERN_BYTES} bytes`;
+  let i = 0;
+  const p = pattern;
+  const peek = ()                     => p[i];
+  function escape()                     { // after the backslash
+    const c = p[i++];
+    if (c === undefined) return 'trailing backslash';
+    if (/[1-9]/.test(c) || c === 'k') return 'backreferences are not allowed';
+    if (c === 'p' || c === 'P') return 'unicode property escapes are not allowed';
+    if (c === 'x') { if (!/^[0-9a-fA-F]{2}$/.test(p.slice(i, i + 2))) return 'bad \\x escape'; i += 2; return; }
+    if (c === 'u') { if (!/^[0-9a-fA-F]{4}$/.test(p.slice(i, i + 4))) return 'bad \\u escape'; i += 4; return; }
+    if (c === 'c') return 'control escapes are not allowed';
+    if (escapeClass.test(c) || /[^A-Za-z0-9]/.test(c)) return;
+    return `unknown escape \\${c}`;
+  }
+  function charClass()                     { // after '['
+    if (peek() === '^') i++;
+    let first = true;
+    for (;;) {
+      const c = p[i++];
+      if (c === undefined) return 'unterminated character class';
+      if (c === ']' && !first) return;
+      first = false;
+      if (c === '[') return 'nested character classes are not allowed';
+      if (c === '\\') { const err = escape(); if (err) return err; }
+    }
+  }
+  function quantifier()                                   { // returns {err} or {none} or {}
+    const c = peek();
+    if (c === '*' || c === '+' || c === '?') { i++; }
+    else if (c === '{') {
+      const m = /^\{(\d{1,3})(?:,(\d{1,3}))?\}/.exec(p.slice(i));
+      if (!m) return { err: 'counted repetition must be {n} or {n,m}' };
+      const lo = Number(m[1]), hi = m[2] === undefined ? lo : Number(m[2]);
+      if (hi < lo) return { err: 'repetition upper bound below lower bound' };
+      if (hi > MAX_REPEAT) return { err: `repetition bound above ${MAX_REPEAT}` };
+      i += m[0].length;
+    } else return { none: true };
+    if (/[*+?{]/.test(peek() ?? '')) return { err: 'stacked or lazy quantifiers are not allowed' };
+    return {};
+  }
+  // Parses one alternation; returns {err} or {quantified: boolean} where
+  // quantified says whether anything inside carries a quantifier.
+  function alternation(depth        )                                                                   {
+    let quantified = false;
+    for (;;) {
+      const c = p[i];
+      if (c === undefined || c === '|' || c === ')') return { quantified, end: c };
+      i++;
+      let atom = 'single';
+      if (c === '\\') { const err = escape(); if (err) return { err }; }
+      else if (c === '[') { const err = charClass(); if (err) return { err }; }
+      else if (c === '(') {
+        if (peek() === '?') {
+          if (p[i + 1] !== ':') return { err: 'lookaround and named groups are not allowed' };
+          i += 2;
+        }
+        let inner                      = false;
+        for (;;) {
+          const r = alternation(depth + 1);
+          if (r.err) return r;
+          inner = inner || r.quantified;
+          if (r.end === '|') { i++; continue; }
+          if (r.end === ')') { i++; break; }
+          return { err: 'unterminated group' };
+        }
+        atom = inner ? 'group-quantified' : 'group';
+      }
+      else if (c === ')') return { err: 'unbalanced parenthesis' };
+      else if (c === '^' || c === '$') atom = 'anchor';
+      else if (c === '*' || c === '+' || c === '?' || c === '{') {
+        if (c === '{') continue; // a literal brace where no quantifier can apply
+        return { err: 'quantifier without a preceding atom' };
+      }
+      const q = quantifier();
+      if (q.err) return { err: q.err };
+      if (q.none) continue;
+      if (atom === 'anchor') return { err: 'quantifier on an anchor' };
+      if (atom === 'group-quantified') return { err: 'nested quantifiers are not allowed' };
+      if (atom === 'group' && p[i - 1] !== '?') return { err: 'only ? may quantify a group; put * + {n,m} on a single atom' };
+      quantified = true;
+    }
+  }
+  for (;;) {
+    const r = alternation(0);
+    if (r.err) return r.err;
+    if (r.end === '|') { i++; continue; }
+    if (r.end === ')') return 'unbalanced parenthesis';
+    break;
+  }
+  try { new RegExp(pattern, 'i'); } catch (error) { return `invalid regular expression: ${(error         ).message}`; }
+  return undefined;
+}
+
+function checkPatterns(entries              , where        )       {
+  for (const entry of entries) {
+    const problem = validatePattern(entry.pattern);
+    if (problem) throw new ConfigError(`${where}: pattern ${JSON.stringify(String(entry.pattern))} rejected (${problem})`);
+  }
+}
+
+// One RegExp per list, alternated: a single pass over the header per list
+// instead of one per pattern, and the list name still known on a hit.
+function compileList(label        , entries              )                      {
+  if (!entries.length) return null;
+  const regexp = new RegExp(entries.map(({ pattern }) => `(?:${pattern})`).join('|'), 'i');
+  return { label, count: entries.length, regexp };
+}
+
+export function isBundled(reference        )          { return Object.hasOwn(bundled, reference); }
+export function isListFile(reference         )                      { return typeof reference === 'string' && reference.endsWith('.json'); }
+
+// Resolves one `deny`/`allow` reference to {label, entries, source}. Bundled
+// names come from the generated index; a `.json` reference must be in
+// `loaded` (Node: read by src/agent-lists.ts; Worker: attached at build).
+function resolveReference(reference        , loaded                                          , routePattern        )               {
+  if (isBundled(reference)) {
+    const list = bundled[reference] ;
+    return { label: reference, entries: list.patterns.map(([entryName, pattern]) => ({ name: entryName, pattern })), source: list.source, revision: list.revision };
+  }
+  if (isListFile(reference)) {
+    const entries = loaded?.[reference];
+    assert(Array.isArray(entries), `${routePattern}: policies.agents list ${JSON.stringify(reference)} is not loaded on this target; bundled names are ${bundledLists.join(', ')}`);
+    return { label: reference, entries, source: 'project', revision: 'project' };
+  }
+  throw new ConfigError(`${routePattern}: policies.agents references unknown list ${JSON.stringify(reference)}; bundled names are ${bundledLists.join(', ')}, or give a project-relative path ending in .json`);
+}
+
+function build(config                          , { route, shared, loaded }                                                                       )              {
+  assert(config && typeof config === 'object', `policies.${name} on ${route.pattern} must be an object`);
+  const where = `${route.pattern} policies.agents`;
+  const mode = config.mode ?? 'enforce';
+  assert(mode === 'enforce' || mode === 'report', `${where}.mode must be enforce or report`);
+  const status = config.status ?? 403;
+  assert(Number.isInteger(status) && status >= 400 && status <= 599, `${where}.status must be an integer between 400 and 599`);
+  const lists                                        = { deny: [], allow: [] };
+  const used                          = { deny: [], allow: [] };
+  for (const side of ['deny', 'allow']         ) {
+    for (const reference of config[side] ?? []) {
+      const list = resolveReference(reference, loaded, route.pattern);
+      checkPatterns(list.entries, `${where}.${side} list ${JSON.stringify(reference)}`);
+      lists[side].push(compileList(list.label, list.entries));
+      used[side].push({ name: list.label, patterns: list.entries.length, source: list.source, revision: list.revision });
+    }
+    const patterns = (config[`${side}Patterns`         ] ?? []).map(pattern => ({ pattern }));
+    checkPatterns(patterns, `${where}.${side}Patterns`);
+    const compiled = compileList('pattern', patterns);
+    if (compiled) lists[side].push(compiled);
+  }
+  const compiled = (list                     )                       => Boolean(list);
+  const state              = {
+    route: route.pattern, mode, status, denyEmpty: config.denyEmpty === true,
+    deny: lists.deny.filter(compiled), allow: lists.allow.filter(compiled),
+    used, patternCounts: { deny: config.denyPatterns?.length ?? 0, allow: config.allowPatterns?.length ?? 0 },
+    log: shared?.log,
+  };
+  return state;
+}
+
+// Synchronous on the Worker (it is called without await there); on Node the
+// project-relative list files are read first, so the result is a promise.
+export function compile(config                          , context               )                                     {
+  const { target, root } = context;
+  const files = [...(config?.deny ?? []), ...(config?.allow ?? [])].filter(isListFile);
+  if (target === 'cloudflare' || !files.length) return build(config, { ...context, loaded: config?.resolved });
+  // Non-literal specifier on purpose: a Worker bundler must not follow this
+  // Node-only import; the Worker never reaches this line.
+  const loader = '../agent-lists.js';
+  return import(loader).then(async ({ loadListFiles }                                    ) => build(config, { ...context, loaded: await loadListFiles(files, root, context.route.pattern) }));
+}
+
+const encoder = new TextEncoder();
+function firstMatch(lists                , agent        )                     {
+  for (const list of lists) if (list.regexp.test(agent)) return list.label;
+  return undefined;
+}
+
+export function onRequest(state             , request                                                   )                            {
+  const agent = request.headers.get('user-agent');
+  let list                    ;
+  if (agent === null || agent.trim() === '') { if (state.denyEmpty) list = 'empty'; }
+  else if (firstMatch(state.allow, agent) === undefined) list = firstMatch(state.deny, agent);
+  if (list === undefined) return undefined;
+  const denied = state.mode === 'enforce';
+  // The list name is logged, never the header: a User-Agent is attacker text.
+  try { state.log?.({ event: 'agents', route: state.route, list, outcome: denied ? 'denied' : 'reported' }); } catch { /* logging cannot fail a request */ }
+  if (!denied) return undefined;
+  return { status: state.status, headers: [['content-type','text/plain; charset=utf-8'],['cache-control','no-store']], body: encoder.encode('Forbidden\n') };
+}
+
+export function describe(state             )                    {
+  const total = (side      )         => state[side].reduce((sum, list) => sum + list.count, 0);
+  return { mode: state.mode, status: state.status, denyEmpty: state.denyEmpty,
+    deny: state.used.deny, allow: state.used.allow,
+    denyPatterns: state.patternCounts.deny, allowPatterns: state.patternCounts.allow,
+    patterns: { deny: total('deny'), allow: total('allow') } };
+}
+
+export async function close()                {}