@browserlessapi/inferlo 0.5.0 → 0.7.0

package/dist/app.js

@@ -4,21 +4,33 @@
  */
 import { bindTools, createAI } from "./ai/index.js";
 import { memory } from "./db/memory.js";
-import { bindDb, createDb, guardAdapter } from "./db/table.js";
+import { createAudit } from "./audit.js";
+import { checkRouteCache, createCache, databaseCacheStore, etagFor, etagMatches, memoryCacheStore, resolveCacheConfig, routeCacheKey } from "./cache.js";
+import { bindDb, checkTenantId, createDb, guardAdapter } from "./db/table.js";
 import { describeApp } from "./describe.js";
 import { InferloError, didYouMean, suggest } from "./errors.js";
 import { callTool, handleMcp, toolDefinition } from "./mcp.js";
 import { buildOpenAPI } from "./openapi.js";
-import { isRoute } from "./route.js";
+import { collectRoutes } from "./route.js";
+import { checkRedisClient, pingRedis, redisCacheStore, redisMissing, redisPrefix, redisRateLimitStore } from "./redis.js";
 import { checkRateLimit, databaseRateLimitStore, memoryRateLimitStore, rateLimitResult, windowMs } from "./rate-limit.js";
-import { clientIp, clientIps } from "./client-ip.js";
-import { collectCrons, collectJobs, createJobs, jobStoreFor, stopWorkers } from "./jobs.js";
+import { clientIp, clientIps, clientSignals, keepEventStreamOpen, platformWaitUntil } from "./client-ip.js";
+import { redisJobStore } from "./redis-jobs.js";
+import { knownBodies } from "./response-body.js";
+import { collectCrons, collectJobs, collectSubscriptions, createJobs, jobStoreFor, stopWorkers, withTenant } from "./jobs.js";
+import { checkEventsConfig, invalidTransport } from "./events.js";
+import { redisEventTransport } from "./redis-events.js";
 import { ValidationError } from "./schema.js";
 import { createRedactor, redactingLogger, redactValues, secretsOf } from "./redact.js";
 import { defaultLogger, loggingOptions, REQUEST_ID } from "./logging.js";
+import { clientTracing, jobTracing, requestTracing, traceAdapter, traceFields } from "./tracing.js";
 import { resolveDeprecation } from "./deprecation.js";
 import { createMetrics, hasMetricsToken, resolveMetrics } from "./metrics.js";
 import { INFERLO_VERSION } from "./describe.js";
