@jimhoyd/urlcode 0.3.0

package/dist/config.js

@@ -0,0 +1,172 @@
+import { Worker } from 'node:worker_threads';
+import { readFile, realpath, stat, lstat, open } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, extname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseDocument, visit, isAlias, isScalar, isMap, isNode } from 'yaml';
+import Ajv from 'ajv/dist/2020.js';
+import { assert, ConfigError } from './errors.js';
+                                                                               
+
+/** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
+                                                                               
+                                                     
+
+// The schema file is this package's own; JSON.parse gives unknown and Ajv takes it as a schema object.
+const schema = JSON.parse(await readFile(new URL('../schemas/urlcode.schema.json', import.meta.url), 'utf8'))          ;
+// Node hands the CJS module.exports (the class) to a default import; TypeScript types it as the namespace, whose .default is the same class.
+const validate = new Ajv.default({ allErrors: false, strict: true, strictRequired: false, allowUnionTypes: true }).compile(schema);
+export const MAX_CONFIG_BYTES = 32 * 1024 * 1024;
+export function parseYaml(text        )          {
+  assert(Buffer.byteLength(text) <= MAX_CONFIG_BYTES, 'Configuration exceeds 32 MiB');
+  const doc = parseDocument(text, { version: '1.2', uniqueKeys: false, strict: true });
+  assert(!doc.errors.length && !doc.warnings.length, 'Invalid YAML: check syntax, duplicate keys and tags');
+  visit(doc, (_key, node) => {
+    assert(!isAlias(node) && !(isNode(node) && (node.anchor || node.tag)), 'YAML aliases, anchors and explicit tags are unsupported');
+    if (isMap(node)) {
+      // The parser's generic pair comparison is quadratic on large mappings.
+      // Our string-only profile permits equivalent linear duplicate detection.
+      const keys = new Set        ();
+      for (const pair of node.items) {
+        assert(isScalar(pair.key) && typeof pair.key.value === 'string', 'YAML mapping keys must be strings');
+        assert(!keys.has(pair.key.value), 'Duplicate YAML mapping key');
+        keys.add(pair.key.value);
+      }
+    }
+    if (isScalar(node)) assert(node.value === null || ['string', 'number', 'boolean'].includes(typeof node.value), 'Non-JSON YAML value');
+  });
+  const data          = doc.toJS({ maxAliasCount: 0, mapAsMap: false });
+  const inspect = (value         , depth = 0)       => {
+    assert(depth < 40, 'Configuration nesting exceeds 40 levels');
+    if (typeof value === 'number') assert(Number.isFinite(value), 'Non-finite YAML number');
+    if (value && typeof value === 'object') {
+      for (const [key, child] of Object.entries(value)) {
+        assert(!['__proto__', 'prototype', 'constructor', '<<'].includes(key), 'Reserved mapping key');
+        inspect(child, depth + 1);
+      }
+    }
+  };
+  inspect(data);
+  return data;
+}
+export function validateDocument(data         )                  {
+  if (!validate(data)) {
+    const e = validate.errors [0] ;
+    throw new ConfigError(`Invalid configuration at ${e.instancePath || '/'} (${e.keyword})`);
+  }
+  return data                   ; // trust boundary: the schema just admitted it
+}
+export async function safeFile(root        , file         )                  {
+  root = await realpath(root);
+  assert(typeof file === 'string' && file.length && !isAbsolute(file), 'File reference must be project-relative');
+  const actual = await realpath(resolve(root, file)).catch(() => { throw new ConfigError('Referenced project file is missing'); });
+  const rel = relative(root, actual);
+  assert(rel && rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(rel), 'File reference escapes project');
+  assert((await stat(actual)).isFile(), 'Reference must point to a file');
+  return actual;
+}
+export const MAX_PROJECT_CONFIG_BYTES = 64 * 1024 * 1024;
+async function readConfig(file        , budget                       )                   {
+  const handle = await open(file, 'r');
+  try {
+    const size = (await handle.stat()).size;
+    assert(size <= MAX_CONFIG_BYTES, 'Configuration exceeds 32 MiB');
+    assert(size <= budget.remaining, 'Project configuration exceeds aggregate 64 MiB');
+    // Read at most the checked size plus one byte; concurrent growth cannot
+    // turn a small stat result into an unbounded readFile allocation.
+    const buffer = Buffer.alloc(size + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const {bytesRead} = await handle.read(buffer, offset, buffer.length-offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    assert(offset <= size, 'Configuration changed while reading');
+    budget.remaining -= offset;
+    return parseYaml(new TextDecoder('utf-8', {fatal:true}).decode(buffer.subarray(0,offset)));
+  } finally { await handle.close(); }
+}
+// Resource limits contain parser/AST/schema expansion, not just source bytes.
+// The parent can terminate a blocked parser without blocking serving requests.
+let activeLoads = 0;
+export async function loadDocument(project        , {timeoutMs=10000}                      ={})                          {
+  assert(Number.isInteger(timeoutMs) && timeoutMs>=1 && timeoutMs<=30000, 'Configuration deadline must be 1–30000 ms');
+  assert(activeLoads < 2, 'Configuration compilation capacity unavailable');
+  activeLoads++;
+  let worker                    ;
+  try {
+    const data                   = {project};
+    worker = new Worker(new URL('./config-worker.js', import.meta.url), {
+      workerData:data, env:{}, execArgv:[], stdout:true, stderr:true,
+      resourceLimits:{maxOldGenerationSizeMb:256, maxYoungGenerationSizeMb:16, stackSizeMb:4},
+    });
+    worker.stdout.resume(); worker.stderr.resume();
+    const started = worker;
+    return await new Promise                ((resolve,reject)=>{
+      const timer=setTimeout(()=>reject(new ConfigError('Configuration compilation deadline exceeded')),timeoutMs);
+      const done=(error              ,value                 )=>{clearTimeout(timer); if(error)reject(error);else resolve(value );};
+      // The worker only ever posts a ConfigWorkerResult (config-worker.ts).
+      started.once('message',(message                    )=>'error' in message ? done(new ConfigError(message.error)) : done(null,message.value));
+      started.once('error',()=>done(new ConfigError('Configuration worker resource limit or failure')));
+      started.once('exit',()=>done(new ConfigError('Configuration worker exited')));
+    });
+  } finally { try { await worker?.terminate(); } finally { activeLoads--; } }
+}
+export async function loadDocumentInWorker(project        )                          {
+  const budget={remaining:MAX_PROJECT_CONFIG_BYTES};
+  const root = await realpath(project);
+  const file = await safeFile(root, 'urlcode.yaml');
+  const document = validateDocument(await readConfig(file, budget));
+  const routes                              = Object.assign(Object.create(null)                               , document.routes);
+  const files = [file];
+  let routeCount=Object.keys(routes).length;
+  for (const include of document.includes || []) {
+    const path = await safeFile(root, include);
+    assert(!files.includes(path), 'Duplicate include');
+    files.push(path);
+    const part = validateDocument(await readConfig(path, budget));
+    assert(!part.includes?.length, 'Nested includes are unsupported');
+    assert(part.dynamicLinks===undefined, 'dynamicLinks may only be set in the entry urlcode.yaml');
+    assert(part.site===undefined, 'site may only be set in the entry urlcode.yaml');
+    for (const [pattern, route] of Object.entries(part.routes)) {
+      assert(!Object.hasOwn(routes, pattern), 'Duplicate route across files');
+      routes[pattern] = route;
+      assert(++routeCount <= 100000, 'Maximum 100000 routes per project');
+    }
+  }
+  assert(Object.keys(routes).length <= 100000, 'Maximum 100000 routes per project');
+  assert(document.dynamicLinks===true || !Object.values(routes).some(route=>route.link), 'Link routes require dynamicLinks: true in urlcode.yaml');
+  return { root, document, routes, files, version: createHash('sha256').update(JSON.stringify(document.site ? {...(document.dynamicLinks===true?{routes,dynamicLinks:true}:{routes}), site:document.site} : document.dynamicLinks===true?{routes,dynamicLinks:true}:routes)).digest('hex').slice(0, 16) };
+}
+export async function loadBindings(root        , local = false, environment                                     = process.env)                                              {
+  const vars                         = {};
+  if (local) {
+    try {
+      const path = await safeFile(root, '.env.local');
+      assert((await stat(path)).size <= 65536, '.env.local exceeds 64 KiB');
+      const text = await readFile(path, 'utf8');
+      // A deliberately small non-executable dotenv profile. No interpolation/escapes.
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.trim() || line.trimStart().startsWith('#')) continue;
+        const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        assert(match, 'Invalid .env.local assignment');
+        const [, key = '', raw = ''] = match;
+        assert(!Object.hasOwn(vars, key), 'Duplicate .env.local name');
+        let value = raw.trim();
+        if (value.startsWith('"') || value.startsWith("'")) {
+          assert(value.length >= 2 && value.endsWith(value[0] ), 'Invalid .env.local quote');
+          value = value.slice(1, -1);
+        }
+        vars[key] = value;
+      }
+    } catch (error) {
+      // Only absence is optional. Malformed files and unsafe symlinks fail closed.
+      try { await lstat(resolve(root, '.env.local')); } catch (e) { if ((e                         ).code === 'ENOENT') return { ...environment }; }
+      throw error;
+    }
+  }
+  return { ...vars, ...environment };
+}
+export async function functionFile(root        , file        )                  {
+  assert(['.mjs', '.js'].includes(extname(file)), 'Functions must be JavaScript ES modules (.mjs or .js)');
+  return safeFile(root, file);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class ConfigError extends Error {}
+export class HttpError extends Error {
+           status        ;
+  constructor(status        , message        ) { super(message); this.status = status; }
+}
+export function assert(condition         , message        )                    {
+  if (!condition) throw new ConfigError(message);
+}

package/dist/function-sources.js

@@ -0,0 +1,54 @@
+import { readFile, stat } from 'node:fs/promises';
+import { relative, dirname, resolve, sep, posix } from 'node:path';
+import { init, parse } from 'es-module-lexer';
+import { functionFile } from './config.js';
+import { assert } from './errors.js';
+
+/** A function or middleware reference with its export named: what the sandbox loads. */
+                                                                      
+/** Any route-like object carrying function definitions (a YAML route, whose `export` may be absent, or a compiled one). */
+                                                                                                                 
+                                  
+                                                                          
+                                                                          
+                                                
+                              
+                                             
+                             
+ 
+
+export function routeFunctions   (route                  )      { return [...(route.middleware || []), ...(route.function ? [route.function] : [])]; }
+
+// Parse and snapshot source without ever importing project code into Node.
+export async function collectFunctionSources(routes                 , root        )                           {
+  await init;
+  const sources                         = Object.create(null), dependencies                           = Object.create(null);
+  const entries                     = [], names = new Map                (), seenEntries = new Set        ();
+  let bytes = 0;
+  async function collect(file        )                  {
+    const name = '/' + relative(root,file).split(sep).join('/');
+    if (Object.hasOwn(sources,name)) return name;
+    assert(Object.keys(sources).length < 128, 'Function module limit exceeded');
+    const info = await stat(file);
+    assert(info.size <= 1048576 && bytes + info.size <= 4194304, 'Function source limit exceeded');
+    const code = await readFile(file,'utf8'); bytes += Buffer.byteLength(code);
+    assert(bytes <= 4194304, 'Function source limit exceeded');
+    sources[name] = code; const deps           = dependencies[name] = [];
+    const [imports] = parse(code);
+    for (const item of imports) {
+      assert(item.type === 'static' && typeof item.specifier === 'string' && !item.attributes && !item.phase, 'Dynamic imports and import.meta are unsupported in sandbox functions');
+      assert(item.specifier.startsWith('./') || item.specifier.startsWith('../'), 'Only relative project JavaScript imports are allowed');
+      const dependency = await functionFile(root,relative(root,resolve(dirname(file),item.specifier)));
+      assert(posix.normalize(posix.join(posix.dirname(name),item.specifier)).startsWith('/'), 'Invalid module reference');
+      deps.push(await collect(dependency));
+    }
+    return name;
+  }
+  for (const definition of routes.flatMap(routeFunctions)) {
+    const name = await collect(definition.source);
+    names.set(definition.source,name);
+    const key = name + ":" + definition.export;
+    if (!seenEntries.has(key)) { entries.push([name,definition.export]); seenEntries.add(key); }
+  }
+  return { sources,dependencies,entries,names };
+}

