@browserlessapi/inferlo 0.7.0 → 0.8.0

package/README.md

@@ -47,7 +47,7 @@ That one model definition gives you the database table, insert and update valida
 - **Embeddings** for search and recommendations.
 - **Usage, cost and budgets.** Every call is tracked per user, so you can bill customers and stop calls when their credits run out.
 - **MCP server.** Mark a route `tool: true` and AI agents can call your API, with the same permissions as any other client.
-- **Use it in any framework.** `import { createAI } from "@browserlessapi/inferlo/ai"` gives you the same AI module without `createApp`, for Express, Hono, Fastify, NestJS or a plain script, and `toNodeHandler(app, { prefix: "/ai" })` mounts a whole Inferlo app (routes, OpenAPI, MCP) inside Express, Fastify, NestJS or `node:http`, `hono.use(inferloAI(ai))` from `@browserlessapi/inferlo/hono` gives Hono handlers `c.var.ai`, `server.use(inferloAI(ai))` from `@browserlessapi/inferlo/express` gives Express handlers `req.ai`, and `fastify.register(inferloPlugin, { ai })` from `@browserlessapi/inferlo/fastify` gives Fastify `request.ai`, `server.register({ plugin: inferloPlugin, options: { ai } })` from `@browserlessapi/inferlo/hapi` gives hapi `request.ai` (and `options: { app }` with `routes: { prefix }` serves a whole Inferlo app), `new Elysia().use(inferloAI(ai))` from `@browserlessapi/inferlo/elysia` gives Elysia handlers `ai`, `InferloModule.forRoot({ ai })` from `@browserlessapi/inferlo/nestjs` makes the AI client injectable in NestJS, the provider from `@browserlessapi/inferlo/adonisjs` gives AdonisJS routes `ctx.ai`, `@Configuration({ imports: [inferloAI(ai)] })` from `@browserlessapi/inferlo/tsed` makes the AI client injectable in Ts.ED as `InferloAI`, `trpc.procedure.use(inferloAI(ai))` from `@browserlessapi/inferlo/trpc` gives tRPC procedures `ctx.ai` while `trpcTools(router, { caller, procedures })` lets a model call tRPC procedures as tools, `koa.use(inferloAI(ai))` and `koa.use(toKoaMiddleware(app, { prefix: "/api" }))` from `@browserlessapi/inferlo/koa` give Koa `ctx.ai` and a whole Inferlo app, `export const { GET, POST } = toNextHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/nextjs` serves a whole Inferlo app from a Next.js App Router route, `export default toH3Handler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/h3` serves it from a Nuxt or Nitro server route (with `event.context.ai` from a Nitro plugin), `export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/sveltekit` serves it from a SvelteKit rest route (with `event.locals.ai` from a handle hook), `export const ALL = toAstroHandler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/astro` serves it from an Astro endpoint (with `locals.ai` from a middleware), `export const { loader, action } = toReactRouterHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/react-router` serves it from a React Router (Remix) resource route, `export const handler = toLambdaHandler(app)` from `@browserlessapi/inferlo/lambda` runs it on AWS Lambda (function URLs and API Gateway, with response streaming), `handler: toAzureHandler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/azure` runs it in an Azure Functions HTTP trigger (with streaming), `functions.http("inferlo", toNodeHandler(app))` runs it as a Google Cloud Run function, `export default app` runs it as a Cloudflare Worker or a Vercel Function and `export default app.fetch` as a Netlify Function, and an Encore.ts raw endpoint serves a whole Inferlo app with `api.raw({ expose: true, method: "*", path: "/inferlo/*rest" }, toNodeHandler(app, { prefix: "/inferlo" }))` An app that already uses Drizzle ORM adds Inferlo on the same Postgres pool, with Drizzle and Inferlo writes in one transaction through `tx.$pgClient()` (see [Use with other frameworks](docs/integrations.md)).
+- **Use it in any framework.** `import { createAI } from "@browserlessapi/inferlo/ai"` gives you the same AI module without `createApp`, for Express, Hono, Fastify, NestJS or a plain script, and `toNodeHandler(app, { prefix: "/ai" })` mounts a whole Inferlo app (routes, OpenAPI, MCP) inside Express, Fastify, NestJS or `node:http`, `hono.use(inferloAI(ai))` from `@browserlessapi/inferlo/hono` gives Hono handlers `c.var.ai`, `server.use(inferloAI(ai))` from `@browserlessapi/inferlo/express` gives Express handlers `req.ai`, and `fastify.register(inferloPlugin, { ai })` from `@browserlessapi/inferlo/fastify` gives Fastify `request.ai`, `server.register({ plugin: inferloPlugin, options: { ai } })` from `@browserlessapi/inferlo/hapi` gives hapi `request.ai` (and `options: { app }` with `routes: { prefix }` serves a whole Inferlo app), `new Elysia().use(inferloAI(ai))` from `@browserlessapi/inferlo/elysia` gives Elysia handlers `ai`, `InferloModule.forRoot({ ai })` from `@browserlessapi/inferlo/nestjs` makes the AI client injectable in NestJS, the provider from `@browserlessapi/inferlo/adonisjs` gives AdonisJS routes `ctx.ai`, `@Configuration({ imports: [inferloAI(ai)] })` from `@browserlessapi/inferlo/tsed` makes the AI client injectable in Ts.ED as `InferloAI`, `trpc.procedure.use(inferloAI(ai))` from `@browserlessapi/inferlo/trpc` gives tRPC procedures `ctx.ai` while `trpcTools(router, { caller, procedures })` lets a model call tRPC procedures as tools, `koa.use(inferloAI(ai))` and `koa.use(toKoaMiddleware(app, { prefix: "/api" }))` from `@browserlessapi/inferlo/koa` give Koa `ctx.ai` and a whole Inferlo app, `export const { GET, POST } = toNextHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/nextjs` serves a whole Inferlo app from a Next.js App Router route, `export default toH3Handler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/h3` serves it from a Nuxt or Nitro server route (with `event.context.ai` from a Nitro plugin), `export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/sveltekit` serves it from a SvelteKit rest route (with `event.locals.ai` from a handle hook), `export const ALL = toAstroHandler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/astro` serves it from an Astro endpoint (with `locals.ai` from a middleware), `export const { loader, action } = toReactRouterHandlers(app, { prefix: "/api" })` from `@browserlessapi/inferlo/react-router` serves it from a React Router (Remix) resource route, `export const handler = toLambdaHandler(app)` from `@browserlessapi/inferlo/lambda` runs it on AWS Lambda (function URLs and API Gateway, with response streaming), `handler: toAzureHandler(app, { prefix: "/api" })` from `@browserlessapi/inferlo/azure` runs it in an Azure Functions HTTP trigger (with streaming), `functions.http("inferlo", toNodeHandler(app))` runs it as a Google Cloud Run function, `export default app` runs it as a Cloudflare Worker or a Vercel Function and `export default app.fetch` as a Netlify Function, and an Encore.ts raw endpoint serves a whole Inferlo app with `api.raw({ expose: true, method: "*", path: "/inferlo/*rest" }, toNodeHandler(app, { prefix: "/inferlo" }))` An app that already uses Drizzle ORM or Prisma adds Inferlo on the same Postgres pool, with Drizzle and Inferlo writes in one transaction through `tx.$pgClient()` (see [Use with other frameworks](docs/integrations.md)).
 - **Background jobs for slow AI work.** Queue a typed job from a route with `ctx.jobs.enqueue(...)` and it runs after the response, with retries, from a Postgres queue shared by every instance (`inferlo worker` runs them in their own process), and schedule jobs with `cron("0 3 * * *", job)`.
 
 ## Why Inferlo
