@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/recipes.js

@@ -0,0 +1,41 @@
+import {fileURLToPath} from 'node:url';
+import {readAuthoringFile,publishAuthoringProject} from './authoring-files.js';
+import {validateDocument,parseYaml} from './config.js';
+import {readMetadata,searchMetadata} from './catalog.js';
+                                                            
+import {assert} from './errors.js';
+
+/** recipe.yaml, validated against schemas/recipe.schema.json; `name` repeats `id` and `files` is the copy list. */
+                                                                       
+                                                                                
+                                                                                                   
+                                                                                                                                     
+// This fixed local catalog is trusted package data, never an executable registry:
+// names come from here, metadata from each recipe's schema-checked recipe.yaml.
+export const recipeNames=['redirect','json-api','typescript','middleware','health-page','static-plus-api','cors-api','webhook-receiver','contact-form','authenticated-json-api','protected-download']         ;
+const recipesRoot=fileURLToPath(new URL('../recipes/',import.meta.url));
+const root=(name        )=>recipesRoot+name+'/';
+async function metadata(name        )                         {const value=await readMetadata(root(name),name,'recipe.yaml');return {name,...value};}
+export async function listRecipes()                           {
+  const result                 =[];
+  for(const name of recipeNames)result.push(await metadata(name));
+  return result;
+}
+function flatten(hits                            )                                {return hits.map(hit=>({...hit.entry,score:hit.score,matched:hit.matched}));}
+/** Matches id, description, tags and capabilities locally; no service is consulted. */
+export async function searchRecipes(text        )                              {
+  const hits=searchMetadata(await listRecipes(),text);
+  return {query:text,count:hits.length,results:flatten(hits)};
+}
+export async function showRecipe(name        )                  {
+  assert((recipeNames                     ).includes(name),'Unknown local recipe');
+  const summary=await metadata(name),content                       =Object.create(null)                         ;
+  for(const path of summary.files)content[path]=(await readAuthoringFile(root(name),path,1048576)).toString('utf8');
+  assert(content['urlcode.yaml'],'Recipe must copy urlcode.yaml');
+  validateDocument(parseYaml(content['urlcode.yaml']));
+  return {...summary,content};
+}
+export async function addRecipe(name        ,output        ,{dryRun=false}                              ={})                           {
+  const recipe=await showRecipe(name);
+  return {name,output:await publishAuthoringProject(output,new Map(Object.entries(recipe.content)),dryRun),dryRun,files:[...recipe.files]};
+}

package/dist/route-diff.js