+import { registerRequestMatcher } from "./request-matcher.js";
+import { versionDocPath, versionsOf } from "./api-version.js";
+import { resolveModules } from "./module.js";
+import { isPermissions } from "./permissions.js";
 import { applySecureHeaders, resolveSecureHeaders } from "./secure-headers.js";
 const testUsers = new WeakMap();
 function compile(def) {
@@ -45,29 +57,6 @@ function compile(def) {
         .join("");
     return { def, regex: new RegExp(`^${pattern || ""}/?$`), keys, score: score * 10 + parts.length };
 }
-function collectRoutes(sources) {
-    const out = [];
-    const seen = new Set();
-    const visit = (source, name) => {
-        if (!source || typeof source !== "object" || seen.has(source))
-            return;
-        seen.add(source);
-        if (isRoute(source)) {
-            out.push(name && !source.name ? { ...source, name } : source);
-            return;
-        }
-        if (Array.isArray(source)) {
-            for (const item of source)
-                visit(item);
-            return;
-        }
-        for (const [key, value] of Object.entries(source))
-            if (isRoute(value) || Array.isArray(value))
-                visit(value, key === "default" ? undefined : key);
-    };
-    visit(sources);
-    return out;
-}
 function corsHeaders(config, origin) {
     const allowed = config.origin === "*" ? "*" : origin && (Array.isArray(config.origin) ? config.origin : [config.origin]).includes(origin) ? origin : null;
     if (!allowed)
@@ -131,14 +120,22 @@ function withHeader(response, name, value) {
 }
 function json(data, status, headers) {
     headers.set("content-type", "application/json; charset=utf-8");
-    return new Response(JSON.stringify(data), { status, headers });
+    const text = JSON.stringify(data);
+    const response = new Response(text, { status, headers });
+    knownBodies.set(response, text);
+    return response;
 }
 export function createApp(config = {}) {
     // Everything the app logs goes through the redactor: credentials and secrets never reach the logs.
     const redactor = createRedactor([...redactValues(config.redact), ...Object.values(config.ai?.providers ?? {}).flatMap((p) => secretsOf(p))]);
     const logging = loggingOptions(config.logging, config.logger !== undefined);
     const logger = redactingLogger(config.logger ?? defaultLogger(logging.format, config.name ?? "inferlo-app"), redactor);
-    const models = (config.models ?? []);
+    const tracing = requestTracing(config.tracing, config.name ?? "inferlo-app", config.version ?? "0.0.0");
+    const tracingApi = tracing ? config.tracing.api : undefined;
+    // The server span of each request, for errors recorded while it runs.
+    const requestSpans = new WeakMap();
+    const { modules, modelOwner } = resolveModules(config.modules, config.models ?? []);
+    const models = [...(config.models ?? []), ...modules.flatMap((m) => m.models)];
     const modelNames = new Set();
     for (const m of models) {
         if (modelNames.has(m.name))
@@ -155,7 +152,15 @@ export function createApp(config = {}) {
             }
         }
     }
+    // Routes of the app itself, then each module's; routeModule remembers which module a route came from.
+    const routeModule = new Map();
     const routes = collectRoutes(config.routes);
+    for (const m of modules) {
+        for (const r of collectRoutes(m.routes)) {
+            routeModule.set(r, m.name);
+            routes.push(r);
+        }
+    }
     const compiled = routes.map(compile).sort((a, b) => b.score - a.score);
     const signatures = new Map();
     for (const r of routes) {
@@ -180,9 +185,29 @@ export function createApp(config = {}) {
             fix: 'Routes are private by default. Add auth: "public" to routes anyone may call, or pass createApp({ auth: { resolve(req) { ... } } }).',
         });
     }
+    if (config.permissions !== undefined && !isPermissions(config.permissions)) {
+        throw new InferloError("IL6026", "createApp({ permissions }) takes the result of permissions({ ... }).", { fix: 'Define them with permissions({ "tickets.update": ({ user, ticket }) => ticket.ownerId === user.id }) and pass that value.' });
+    }
+    for (const r of routes) {
+        const name = r.options.permission;
+        if (name === undefined)
+            continue;
+        const where = `${r.method} ${r.path}`;
+        if (typeof name !== "string" || !config.permissions?.has(name)) {
+            throw new InferloError("IL6026", config.permissions ? `The route ${where} uses the unknown permission "${String(name)}".` : `The route ${where} uses the permission "${String(name)}", but createApp has no permissions.`, {
+                fix: config.permissions ? `Use one of: ${config.permissions.list.map((p) => p.name).join(", ")}, or add it to permissions({ ... }).` : "Pass createApp({ permissions }) with the value from permissions({ ... }).",
+            });
+        }
+        if (r.options.auth === "public") {
+            throw new InferloError("IL6026", `The route ${where} has a permission but auth: "public".`, { fix: 'A permission needs a signed-in user: remove auth: "public" from the route.' });
+        }
+    }
     for (const r of routes)
         if (r.options.rateLimit !== undefined)
             checkRateLimit(r.options.rateLimit, `${r.method} ${r.path}`);
+    for (const r of routes)
+        if (r.options.cache !== undefined)
+            checkRouteCache(r.options.cache, r.method, `${r.method} ${r.path}`);
     const requestTimeoutMs = config.requestTimeoutMs === undefined ? 60_000 : checkTimeout(config.requestTimeoutMs, "createApp({ requestTimeoutMs })");
     for (const r of routes)
         if (r.options.timeoutMs !== undefined)
@@ -194,39 +219,90 @@ export function createApp(config = {}) {
             deprecations.set(r, resolved);
     }
     const storeName = config.rateLimit?.store ?? "memory";
-    if (storeName !== "memory" && storeName !== "database") {
-        throw new InferloError("IL6007", `Invalid rateLimit store "${String(storeName)}".`, { fix: 'Use createApp({ rateLimit: { store: "memory" } }) or { store: "database" }.' });
+    if (storeName !== "memory" && storeName !== "database" && storeName !== "redis") {
+        throw new InferloError("IL6007", `Invalid rateLimit store "${String(storeName)}".`, { fix: 'Use createApp({ rateLimit: { store: "memory" } }), { store: "database" } or { store: "redis" }.' });
     }
+    const redis = checkRedisClient(config.redis);
+    if (storeName === "redis" && !redis)
+        throw redisMissing("rateLimit");
     const openapiPath = config.openapi === undefined ? "/openapi.json" : config.openapi;
     const hasTools = routes.some((r) => r.options.tool);
     const mcpPath = config.mcp === undefined ? (hasTools ? "/mcp" : false) : config.mcp;
-    const health = resolveHealth(config.health, routes, [openapiPath, mcpPath]);
+    const health = resolveHealth(config.health, routes, [openapiPath, mcpPath], redis ? ["redis"] : []);
+    // apiVersion("v1", ...) routes get their own OpenAPI document at /v1/openapi.json.
+    const versions = versionsOf(routes);
+    const versionDocs = new Map(openapiPath ? versions.map((v) => [versionDocPath(v, openapiPath), v]) : []);
+    for (const docPath of versionDocs.keys()) {
+        const clash = routes.find((r) => r.method === "GET" && r.path.replace(/\/+$/, "") === docPath);
+        if (clash)
+            throw new InferloError("IL6025", `The route GET ${clash.path} has the path of the OpenAPI document of API version ${versionDocs.get(docPath)}.`, { fix: "Rename the route; Inferlo serves each version's OpenAPI document there." });
+    }
     const metricsConfig = resolveMetrics(config.metrics, [
+        ...[...versionDocs.keys()].map((path) => ({ path, what: "an OpenAPI document path" })),
         { path: openapiPath, what: "the OpenAPI path" },
         { path: mcpPath, what: "the MCP path" },
         { path: health?.path ?? false, what: "the health path" },
         { path: health?.readyPath ?? false, what: "the readiness path" },
         ...routes.filter((r) => r.method === "GET").map((r) => ({ path: r.path, what: `the route GET ${r.path}` })),
     ]);
-    const adapter = config.db ?? memory();
+    // With tracing, database queries made while a request or job is traced get client spans.
+    const appTracing = tracing ? { ...config.tracing, tracerName: config.tracing.tracerName ?? config.name ?? "inferlo-app" } : undefined;
+    const adapter = appTracing ? traceAdapter(config.db ?? memory(), clientTracing(appTracing, "inferlo-app", config.version ?? "0.0.0")) : (config.db ?? memory());
     const db = createDb(models, adapter);
-    const rateLimits = storeName === "database" ? databaseRateLimitStore(adapter) : memoryRateLimitStore();
+    const rateLimits = storeName === "redis" ? redisRateLimitStore(redis, redisPrefix(config.name)) : storeName === "database" ? databaseRateLimitStore(adapter) : memoryRateLimitStore();
+    const cacheConfig = resolveCacheConfig(config.cache);
+    if (cacheConfig.store === "redis" && !redis)
+        throw redisMissing("cache");
+    const cacheStore = cacheConfig.store === "redis" ? redisCacheStore(redis, redisPrefix(config.name)) : cacheConfig.store === "database" ? databaseCacheStore(adapter) : memoryCacheStore(cacheConfig.maxEntries);
+    const cache = createCache(cacheStore, cacheConfig.store);
     const metrics = metricsConfig
         ? createMetrics({ app: config.name ?? "inferlo-app", version: config.version ?? "0.0.0", inferlo: INFERLO_VERSION }, metricsConfig.buckets)
         : undefined;
     // With metrics on, every AI call that reports usage is counted before the app's own onUsage runs.
-    const aiConfig = metrics && config.ai
-        ? { ...config.ai, onUsage: (usage) => (metrics.ai(usage), config.ai.onUsage?.(usage)) }
+    // With tracing, AI calls get client spans too (unless the AI config has its own tracing).
+    const aiConfig = config.ai && (metrics || appTracing)
+        ? {
+            ...config.ai,
+            ...(metrics ? { onUsage: (usage) => (metrics.ai(usage), config.ai.onUsage?.(usage)) } : {}),
+            ...(appTracing ? { tracing: config.ai.tracing ?? appTracing } : {}),
+        }
         : config.ai;
     const ai = createAI(aiConfig);
-    const jobs = createJobs(collectJobs(config.jobs), {
+    const jobModule = new Map();
+    for (const m of modules)
+        for (const j of collectJobs(m.jobs))
+            jobModule.set(j.name, m.name);
+    const moduleInfo = { modules, routeModule, modelOwner, jobModule };
+    const jobSources = [...(config.jobs ?? []), ...modules.flatMap((m) => m.jobs)];
+    const transportOption = checkEventsConfig(config.events);
+    let eventTransport;
+    if (transportOption === "redis") {
+        if (!redis)
+            throw new InferloError("IL6031", 'events transport "redis" needs a Redis client, but createApp has no redis option.', { fix: 'Create and connect a client with the redis package: const redis = await createClient({ url: process.env.REDIS_URL }).connect(); then createApp({ name: "billing", redis, events: { transport: "redis" } }).' });
+        // The app name is the consumer group: two services with one name would split each other's events.
+        if (!config.name)
+            throw invalidTransport('events transport "redis" needs createApp({ name }): each service reads events as its own consumer group, named after the app.');
+        eventTransport = redisEventTransport(redis, { group: config.name });
+    }
+    else
+        eventTransport = transportOption;
+    const jobs = createJobs(collectJobs(jobSources), {
         db: db,
         ai,
-        store: jobStoreFor(config.jobQueue, adapter),
+        cache,
+        audit: (run) => createAudit(models, redactor, () => db, { userId: null, tenantId: run.tenantId, source: `job ${run.name}` }),
+        store: jobStoreFor(config.jobQueue, adapter, () => {
+            if (!redis)
+                throw redisMissing("jobQueue");
+            return redisJobStore(redis, redisPrefix(config.name));
+        }),
         queue: config.jobQueue?.store ?? "memory",
         logger,
         onRun: metrics ? (name, outcome, ms) => metrics.job(name, outcome, ms / 1000) : undefined,
-    }, collectCrons(config.jobs));
+        tracing: appTracing ? jobTracing(appTracing, "inferlo-app", config.version ?? "0.0.0") : undefined,
+        eventTransport,
+    }, collectCrons(jobSources), collectSubscriptions(jobSources));
+    const events = jobs.events;
     const maxBody = config.maxBodySize ?? 1024 * 1024;
     const secureHeaders = resolveSecureHeaders(config.secureHeaders);
     const cors = config.cors === true ? { origin: "*" } : config.cors || undefined;
@@ -250,6 +326,8 @@ export function createApp(config = {}) {
             }
         };
     }