@@ -98,7 +98,7 @@ npm install @browserlessapi/inferlo
 
 ## Features
 
-- **Routing:** `route.get/post/put/patch/delete`, typed path params, query coercion, CORS, middleware, body limits
+- **Routing:** `route.get/post/put/patch/delete`, typed path params, query coercion, CORS, middleware, body limits, WebSockets with `route.ws(path, { message })` on Node.js, Bun and Deno
 - **Schemas:** `t.string()`, `t.email()`, `t.enum()`, `t.ref()`, ... with `.optional()`, `.default()`, `.pick()`, `.partial()`, JSON Schema output
 - **Database:** typed tables (`db.tickets.findMany(...)`), PostgreSQL and in-memory adapters, `inferlo db push`, versioned migrations (`inferlo db migrate`), transactions, unique and foreign keys
 - **Auth:** `auth.resolve(req)`, `bearer()` API keys, roles, password hashing with Web Crypto
@@ -121,6 +121,7 @@ npm install @browserlessapi/inferlo
 - [Modules](docs/modules.md)
 - [Service-to-service calls](docs/services.md)
 - [Caching](docs/caching.md)
+- [File storage](docs/storage.md)
 - [Redis](docs/redis.md)
 - [MCP, OpenAPI and describe](docs/mcp.md)
 - [CLI](docs/cli.md)

package/dist/app.d.ts

@@ -3,12 +3,15 @@
  * fetch(Request) => Response handler that runs on Node, Bun, Deno and edge runtimes.
  */
 import { type AI, type AIConfig } from "./ai/index.ts";