@@ -0,0 +1,106 @@
+// Route-inventory diff: compares two `urlcode routes` reports and reports what
+// was added, removed or changed. Pure and generic: it knows nothing about
+// pull requests; the GitHub action renders its Markdown into a PR comment.
+import { ConfigError } from './errors.js';
+                                                                 
+
+/** One route as the diff sees it: the inventory entry plus its policy description from the `policies` map. */
+                                                                                            
+/** The parts of a `urlcode routes` report the diff reads. */
+                                                                                                                                  
+                                                                                      
+                                                                                                   
+
+const states                        = ['active','disabled','expired'];
+const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isStrings = (value         )                    => Array.isArray(value) && value.every(item => typeof item === 'string');
+function entry(value         , index        )                     {
+  const fail = (what        )        => { throw new ConfigError(`Route report inventory[${index}] ${what}`); };
+  if (!isRecord(value)) return fail('is not an object');
+  const { path, handler, methods, middleware, policies, generated, state } = value;
+  if (typeof path !== 'string' || !path) return fail('needs a path');
+  if (handler !== undefined && typeof handler !== 'string') return fail('has an invalid handler');
+  if (!isStrings(methods)) return fail('needs methods');
+  if (typeof middleware !== 'number' || !Number.isInteger(middleware) || middleware < 0) return fail('needs a middleware count');
+  if (!isStrings(policies)) return fail('needs policies');
+  if (generated !== undefined && typeof generated !== 'string') return fail('has an invalid generated marker');
+  if (typeof state !== 'string' || !states.includes(state              )) return fail('needs a state');
+  return { path, handler, methods, middleware, policies, ...(generated !== undefined ? { generated } : {}), state:state               };
+}
+/** Validates a parsed `urlcode routes` JSON report (a child-process or file boundary) into a snapshot. */
+export function parseRouteSnapshot(value         )                {
+  if (!isRecord(value) || !Array.isArray(value.inventory)) throw new ConfigError('Route report needs an inventory array');
+  const inventory = value.inventory.map(entry);
+  const policies                                          = {};
+  if (value.policies !== undefined) {
+    if (!isRecord(value.policies)) throw new ConfigError('Route report policies must be an object');
+    for (const [path, description] of Object.entries(value.policies)) {
+      if (!isRecord(description)) throw new ConfigError(`Route report policies[${path}] must be an object`);
+      policies[path] = description;
+    }
+  }
+  return { inventory, policies };
+}
+// Key order in a report is not a change: compare canonical JSON.
+function canonical(value         )         {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (isRecord(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value) ?? 'null';
+}
+function records(snapshot               )                           {
+  const map = new Map                     ();
+  for (const item of snapshot.inventory) {
+    if (map.has(item.path)) throw new ConfigError(`Route report lists ${item.path} twice`);
+    const policy = snapshot.policies?.[item.path];
+    map.set(item.path, policy ? { ...item, policy } : { ...item });
+  }
+  return map;
+}
+/** Compares two route reports. Paths are sorted; an entry changes when any inventory field or its policy description differs. */
+export function diffRoutes(before               , after               )            {
+  const previous = records(before), current = records(after);
+  const paths = [...new Set([...previous.keys(), ...current.keys()])].sort();
+  const diff            = { added:[], removed:[], changed:[] };
+  for (const path of paths) {
+    const old = previous.get(path), now = current.get(path);
+    if (old && !now) diff.removed.push(old);
+    else if (now && !old) diff.added.push(now);
+    else if (old && now && canonical(old) !== canonical(now)) diff.changed.push({ path, before:old, after:now });
+  }
+  return diff;
+}
+export const hasRouteChanges = (diff           )          => diff.added.length + diff.removed.length + diff.changed.length > 0;
+
+const fields = ['handler','methods','state','middleware','policies','generated','policy']         ;
+                                   
+const cell = (value         )         => {
+  const text = value === undefined ? '' : Array.isArray(value) && value.every(item => typeof item === 'string') ? value.join(', ') : typeof value === 'string' ? value : canonical(value);
+  // Backslashes first, so an escape this adds is never itself re-escaped.
+  return text.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ') || '-';
+};
+const code = (value        )         => `\`${value.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\|/g, '\\|')}\``;
+function table(headers          , rows            )           {
+  return [`| ${headers.join(' | ')} |`, `|${headers.map(() => '---').join('|')}|`, ...rows.map(row => `| ${row.join(' | ')} |`)];
+}
+const routeRow = (record             )           => [code(record.path), cell(record.handler), cell(record.methods), cell(record.state), String(record.middleware), cell(record.policies), cell(record.generated)];
+/** Renders a diff as Markdown: one table per nonempty section, or "No route changes". */
+export function renderRouteDiff(diff           )         {
+  if (!hasRouteChanges(diff)) return 'No route changes\n';
+  const lines           = [];
+  const routeHeaders = ['Route','Handler','Methods','State','Middleware','Policies','Generated'];
+  const section = (title        , list               ) => {
+    if (!list.length) return;
+    lines.push(`### ${title} (${list.length})`, '', ...table(routeHeaders, list.map(routeRow)), '');
+  };
+  section('Added routes', diff.added);
+  section('Removed routes', diff.removed);
+  if (diff.changed.length) {
+    const rows             = [];
+    for (const change of diff.changed) {
+      const differing = fields.filter((field       ) => canonical(change.before[field]) !== canonical(change.after[field]));
+      for (const field of differing) rows.push([code(change.path), field, cell(change.before[field]), cell(change.after[field])]);
+    }
+    lines.push(`### Changed routes (${diff.changed.length})`, '', ...table(['Route','Field','Before','After'], rows), '');
+  }
+  return lines.join('\n');
+}

package/dist/router.js

@@ -1,3 +1,9 @@
+import { hasExtensionPolicy } from './extensions.js';
+import { validateProxy } from './proxy.js';
+import { validateSignal } from './signals.js';
+                                                
+import { normalizeMatch, assertDisjointMatches } from './conditions.js';
+import { effectivePolicies } from './policies.js';
 import { setImmediate as yieldTurn } from 'node:timers/promises';
 import { compileHttp } from './http-policy.js';
 import Ajv from 'ajv/dist/2020.js';
@@ -63,7 +69,7 @@ export async function compileRoutes(loaded                , bindings
     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(!pattern.includes('*') || ((config.static || config.extension) && pattern.endsWith('/*') && parts.filter(p => p.includes('*')).length === 1 && parts.at(-1) === '*' && !names.length), 'Only static or extension 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');
@@ -72,6 +78,28 @@ export async function compileRoutes(loaded                , bindings
     const route                = { ...declared, pattern, parts, names, specificity: parts.length - names.length,
       methods: config.methods || methodsDefault, parameters: [], env: dict(), secrets: dict(), responseHeaders: [], middleware: [] };
     compileHttp(route);
+    if (config.match) route.match = normalizeMatch(config.match);
+    if(config.extension){assert(!config.middleware?.length&&!config.parameters?.length&&!config.env&&!config.secrets,'Extension handlers cannot declare guest middleware, parameters or bindings');assert(pattern.endsWith('/*')&&!names.length&&pattern!=='/*','Extension handler requires a non-root literal /* mount');}
+    if (config.match || config.conditional || config.extension || hasExtensionPolicy(loaded.document,config)) {
+      const cache = effectivePolicies(loaded.document,config).cache;
+      assert(!cache || cache.strategy === 'no-store', `${pattern}: conditional routing requires cache disabled or no-store`);
+      assert(!route.responseHeaders.some(([name,value]) => ['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control'].includes(name.toLowerCase()) && value !== 'no-store'), 'Conditional responses require no-store');
+    }
+    if (config.conditional) {
+      const matches = config.conditional.cases.map(item => normalizeMatch(item.match));
+      assertDisjointMatches(matches);
+      const compileBranch = async (branch                                                                                 ) => {
+        const entry = { ...branch, ...(config.parameters ? { parameters: config.parameters } : {}), ...(config.methods ? { methods: config.methods } : {}) };
+        const table = await compileRoutes({ ...loaded, routes: { [pattern]: entry } }, {}, {});
+        return table.exact.get(pattern) ?? [...table.byLength.values()].flat()[0] ;
+      };
+      route.conditionalRoutes = { cases: [] };
+      for (const [index,item] of config.conditional.cases.entries()) {
+        const { match: _match, ...branch } = item;
+        route.conditionalRoutes.cases.push({ match: matches[index] , route: await compileBranch(branch) });
+      }
+      if (config.conditional.fallback) route.conditionalRoutes.fallback = await compileBranch(config.conditional.fallback);
+    }
     const seen = new Set        ();
     for (const param of config.parameters || []) {
       const schema = param.schema, name = param.in === 'header' ? param.name.toLowerCase() : param.name;
@@ -101,6 +129,17 @@ export async function compileRoutes(loaded                , bindings
       assert(typeof value === 'string' && value.length, 'Missing required secret binding');
       route.secrets[alias] = value;
     }
+    const resolveHeaders=(headers                        )                       => Object.fromEntries(Object.entries(headers||{}).map(([key,value])=>{if(typeof value==='string')return [key,value];assert(own(route.secrets,value.secret),'Unknown egress secret alias');return [key,route.secrets[value.secret] ];}));
+    if(config.proxy){
+      assert(!config.middleware?.length,'Proxy middleware is not supported; authorize requests with host policy before egress');
+      const cache=effectivePolicies(loaded.document,config).cache;
+      assert(!cache||cache.strategy==='no-store','Proxy routes require cache disabled or no-store');
+      assert(!route.responseHeaders.some(([name,value])=>['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control'].includes(name.toLowerCase())&&value!=='no-store'),'Proxy response caching must be no-store');
+      route.compiledProxy={...config.proxy,headers:resolveHeaders(config.proxy.headers)};validateProxy(route.compiledProxy);
+      for(const match of config.proxy.url.matchAll(/(?:\{|%7B)([A-Za-z_][A-Za-z0-9_]*)(?:\}|%7D)/gi))assert(names.includes(match[1] ), 'Proxy placeholder requires a declared path parameter');
+      assert(!Object.keys(config.response?.headers||{}).some(name=>name.toLowerCase()==='content-encoding'),'Proxy content encoding cannot be overridden');
+    }
+    if(config.signals){route.compiledSignals=config.signals.map(signal=>({...signal,headers:resolveHeaders(signal.headers)}));for(const signal of route.compiledSignals)validateSignal(signal);}
     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);
@@ -141,7 +180,7 @@ export async function compileRoutes(loaded                , bindings
       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); }
+    if (config.static || config.extension) { 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');
@@ -160,6 +199,7 @@ export async function compileRoutes(loaded                , bindings
     if (!byLength.has(route.parts.length)) byLength.set(route.parts.length, []);
     byLength.get(route.parts.length) .push(route);
   }
+  for(const mount of mounts.filter(route=>route.extension)){const base=mount.parts.slice(0,-1);for(const candidate of [...exact.values(),...dynamic,...mounts]){if(candidate===mount)continue;const parts=candidate.parts;const shared=Math.min(base.length,parts.length-(candidate.prefix?1:0));const compatible=base.slice(0,shared).every((part,index)=>part===parts[index]||parameterName(parts[index] ));assert(!compatible||(!candidate.prefix&&parts.length<base.length),'Extension mount overlaps another 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

@@ -1,3 +1,11 @@
+import { prepareExtensions, effectiveExtensionPolicies, hasExtensionPolicy, extensionResponse } from './extensions.js';
+                                                                                                                    
+import { EgressClient, EgressError } from './egress.js';
+                                                      
+import { executeProxy } from './proxy.js';
+import { SignalBroker } from './signals.js';
+import { matchesRoute } from './conditions.js';
+import { analyzeProjectCapabilities, assertTargetCompatibility } from './capabilities.js';
 import { projectPlan, hasRedirect } from './readiness.js';
                                                   
 import { checkRequest, decorateResponse } from './http-policy.js';
@@ -6,7 +14,7 @@ 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 { prepareFunctionSnapshot, validatePolicy, authorizeEgress } from './policy.js';
                                                   
 import {openLinkStore} from './link-store.js';
                                                                 
@@ -35,11 +43,20 @@ import { applySite } from './site.js';
                                                                     
                                                                                                                   
                                  
+                                              
+                                                                                        
+                                          
                                                                                                                         
                                                                                         
                                                                                                 
                                                                       
                                                                                               
+                                                                                   
+                                                                                   
+                                                                                    
+                                                                                   
+                                                                                  
+                                       
  
 /** Per-request facts the host may read after handle() settles; never request text. */
                                                                                       
@@ -71,11 +88,23 @@ export async function createRuntime(project        , rawOptions
   // 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 });
+  if (options.only !== undefined) {
+    const only = options.only;
+    assert(Array.isArray(only) && only.every(pattern => typeof pattern === 'string'), 'Route restriction must be a string array');
+    // An unknown pattern is a caller mistake, not an empty selection: a silent
+    // miss would prerender a partial site that looks whole.
+    for (const pattern of only) assert(Object.hasOwn(loaded.routes, pattern), `Route restriction names unknown route ${pattern}`);
+    const kept = new Set(only);
+    for (const pattern of Object.keys(loaded.routes)) if (!kept.has(pattern)) delete loaded.routes[pattern];
+  }
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, options.target || 'node'));
   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 egressGrants=authorizeEgress(loaded,snapshot.projectSha256,options.permissions);
+  const extensionPlan=prepareExtensions(loaded.document,loaded.routes,options.extensions,{origin:options.origin??'',target:options.target??'node',projectSha256:snapshot.projectSha256});
+  const bindings = await loadBindings(loaded.root, options.local, options.environment);
   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);
@@ -85,6 +114,9 @@ export async function createRuntime(project        , rawOptions
   // reloads: a new snapshot starts with empty counters and an empty cache.
   const target = options.target || 'node';
   const plugins = validatePlugins(options.plugins, target);
+  // Capture the operator declaration once, before activation hooks can mutate
+  // their plugin objects. This boundary applies to public guest routes too.
+  const credentialHeaders=new Set(plugins.flatMap(plugin=>plugin.credentialHeaders||[]).map(name=>name.toLowerCase()));
   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;
@@ -106,6 +138,19 @@ export async function createRuntime(project        , rawOptions
   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;}
+  const proxyClient=new EgressClient({grantOrigins:egressGrants.proxy},options.egressDependencies);
+  const signalClient=new EgressClient({grantOrigins:egressGrants.signals,concurrency:8},options.egressDependencies);
+  let lastSignals={accepted:0,delivered:0,failed:0,dropped:0};
+  const signalBroker=new SignalBroker(signalClient,8,stats=>{for(const outcome of ['accepted','delivered','failed','dropped']         ){const count=stats[outcome]-lastSignals[outcome];if(count)sink({event:'signal',outcome,count});}lastSignals=stats;});
+  let extensionRegistry                  ;
+  try{extensionRegistry=await extensionPlan.activate();}
+  catch(error){await pool.close();await ownedStore?.close();await closePolicies(shared);await proxyClient.close();await signalClient.close();throw error;}
+  for(const name of extensionRegistry.credentialHeaders)credentialHeaders.add(name);
+  for(const route of routes)route.extensionPolicyNames=Object.keys(effectiveExtensionPolicies(loaded.document,route));
+  const privateRoutes=new Set(routes.filter(route=>route.extension||hasExtensionPolicy(loaded.document,route)).map(route=>route.pattern));
+  // Only an extension's own mount can serve its declared immutable assets.
+  const assetPrefixes=new Map(routes.filter(route=>route.extension).map(route=>[route.pattern,extensionRegistry.entries.get(route.extension ) .assetPrefixes]));
+  const assetContext=(method       ,path       ,pattern       )                                =>{const prefixes=assetPrefixes.get(pattern);return prefixes?.length?{method,path,prefixes}:undefined;};
   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
@@ -115,19 +160,23 @@ export async function createRuntime(project        , rawOptions
   // 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;
+    const confidential=privateRoutes.has(request.route),asset=assetContext(request.method,request.path,request.route);
+    let out = confidential?extensionResponse(result,asset):result;
     for (const [module, state] of policy?.response || []) {
+      if(confidential&&module.name==='compression')continue;
       if (producer === 'plugin' ? module.onRequest : module === producer) continue;
       out = await module.onResponse?.(state, request, out) ?? out;
     }
-    return pluginsResponse(plugins, request, out);
+    out=await pluginsResponse(plugins, request, out);
+    return confidential?extensionResponse(out,asset):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 });
+  try{await activatePlugins(plugins, { testPlan, version: loaded.version + assets.digest, root: loaded.root, target });}
+  catch(error){await Promise.all([extensionRegistry.close(),signalBroker.close(),signalClient.close(),proxyClient.close(),pool.close(),ownedStore?.close(),closePolicies(shared),closePlugins(plugins),sink.close()]);throw error;}
   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,
@@ -144,7 +193,7 @@ export async function createRuntime(project        , rawOptions
     },
     requestLimit(target) {
       const match = matchRoute(compiled, parseTarget(target));
-      return match?.route.request?.body?.maxBytes;
+      return match?.route.request?.body?.maxBytes ?? (match?.route.proxy||match?.route.extension?1048576:undefined);
     },
     async handle({ target, method = 'GET', headers = new Headers(), body, headerCounts, trace = {}, origin = 'http://localhost', client }) {
       if (closing) throw new HttpError(503, 'Runtime unavailable');
@@ -160,20 +209,28 @@ export async function createRuntime(project        , rawOptions
         // 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;
+        const conditionRequest = { query: parsed.query, headers, method, origin, headerCounts };
+        if (route.match && !matchesRoute(route.match,conditionRequest)) throw new HttpError(404,'Not found');
         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) {
+        const protectedRoute=privateRoutes.has(route.pattern);
+        const extensionRequest                 ={method,target,path:parsed.path,query:new URLSearchParams(parsed.query),headers:new Headers(headers),headerCounts:{...headerCounts},body:body??new Uint8Array(),origin:options.origin??origin,route:route.pattern,mount:route.extension?route.pattern.slice(0,-2):null,client:client??null};
+        if(protectedRoute&&(body?.byteLength??0)>Math.min(1048576,route.request?.body?.maxBytes??1048576))throw new HttpError(413,'Request body too large');
+        const authorize=async()                                 =>{for(const name of Object.keys(effectiveExtensionPolicies(loaded.document,route))){const entry=extensionRegistry.entries.get(name) ;const result=await entry.instance.authorize (entry.policies.get(route.pattern) ,extensionRequest);if(result)return result;}return undefined;};
+        if (policy || plugins.length || protectedRoute) {
           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');
+          if(!protectedRoute){const early=await pluginsRequest(plugins,policyReq);if(early)return await finishPolicies(policy,policyReq,early,'plugin');}
+          let authorized=false;
           for (const [module, state] of policy?.request || []) {
+            if(protectedRoute&&module.name==='cache'&&!authorized){const denied=await authorize();authorized=true;if(denied)return await finishPolicies(policy,policyReq,denied);}
             const result = await module.onRequest?.(state, policyReq);
             if (result) return await finishPolicies(policy, policyReq, result, module);
           }
+          if(protectedRoute){if(!authorized){const denied=await authorize();if(denied)return await finishPolicies(policy,policyReq,denied);}const early=await pluginsRequest(plugins,policyReq);if(early)return await finishPolicies(policy,policyReq,early,'plugin');}
         }
         if (!route.methods.includes(method)) {
           const refused                = { status: 405, headers: [['allow', route.methods.join(', ')]], body: Buffer.from('Method not allowed\n') };
@@ -182,10 +239,32 @@ export async function createRuntime(project        , rawOptions
           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);
+        const finishResponse = async (result               )                         => {
+          const out = policyReq ? await finishPolicies(policy, policyReq, decorateResponse(route,result)) : decorateResponse(route,result);
+          if(method!=='HEAD'&&!trace.probe)for(const signal of route.compiledSignals||[])signalBroker.emit(signal,{route:route.pattern,status:out.status,method});
+          if (route.proxy || route.match || route.conditional) return { ...out, headers: [...out.headers.filter(([name]) => !['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control'].includes(name.toLowerCase())), ['cache-control','no-store']] };
+          return out;
+        };
+        // Policies, plugins and body checks retain the original request. Project
+        // inputs and the guest receive a separate, credential-free projection.
+        const guestHeaders=credentialHeaders.size?new Headers(headers):headers;
+        for(const name of credentialHeaders)guestHeaders.delete(name);
+        const context                  = contextFor(route, path, parsed.query, guestHeaders, headerCounts);
+        // A declared schema default must not recreate a withheld header entry.
+        for(const name of credentialHeaders)delete context.inputs.header[name];
         let native                           ;
-        if (hasRedirect(route)) native = { status: route.redirect.status || 302,
+        if(route.extension){native=extensionResponse(await extensionRegistry.entries.get(route.extension) .instance.handle(extensionRequest),assetContext(method,parsed.path,route.pattern));}
+        else if(route.compiledProxy){
+          try {const result=await executeProxy(proxyClient,route.compiledProxy,{method,url:origin+target,params:path,headers:Object.fromEntries(headers),...(body?{body}:{})});native={status:result.status,headers:Object.entries(result.headers),body:result.body};}
+          catch(error){throw new HttpError(error instanceof EgressError&&error.code==='timeout'?504:error instanceof EgressError&&['busy','closed','aborted'].includes(error.code)?503:502,'Proxy upstream unavailable');}
+        }
+        else if (route.conditionalRoutes) {
+          const selected = route.conditionalRoutes.cases.find(item => matchesRoute(item.match,conditionRequest))?.route ?? route.conditionalRoutes.fallback;
+          if (!selected) throw new HttpError(404,'Not found');
+          if (hasRedirect(selected)) native = { status: selected.redirect.status || 302, headers: [['location',redirectLocation(selected,context,parsed.query)]], body: Buffer.alloc(0) };
+          else native = selected.reply;
+        }
+        else 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
@@ -212,9 +291,9 @@ export async function createRuntime(project        , rawOptions
             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);
+        if (native && !route.middleware.length) return await 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));
+        return await finishResponse(await pool.execute(route, { url: origin + target, method, headers: [...guestHeaders], body }, context, native));
       } catch (error) {
         if (policy !== undefined && error && typeof error === 'object') errorRoutes.set(error, policy);
         if (policyReq) {
@@ -233,11 +312,13 @@ export async function createRuntime(project        , rawOptions
     },
     async close() {
       closing = true;
+      await Promise.all([signalBroker.close(),signalClient.close(),proxyClient.close()]);
       if (active) await new Promise      (resolve => { finish = resolve; });
       await pool.close();
       await ownedStore?.close();
       await closePolicies(shared);
       await closePlugins(plugins);
+      await extensionRegistry.close();
       await sink.close();
     },
   };

package/dist/schema-query.js

@@ -0,0 +1,62 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {ConfigError} from './errors.js';
+
+                                 
+                                                                                 
+const maxDepth=12;
+let cached               ;
+function schema()      {
+  cached??=JSON.parse(readFileSync(fileURLToPath(new URL('../schemas/urlcode.schema.json',import.meta.url)),'utf8'))        ;
+  return cached;
+}
+const object=(value        )              =>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const properties=(node     )     =>object(node.properties)?node.properties:{};
+function definition(root     ,ref       )      {
+  const defs=object(root.$defs)?root.$defs:{};
+  const name=ref.startsWith('#/$defs/')?ref.slice('#/$defs/'.length):undefined;
+  const found=name===undefined?undefined:defs[name];
+  if(!object(found))throw new ConfigError('Schema reference cannot be resolved');
+  return found;
+}
+/** Definitions that are their own dotted path stay summarized when nested, so `routes` does not inline the whole route object. */
+const summarized                      ={'#/$defs/route':'route','#/$defs/policies':'policies'};
+/** Inline every local `$ref` with a depth bound and a cycle guard. The bundled schema has no cycles; a cycle would surface as an annotation, not a crash. */
+function inline(root     ,node        ,stack                  )         {
+  if(Array.isArray(node))return node.map(item=>inline(root,item,stack));
+  if(!object(node))return node;
+  if(typeof node.$ref==='string') {
+    const {$ref,...rest}=node;
+    if(stack.includes($ref)||stack.length>=maxDepth)return {...rest,$comment:`unresolved reference ${$ref}: ${stack.includes($ref)?'cycle':'depth limit'}`};
+    const path=summarized[$ref];
+    if(path!==undefined)return {type:'object',...rest,$comment:`${path} object; see urlcode schema ${path}`};
+    return {...inline(root,definition(root,$ref),[...stack,$ref])        ,...inline(root,rest,stack)        };
+  }
+  return Object.fromEntries(Object.entries(node).map(([key,value])=>[key,inline(root,value,stack)]));
+}
+const resolved=(root     ,node     )     =>typeof node.$ref==='string'?{...definition(root,node.$ref),...Object.fromEntries(Object.entries(node).filter(([key])=>key!=='$ref'))}:node;
+/** Top-level document keys first, then `route` itself and every route property (`redirect`, `function`, `middleware`, ...). */
+export function schemaPathNames()          {
+  const root=schema();
+  const route=definition(root,'#/$defs/route');
+  return [...new Set([...Object.keys(properties(root)),'route',...Object.keys(properties(route))])];
+}
+/** Only the fragment for a dotted path, with references resolved inline. No validation, defaults or authority. */
+export function getSchemaFragment(path       )                {
+  if(typeof path!=='string'||path.length>256||!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(path))throw new ConfigError('Schema path must be dotted property names; top-level names: '+schemaPathNames().join(', '));
+  const root=schema(),route=definition(root,'#/$defs/route');
+  const [first,...rest]=path.split('.');
+  let node     ,pointer       ;
+  if(first!==undefined&&object(properties(root)[first])){node=properties(root)[first]        ;pointer='#/properties/'+first;}
+  else if(first==='route'){node=route;pointer='#/$defs/route';}
+  else if(first!==undefined&&object(properties(route)[first])){node=properties(route)[first]        ;pointer='#/$defs/route/properties/'+first;}
+  else throw new ConfigError(`Unknown schema path; top-level names: ${schemaPathNames().join(', ')}`);
+  for(const segment of rest) {
+    const current=resolved(root,node);
+    const alternatives=[current,...(Array.isArray(current.oneOf)?current.oneOf.filter(object).map(item=>resolved(root,item)):[])];
+    const next=alternatives.map(item=>properties(item)[segment]).find(object);
+    if(!next)throw new ConfigError(`Unknown schema path segment; names under ${pointer}: ${[...new Set(alternatives.flatMap(item=>Object.keys(properties(item))))].join(', ')||'(none)'}`);
+    node=next;pointer+='/properties/'+segment;
+  }
+  return {format:1,path,pointer,schema:inline(root,resolved(root,node),[])        };
+}

package/dist/signals.js

@@ -0,0 +1,24 @@
+import { egressUrl, safeEgressHeaders } from './egress.js';
+                                                  
+                                                                                
+                                                                           
+                                                                                                 
+export function validateSignal(definition                 )      {if(!definition||typeof definition!=='object'||Object.keys(definition).some(key=>!['url','headers'].includes(key))) throw new Error('Invalid signal');egressUrl(definition.url);safeEgressHeaders(definition.headers||{});}
+/** No queue, retries, ordering promise, or durable delivery. Counters contain no URL/header data. */
+export class SignalBroker {
+           #onStats                                      ;          #client                ;          #concurrency       ;          #pending=new Set               ();          #controller=new AbortController();
+           #stats            ={accepted:0,delivered:0,failed:0,dropped:0}; #closed=false;
+  constructor(client                ,concurrency=8,onStats                            ) {if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>128) throw new Error('Invalid signal concurrency');this.#onStats=onStats;this.#client=client;this.#concurrency=concurrency;}
+  get stats()             {return {...this.#stats};}
+  emit(definition                 ,event            )         {
+    if(this.#closed||this.#pending.size>=this.#concurrency) {this.#stats.dropped++;this.#notify();return false;}
+    try {validateSignal(definition);} catch {this.#stats.dropped++;this.#notify();return false;}
+    if(!event.route.startsWith('/')||event.route.length>2048||!/^[A-Z]{1,16}$/.test(event.method)||!Number.isInteger(event.status)||event.status<100||event.status>599) {this.#stats.dropped++;this.#notify();return false;}
+    this.#stats.accepted++;this.#notify();
+    const body=Buffer.from(JSON.stringify({version:1,route:event.route,status:event.status,method:event.method}));
+    const pending=Promise.resolve().then(()=>this.#client.request({url:definition.url,method:'POST',headers:{...definition.headers,'content-type':'application/json'},body,signal:this.#controller.signal})).then(result=>{if(result.status>=200&&result.status<300)this.#stats.delivered++;else this.#stats.failed++;},()=>{this.#stats.failed++;}).finally(()=>{this.#pending.delete(pending);this.#notify();});
+    this.#pending.add(pending);return true;
+  }
+  #notify()      {try {this.#onStats?.(this.stats);} catch { /* Observers cannot alter delivery. */ }}
+  async close()               {this.#closed=true;this.#controller.abort();await Promise.allSettled([...this.#pending]);}
+}