+    if (redis)
+        readinessChecks.redis = () => pingRedis(redis);
     Object.assign(readinessChecks, health?.checks);
     const runCheck = async (name, check) => {
         const started = Date.now();
@@ -305,9 +383,19 @@ export function createApp(config = {}) {
         }
         return { name: tool.name, status: response.status, output, text: text || String(response.status) };
     }, describeTool, signal);
+    const tenantScope = (user) => {
+        if (!user)
+            return "none";
+        const id = config.auth?.tenant ? config.auth.tenant(user) : user.tenantId;
+        return id === null || id === undefined ? "none" : { tenant: checkTenantId(id) };
+    };
+    const tenantOf = (scope) => (typeof scope === "object" ? scope.tenant : null);
     const roles = (user) => config.auth?.roles?.(user) ?? (user.roles ?? []);
     const errorResponse = (error, headers, req, requestId) => {
-        const fields = { requestId };
+        const span = requestSpans.get(req);
+        const fields = { requestId, ...traceFields(span) };
+        if (span && !(error instanceof InferloError && error.status < 500))
+            span.recordException(error);
         if (error instanceof InferloError) {
             if (error.status >= 500)
                 logger.error(`${req.method} ${new URL(req.url).pathname} failed: ${error.format()}`, error.cause ?? "", fields);
@@ -329,7 +417,7 @@ export function createApp(config = {}) {
             const method = req.method.toUpperCase();
             if (method === "OPTIONS" && cors) {
                 headers.set("access-control-allow-methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
-                headers.set("access-control-allow-headers", (cors.headers ?? ["content-type", "authorization"]).join(", "));
+                headers.set("access-control-allow-headers", (cors.headers ?? ["content-type", "authorization", "x-csrf-token"]).join(", "));
                 headers.set("access-control-max-age", String(cors.maxAge ?? 600));
                 return new Response(null, { status: 204, headers });
             }
@@ -352,13 +440,33 @@ export function createApp(config = {}) {
                 headers.set("connection", "close");
                 throw new InferloError("IL2006", "The server is shutting down.", { status: 503, fix: "Retry the request; another instance will answer it." });
             }
+            if (method === "GET" && versionDocs.has(url.pathname)) {
+                seen.route = url.pathname;
+                return json(app.openapi({ version: versionDocs.get(url.pathname) }), 200, headers);
+            }
             if (openapiPath && url.pathname === openapiPath && method === "GET") {
                 seen.route = openapiPath;
                 return json(app.openapi(), 200, headers);
             }
             if (mcpPath && url.pathname === mcpPath) {
                 seen.route = mcpPath;
-                return await handleMcp(app, req, headers, testUsers);
+                // tools/list leaves out tools that need a role or permission the caller does not have.
+                let caller;
+                const visible = async (def) => {
+                    const level = def.options.auth ?? "user";
+                    if (!def.options.permission && (level === "public" || level === "user"))
+                        return true;
+                    caller ??= testUsers.has(req) ? Promise.resolve(testUsers.get(req) ?? null) : config.auth ? Promise.resolve(config.auth.resolve(req, { db: db, url })).then((u) => u ?? null) : Promise.resolve(null);
+                    const user = await caller;
+                    if (!user)
+                        return false;
+                    if (level !== "public" && level !== "user" && !roles(user).includes(level))
+                        return false;
+                    if (!def.options.permission)
+                        return true;
+                    return config.permissions.can(def.options.permission, { user }).catch(() => false);
+                };
+                return await handleMcp(app, req, headers, testUsers, visible);
             }
             const lookup = method === "HEAD" ? "GET" : method;
             let match;
@@ -390,8 +498,18 @@ export function createApp(config = {}) {
             const limit = opts.timeoutMs === undefined ? requestTimeoutMs : opts.timeoutMs;
             // timeout aborts when the route takes too long; signal (ctx.signal) also when the client disconnects.
             const timeout = new AbortController();
-            const signal = AbortSignal.any([req.signal, timeout.signal]);
+            // Combined on first use: AbortSignal.any is costly, and most handlers never read ctx.signal.
+            let combined;
+            const signal = () => (combined ??= AbortSignal.any([clientSignals.get(req) ?? req.signal, timeout.signal]));
             let requestDb;
+            let queues;
+            let requestUser = null;
+            const tenantQueues = () => {
+                if (queues)
+                    return queues;
+                const scope = tenantScope(requestUser);
+                return (queues = typeof scope === "object" ? withTenant({ jobs, events }, scope.tenant) : { jobs, events });
+            };
             const run = async () => {
                 // Auth
                 let user = null;
@@ -399,6 +517,7 @@ export function createApp(config = {}) {
                     user = testUsers.get(req) ?? null;
                 else if (config.auth)
                     user = (await config.auth.resolve(req, { db: db, url })) ?? null;
+                requestUser = user;
                 const level = opts.auth ?? "user";
                 if (level !== "public") {
                     if (!user)
@@ -406,9 +525,14 @@ export function createApp(config = {}) {
                     if (level !== "user" && !roles(user).includes(level))
                         throw new InferloError("IL3002", `This requires the "${level}" role.`, { status: 403 });
                 }
-                // Rate limit: counted per user (or IP without one), after auth so failed sign-ins on private routes do not use it up.
+                if (opts.permission)
+                    await config.permissions.authorize(opts.permission, { user });
+                // Rate limit: counted per user, tenant or IP, after auth so failed sign-ins on private routes do not use it up.
+                // by "tenant" counts users without a tenant one by one; by "user" and "tenant" count requests without a user by IP.
                 if (opts.rateLimit) {
-                    const who = (opts.rateLimit.by ?? "user") === "user" && user ? `user:${user.id}` : `ip:${ip}`;
+                    const by = opts.rateLimit.by ?? "user";
+                    const scope = by === "tenant" && user ? tenantScope(user) : "none";
+                    const who = typeof scope === "object" ? `tenant:${scope.tenant}` : by !== "ip" && user ? `user:${user.id}` : `ip:${ip}`;
                     const hit = await rateLimits.hit(`${def.method} ${def.path} ${who}`, windowMs(opts.rateLimit));
                     const limited = rateLimitResult(opts.rateLimit, hit);
                     for (const [k, v] of Object.entries(limited.headers))
@@ -432,8 +556,12 @@ export function createApp(config = {}) {
                     const type = req.headers.get("content-type") ?? "";
                     let raw = undefined;
                     if (text) {
-                        if (type.includes("application/x-www-form-urlencoded"))
-                            raw = Object.fromEntries(new URLSearchParams(text));
+                        if (type.includes("application/x-www-form-urlencoded")) {
+                            // _csrf is the sessions() CSRF field of HTML forms, checked before the handler and not part of the body.
+                            const form = new URLSearchParams(text);
+                            form.delete("_csrf");
+                            raw = Object.fromEntries(form);
+                        }
                         else {
                             try {
                                 raw = JSON.parse(text);
@@ -445,6 +573,34 @@ export function createApp(config = {}) {
                     }
                     body = parseOrThrow(opts.body, raw, "request body", type.includes("application/x-www-form-urlencoded"));
                 }
+                // Response cache: after auth, permissions, rate limits and input checks, so a cached response is only
+                // served to callers who may call the route with valid input.
+                const routeCache = opts.cache;
+                const cacheKey = routeCache ? await routeCacheKey(def.method, def.path, routeCache, user?.id, url, routeCache.by === "tenant" && user ? tenantOf(tenantScope(user)) : undefined) : undefined;
+                const cacheHeaders = (outcome, etag) => {
+                    headers.set("x-inferlo-cache", outcome);
+                    headers.set("etag", etag);
+                    if (!headers.has("cache-control"))
+                        headers.set("cache-control", `${(routeCache.by ?? "user") === "public" && (opts.auth ?? "user") === "public" ? "public" : "private"}, no-cache`);
+                    if ((routeCache.by ?? "user") !== "public")
+                        headers.append("vary", "Authorization, Cookie");
+                };
+                const cachedAnswer = (body, etag) => {
+                    if (etagMatches(req.headers.get("if-none-match"), etag))
+                        return new Response(null, { status: 304, headers });
+                    headers.set("content-type", "application/json; charset=utf-8");
+                    return new Response(method === "HEAD" ? null : body, { status: 200, headers });
+                };
+                if (cacheKey) {
+                    const hit = await cache.get(cacheKey);
+                    if (hit) {
+                        for (const [name, value] of hit.headers)
+                            headers.set(name, value);
+                        cacheHeaders("HIT", hit.etag);
+                        return cachedAnswer(JSON.stringify(hit.body), hit.etag);
+                    }
+                }
+                const handlerHeaders = [];
                 let status = 0;
                 const ctx = {
                     body,
@@ -453,30 +609,67 @@ export function createApp(config = {}) {
                     user,
                     get db() {
                         // Built on first use: after a timeout, new queries fail with IL2007 instead of running.
-                        return (requestDb ??= bindDb(models, guardAdapter(adapter, timeout.signal)));
+                        // Tenant-scoped tables are filtered by the signed-in user's tenant (none without one).
+                        return (requestDb ??= bindDb(models, guardAdapter(adapter, timeout.signal), tenantScope(user)));
+                    },
+                    // ctx.ai and ctx.audit are built on first use too, so routes that do not use them pay nothing.
+                    get ai() {
+                        const value = toolsFor(req, signal());
+                        Object.defineProperty(ctx, "ai", { value, enumerable: true });
+                        return value;
+                    },
+                    get signal() {
+                        return signal();
                     },
-                    ai: toolsFor(req, signal),
-                    signal,
                     requestId,
-                    jobs,
+                    // With a tenant, jobs and events queued by the request carry it.
+                    get jobs() {
+                        return tenantQueues().jobs;
+                    },
+                    get events() {
+                        return tenantQueues().events;
+                    },
+                    cache,
                     req,
                     url,
                     headers: req.headers,
                     state,
                     status: (code) => void (status = code),
-                    header: (name, value) => headers.set(name, value),
+                    header: (name, value) => {
+                        // Set-Cookie is added, not replaced, so a handler can set several cookies.
+                        if (name.toLowerCase() === "set-cookie")
+                            headers.append(name, value);
+                        else
+                            headers.set(name, value);
+                        handlerHeaders.push([name.toLowerCase(), value]);
+                    },
                     waitUntil: (p) => void pending.push(p.catch((e) => logger.error("waitUntil task failed", e, { requestId }))),
+                    get audit() {
+                        const value = createAudit(models, redactor, () => ctx.db, { userId: user?.id ?? null, tenantId: tenantOf(tenantScope(user)), source: `${def.method} ${def.path}`, requestId });
+                        Object.defineProperty(ctx, "audit", { value, enumerable: true });
+                        return value;
+                    },
                 };
                 const result = await def.handler(ctx);
                 if (result instanceof Response) {
                     headers.forEach((v, k) => {
-                        if (!result.headers.has(k))
+                        if (k !== "set-cookie" && !result.headers.has(k))
                             result.headers.set(k, v);
                     });
+                    for (const cookie of headers.getSetCookie())
+                        result.headers.append("set-cookie", cookie);
                     return result;
                 }
                 if (result === undefined)
                     return new Response(null, { status: status || 204, headers });
+                // Only plain 200 JSON answers are cached, never one that sets a cookie.
+                if (cacheKey && (status || 200) === 200 && !handlerHeaders.some(([name]) => name === "set-cookie")) {
+                    const body = JSON.stringify(result);
+                    const etag = await etagFor(body);
+                    await cache.set(cacheKey, { body: JSON.parse(body), headers: handlerHeaders, etag }, { ttlMs: routeCache.ttlMs, tags: routeCache.tags ?? [] });
+                    cacheHeaders("MISS", etag);
+                    return cachedAnswer(body, etag);
+                }
                 const response = json(result, status || 200, headers);
                 return method === "HEAD" ? new Response(null, { status: response.status, headers: response.headers }) : response;
             };
@@ -540,8 +733,29 @@ export function createApp(config = {}) {
         }
     };
     async function handle(req, rest) {
-        const started = performance.now();
         const url = new URL(req.url);
+        // Health and metrics endpoints are called every few seconds by load balancers and scrapers: not logged, counted or traced.
+        const probe = url.pathname === health?.path || url.pathname === health?.readyPath || url.pathname === metricsConfig?.path;
+        if (!tracing || probe)
+            return handleTraced(req, rest, url, probe, undefined);
+        return tracing.run(req, url, async (span) => {
+            requestSpans.set(req, span);
+            let status = 500;
+            try {
+                const response = await handleTraced(req, rest, url, probe, span);
+                status = response.status;
+                return response;
+            }
+            finally {
+                span.setAttribute("http.response.status_code", status);
+                if (status >= 500)
+                    span.setStatus({ code: tracingApi.SpanStatusCode.ERROR });
+                span.end();
+            }
+        });
+    }
+    async function handleTraced(req, rest, url, probe, span) {
+        const started = performance.now();
         // Behind a trusted proxy, keep the id it sent so log entries line up across services.
         const incoming = config.trustProxy ? req.headers.get("x-request-id") : null;
         const requestId = incoming && REQUEST_ID.test(incoming) ? incoming : crypto.randomUUID();
@@ -567,15 +781,17 @@ export function createApp(config = {}) {
             response = errorResponse(error, new Headers(), req, requestId);
         }
         response = withHeader(response, "x-request-id", requestId);
-        // Health and metrics endpoints are called every few seconds by load balancers and scrapers: not logged or counted.
-        const probe = url.pathname === health?.path || url.pathname === health?.readyPath || url.pathname === metricsConfig?.path;
+        if (span && seen.route !== "unmatched") {
+            span.updateName(`${req.method.toUpperCase()} ${seen.route}`);
+            span.setAttribute("http.route", seen.route);
+        }
         if (!probe) {
             const elapsed = performance.now() - started;
             const method = req.method.toUpperCase();
             metrics?.request(method, seen.route, response.status, elapsed / 1000);
             if (logging.requests) {
                 const durationMs = Math.round(elapsed * 10) / 10;
-                logger.info(`${method} ${url.pathname} ${response.status} ${durationMs}ms`, undefined, { requestId, method, path: url.pathname, status: response.status, durationMs });
+                logger.info(`${method} ${url.pathname} ${response.status} ${durationMs}ms`, undefined, { requestId, ...traceFields(span), method, path: url.pathname, status: response.status, durationMs });
             }
         }
         if (secureHeaders.length) {
@@ -584,9 +800,9 @@ export function createApp(config = {}) {
         }
         if (pending.length) {
             const all = Promise.all(pending);
-            const execution = rest[1];
-            if (execution?.waitUntil)
-                execution.waitUntil(all);
+            const execution = platformWaitUntil(rest);
+            if (execution)
+                execution(all);
             else {
                 // Kept until it settles, so app.close() waits for it.
                 tasks.add(all);
@@ -603,9 +819,12 @@ export function createApp(config = {}) {
         version: config.version ?? "0.0.0",
         routes,
         models,
+        modules,
         db,
         ai,
         jobs,
+        events,
+        cache,
         get closing() {
             return closing;
         },
@@ -613,7 +832,10 @@ export function createApp(config = {}) {
             inFlight++;
             metrics?.inFlight(1);
             try {
-                return await handle(req, rest);
+                const response = await handle(req, rest);
+                if (rest.length)
+                    keepEventStreamOpen(rest[0], req, response);
+                return response;
             }
             finally {
                 inFlight--;
@@ -706,15 +928,37 @@ export function createApp(config = {}) {
                 requestTimeoutMs,
                 logging: { format: config.logger ? "custom" : logging.format, requests: logging.requests },
                 description: config.description,
+                modules: moduleInfo,
+                versions: versions.map((v) => ({ name: v, openapi: openapiPath ? versionDocPath(v, openapiPath) : false })),
+                permissions: config.permissions?.list.map((p) => (p.roles ? { name: p.name, roles: [...p.roles] } : { name: p.name })) ?? [],
             });
         },
-        openapi() {
-            return buildOpenAPI(app, { description: config.description, auth: Boolean(config.auth) });
+        openapi(options = {}) {
+            if (options.version !== undefined && !versions.includes(options.version)) {
+                throw new InferloError("IL6025", `The app has no API version ${JSON.stringify(options.version)}.${versions.length ? ` Its versions: ${versions.join(", ")}.` : " It has no apiVersion() routes."}`, {
+                    fix: 'Pass a version used in apiVersion("v1", routes), or call app.openapi() for every route.',
+                });
+            }
+            return buildOpenAPI(app, { description: config.description, auth: Boolean(config.auth), modules: moduleInfo, version: options.version });
         },
     };
+    // Built-in endpoints with the methods dispatch answers them for (MCP takes every method).
+    const readEndpoints = [health?.path, health?.readyPath, metricsConfig?.path].filter((p) => typeof p === "string");
+    registerRequestMatcher(app, (rawMethod, pathname) => {
+        const method = rawMethod.toUpperCase();
+        if (mcpPath && pathname === mcpPath)
+            return true;
+        if (method === "GET" && ((openapiPath && pathname === openapiPath) || versionDocs.has(pathname)))
+            return true;
+        if ((method === "GET" || method === "HEAD") && readEndpoints.includes(pathname))
+            return true;
+        const lookup = method === "HEAD" ? "GET" : method;
+        // A CORS preflight belongs to the app when any of its routes has this path.
+        return compiled.some((c) => (method === "OPTIONS" || c.def.method === lookup) && c.regex.test(pathname));
+    });
     return app;
 }
-function resolveHealth(option, routes, taken) {
+function resolveHealth(option, routes, taken, builtIn) {
     if (option === undefined || option === false)
         return undefined;
     const bad = (message, fix) => new InferloError("IL6014", message, { fix });
@@ -731,9 +975,9 @@ function resolveHealth(option, routes, taken) {
     if (!Number.isFinite(resolved.timeoutMs) || resolved.timeoutMs <= 0)
         throw bad(`health.timeoutMs must be a positive number of milliseconds, got ${String(resolved.timeoutMs)}.`, "Use health: { timeoutMs: 5000 }.");
     if (typeof resolved.checks !== "object" || resolved.checks === null)
-        throw bad("health.checks must be an object of functions.", "Use health: { checks: { redis: () => redis.ping() } }.");
+        throw bad("health.checks must be an object of functions.", "Use health: { checks: { search: () => search.ping() } }.");
     for (const [name, check] of Object.entries(resolved.checks)) {
-        if (name === "database" || name === "ai")
+        if (name === "database" || name === "ai" || builtIn.includes(name))
             throw bad(`health.checks.${name} is built in.`, `Give your check another name, for example "${name}Replica".`);
         if (typeof check !== "function")
             throw bad(`health.checks.${name} must be a function.`, `Use health: { checks: { ${name}: async () => { ... } } }; throw when it is not ready.`);