+import { type Storage, type StorageStore } from "./storage.ts";
 import { type Cache, type CacheConfig } from "./cache.ts";
 import { type Db } from "./db/table.ts";
 import type { Adapter } from "./db/types.ts";
 import { type AppDescription } from "./describe.ts";
 import type { AnyModel } from "./model.ts";
 import { type AppDb, type AppUser, type Method, type RouteDef } from "./route.ts";
+import { type AppSockets } from "./sockets.ts";
+import { type SocketsConfig } from "./redis-sockets.ts";
 import { type RedisClient } from "./redis.ts";
 import { type RateLimitConfig } from "./rate-limit.ts";
 import { type AppJobs, type JobQueueConfig, type JobSource } from "./jobs.ts";
@@ -118,6 +121,11 @@ export interface AppConfig<Models extends readonly AnyModel[], Modules extends r
      * table inferlo_cache) or { store: "redis" } (createApp({ redis })), both shared by every instance.
      */
     cache?: CacheConfig;
+    /**
+     * Where ctx.storage and app.storage keep files: diskStorage({ dir: "./uploads" }), memoryStorage() in tests, or
+     * your own StorageStore. Without it, ctx.storage throws IL6037.
+     */
+    storage?: StorageStore;
     /** Database adapter. Default: memory(). Use postgres() from "@browserlessapi/inferlo/postgres" in production. */
     db?: Adapter;
     auth?: AuthConfig;
@@ -138,6 +146,12 @@ export interface AppConfig<Models extends readonly AnyModel[], Modules extends r
      * after app.close().
      */
     redis?: RedisClient;
+    /**
+     * WebSocket broadcasts across instances: { transport: "redis", subscriber: await redis.duplicate().connect() }
+     * publishes every sockets.broadcast through Redis Pub/Sub (needs redis and name), so it reaches the sockets of
+     * every instance. Default: broadcasts reach the sockets of this process only.
+     */
+    sockets?: SocketsConfig;
     /**
      * Where route rateLimit counts are kept: { store: "memory" } (default), { store: "database" } (Postgres) or
      * { store: "redis" } (createApp({ redis })), both shared by every instance.
@@ -165,6 +179,12 @@ export interface AppConfig<Models extends readonly AnyModel[], Modules extends r
      * 503 IL2007 and ctx.signal is aborted. Routes can set their own timeoutMs. false turns it off. Default 60000.
      */
     requestTimeoutMs?: number | false;
+    /**
+     * Check each JSON answer of a route with a response schema against it: "warn" logs IL2016 once per route,
+     * "error" answers 500 IL2016 (for tests), false skips the check. Default: "warn", or false when the environment
+     * (INFERLO_ENV, then NODE_ENV) is "production".
+     */
+    validateResponses?: "warn" | "error" | false;
     /**
      * More values to hide from logs, besides credentials Inferlo finds itself (authorization and cookie headers,
      * tokens, API keys, passwords in URLs) and the AI provider keys: your config() result (its secrets) or
@@ -219,6 +239,10 @@ export interface App<Models extends readonly AnyModel[]> {
     readonly events: AppEvents;
     /** The app cache, the same as ctx.cache: await app.cache.getOrSet(key, { ttlMs, tags }, compute), app.cache.invalidate(tag). */
     readonly cache: Cache;
+    /** Files, the same as ctx.storage: await app.storage.put(key, file), app.storage.get(key), app.storage.delete(key). */
+    readonly storage: Storage;
+    /** WebSocket rooms: await app.sockets.broadcast(room, data, { tenantId }) sends to the sockets that joined it in this process. */
+    readonly sockets: AppSockets;
     /** Standard fetch handler: export default app works on Bun, Deno and Cloudflare Workers. */
     fetch(req: Request, ...rest: unknown[]): Promise<Response>;
     /** In-process request for tests: await app.request("/tickets", { method: "POST", json: {...}, as: user }). */

package/dist/app.js

@@ -5,6 +5,8 @@
 import { bindTools, createAI } from "./ai/index.js";
 import { memory } from "./db/memory.js";
 import { createAudit } from "./audit.js";
+import { readEnv } from "./env.js";
+import { checkStorageStore, createStorage } from "./storage.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";
@@ -12,15 +14,19 @@ import { InferloError, didYouMean, suggest } from "./errors.js";
 import { callTool, handleMcp, toolDefinition } from "./mcp.js";
 import { buildOpenAPI } from "./openapi.js";
 import { collectRoutes } from "./route.js";