package/dist/function-worker.js

@@ -0,0 +1,105 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { posix } from 'node:path';
+import { getQuickJS,                    } from 'quickjs-emscripten';
+import { guestBootstrap } from './guest-api.js';
+                                                                                                       
+                                                           
+
+if (!parentPort) throw new Error('Function worker requires a parent');
+const port = parentPort;
+const data = workerData                      ; // trust boundary: set by FunctionPool.spawn
+const post = (message                       )       => port.postMessage(message);
+const engine = await getQuickJS();
+async function evaluate(entry                    , name                    , payload         , timeoutMs = 5000, chain                                 = [])                              {
+  // New heap/module state for every invocation, including validation. No Node
+  // objects/functions are injected. Only strings and JSON cross the boundary.
+  const allowed = new Set        ();
+  function allow(name        ) { if (allowed.has(name)) return; allowed.add(name); for (const dep of data.dependencies[name] || []) allow(dep); }
+  if (entry) allow(entry);
+  for (const item of chain) if (item.source !== undefined) allow(item.source);
+  const runtime = engine.newRuntime();
+  runtime.setMemoryLimit(32 * 1024 * 1024);
+  runtime.setMaxStackSize(512 * 1024);
+  const deadline = Date.now() + timeoutMs;
+  runtime.setInterruptHandler(() => Date.now() >= deadline);
+  runtime.setModuleLoader(moduleName => {
+    const source = data.sources[moduleName];
+    if (!allowed.has(moduleName) || source === undefined) throw new Error('Module denied');
+    return source;
+  }, (base, requested) => {
+    const resolved = requested.startsWith('./') || requested.startsWith('../') ? posix.resolve(posix.dirname(base),requested) : requested;
+    if (!allowed.has(resolved)) throw new Error('Module denied');
+    return resolved;
+  });
+  const vm = runtime.newContext();
+  function run(code        , filename = 'bootstrap.js', type                      = 'global') {
+    const result = vm.evalCode(code,filename,{type});
+    if (result.error) { result.error.dispose(); throw new Error('Guest evaluation failed'); }
+    result.value.dispose();
+  }
+  function string(name        )         {
+    const handle                = vm.getProp(vm.global,name);
+    try { return vm.getString(handle); } finally { handle.dispose(); }
+  }
+  try {
+    run(guestBootstrap);
+    if (payload !== undefined) {
+      const value = vm.newString(payload); vm.setProp(vm.global,'__payload',value); value.dispose();
+    }
+    if (chain.length) {
+      const imports = chain.map((item,i) => `import * as mw${i} from ${JSON.stringify(item.source)};`).join('\n');
+      const functions = chain.map((item,i) => `mw${i}[${JSON.stringify(item.name)}]`).join(',');
+      run(`${imports}
+        ${entry ? `import * as entry from ${JSON.stringify(entry)};` : ''}
+        globalThis.__invokePipeline([${functions}], ${entry ? `entry[${JSON.stringify(name)}]` : 'null'}, globalThis.__payload);`,
+      '/__urlcode_entry.mjs','module');
+    } else {
+      run(`import * as entry from ${JSON.stringify(entry)};
+        if (typeof entry[${JSON.stringify(name)}] !== 'function') throw new Error('Invalid export');
+        ${payload === undefined ? "globalThis.__state = 'done';" : `globalThis.__invoke(entry[${JSON.stringify(name)}], globalThis.__payload);`}`,
+      '/__urlcode_entry.mjs','module');
+    }
+    while (string('__state') === 'pending') {
+      if (Date.now() >= deadline) throw new Error('Guest deadline exceeded');
+      const jobs = runtime.executePendingJobs(100);
+      if (jobs.error) { jobs.error.dispose(); throw new Error('Guest promise failed'); }
+      run('globalThis.__pump()');
+      if (string('__state') === 'pending') await new Promise(resolve => setTimeout(resolve,2));
+    }
+    if (string('__state') !== 'done') throw new Error('Guest invocation failed');
+    return payload === undefined ? undefined : string('__output');
+  } finally { vm.dispose(); runtime.dispose(); }
+}
+try {
+  for (const [source,name] of data.entries) await evaluate(source,name);
+  post({ready:true});
+} catch { post({startupError:true}); }
+const isPair = (pair         )                           => Array.isArray(pair) && pair.length === 2 && pair.every(v => typeof v === 'string');
+port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,chain=[],native}                       ) => { // trust boundary: posted by FunctionPool.execute
+  try {
+    const payload = JSON.stringify({request:{...request,body:Buffer.from(request.body || []).toString('utf8')},context,native});
+    if (Buffer.byteLength(payload) > 4 * 1024 * 1024) throw new Error('Input limit');
+    const output = await evaluate(source,name,payload,timeoutMs,chain);
+    if (output === undefined || Buffer.byteLength(output) > maxBytes * 6 + 65536) throw new Error('Output limit');
+    const value = JSON.parse(output)                               ; // trust boundary: guest JSON, checked below
+    if (!value || !Number.isInteger(value.status) || value.status < 200 || value.status > 599 || typeof value.body !== 'string' || !Array.isArray(value.headers) || value.headers.length > 256) throw new Error('Invalid response');
+    if (value.nativeBody) {
+      if (!native || value.status !== native.status || value.body !== '') throw new Error('Invalid native response');
+      // Preserve native status and metadata (validators, ranges, redirect Location).
+      for (const key of new Set(native.headers.map(([k]) => k.toLowerCase()))) {
+        const originals = native.headers.filter(([k]) => k.toLowerCase() === key).map(([,v])=>v);
+        const output = (value.headers             ).flatMap(pair => Array.isArray(pair) && typeof pair[0] === 'string' && pair[0].toLowerCase() === key ? [pair[1]           ] : []);
+        if (JSON.stringify(originals) !== JSON.stringify(output)) throw new Error('Native metadata changed');
+      }
+    }
+    const body = Buffer.from(value.body,'utf8');
+    if (body.length > maxBytes) throw new Error('Response limit');
+    let bytes = 0;
+    for (const pair of value.headers             ) {
+      if (!isPair(pair)) throw new Error('Invalid headers');
+      bytes += Buffer.byteLength(pair[0]) + Buffer.byteLength(pair[1]) + 4;
+    }
+    if (bytes > 16384) throw new Error('Header limit');
+    post({id,status:value.status,headers:value.headers,body,nativeBody:value.nativeBody === true});
+  } catch { post({id,error:true}); }
+});

