@jimhoyd/urlcode 0.3.0

package/dist/router.js

@@ -0,0 +1,166 @@
+import { setImmediate as yieldTurn } from 'node:timers/promises';
+import { compileHttp } from './http-policy.js';
+import Ajv from 'ajv/dist/2020.js';
+import { assert } from './errors.js';
+import { functionFile } from './config.js';
+import { parameterName } from './match.js';
+                                                                                       
+                                                                                                                      
+// Re-exported so existing importers keep one entry point for routing.
+export { parseTarget, matchRoute, contextFor, resolveValue, redirectLocation } from './match.js';
+
+/** The grants compileRoutes consults: a validated OperatorPolicy (policy.ts) or nothing, which denies every binding. */
+                                                                                                                               
+                                               
+                                                    
+
+const methodsDefault = ['GET', 'HEAD'];
+const token = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const own = (obj        , key        )          => Object.hasOwn(obj, key);
+const dict = ()                         => Object.create(null)                          ;
+function inputValidator(schema                 , ajv             , validators                        )            {
+  const { default: _default, ...shape } = schema;
+  const key = JSON.stringify(shape);
+  if (!validators.has(key)) {
+    assert(validators.size < 1024, 'Maximum 1024 distinct input schemas per snapshot');
+    validators.set(key, ajv.compile(shape));
+  }
+  return validators.get(key) ;
+}
+function segments(pattern        )           {
+  assert(pattern.startsWith('/') && !/[?#%\\\s\u0000-\u001f\u007f]/u.test(pattern), 'Route must be a literal absolute path with optional whole-segment {parameters}');
+  const parts = pattern.split('/').slice(1);
+  assert(parts.length <= 32 && pattern.length <= 2048, 'Route exceeds path limits');
+  for (const part of parts) {
+    assert(part !== '.' && part !== '..', 'Dot path segments are unsupported');
+    if (part.includes('{') || part.includes('}')) assert(/^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(part), 'Invalid route parameter');
+  }
+  return parts;
+}
+function referenceCheck(ref                               , route               , allowBindings = false)       {
+  if (typeof ref !== 'object' || ref === null) return;
+  if (ref.from) assert(route.parameters.some(p => p.in === ref.from && p.name === (ref.from === 'header' ? ref.name .toLowerCase() : ref.name)), 'Reference uses undeclared input');
+  else if (ref.env && allowBindings) assert(own(route.env, ref.env), 'Reference uses undeclared environment alias');
+  else if (ref.secret && allowBindings) assert(own(route.secrets, ref.secret), 'Reference uses undeclared secret alias');
+  else assert(false, 'Invalid argument reference');
+}
+// A declared `pass: false` reads as no passthrough, the same as leaving it
+// out; dropping the key is what gives match.ts its RedirectSpec.
+function compiledRedirect(redirect                )                   {
+  if (redirect.query?.pass !== false) return redirect                    ; // pass is string[] | undefined here; TypeScript cannot narrow through the optional query
+  const { pass: _pass, ...query } = redirect.query;
+  return { ...redirect, query };
+}
+export async function compileRoutes(loaded                , bindings                                    , permissions                     = {}, projectSha256         )                              {
+  const deadline=performance.now()+10000;
+  let processed=0;
+  const exact = new Map                       (), dynamic                  = [], mounts                  = [], modules = new Map              ();
+  // 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 ajv = new Ajv.default({ strict: false, allErrors: false }), validators = new Map                   ();
+  for (const [pattern, config] of Object.entries(loaded.routes)) {
+    if (++processed % 64 === 0) await yieldTurn();
+    assert(performance.now()<deadline, 'Route compilation deadline exceeded');
+    const parts = segments(pattern);
+    assert(!pattern.startsWith('/_urlcode'), 'The /_urlcode prefix is reserved for runtime operations');
+    const names = parts.map(parameterName).filter((name)                 => Boolean(name));
+    assert(!pattern.includes('*') || (config.static && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static routes support a terminal /* wildcard');
+    assert(!config.static || pattern.endsWith('/*'), 'Static routes require a terminal /* wildcard');
+    if (config.page || config.download || config.static) assert((config.methods || methodsDefault).every(m => methodsDefault.includes(m)), 'Asset routes support only GET and HEAD');
+    assert(new Set(names).size === names.length, 'Duplicate path parameter');
+    // `redirect` and `function` are re-attached below in their compiled shape.
+    const { redirect: declaredRedirect, function: declaredFunction, ...declared } = config;
+    const route                = { ...declared, pattern, parts, names, specificity: parts.length - names.length,
+      methods: config.methods || methodsDefault, parameters: [], env: dict(), secrets: dict(), responseHeaders: [], middleware: [] };
+    compileHttp(route);
+    const seen = new Set        ();
+    for (const param of config.parameters || []) {
+      const schema = param.schema, name = param.in === 'header' ? param.name.toLowerCase() : param.name;
+      assert(!seen.has(`${param.in}:${name}`), 'Duplicate parameter declaration');
+      seen.add(`${param.in}:${name}`);
+      assert(param.in !== 'path' || (names.includes(name) && param.required === true && schema.type === 'string'), 'Path parameters must be declared required strings');
+      assert(schema.type !== 'array' || (param.in === 'query' && schema.items), 'Only query arrays with scalar items are supported');
+      assert(schema.type === 'array' || !schema.items, 'items requires array input');
+      assert(param.in !== 'path' || !own(schema, 'default'), 'Path parameters cannot have defaults');
+      assert(!['minLength','maxLength'].some(k => own(schema,k)) || schema.type === 'string', 'String bounds require string type');
+      assert(!['minimum','maximum'].some(k => own(schema,k)) || ['integer','number'].includes(schema.type), 'Numeric bounds require numeric type');
+      assert(!own(schema,'maxItems') || schema.type === 'array', 'maxItems requires array type');
+      const p                    = { ...param, name, required: param.required === true, validate: inputValidator(schema, ajv, validators) };
+      if (own(schema, 'default')) assert(p.validate(schema.default), 'Invalid parameter default');
+      route.parameters.push(p);
+    }
+    assert(names.every(name => route.parameters.some(p => p.in === 'path' && p.name === name)), 'Every path placeholder requires an input declaration');
+    for (const [alias, ref] of Object.entries(config.env || {})) {
+      if (ref.env) assert(permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.env?.includes(ref.env), 'Environment binding denied by operator policy');
+      const value = own(ref, 'value') ? ref.value : bindings[ref.env ];
+      assert(typeof value === 'string', 'Missing required environment binding');
+      route.env[alias] = value;
+    }
+    for (const [alias, ref] of Object.entries(config.secrets || {})) {
+      assert(permissions.projectSha256 === projectSha256 && permissions.routes?.[pattern]?.secrets?.includes(ref.secret), 'Secret binding denied by operator policy');
+      const value = bindings[ref.secret];
+      assert(typeof value === 'string' && value.length, 'Missing required secret binding');
+      route.secrets[alias] = value;
+    }
+    if (config.expires) {
+      assert(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(config.expires) && Number.isFinite(Date.parse(config.expires)), 'Expiry must be a UTC ISO timestamp');
+      route.expiresAt = Date.parse(config.expires);
+      assert(new Date(route.expiresAt).toISOString().replace('.000Z','Z') === config.expires.replace('.000Z','Z'), 'Invalid calendar expiry');
+    }
+    if (declaredRedirect) {
+      const value = declaredRedirect.url;
+      assert(!/[\u0000-\u0020\u007f\\]/u.test(value), 'Redirect URL contains unsafe characters');
+      let dest     ;
+      try { dest = new URL(value); } catch { assert(false, 'Redirect URL must be absolute HTTP(S)'); }
+      assert(['http:', 'https:'].includes(dest.protocol) && !dest.username && !dest.password, 'Redirect must use HTTP(S) without credentials');
+      const authority = value.match(/^https?:\/\/([^/?#]+)/i)?.[1];
+      assert(authority && !/[{}]/.test(authority) && !/[{}]/.test(dest.search + dest.hash), 'Redirect placeholders are allowed only in path segments');
+      const placeholders = [...value.matchAll(/\{([^}]+)\}/g)].map(m => m[1] );
+      assert(placeholders.every(n => token.test(n) && names.includes(n)), 'Redirect placeholder must reference a declared path input');
+      assert(!/[{}]/.test(value.replace(/\{[A-Za-z_][A-Za-z0-9_]*\}/g, '')), 'Invalid redirect placeholder');
+      const query = declaredRedirect.query || {};
+      const reserved = new Set(dest.searchParams.keys());
+      for (const [key, ref] of Object.entries(query.map || {})) {
+        assert(!reserved.has(key), 'Redirect query mapping conflicts with destination');
+        reserved.add(key); referenceCheck(ref, route);
+      }
+      for (const key of query.pass || []) assert(!reserved.has(key), 'Query passthrough conflicts with destination or mapping');
+      route.redirect = compiledRedirect(declaredRedirect);
+    }
+    if (config.link) {
+      assert(route.methods.every(method => methodsDefault.includes(method)), 'Stored links support only GET and HEAD');
+      referenceCheck(config.link.code,route);
+    }
+    for (const item of config.middleware || []) {
+      const source = await functionFile(loaded.root,item.source);
+      modules.set(source,true);
+      route.middleware.push({source,export:item.export || 'default'});
+    }
+    if (declaredFunction) {
+      const source = await functionFile(loaded.root, declaredFunction.source);
+      modules.set(source, true);
+      route.function = { ...declaredFunction, source, export: declaredFunction.export || 'default' };
+      for (const ref of Object.values(declaredFunction.args || {})) referenceCheck(ref, route, true);
+    }
+    if (config.static) { route.prefix = pattern.slice(0, -1); mounts.push(route); }
+    else if (!names.length) exact.set(pattern, route);
+    else {
+      assert(dynamic.length < 1000, 'Maximum 1000 parameterized routes per snapshot');
+      for (const existing of dynamic) {
+        if (existing.parts.length === parts.length && existing.specificity === route.specificity) {
+          assert(!parts.every((p, i) => p === existing.parts[i] || parameterName(p) || parameterName(existing.parts[i] )), 'Equally specific parameterized routes overlap');
+        }
+      }
+      dynamic.push(route);
+    }
+  }
+  dynamic.sort((a, b) => b.specificity - a.specificity);
+  // Index parameter routes by segment count; exact paths take the O(1) fast path.
+  const byLength = new Map                         ();
+  for (const route of dynamic) {
+    if (!byLength.has(route.parts.length)) byLength.set(route.parts.length, []);
+    byLength.get(route.parts.length) .push(route);
+  }
+  mounts.sort((a,b) => b.prefix .length - a.prefix .length);
+  assert(performance.now()<deadline, 'Route compilation deadline exceeded');
+  return { exact, byLength, mounts, modules: [...modules.keys()], count: exact.size + dynamic.length + mounts.length };
+}

package/dist/runtime.js

@@ -0,0 +1,244 @@
+import { projectPlan, hasRedirect } from './readiness.js';
+                                                  
+import { checkRequest, decorateResponse } from './http-policy.js';
+import { compileAssets, assetResponse } from './assets.js';
+import { loadDocument, loadBindings } from './config.js';
+import { compileRoutes, parseTarget, matchRoute, contextFor, resolveValue, redirectLocation } from './router.js';
+import { FunctionPool } from './functions.js';
+                                                      
+import { prepareFunctionSnapshot, validatePolicy } from './policy.js';
+                                                  
+import {openLinkStore} from './link-store.js';
+                                                                
+import {linkCode,linkData,linkCollection} from './link-records.js';
+import {assert} from './errors.js';
+import { HttpError } from './errors.js';
+import { compilePolicies, closePolicies, policyRequest, compileErrorPolicy, errorHeaders } from './policies.js';
+import { validatePlugins, activatePlugins, pluginsRequest, pluginsResponse, pluginsError, closePlugins } from './plugins.js';
+                                           
+import { createObserverSink } from './observability.js';
+                                                                                  
+import { applySite } from './site.js';
+                                                                    
+                                                                                                                                                 
+                                                            
+
+/** A stored link as a link store returns it; the runtime validates the fields it uses. */
+                                                                                                     
+/** What a `linkStores` binding must provide: a reader and, optionally, its health. */
+                                                                                                                                                                         
+/** An operator-owned SQLite link store the runtime opens read-only for one collection. */
+                                                                                 
+                                                  
+/** An operator plugin (src/plugins.ts). */
+                                
+                                                                    
+                                                                                                                  
+                                 
+                                                                                                                        
+                                                                                        
+                                                                                                
+                                                                      
+                                                                                              
+ 
+/** Per-request facts the host may read after handle() settles; never request text. */
+                                                                                      
+                                                                                                           
+                                 
+                                                                                                            
+                                                                                                                                                
+ 
+                          
+                                                                                                
+                       
+                                                        
+                                                       
+                             
+                                                             
+                                                   
+                                                          
+                         
+ 
+export async function createRuntime(project        , rawOptions                 = {})                   {
+  // Observers see every event this runtime emits; the operator's log stays
+  // the default sink. A server passes none down: it owns its own sink and
+  // counters, which survive the runtimes it replaces on reload.
+  const { observers, ...options } = rawOptions;
+  const sink               = createObserverSink(observers, options.log);
+  options.log = sink;
+  const loaded = await loadDocument(project);
+  // Site conventions become ordinary routes before compilation; a declared
+  // route at the same path wins. The public origin, when the server knows
+  // it, is what absolute URLs in generated files are built from.
+  await applySite(loaded, { origin: options.origin, log: options.log });
+  const dynamicLinks=loaded.document.dynamicLinks===true;
+  assert(dynamicLinks || (!options.linkStore && !Object.keys(options.linkStores||{}).length),'Link-store bindings require dynamicLinks: true in urlcode.yaml');
+  const bindings = await loadBindings(loaded.root, options.local, options.environment);
+  const snapshot = await prepareFunctionSnapshot(loaded);
+  if (options.permissions) validatePolicy(options.permissions);
+  const compiled                     = await compileRoutes(loaded, bindings, options.permissions, snapshot.projectSha256);
+  const routes = [...compiled.mounts, ...compiled.exact.values(), ...[...compiled.byLength.values()].flat()];
+  const assets = await compileAssets(loaded.root, routes);
+  // Host policies compile after assets so a policy can see what a route serves
+  // (precompressed variants, cacheability). Cross-request state lives in one
+  // per-runtime object and is released with the runtime, never shared across
+  // reloads: a new snapshot starts with empty counters and an empty cache.
+  const target = options.target || 'node';
+  const plugins = validatePlugins(options.plugins, target);
+  const shared               = { target, log: options.log, routes: routes.length };
+  const anyPolicy = Boolean(loaded.document.policies) || routes.some(route => route.policies);
+  for (const route of routes) route.policy = anyPolicy ? await compilePolicies(loaded.document, route, { route, shared, target, root: loaded.root }) : null;
+  const projectErrorPolicy                       = anyPolicy ? compileErrorPolicy(loaded.document, { target }) : null;
+  // Which route's policy an error belongs to, so its headers follow the route
+  // the request matched rather than the project default.
+  const errorRoutes = new WeakMap                            ();
+  const stores                             = Object.assign(Object.create(null)                              ,options.linkStores);
+  let ownedStore                       ;
+  try {
+    if(options.linkStore){
+      linkCollection(options.linkStore.collection);
+      assert(!Object.hasOwn(stores,options.linkStore.collection), 'Duplicate link store binding');
+      ownedStore=await openLinkStore({...options.linkStore,project:loaded.root,readOnly:true,log:options.log});
+      stores[options.linkStore.collection]=ownedStore;
+    }
+    for(const route of routes)if(route.link)assert(Object.hasOwn(stores,route.link.collection) && typeof stores[route.link.collection]?.get==='function','Missing operator link store binding');
+  }catch(error){await ownedStore?.close();throw error;}
+  let pool              ;
+  try{pool=await new FunctionPool(routes, { root:loaded.root, snapshot, log:options.log, workers:options.workers, timeoutMs:options.timeoutMs, maxBytes:options.maxBytes }).start();}
+  catch(error){await ownedStore?.close();throw error;}
+  let active = 0, closing = false, finish                          ;
+  // Response phase: cache store, throttle headers, security headers,
+  // compression, then operator plugins in reverse. A result produced by a
+  // request-phase policy skips that policy's own response hook (a cache hit
+  // is not stored twice) but still passes through the others (a hit still
+  // carries the client's rate-limit headers; a denial is not stored because
+  // its status is not cacheable). A plugin short-circuit ran before any
+  // policy, so it skips every request-phase policy's response hook.
+  async function finishPolicies(policy                                , request               , result               , producer                          )                         {
+    let out = result;
+    for (const [module, state] of policy?.response || []) {
+      if (producer === 'plugin' ? module.onRequest : module === producer) continue;
+      out = await module.onResponse?.(state, request, out) ?? out;
+    }
+    return pluginsResponse(plugins, request, out);
+  }
+  function policyInventory()                                  {
+    return Object.fromEntries(routes.flatMap(route => route.policy && Object.keys(route.policy.describe).length ? [[route.pattern, route.policy.describe]         ] : []));
+  }
+  const workers = () => ({ healthy: pool.slots.filter(slot => slot?.ready).length, slots: pool.size });
+  const testPlan = ()           => ({...projectPlan(compiled),dynamicLinks,policies:policyInventory()});
+  await activatePlugins(plugins, { testPlan, version: loaded.version + assets.digest, root: loaded.root, target });
+  return {
+    get healthy() { return !closing && pool.healthy && Object.values(stores).every(store=>(store.readHealthy??store.healthy)!==false); },
+    assetWatch: assets.watch, version: loaded.version + assets.digest, count: compiled.count, root: loaded.root,
+    testPlan,
+    get plugins() { return plugins.map(plugin => ({ name: plugin.name, version: plugin.version })); },
+    get workers() { return workers(); },
+    metrics() { const { healthy, slots } = workers(); const snapshot = sink.metrics.snapshot(); snapshot.functionWorkers.healthySlots = healthy; snapshot.functionWorkers.slots = slots; return snapshot; },
+    // Security headers for an error answer: the matched route's when handle()
+    // threw after matching, the project's otherwise (no match, or a host-side
+    // error such as an oversized body or shed admission).
+    errorHeaders(error, origin) {
+      const policy = error && typeof error === 'object' ? errorRoutes.get(error) : undefined;
+      return errorHeaders(policy === undefined ? projectErrorPolicy : policy?.security ?? null, origin);
+    },
+    requestLimit(target) {
+      const match = matchRoute(compiled, parseTarget(target));
+      return match?.route.request?.body?.maxBytes;
+    },
+    async handle({ target, method = 'GET', headers = new Headers(), body, headerCounts, trace = {}, origin = 'http://localhost', client }) {
+      if (closing) throw new HttpError(503, 'Runtime unavailable');
+      active++;
+      let policyReq                           , policy                                ;
+      try {
+        const parsed = parseTarget(target);
+        const match = matchRoute(compiled, parsed);
+        if (!match) throw new HttpError(404, 'Not found');
+        const { route, path } = match;
+        // Configured pattern only; never the request path, query or parameter values.
+        trace.route = route.pattern;
+        // Known from here on, so an error thrown by the route's own checks
+        // (disabled, expired) is answered with that route's security headers.
+        policy = route.policy;
+        if (route.enabled === false) throw new HttpError(404, 'Not found');
+        if (route.expiresAt && Date.now() >= route.expiresAt) throw new HttpError(410, 'Gone');
+        // Host policies and plugins run once the route is known and before
+        // its contract is checked: a denied agent or an exhausted budget is
+        // answered without reading a body or touching the sandbox.
+        if (policy || plugins.length) {
+          policyReq = policyRequest({ method, target, path: parsed.path, params: path, query: parsed.query, headers, headerCounts, client, origin, route });
+          trace.client = policyReq.client;
+          const early = await pluginsRequest(plugins, policyReq);
+          if (early) return await finishPolicies(policy, policyReq, early, 'plugin');
+          for (const [module, state] of policy?.request || []) {
+            const result = await module.onRequest?.(state, policyReq);
+            if (result) return await finishPolicies(policy, policyReq, result, module);
+          }
+        }
+        if (!route.methods.includes(method)) {
+          const refused                = { status: 405, headers: [['allow', route.methods.join(', ')]], body: Buffer.from('Method not allowed\n') };
+          // Counted by throttle already, so it carries the budget headers and
+          // the security profile like any other answer; nothing caches a 405.
+          return policyReq ? await finishPolicies(policy, policyReq, refused) : refused;
+        }
+        checkRequest(route, body || Buffer.alloc(0), headers, headerCounts);
+        const finishResponse = async (result               ) => policyReq ? finishPolicies(policy, policyReq, decorateResponse(route,result)) : decorateResponse(route,result);
+        const context                  = contextFor(route, path, parsed.query, headers, headerCounts);
+        let native                           ;
+        if (hasRedirect(route)) native = { status: route.redirect.status || 302,
+          headers: [['location', redirectLocation(route, context, parsed.query)]], body: Buffer.alloc(0) };
+        else if(route.link){
+          // Resolution outcome for a trusted post-response observer. It records
+          // why this request ended the way it did; the caller decides whether a
+          // finished response is ever reported, and never sees stored data.
+          const collection=route.link.collection;
+          const observed           =trace.link={collection,code:null,result:'invalid_code'};
+          let code        ;try{code=linkCode(resolveValue(route.link.code,context));}catch{throw new HttpError(404,'Link not found');}
+          observed.code=code;observed.result='missing';
+          let record                           ;
+          try{const store=stores[collection];assert(store,'Missing operator link store binding');record=await store.get(collection,code);}catch{observed.result='unavailable';throw new HttpError(503,'Link store unavailable');}
+          if(!record)throw new HttpError(404,'Link not found');
+          let data;try{data=linkData({url:record.url,status:record.status,enabled:record.enabled,expires:record.expires});}catch{observed.result='invalid_record';throw new HttpError(503,'Invalid stored link');}
+          if(!data.enabled){observed.result='disabled';throw new HttpError(404,'Link not found');}
+          if(data.expires && Date.parse(data.expires)<=Date.now()){observed.result='expired';throw new HttpError(410,'Link expired');}
+          observed.result='redirect';
+          native={status:data.status,headers:[['location',data.url],['cache-control','no-store']],body:Buffer.alloc(0)};
+        }
+        else if (route.reply) native = route.reply;
+        else if (route.asset) {
+          try { native = assetResponse(route, parsed.path, method, headers); }
+          catch (error) {
+            if (!route.middleware.length || !(error instanceof HttpError)) throw error;
+            native = {status:error.status,headers:[['content-type','text/plain; charset=utf-8'],['cache-control','no-store']],body:Buffer.from(error.message+'\n')};
+          }
+        }
+        if (native && !route.middleware.length) return finishResponse(native);
+        context.args = Object.fromEntries(Object.entries(route.function?.args || {}).map(([key, ref]) => [key, resolveValue(ref, context)]));
+        return finishResponse(await pool.execute(route, { url: origin + target, method, headers: [...headers], body }, context, native));
+      } catch (error) {
+        if (policy !== undefined && error && typeof error === 'object') errorRoutes.set(error, policy);
+        if (policyReq) {
+          // A policy may answer instead of the error (stale-if-error serving a
+          // stored copy); the first fallback wins and still passes through the
+          // response phase. Otherwise the hooks only observe.
+          for (const [module, state] of policy?.error || []) {
+            let fallback;
+            try { fallback = await module.onError?.(state, policyReq, error); } catch { /* an observer cannot change the outcome */ }
+            if (fallback) return await finishPolicies(policy, policyReq, fallback, module);
+          }
+          await pluginsError(plugins, policyReq, error);
+        }
+        throw error;
+      } finally { active--; if (!active && closing) finish?.(); }
+    },
+    async close() {
+      closing = true;
+      if (active) await new Promise      (resolve => { finish = resolve; });
+      await pool.close();
+      await ownedStore?.close();
+      await closePolicies(shared);
+      await closePlugins(plugins);
+      await sink.close();
+    },
+  };
+}

package/dist/scripts/operational-drills.js

@@ -0,0 +1,75 @@
+// Disposable local proof, never a claim about the production deployment.
+import assert from 'node:assert/strict';
+import {mkdtemp,mkdir,writeFile,copyFile,rm,statfs} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {DatabaseSync} from 'node:sqlite';
+import {openLinkStore} from '../link-store.js';
+import {startServer} from '../server.js';
+                                                    
+                                             
+import {HttpError} from '../errors.js';
+// The SQLite rows the drills inspect; node:sqlite returns untyped records.
+                                                                         
+                                                
+                                        
+                              
+// node:sqlite boundary: a single-row query, typed by the caller's expectation.
+const row=   (db              ,sql        )   =>{const r=db.prepare(sql).get();assert.ok(r,`${sql} returned no row`);return r                ;};
+const seconds=Number(process.env.URLCODE_SOAK_SECONDS||5);
+assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=3600,'Soak must be 1–3600 seconds');
+const directory=await mkdtemp(join(tmpdir(),'urlcode-drills-')),project=join(directory,'app');
+let store                     ,app                  ;
+try {
+ await mkdir(project);
+ const config='version: "1"\ndynamicLinks: true\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n  /live/{code}:\n    parameters:\n      - {name: code, in: path, required: true, schema: {type: string}}\n    link: {collection: links, code: {from: path, name: code}}\n';
+ await writeFile(join(project,'urlcode.yaml'),config);
+ await writeFile(join(project,'f.mjs'),'export default () => new Response("isolated");');
+ const file=join(directory,'links.sqlite');
+ store=await openLinkStore({file,project});let link=await store.create('links',{url:'https://example.com/live'},'demo');
+ app=await startServer({project,port:0,linkStore:{collection:'links',file},log:()=>{}});
+ const server=app;
+ const get=async(path        )=>{const r=await fetch(`http://127.0.0.1:${server.address.port}${path}`,{redirect:'manual'});const body=await r.text();return {status:r.status,location:r.headers.get('location'),body};};
+ const start=performance.now(),samples          =[];let requests=0;
+ while(performance.now()-start<seconds*1000){
+   const before=performance.now();const responses=await Promise.all(['/go','/function','/live/demo'].map(get));
+   assert.deepEqual(responses.map(r=>r.status),[302,200,302]);assert.equal(responses[1]?.body,'isolated');
+   assert.equal(responses[2]?.location,link.url);samples.push(performance.now()-before);requests+=3;
+   if(requests%30===0)link=await store.update('links','demo',{url:`https://example.com/live-${requests}`},link.version);
+ }
+ await writeFile(join(project,'urlcode.yaml'),'invalid: configuration');assert.equal(await app.reload(),false);assert.equal((await get('/go')).location,'https://example.com/v1');
+ await writeFile(join(project,'urlcode.yaml'),config.replace('/v1','/v2'));assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v2');
+ await writeFile(join(project,'urlcode.yaml'),config);assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v1');
+ await app.close();app=undefined;await store.close();store=undefined;
+ // A read-only connection may have been the last to close, leaving WAL frames.
+ // Quiesce all users, explicitly checkpoint, then close before copying.
+ const checkpointDb=new DatabaseSync(file);
+ try{const result=row               (checkpointDb,'PRAGMA wal_checkpoint(TRUNCATE)');assert.equal(result.busy,0);assert.equal(result.log,0);assert.equal(result.checkpointed,0);}finally{checkpointDb.close();}
+ const restoreStart=performance.now(),backup=join(directory,'restored.sqlite');await copyFile(file,backup);
+ store=await openLinkStore({file:backup,project,readOnly:true});assert.deepEqual(await store.get('links','demo'),link);
+ const db=new DatabaseSync(backup,{readOnly:true});assert.equal(row              (db,'PRAGMA integrity_check').integrity_check,'ok');assert.equal(row             (db,'SELECT max(revision) AS revision FROM urlcode_link_audit').revision,link.version);db.close();
+ samples.sort((a,b)=>a-b);
+ console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,restoreMs:performance.now()-restoreStart,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback','quiesced backup/restore including audit'],deploymentProof:false}));
+ await store.close();store=undefined;
+ // Only enable inside a disposable, size-limited mount (CI uses 16 MiB tmpfs).
+ if(process.argv[2]==='--disk-full-dir'){
+   const volume=resolve(process.argv[3] ?? '');const isolated=await mkdtemp(join(volume,'urlcode-full-'));
+   try {
+     const reserve=join(isolated,'reserve');await writeFile(reserve,Buffer.alloc(4*1024*1024));
+     const fullFile=join(isolated,'full.sqlite');store=await openLinkStore({file:fullFile,project});let full=false,committed=0;
+     for(let i=0;i<12000;i++){
+       try{await store.create('links',{url:'https://example.com/'+ 'x'.repeat(7000)},'code-'+i);committed++;}
+       catch(error){assert.ok(error instanceof HttpError,'store failure must be an HttpError');assert.equal(error.status,503);full=true;break;}
+     }
+     assert(full,'Disposable volume did not fill within the 84 MiB write budget');
+     const space=await statfs(isolated);assert(space.bavail*space.bsize<1024*1024,'Expected actual volume exhaustion');
+     await rm(reserve);await store.create('links',{url:'https://example.com/recovered'},'recovered');committed++;
+     await store.close();store=undefined;
+     const check=new DatabaseSync(fullFile,{readOnly:true});
+     assert.equal(row              (check,'PRAGMA integrity_check').integrity_check,'ok');
+     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_links').n,committed);
+     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_link_audit').n,committed);check.close();
+     console.log(JSON.stringify({event:'disposable-volume-exhaustion',committed,integrity:'ok',auditAtomic:true}));
+   }finally{await store?.close();store=undefined;await rm(isolated,{recursive:true,force:true});}
+ }
+} finally {await app?.close();await store?.close();await rm(directory,{recursive:true,force:true});}