+import { createSocketHub } from "./sockets.js";
+import { checkSocketsConfig, redisSocketRelay } from "./redis-sockets.js";
+import { bunUpgrader, denoUpgrader, upgraders, upgrades, validKey } from "./websocket.js";
 import { checkRedisClient, pingRedis, redisCacheStore, redisMissing, redisPrefix, redisRateLimitStore } from "./redis.js";
 import { checkRateLimit, databaseRateLimitStore, memoryRateLimitStore, rateLimitResult, windowMs } from "./rate-limit.js";
 import { clientIp, clientIps, clientSignals, keepEventStreamOpen, platformWaitUntil } from "./client-ip.js";
 import { redisJobStore } from "./redis-jobs.js";
 import { knownBodies } from "./response-body.js";
+import { checkFileContents, checkFileFields, fileBudget, isMultipart, readMultipart } from "./files.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 { Schema, 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";
@@ -67,11 +73,14 @@ function corsHeaders(config, origin) {
     return h;
 }
 async function readBody(req, limit, signal) {
+    return new TextDecoder().decode(await readBytes(req, limit, signal));
+}
+async function readBytes(req, limit, signal) {
     const length = Number(req.headers.get("content-length") ?? "0");
     if (length > limit)
         throw new InferloError("IL2004", `Request body is larger than ${limit} bytes.`, { status: 413 });
     if (!req.body)
-        return "";
+        return new Uint8Array(0);
     const reader = req.body.getReader();
     // Stop reading a slow body once the request timed out.
     signal?.addEventListener("abort", () => void reader.cancel().catch(() => { }), { once: true });
@@ -94,7 +103,7 @@ async function readBody(req, limit, signal) {
         all.set(c, offset);
         offset += c.byteLength;
     }
-    return new TextDecoder().decode(all);
+    return all;
 }
 function queryObject(url) {
     const out = {};
@@ -179,6 +188,14 @@ export function createApp(config = {}) {
         }
         names.set(r.name, r);
     }
+    // Routes with t.file() fields take multipart/form-data bodies up to maxBodySize plus their files' maxBytes.
+    const fileBudgets = new Map();
+    for (const r of routes) {
+        checkFileFields(r);
+        const budget = fileBudget(r.options.body);
+        if (budget > 0)
+            fileBudgets.set(r, budget);
+    }
     const needsAuth = routes.filter((r) => (r.options.auth ?? "user") !== "public");
     if (needsAuth.length && !config.auth) {
         throw new InferloError("IL3003", `${needsAuth.length} route(s) require a signed-in user, but createApp has no auth configured: ${needsAuth.map((r) => `${r.method} ${r.path}`).join(", ")}.`, {
@@ -205,10 +222,20 @@ export function createApp(config = {}) {
     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.websocket)
+            continue;
+        const message = r.options.message;
+        if (message !== undefined && !(message instanceof Schema)) {
+            throw new InferloError("IL6035", `The WebSocket route ${r.path} has a message option that is not a schema.`, { fix: 'Pass a schema: route.ws("/chat", { message: t.object({ text: t.string() }) }).' });
+        }
+    }
     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 })");
+    const validateResponses = resolveValidateResponses(config.validateResponses);
+    const warnedResponses = new Set();
     for (const r of routes)
         if (r.options.timeoutMs !== undefined)
             checkTimeout(r.options.timeoutMs, `${r.method} ${r.path} { timeoutMs }`);