package/dist/functions.js

@@ -0,0 +1,174 @@
+import { Worker } from 'node:worker_threads';
+import { randomUUID } from 'node:crypto';
+import { collectFunctionSources, routeFunctions } from './function-sources.js';
+                                                                            
+import { assert, ConfigError, HttpError } from './errors.js';
+                                                                    
+                                                                 
+                                        
+                                                          
+                                                                               
+                                                                                
+                                      
+                                                                                                  
+                                                                                         
+ 
+
+// The worker protocol. Only JSON-shaped data and byte buffers cross it.
+                                                                                                                                            
+                                                                                         
+                                        
+                                                                   
+                                                        
+                                                                
+                                                                                              
+ 
+                                                                              
+                                   
+                                            
+                                                                                                
+                                
+
+                                                                                                                                   
+                                                                          
+
+export class FunctionPool {
+  root                    ; routes                 ; preparedSnapshot                             ; snapshot                             ;
+  restarts                     ; restartTimers                     ; log       ; timeoutMs        ; maxBytes        ;
+  modules                      ; size        ; slots                      ; closed         ;
+  constructor(routes                 , { root, snapshot, workers = 2, timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                      = {}) {
+    assert(Number.isInteger(workers) && workers >= 1 && workers <= 32, 'Workers must be 1–32');
+    assert(Number.isInteger(timeoutMs) && timeoutMs >= 10 && timeoutMs <= 60000, 'Function timeout must be 10–60000 ms');
+    assert(Number.isInteger(maxBytes) && maxBytes >= 1 && maxBytes <= 16777216, 'Response limit must be 1–16777216 bytes');
+    this.root = root; this.routes = routes; this.preparedSnapshot = snapshot;
+    // Consecutive replacement attempts per slot; cleared by a completed invocation.
+    this.restarts = new Map(); this.restartTimers = new Set();
+    this.log = log;
+    this.timeoutMs = timeoutMs; this.maxBytes = maxBytes;
+    const modules = new Map                     ();
+    for (const definition of routes.flatMap(routeFunctions)) {
+      const { source, export: name } = definition;
+      let names = modules.get(source);
+      if (!names) { names = new Set(); modules.set(source, names); }
+      names.add(name);
+    }
+    this.modules = [...modules].map(([source, names]) => [source, [...names]]);
+    this.size = this.modules.length ? workers : 0;
+    this.slots = []; this.closed = false;
+  }
+  async start()                {
+    let snapshot = this.preparedSnapshot;
+    if (!snapshot && this.size) { assert(this.root !== undefined, 'Function pool requires a project root'); snapshot = await collectFunctionSources(this.routes,this.root); }
+    snapshot ??= {sources:{},dependencies:{},entries:[],names:new Map()};
+    this.snapshot = snapshot;
+    try { await Promise.all(Array.from({ length: this.size }, (_, i) => this.spawn(i))); }
+    catch { await this.close(); throw new ConfigError('Function initialization failed (check module syntax, imports and exports)'); }
+    return this;
+  }
+  spawn(index        )                {
+    return new Promise((resolve, reject) => {
+      if (this.closed) return reject(new Error('Pool closed'));
+      const snapshot = this.snapshot;
+      assert(snapshot, 'Pool not started');
+      // The WASM guest is the capability boundary. The outer worker supplies
+      // an independent termination deadline if the guest engine stops responding.
+      const workerData                     = { sources:snapshot.sources, dependencies:snapshot.dependencies, entries:snapshot.entries };
+      const worker = new Worker(new URL('./function-worker.js', import.meta.url), {
+        env: {}, execArgv: [],
+        workerData, stdout: true, stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: 128, stackSizeMb: 4 },
+      });
+      worker.stdout.resume(); worker.stderr.resume(); // Engine diagnostics must not expose guest data.
+      const slot       = { worker, ready: false, pending: null };
+      this.slots[index] = slot;
+      let initialized = false;
+      const timer = setTimeout(() => fail(), 5000);
+      const fail = () => {
+        clearTimeout(timer);
+        slot.ready = false;
+        if (!initialized) reject(new Error('Worker initialization failed'));
+        if (slot.pending) {
+          clearTimeout(slot.pending.timer);
+          slot.pending.reject(new HttpError(502, 'Function execution failed'));
+          slot.pending = null;
+        }
+        void worker.terminate();
+      };
+      worker.on('message', (message                       ) => { // trust boundary: the worker's own protocol
+        if ('ready' in message && !initialized) {
+          this.report('started', index);
+          initialized = true; clearTimeout(timer); slot.ready = true; resolve(); return;
+        }
+        if ('startupError' in message) { fail(); return; }
+        if (!('id' in message)) return;
+        const pending = slot.pending;
+        if (!pending || pending.id !== message.id) return;
+        // Any answered invocation, success or guest error, proves this worker is
+        // serving again; a worker that starts cleanly but dies on every request
+        // must keep backing off rather than restarting in a tight loop.
+        this.restarts.delete(index);
+        clearTimeout(pending.timer); slot.pending = null;
+        if ('error' in message) pending.reject(new HttpError(502, 'Function execution failed'));
+        else pending.resolve(message);
+      });
+      worker.on('error', fail);
+      worker.on('exit', () => {
+        fail();
+        if (initialized && !this.closed && this.slots[index] === slot) this.scheduleRespawn(index);
+      });
+    });
+  }
+  report(status        , index        , extra         = {})       {
+    try { this.log({ event: 'function_worker', status, slot: index, ...extra }); } catch { /* Logging cannot fail the pool. */ }
+  }
+  // A worker exit must never latch a slot off permanently: a deadline or an
+  // out-of-memory guest is reachable from ordinary request input, so replacement
+  // backs off instead of stopping. Backoff bounds churn; it does not stop it.
+  scheduleRespawn(index        )       {
+    if (this.closed) return;
+    const attempt = (this.restarts.get(index) || 0) + 1;
+    this.restarts.set(index, attempt);
+    const delayMs = Math.min(30000, 250 * 2 ** Math.min(attempt - 1, 7));
+    this.report('restarting', index, { attempt, delayMs });
+    const timer = setTimeout(() => {
+      this.restartTimers.delete(timer);
+      if (this.closed) return;
+      void this.spawn(index).catch(() => this.scheduleRespawn(index));
+    }, delayMs);
+    timer.unref(); this.restartTimers.add(timer);
+  }
+  get healthy()          { return !this.closed && this.slots.length === this.size && this.slots.every(slot => slot?.ready); }
+  execute(route               , request                     , context                 , native                           )                          {
+    const slot = this.slots.find(s => s?.ready && !s.pending);
+    const snapshot = this.snapshot;
+    if (this.closed || !slot || !snapshot) return Promise.reject(new HttpError(503, 'Function capacity unavailable'));
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        slot.pending = null; slot.ready = false;
+        reject(new HttpError(504, 'Function deadline exceeded'));
+        void slot.worker.terminate();
+      }, this.timeoutMs);
+      slot.pending = { id, timer, resolve: message => {
+        // Native bytes never enter the guest; only this invocation's body can be retained.
+        if (message.nativeBody && native) resolve({...message,body:native.body,...(native.contentLength === undefined ? {} : {contentLength:native.contentLength})});
+        else resolve(message);
+      }, reject };
+      const message                        = { id, source: route.function ? snapshot.names.get(route.function.source) : undefined, name: route.function?.export,
+        chain: (route.middleware || []).map(item => ({source:snapshot.names.get(item.source),name:item.export})),
+        native: native ? {status:native.status,headers:native.headers} : undefined,
+        request, context, maxBytes: this.maxBytes, timeoutMs:this.timeoutMs + 100 };
+      slot.worker.postMessage(message);
+    });
+  }
+  async close()                {
+    this.closed = true;
+    for (const timer of this.restartTimers) clearTimeout(timer);
+    this.restartTimers.clear();
+    for (const slot of this.slots) if (slot?.pending) {
+      clearTimeout(slot.pending.timer);
+      slot.pending.reject(new HttpError(503, 'Runtime shutting down')); slot.pending = null;
+    }
+    await Promise.all(this.slots.map(s => s?.worker.terminate()));
+  }
+}

