@browserlessapi/inferlo 0.5.0 → 0.6.0

package/dist/app.js

@@ -4,21 +4,28 @@
  */
 import { bindTools, createAI } from "./ai/index.js";
 import { memory } from "./db/memory.js";
+import { createAudit } from "./audit.js";
+import { checkRouteCache, createCache, databaseCacheStore, etagFor, etagMatches, memoryCacheStore, resolveCacheConfig, routeCacheKey } from "./cache.js";
 import { bindDb, 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 { 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 { 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 +52,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)
@@ -138,7 +122,12 @@ export function createApp(config = {}) {
     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 +144,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 +177,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)
@@ -201,32 +218,59 @@ export function createApp(config = {}) {
     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]);
+    // 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 cacheConfig = resolveCacheConfig(config.cache);
+    const cache = createCache(cacheConfig.store === "database" ? databaseCacheStore(adapter) : memoryCacheStore(cacheConfig.maxEntries), 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 jobs = createJobs(collectJobs(jobSources), {
         db: db,
         ai,
+        cache,
+        audit: (run) => createAudit(models, redactor, () => db, { userId: null, source: `job ${run.name}` }),
         store: jobStoreFor(config.jobQueue, adapter),
         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,
+    }, collectCrons(jobSources));
     const maxBody = config.maxBodySize ?? 1024 * 1024;
     const secureHeaders = resolveSecureHeaders(config.secureHeaders);
     const cors = config.cors === true ? { origin: "*" } : config.cors || undefined;
@@ -307,7 +351,10 @@ export function createApp(config = {}) {
     }, describeTool, signal);
     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 +376,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 +399,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;
@@ -406,6 +473,8 @@ export function createApp(config = {}) {
                     if (level !== "user" && !roles(user).includes(level))
                         throw new InferloError("IL3002", `This requires the "${level}" role.`, { status: 403 });
                 }
+                if (opts.permission)
+                    await config.permissions.authorize(opts.permission, { user });
                 // 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.rateLimit) {
                     const who = (opts.rateLimit.by ?? "user") === "user" && user ? `user:${user.id}` : `ip:${ip}`;
@@ -432,8 +501,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 +518,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) : 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") === "user")
+                        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,
@@ -459,24 +560,43 @@ export function createApp(config = {}) {
                     signal,
                     requestId,
                     jobs,
+                    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 }))),
+                    audit: createAudit(models, redactor, () => ctx.db, { userId: user?.id ?? null, source: `${def.method} ${def.path}`, requestId }),
                 };
                 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 +660,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 +708,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) {
@@ -603,9 +746,11 @@ export function createApp(config = {}) {
         version: config.version ?? "0.0.0",
         routes,
         models,
+        modules,
         db,
         ai,
         jobs,
+        cache,
         get closing() {
             return closing;
         },
@@ -706,12 +851,34 @@ 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) {