@@ -255,6 +282,7 @@ export function createApp(config = {}) {
         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 storage = createStorage(checkStorageStore(config.storage));
     const metrics = metricsConfig
         ? createMetrics({ app: config.name ?? "inferlo-app", version: config.version ?? "0.0.0", inferlo: INFERLO_VERSION }, metricsConfig.buckets)
         : undefined;
@@ -286,10 +314,14 @@ export function createApp(config = {}) {
     }
     else
         eventTransport = transportOption;
+    const socketSubscriber = checkSocketsConfig(config.sockets, redis, config.name);
+    const socketHub = createSocketHub(socketSubscriber ? redisSocketRelay(redis, socketSubscriber, `${redisPrefix(config.name)}sockets`, (message, error) => logger.error(`WebSocket broadcasts: ${message}`, error ?? "")) : undefined);
     const jobs = createJobs(collectJobs(jobSources), {
         db: db,
         ai,
         cache,
+        storage,
+        sockets: socketHub,
         audit: (run) => createAudit(models, redactor, () => db, { userId: null, tenantId: run.tenantId, source: `job ${run.name}` }),
         store: jobStoreFor(config.jobQueue, adapter, () => {
             if (!redis)
@@ -364,6 +396,11 @@ export function createApp(config = {}) {
                 fix: "Pass routes that are registered in createApp({ routes }) to ai.generate({ tools }).",
             });
         }
+        if (fileBudgets.has(found)) {
+            throw new InferloError("IL1004", `Route ${found.method} ${found.path} takes files, so it cannot be an AI tool (tools send JSON).`, {
+                fix: "Pass routes without t.file() fields to ai.generate({ tools }).",
+            });
+        }
         return toolDefinition(found);
     };
     const describeTool = (route) => {
@@ -408,7 +445,218 @@ export function createApp(config = {}) {
         const message = config.exposeErrors && error instanceof Error ? redactor.text(error.message) : "Internal server error";
         return json({ error: { code: "IL9000", message, docs: new InferloError("IL9000", "").docs } }, 500, headers);
     };
-    const dispatch = async (req, url, state, pending, ip, requestId, seen) => {
+    // Rate limit counts are kept per route and per user, tenant or IP. by "tenant" counts users without a tenant one by
+    // one; by "user" and "tenant" count requests without a user by IP.
+    const rateLimitKey = (def, user, ip) => {
+        const by = def.options.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}`;
+        return `${def.method} ${def.path} ${who}`;
+    };
+    // Open WebSockets, closed with 1001 by app.close().
+    const sockets = new Set();
+    const encoder = new TextEncoder();
+    /** The JSON error message a socket gets when one of its messages fails (the same body as an HTTP error answer). */
+    const socketError = (error, def, requestId) => {
+        if (error instanceof InferloError) {
+            if (error.status >= 500)
+                logger.error(`WS ${def.path} message failed: ${error.format()}`, error.cause ?? "", { requestId });
+            const body = error.toJSON();
+            if (config.exposeErrors && !error.expose)
+                body.error.message = redactor.text(error.message);
+            return body;
+        }
+        logger.error(`WS ${def.path} message failed`, error, { requestId });
+        const message = config.exposeErrors && error instanceof Error ? redactor.text(error.message) : "Internal server error";
+        return { error: { code: "IL9000", message, docs: new InferloError("IL9000", "").docs } };
+    };
+    /** Checks the upgrade request of a WebSocket route (after auth, permissions, rate limits and input) and accepts it. */
+    const acceptSocket = async (def, req, url, headers, rest, conn) => {
+        if (req.method.toUpperCase() !== "GET" || req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+            headers.set("upgrade", "websocket");
+            throw new InferloError("IL2010", `${def.path} is a WebSocket route: open it with a WebSocket client.`, { status: 426, fix: `Connect with new WebSocket("wss://<host>${def.path}"); plain HTTP requests are not answered.` });
+        }
+        if (req.headers.get("sec-websocket-version") !== "13" || !validKey(req.headers.get("sec-websocket-key"))) {
+            headers.set("sec-websocket-version", "13");
+            throw new InferloError("IL2010", "Invalid WebSocket handshake.", { status: 400, fix: "Use a WebSocket client that speaks RFC 6455 (Sec-WebSocket-Version: 13 with a Sec-WebSocket-Key)." });
+        }
+        // Browsers send cookies with WebSocket upgrades from any page, so only the app's own origin (and the origins
+        // allowed by createApp({ cors })) may connect. Clients without an Origin header (servers, CLIs) may.
+        const origin = req.headers.get("origin");
+        if (origin !== null && !socketOriginAllowed(origin, req, url)) {
+            throw new InferloError("IL3006", `Connections from the origin ${origin} are not allowed.`, { status: 403, fix: "Open the socket from a page of the app's own origin, or list the page's origin in createApp({ cors: { origin: [...] } })." });
+        }
+        const upgrader = upgraders.get(req) ?? denoUpgrader(req, rest[0]) ?? bunUpgrader(req, rest[0]);
+        if (!upgrader) {
+            throw new InferloError("IL2011", "This server cannot accept WebSocket connections.", {
+                status: 501,
+                fix: 'Serve the app with app.listen() or serve(app), with Deno.serve(app.fetch) or deno serve on Deno, or with Bun.serve({ fetch: app.fetch, websocket: bunWebSocket }) on Bun. On a Node.js server another framework created, add server.on("upgrade", toNodeUpgradeHandler(app)). app.request() cannot upgrade: test against await app.listen(0).',
+            });
+        }
+        // With sockets: { transport: "redis" }, the first connection subscribes this instance to the app's broadcasts.
+        await socketHub.ready();
+        const response = await upgrader((transport) => openSocket(def, req, url, transport, conn));
+        upgrades.set(req, response ?? null);
+        // On Node.js and Bun the server already answered the handshake; this response is never sent.
+        return response ?? new Response(null, { status: 200, headers });
+    };
+    const socketOriginAllowed = (origin, req, url) => {
+        try {
+            if (new URL(origin).host === (req.headers.get("host") ?? url.host))
+                return true;
+        }
+        catch {
+            return false;
+        }
+        if (!cors)
+            return false;
+        return cors.origin === "*" || (Array.isArray(cors.origin) ? cors.origin : [cors.origin]).includes(origin);
+    };
+    /** One open WebSocket: runs the route's handler for each message, in order. */
+    const openSocket = (def, req, url, transport, conn) => {
+        const { user, requestId, ip } = conn;
+        const opts = def.options;
+        const closed = new AbortController();
+        let open = true;
+        const member = {
+            sendText: (text) => {
+                if (open)
+                    transport.send(text);
+            },
+        };
+        const finish = () => {
+            closed.abort();
+            sockets.delete(shutdown);
+            socketHub.drop(member);
+        };
+        const end = (code, reason) => {
+            if (!open)
+                return;
+            open = false;
+            transport.close(code, reason);
+            finish();
+        };
+        const shutdown = () => end(1001, "Server shutting down");
+        sockets.add(shutdown);
+        socketHub.open(member);
+        const scope = tenantScope(user);
+        const socket = {
+            id: crypto.randomUUID(),
+            send: (data) => {
+                if (open)
+                    transport.send(JSON.stringify(data));
+            },
+            close: (code = 1000, reason = "") => {
+                if (!(code === 1000 || (Number.isInteger(code) && code >= 3000 && code <= 4999))) {
+                    throw new InferloError("IL2012", `Invalid WebSocket close code ${String(code)}.`, { fix: "Close with 1000 (normal), or an application code from 3000 to 4999: socket.close(4000, \"reason\")." });
+                }
+                end(code, reason);
+            },
+            join: (room) => socketHub.join(member, room, tenantOf(scope)),
+            leave: (room) => socketHub.leave(member, room, tenantOf(scope)),
+            stream: async (result) => {
+                if (!result || typeof result[Symbol.asyncIterator] !== "function" || typeof result.usage !== "function") {
+                    throw new InferloError("IL2013", "socket.stream() takes the result of ai.stream(...).", { fix: 'Pass the stream itself: await socket.stream(ai.stream({ model: "fast", prompt })).' });
+                }
+                let text = "";
+                // After the socket closes, sends do nothing; with ctx.ai the stream itself is cancelled by ctx.signal.
+                for await (const chunk of result) {
+                    text += chunk;
+                    socket.send({ type: "text", text: chunk });
+                }
+                const usage = await result.usage();
+                socket.send({ type: "done", usage });
+                return { text, usage };
+            },
+        };
+        let socketDb;
+        let socketRooms;
+        let queues;
+        const tenantQueues = () => (queues ??= typeof scope === "object" ? withTenant({ jobs, events }, scope.tenant) : { jobs, events });
+        const handleMessage = async (data) => {
+            if (typeof data !== "string")
+                return end(1003, "Send JSON text messages");
+            if (data.length > maxBody / 3 && encoder.encode(data).byteLength > maxBody)
+                return end(1009, "Message too big");
+            try {
+                let raw;
+                try {
+                    raw = JSON.parse(data);
+                }
+                catch {
+                    throw new InferloError("IL2003", "Message is not valid JSON.", { status: 400, fix: "Send each message as JSON text: socket.send(JSON.stringify(message))." });
+                }
+                if (opts.rateLimit) {
+                    const limited = rateLimitResult(opts.rateLimit, await rateLimits.hit(rateLimitKey(def, user, ip), windowMs(opts.rateLimit)));
+                    if (limited.error)
+                        throw limited.error;
+                }
+                const message = opts.message ? parseOrThrow(opts.message, raw, "message", false) : raw;
+                const ctx = {
+                    message,
+                    query: conn.query,
+                    params: conn.params,
+                    user,
+                    socket,
+                    get db() {
+                        return (socketDb ??= bindDb(models, adapter, scope));
+                    },
+                    get ai() {
+                        const value = toolsFor(req, closed.signal);
+                        Object.defineProperty(ctx, "ai", { value, enumerable: true });
+                        return value;
+                    },
+                    get jobs() {
+                        return tenantQueues().jobs;
+                    },
+                    get events() {
+                        return tenantQueues().events;
+                    },
+                    cache,
+                    storage,
+                    get sockets() {
+                        return (socketRooms ??= socketHub.forTenant(tenantOf(scope)));
+                    },
+                    get audit() {
+                        const value = createAudit(models, redactor, () => ctx.db, { userId: user?.id ?? null, tenantId: tenantOf(scope), source: `WS ${def.path}`, requestId });
+                        Object.defineProperty(ctx, "audit", { value, enumerable: true });
+                        return value;
+                    },
+                    signal: closed.signal,
+                    requestId,
+                    url,
+                    headers: req.headers,
+                };
+                const result = await def.handler(ctx);
+                if (result !== undefined)
+                    socket.send(result);
+            }
+            catch (error) {
+                if (open)
+                    transport.send(JSON.stringify(socketError(error, def, requestId)));
+            }
+        };
+        let chain = Promise.resolve();
+        return {
+            message(data) {
+                if (!open)
+                    return;
+                // One message at a time, in order; app.close() waits for the one running.
+                const next = chain.then(() => (open ? handleMessage(data) : undefined));
+                chain = next;
+                tasks.add(next);
+                void next.finally(() => {
+                    tasks.delete(next);
+                    settle();
+                });
+            },
+            close() {
+                open = false;
+                finish();
+            },
+        };
+    };
+    const dispatch = async (req, url, state, pending, ip, requestId, seen, rest) => {
         const headers = new Headers();
         if (cors)
             for (const [k, v] of Object.entries(corsHeaders(cors, req.headers.get("origin"))))
@@ -530,10 +778,7 @@ export function createApp(config = {}) {
                 // 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 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 hit = await rateLimits.hit(rateLimitKey(def, user, ip), windowMs(opts.rateLimit));
                     const limited = rateLimitResult(opts.rateLimit, hit);
                     for (const [k, v] of Object.entries(limited.headers))
                         headers.set(k, v);
@@ -550,10 +795,24 @@ export function createApp(config = {}) {
                 const params = opts.params ? parseOrThrow(opts.params, rawParams, "path parameters", true) : rawParams;
                 const rawQuery = queryObject(url);
                 const query = opts.query ? parseOrThrow(opts.query.strip(), rawQuery, "query string", true) : rawQuery;
+                // WebSocket routes answer the upgrade here; their handler then runs once per message.
+                if (def.websocket)
+                    return await acceptSocket(def, req, url, headers, rest, { user, params, query, requestId, ip });
                 let body;
-                if (opts.body) {
+                const contentType = req.headers.get("content-type") ?? "";
+                const filesLimit = fileBudgets.get(def);
+                if (opts.body && filesLimit !== undefined && isMultipart(contentType) && method !== "GET" && method !== "HEAD") {
+                    // File uploads: read with the route's limit (maxBodySize plus its files' maxBytes), then check sizes,
+                    // types and file contents before the handler runs.
+                    const bytes = await readBytes(req, maxBody + filesLimit, timeout.signal);
+                    body = parseOrThrow(opts.body, await readMultipart(bytes, contentType, opts.body), "request body", true);
+                    const issues = await checkFileContents(opts.body, body);
+                    if (issues.length)
+                        throw new ValidationError(issues, "request body");
+                }
+                else if (opts.body) {
                     const text = method === "GET" || method === "HEAD" ? "" : await readBody(req, maxBody, timeout.signal);
-                    const type = req.headers.get("content-type") ?? "";
+                    const type = contentType;
                     let raw = undefined;
                     if (text) {
                         if (type.includes("application/x-www-form-urlencoded")) {
@@ -630,6 +889,10 @@ export function createApp(config = {}) {
                         return tenantQueues().events;
                     },
                     cache,
+                    storage,
+                    get sockets() {
+                        return socketHub.forTenant(tenantOf(tenantScope(user)));
+                    },
                     req,
                     url,
                     headers: req.headers,
@@ -662,6 +925,24 @@ export function createApp(config = {}) {
                 }
                 if (result === undefined)
                     return new Response(null, { status: status || 204, headers });
+                if (validateResponses && opts.response && (status || 200) < 300) {
+                    const issues = responseIssues(opts.response, result);
+                    if (issues) {
+                        const where = `${def.method} ${def.path}`;
+                        const summary = issues.slice(0, 5).map((i) => `${i.path.length ? i.path.join(".") : "(root)"}: ${i.message}`).join("; ") + (issues.length > 5 ? ` (and ${issues.length - 5} more)` : "");
+                        if (validateResponses === "error") {
+                            throw new InferloError("IL2016", `${where}: the response does not match the route's response schema. ${summary}`, {
+                                expose: true,
+                                fix: "Return what the route's response schema describes, or change the schema. Fields not in an object schema count as mismatches, so the check also finds fields that should not be sent.",
+                                details: issues.map((i) => ({ path: i.path, code: i.code, message: i.message })),
+                            });
+                        }
+                        if (!warnedResponses.has(def)) {
+                            warnedResponses.add(def);
+                            logger.error(`IL2016 ${where}: the response does not match the route's response schema (sent anyway; logged once per route). ${summary}`, undefined, { requestId });
+                        }
+                    }
+                }
                 // 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);