package/dist/guest-api.js

@@ -0,0 +1,114 @@
+                                                     
+// The JSON that crosses the guest boundary, in both directions. Only strings
+// cross it; function-worker.ts stringifies the request and checks the
+// response's shape before trusting it.
+/** The request the guest receives (stringified as JSON in the worker). */
+                                                                                                                          
+/** What the guest returns as JSON text; the worker enforces this shape before trusting it. */
+                                                                                                                   
+// Runs only inside QuickJS/WASM. No native host functions or objects are exposed.
+// This is the documented text/JSON subset, not a complete Fetch implementation.
+export const guestBootstrap = String.raw`
+(() => {
+  const NativeJSON = JSON;
+  const stringify = JSON.stringify.bind(JSON);
+  const now = Date.now.bind(Date);
+  const timers = new Map(); let next = 1;
+  globalThis.setTimeout = (fn, delay = 0) => {
+    if (typeof fn !== 'function' || timers.size >= 128) throw new Error('Timer limit');
+    const id = next++; timers.set(id, {fn, at:now() + Math.max(0, Number(delay) || 0)}); return id;
+  };
+  globalThis.clearTimeout = id => timers.delete(id);
+  globalThis.__pump = () => {
+    for (const [id,timer] of timers) if (timer.at <= now()) { timers.delete(id); timer.fn(); }
+  };
+  globalThis.console = Object.freeze({log(){},error(){},warn(){},info(){},debug(){}});
+  class Headers {
+    constructor(init = []) {
+      this._pairs = [];
+      for (const [k,v] of init instanceof Headers ? init._pairs : Array.isArray(init) ? init : Object.entries(init)) this.append(k,v);
+    }
+    append(key,value) {
+      key = String(key).toLowerCase(); value = String(value).trim();
+      if (!/^[!#$%&'*+.^_\x60|~0-9a-z-]+$/.test(key) || /[\r\n\0]/.test(value)) throw new TypeError('Invalid header');
+      this._pairs.push([key,value]);
+    }
+    set(key,value) { this.delete(key); this.append(key,value); }
+    delete(key) { this._pairs = this._pairs.filter(p => p[0] !== String(key).toLowerCase()); }
+    get(key) { const values = this._pairs.filter(p=>p[0]===String(key).toLowerCase()).map(p=>p[1]); return values.length ? values.join(', ') : null; }
+    has(key) { return this.get(key) !== null; }
+    getSetCookie() { return this._pairs.filter(p=>p[0]==='set-cookie').map(p=>p[1]); }
+    *entries() { const keys = new Set(this._pairs.map(p=>p[0])); for (const key of keys) yield [key,this.get(key)]; }
+    [Symbol.iterator]() { return this.entries(); }
+  }
+  class Request {
+    constructor(url, init = {}) {
+      this.url = String(url); this.method = init.method || 'GET'; this.headers = new Headers(init.headers);
+      this._text = init.body || ''; this.bodyUsed = false;
+    }
+    async text() { if (this.bodyUsed) throw new TypeError('Body already read'); this.bodyUsed = true; return this._text; }
+    async json() { return NativeJSON.parse(await this.text()); }
+  }
+  class Response {
+    constructor(body = null, init = {}) {
+      if (body !== null && typeof body !== 'string') throw new TypeError('Only text/JSON bodies are supported');
+      this.status = init.status ?? 200;
+      if (!Number.isInteger(this.status) || this.status < 200 || this.status > 599) throw new TypeError('Invalid status');
+      if ([204,205,304].includes(this.status) && body !== null && body !== '') throw new TypeError('Null-body status');
+      this.headers = new Headers(init.headers);
+      this._text = body || ''; this.bodyUsed = false; this.ok = this.status >= 200 && this.status < 300;
+      if (body !== null && !this.headers.has('content-type')) this.headers.set('content-type','text/plain;charset=UTF-8');
+    }
+    async text() { if (this.bodyUsed) throw new TypeError('Body already read'); this.bodyUsed = true; return this._text; }
+    async json() { return NativeJSON.parse(await this.text()); }
+    static json(value, init = {}) { const headers = new Headers(init.headers); if (!headers.has('content-type')) headers.set('content-type','application/json'); return new Response(stringify(value), {...init,headers}); }
+    static redirect(url, status = 302) { if (![301,302,303,307,308].includes(status)) throw new TypeError('Invalid redirect status'); return new Response(null,{status,headers:{location:String(url)}}); }
+  }
+  globalThis.Headers = Headers; globalThis.Request = Request; globalThis.Response = Response;
+  globalThis.__invokePipeline = async (middleware, handler, payload) => {
+    try {
+      const input = NativeJSON.parse(payload);
+      const request = new Request(input.request.url, input.request);
+      const context = input.context; context.state = {};
+      let nativeResponse;
+      if (input.native) {
+        nativeResponse = new Response(null,input.native);
+        nativeResponse.text = nativeResponse.json = async () => { throw new TypeError('Native body is opaque; return a new Response to replace it'); };
+      }
+      let violated = false;
+      async function dispatch(index) {
+        if (index === middleware.length) return handler ? await handler(request,context) : nativeResponse;
+        let called = false, open = true, pending;
+        const next = (...args) => {
+          if (args.length || called || !open) { violated = true; throw new TypeError('next may be called once during middleware'); }
+          called = true; pending = dispatch(index+1); return pending;
+        };
+        try {
+          const response = await middleware[index](request,context,next);
+          // Drain downstream work under the same deadline even if the caller forgot await.
+          if (pending) await pending.catch(() => {});
+          if (!(response instanceof Response)) throw new TypeError('Middleware must return a Response');
+          return response;
+        } finally { open = false; }
+      }
+      const response = await dispatch(0);
+      if (violated || !(response instanceof Response)) throw new TypeError('Invalid middleware response');
+      const nativeBody = response === nativeResponse;
+      globalThis.__output = stringify({status:response.status,headers:response.headers._pairs,
+        body:nativeBody || input.request.method === 'HEAD' ? '' : response._text,nativeBody});
+      globalThis.__state = 'done';
+    } catch { globalThis.__state = 'failed'; }
+  };
+  globalThis.__state = 'pending'; globalThis.__output = '';
+  globalThis.__invoke = async (handler, payload) => {
+    try {
+      const input = NativeJSON.parse(payload);
+      const response = await handler(new Request(input.request.url, input.request), input.context);
+      if (!(response instanceof Response)) throw new TypeError('Return a Response');
+      const headers = response.headers._pairs;
+      globalThis.__output = stringify({status:response.status,headers,body: input.request.method === 'HEAD' ? '' : response._text});
+      globalThis.__state = 'done';
+    } catch { globalThis.__state = 'failed'; }
+  };
+})();
+`;

package/dist/header-validation.js

@@ -0,0 +1,18 @@
+// Header validation with no Node dependency, so one response policy runs on a
+// Node server, a provider adapter and a Web-standard runtime. The rules are
+// Node's: a name is an RFC 7230 token, and a value carries no control
+// characters. test/header-validation.test.ts compares this against node:http
+// across a wide input range, because disagreeing here is header injection.
+const token = /^[\^`\-\w!#$%&'*+.|~]+$/;
+const invalidValue = /[^\t -~€-ÿ]/;
+
+export function validateHeaderName(name         )                         {
+  if (typeof name !== 'string' || !token.test(name)) {
+    throw new TypeError(`Invalid header name: ${String(name)}`);
+  }
+}
+
+export function validateHeaderValue(name        , value         )       {
+  if (value === undefined) throw new TypeError(`Invalid value "undefined" for header "${name}"`);
+  if (invalidValue.test(String(value))) throw new TypeError(`Invalid character in header content ["${name}"]`);
+}