@@ -770,7 +1051,7 @@ export function createApp(config = {}) {
         const run = (i) => {
             const mw = chain[i];
             if (!mw)
-                return dispatch(req, url, state, pending, ip, requestId, seen);
+                return dispatch(req, url, state, pending, ip, requestId, seen, rest);
             return mw({ req, url, state, requestId }, () => run(i + 1));
         };
         let response;
@@ -788,10 +1069,12 @@ export function createApp(config = {}) {
         if (!probe) {
             const elapsed = performance.now() - started;
             const method = req.method.toUpperCase();
-            metrics?.request(method, seen.route, response.status, elapsed / 1000);
+            // An accepted WebSocket upgrade is logged and counted as the 101 the client gets.
+            const status = upgrades.has(req) ? 101 : response.status;
+            metrics?.request(method, seen.route, status, elapsed / 1000);
             if (logging.requests) {
                 const durationMs = Math.round(elapsed * 10) / 10;
-                logger.info(`${method} ${url.pathname} ${response.status} ${durationMs}ms`, undefined, { requestId, ...traceFields(span), method, path: url.pathname, status: response.status, durationMs });
+                logger.info(`${method} ${url.pathname} ${status} ${durationMs}ms`, undefined, { requestId, ...traceFields(span), method, path: url.pathname, status, durationMs });
             }
         }
         if (secureHeaders.length) {
@@ -825,6 +1108,8 @@ export function createApp(config = {}) {
         jobs,
         events,
         cache,
+        storage,
+        sockets: { broadcast: socketHub.broadcast, count: socketHub.count },
         get closing() {
             return closing;
         },
@@ -833,6 +1118,12 @@ export function createApp(config = {}) {
             metrics?.inFlight(1);
             try {
                 const response = await handle(req, rest);
+                // Deno needs its own upgrade response back, untouched; Bun.serve wants undefined for a request it upgraded.
+                const upgrade = upgrades.get(req);
+                if (upgrade)
+                    return upgrade;
+                if (upgrade === null)
+                    return undefined;
                 if (rest.length)
                     keepEventStreamOpen(rest[0], req, response);
                 return response;
@@ -854,6 +1145,13 @@ export function createApp(config = {}) {
                 body = JSON.stringify(options.json);
                 headers["content-type"] ??= "application/json";
             }
+            if (typeof FormData !== "undefined" && body instanceof FormData) {
+                // Sent as bytes: on Node.js 24, cancelling a request body stream made from FormData (as a too large upload
+                // does) raises an unhandled rejection inside fetch's FormData encoder.
+                const encoded = new Response(body);
+                headers["content-type"] ??= encoded.headers.get("content-type");
+                body = new Uint8Array(await encoded.arrayBuffer());
+            }
             const req = new Request(url, { method: (options.method ?? "GET").toUpperCase(), headers, body });
             if ("as" in options)
                 testUsers.set(req, options.as ?? null);
@@ -897,6 +1195,9 @@ export function createApp(config = {}) {
                 if (delayMs > 0)
                     await new Promise((resolve) => setTimeout(resolve, delayMs));
                 refusing = true;
+                // Open WebSockets are told the server is going away (1001); a message being handled still finishes.
+                for (const shutdown of [...sockets])
+                    shutdown();
                 const deadline = Date.now() + timeoutMs;
                 let workersStopped = false;
                 const drained = Promise.all([whenIdle(), stopWorkers(jobs).then(() => void (workersStopped = true))]);
@@ -912,6 +1213,7 @@ export function createApp(config = {}) {
                     if (!(await within(server.close(), Math.max(0, deadline - Date.now()))))
                         forceClosers?.get(server)?.();
                 }));
+                await socketHub.stop().catch((error) => logger.error("WebSocket broadcasts: unsubscribing failed", error));
                 await db.$close();
             })();
             return closed;
@@ -1004,4 +1306,25 @@ function parseOrThrow(schema, value, where, coerce) {
         throw new ValidationError(result.issues, where);
     return result.value;
 }
+function resolveValidateResponses(value) {
+    if (value === undefined)
+        return (readEnv("INFERLO_ENV") || readEnv("NODE_ENV") || "development") === "production" ? false : "warn";
+    if (value === "warn" || value === "error" || value === false)
+        return value;
+    throw new InferloError("IL6040", `Invalid validateResponses option ${JSON.stringify(value)}.`, {
+        fix: 'Use createApp({ validateResponses: "warn" }) (the default outside production), "error" in tests, or false to turn the check off.',
+    });
+}
+/** The issues of the answer as clients receive it (JSON), or undefined when it matches. */
+function responseIssues(schema, result) {
+    let sent;
+    try {
+        sent = JSON.parse(JSON.stringify(result));
+    }
+    catch {
+        return undefined; // Not JSON: the answer itself fails with its own error.
+    }
+    const parsed = schema.safeParse(sent);
+    return parsed.ok ? undefined : parsed.issues;
+}
 //# sourceMappingURL=app.js.map