@browserlessapi/inferlo 0.6.0 → 0.8.0

package/dist/websocket.d.ts

@@ -0,0 +1,81 @@
+/**
+ * WebSocket plumbing shared by the app (src/app.ts) and the servers (src/serve.ts): the per-request upgrader a server
+ * registers, the record of upgraded requests, Deno's built-in upgrade, and the RFC 6455 frame reader and writer used
+ * on Node.js, where the runtime has no WebSocket server of its own. Web APIs only.
+ */
+/** One open connection, as the app sees it: send a text message, or close with a code and reason. */
+export interface SocketTransport {
+    send(text: string): void;
+    close(code: number, reason: string): void;
+}
+/** What the app does with a connection's events. */
+export interface SocketListener {
+    message(data: string | Uint8Array): void;
+    close(code: number, reason: string): void;
+}
+/**
+ * Accepts the WebSocket upgrade of one request: connects the app's listener to the new connection and returns the
+ * response to answer with (Deno), or undefined when the server answers the handshake itself (Node.js, Bun).
+ */
+export type Upgrader = (connect: (transport: SocketTransport) => SocketListener) => Promise<Response | undefined>;
+/** Set by serve() for each request it can upgrade (Node.js upgrade requests, every Bun request). */
+export declare const upgraders: WeakMap<Request, Upgrader>;
+/** Requests the app upgraded, with Deno's upgrade response (null on Node.js and Bun, which answer it themselves). */
+export declare const upgrades: WeakMap<Request, Response | null>;
+/**
+ * On Deno, a request from Deno.serve (or deno serve), which passes its handler info with a remoteAddr to app.fetch,
+ * can be upgraded with Deno.upgradeWebSocket. Requests made any other way (app.request) cannot.
+ */
+export declare function denoUpgrader(req: Request, info: unknown): Upgrader | undefined;
+type BunSocket = {
+    data: {
+        connect: (transport: SocketTransport) => SocketListener;
+        listener?: SocketListener;
+    };
+    send(text: string): void;
+    close(code?: number, reason?: string): void;
+};
+/**
+ * The websocket handlers for Bun.serve, so a Bun server that runs app.fetch serves the app's WebSocket routes:
+ * Bun.serve({ fetch: app.fetch, websocket: bunWebSocket }). serve() and app.listen() on Bun use them already.
+ */
+export declare const bunWebSocket: {
+    open(ws: BunSocket): void;
+    message(ws: BunSocket, data: string | Uint8Array): void;
+    close(ws: BunSocket, code: number, reason: string): void;
+};
+/** On Bun, app.fetch(req, server) gets the Bun server, whose upgrade() hands the connection to bunWebSocket. */
+export declare function bunUpgrader(req: Request, server: unknown): Upgrader | undefined;
+/** The Sec-WebSocket-Accept value for a client's Sec-WebSocket-Key (RFC 6455 section 4.2.2). */
+export declare function acceptKey(key: string): Promise<string>;
+/** True for a well-formed Sec-WebSocket-Key: 16 random bytes in base64. */
+export declare function validKey(key: string | null): key is string;
+export declare const OP_CONTINUATION = 0;
+export declare const OP_TEXT = 1;
+export declare const OP_BINARY = 2;
+export declare const OP_CLOSE = 8;
+export declare const OP_PING = 9;
+export declare const OP_PONG = 10;
+/** A complete, unmasked server frame. */
+export declare function encodeFrame(opcode: number, payload: Uint8Array): Uint8Array;
+/** A close frame with a status code and a reason (cut to the 123 bytes a close frame has room for). */
+export declare function encodeClose(code: number, reason: string): Uint8Array;
+export interface FrameEvents {
+    /** A complete text (string) or binary (bytes) message. */
+    message(data: string | Uint8Array): void;
+    ping(payload: Uint8Array): void;
+    /** The client's close frame: its code (1005 when it sent none) and reason. */
+    close(code: number, reason: string): void;
+    /** The client broke the protocol: close the connection with this code. */
+    error(code: number, reason: string): void;
+}
+/**
+ * Reads client frames (RFC 6455): masked, possibly fragmented, with ping, pong and close control frames in between.
+ * A message larger than maxMessageBytes is an error (1009), so a client cannot make the server buffer without end.
+ */
+export declare class FrameReader {
+    #private;
+    constructor(maxMessageBytes: number, events: FrameEvents);
+    push(chunk: Uint8Array): void;
+}
+export {};

package/dist/websocket.js

@@ -0,0 +1,251 @@
+/**
+ * WebSocket plumbing shared by the app (src/app.ts) and the servers (src/serve.ts): the per-request upgrader a server
+ * registers, the record of upgraded requests, Deno's built-in upgrade, and the RFC 6455 frame reader and writer used
+ * on Node.js, where the runtime has no WebSocket server of its own. Web APIs only.
+ */
+import { InferloError } from "./errors.js";
+/** Set by serve() for each request it can upgrade (Node.js upgrade requests, every Bun request). */
+export const upgraders = new WeakMap();
+/** Requests the app upgraded, with Deno's upgrade response (null on Node.js and Bun, which answer it themselves). */
+export const upgrades = new WeakMap();
+/**
+ * On Deno, a request from Deno.serve (or deno serve), which passes its handler info with a remoteAddr to app.fetch,
+ * can be upgraded with Deno.upgradeWebSocket. Requests made any other way (app.request) cannot.
+ */
+export function denoUpgrader(req, info) {
+    const deno = globalThis.Deno;
+    if (!deno?.upgradeWebSocket || typeof info !== "object" || info === null || !("remoteAddr" in info))
+        return undefined;
+    return async (connect) => {
+        const { socket, response } = deno.upgradeWebSocket(req);
+        const listener = connect({
+            send: (text) => {
+                if (socket.readyState === 1)
+                    socket.send(text);
+            },
+            close: (code, reason) => socket.close(code, reason),
+        });
+        socket.onmessage = (event) => listener.message(typeof event.data === "string" ? event.data : new Uint8Array(event.data));
+        socket.onclose = (event) => listener.close(event.code, event.reason);
+        socket.onerror = () => { };
+        return response;
+    };
+}
+/**
+ * The websocket handlers for Bun.serve, so a Bun server that runs app.fetch serves the app's WebSocket routes:
+ * Bun.serve({ fetch: app.fetch, websocket: bunWebSocket }). serve() and app.listen() on Bun use them already.
+ */
+export const bunWebSocket = {
+    open(ws) {
+        ws.data.listener = ws.data.connect({ send: (text) => ws.send(text), close: (code, reason) => ws.close(code, reason) });
+    },
+    message(ws, data) {
+        ws.data.listener?.message(typeof data === "string" ? data : new Uint8Array(data));
+    },
+    close(ws, code, reason) {
+        ws.data.listener?.close(code, reason);
+    },
+};
+/** On Bun, app.fetch(req, server) gets the Bun server, whose upgrade() hands the connection to bunWebSocket. */
+export function bunUpgrader(req, server) {
+    if (!globalThis.Bun || typeof server?.upgrade !== "function")
+        return undefined;
+    return async (connect) => {
+        let upgraded;
+        try {
+            upgraded = server.upgrade(req, { data: { connect } });
+        }
+        catch {
+            upgraded = false;
+        }
+        if (!upgraded) {
+            throw new InferloError("IL2011", "This Bun server cannot accept WebSocket connections.", { status: 501, fix: 'Pass the websocket handlers to Bun.serve: Bun.serve({ fetch: app.fetch, websocket: bunWebSocket }), with bunWebSocket from "@browserlessapi/inferlo".' });
+        }
+        return undefined;
+    };
+}
+/** The Sec-WebSocket-Accept value for a client's Sec-WebSocket-Key (RFC 6455 section 4.2.2). */
+export async function acceptKey(key) {
+    const digest = await crypto.subtle.digest("SHA-1", new TextEncoder().encode(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"));
+    let binary = "";
+    for (const byte of new Uint8Array(digest))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** True for a well-formed Sec-WebSocket-Key: 16 random bytes in base64. */
+export function validKey(key) {
+    return typeof key === "string" && /^[A-Za-z0-9+/]{22}==$/.test(key);
+}
+export const OP_CONTINUATION = 0x0;
+export const OP_TEXT = 0x1;
+export const OP_BINARY = 0x2;
+export const OP_CLOSE = 0x8;
+export const OP_PING = 0x9;
+export const OP_PONG = 0xa;
+/** A complete, unmasked server frame. */
+export function encodeFrame(opcode, payload) {
+    const length = payload.byteLength;
+    const headerLength = length < 126 ? 2 : length < 65536 ? 4 : 10;
+    const out = new Uint8Array(headerLength + length);
+    out[0] = 0x80 | opcode;
+    if (length < 126)
+        out[1] = length;
+    else if (length < 65536) {
+        out[1] = 126;
+        out[2] = length >> 8;
+        out[3] = length & 0xff;
+    }
+    else {
+        out[1] = 127;
+        new DataView(out.buffer).setBigUint64(2, BigInt(length));
+    }
+    out.set(payload, headerLength);
+    return out;
+}
+/** A close frame with a status code and a reason (cut to the 123 bytes a close frame has room for). */
+export function encodeClose(code, reason) {
+    const text = new TextEncoder().encode(reason).subarray(0, 123);
+    const payload = new Uint8Array(2 + text.byteLength);
+    payload[0] = code >> 8;
+    payload[1] = code & 0xff;
+    payload.set(text, 2);
+    return encodeFrame(OP_CLOSE, payload);
+}
+/**
+ * Reads client frames (RFC 6455): masked, possibly fragmented, with ping, pong and close control frames in between.
+ * A message larger than maxMessageBytes is an error (1009), so a client cannot make the server buffer without end.
+ */
+export class FrameReader {
+    #buffer = new Uint8Array(0);
+    #parts = [];
+    #size = 0;
+    #opcode = -1;
+    #done = false;
+    #max;
+    #events;
+    #decoder = new TextDecoder("utf-8", { fatal: true });
+    constructor(maxMessageBytes, events) {
+        this.#max = maxMessageBytes;
+        this.#events = events;
+    }
+    push(chunk) {
+        if (this.#done)
+            return;
+        if (this.#buffer.byteLength === 0)
+            this.#buffer = chunk;
+        else {
+            const joined = new Uint8Array(this.#buffer.byteLength + chunk.byteLength);
+            joined.set(this.#buffer);
+            joined.set(chunk, this.#buffer.byteLength);
+            this.#buffer = joined;
+        }
+        while (!this.#done && this.#next())
+            ;
+    }
+    #fail(code, reason) {
+        this.#done = true;
+        this.#events.error(code, reason);
+        return false;
+    }
+    /** Reads one frame from the buffer; false when more bytes are needed or reading stopped. */
+    #next() {
+        const b = this.#buffer;
+        if (b.byteLength < 2)
+            return false;
+        const fin = (b[0] & 0x80) !== 0;
+        const opcode = b[0] & 0x0f;
+        if ((b[0] & 0x70) !== 0)
+            return this.#fail(1002, "Extensions are not supported");
+        if ((b[1] & 0x80) === 0)
+            return this.#fail(1002, "Client frames must be masked");
+        let length = b[1] & 0x7f;
+        let offset = 2;
+        if (length === 126) {
+            if (b.byteLength < 4)
+                return false;
+            length = (b[2] << 8) | b[3];
+            offset = 4;
+        }
+        else if (length === 127) {
+            if (b.byteLength < 10)
+                return false;
+            const big = new DataView(b.buffer, b.byteOffset + 2, 8).getBigUint64(0);
+            if (big > BigInt(this.#max))
+                return this.#fail(1009, "Message too big");
+            length = Number(big);
+            offset = 10;
+        }
+        const control = opcode >= 0x8;
+        if (control && (!fin || length > 125))
+            return this.#fail(1002, "Invalid control frame");
+        if (![OP_CONTINUATION, OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG].includes(opcode))
+            return this.#fail(1002, "Unknown opcode");
+        if (!control && this.#size + length > this.#max)
+            return this.#fail(1009, "Message too big");
+        if (b.byteLength < offset + 4 + length)
+            return false;
+        const mask = b.subarray(offset, offset + 4);
+        const payload = b.slice(offset + 4, offset + 4 + length);
+        for (let i = 0; i < payload.byteLength; i++)
+            payload[i] ^= mask[i & 3];
+        this.#buffer = b.subarray(offset + 4 + length);
+        if (opcode === OP_PING)
+            this.#events.ping(payload);
+        else if (opcode === OP_PONG) {
+            // Answers to pings; nothing to do.
+        }
+        else if (opcode === OP_CLOSE) {
+            if (payload.byteLength === 1)
+                return this.#fail(1002, "Invalid close frame");
+            const code = payload.byteLength >= 2 ? (payload[0] << 8) | payload[1] : 1005;
+            let reason = "";
+            try {
+                reason = this.#decoder.decode(payload.subarray(2));
+            }
+            catch {
+                return this.#fail(1007, "Close reason is not UTF-8");
+            }
+            this.#done = true;
+            this.#events.close(code, reason);
+            return false;
+        }
+        else {
+            if (opcode === OP_CONTINUATION ? this.#opcode === -1 : this.#opcode !== -1)
+                return this.#fail(1002, "Unexpected frame order");
+            if (opcode !== OP_CONTINUATION)
+                this.#opcode = opcode;
+            this.#parts.push(payload);
+            this.#size += length;
+            if (fin) {
+                const data = this.#parts.length === 1 ? this.#parts[0] : concat(this.#parts, this.#size);
+                const kind = this.#opcode;
+                this.#parts = [];
+                this.#size = 0;
+                this.#opcode = -1;
+                if (kind === OP_TEXT) {
+                    let text;
+                    try {
+                        text = this.#decoder.decode(data);
+                    }
+                    catch {
+                        return this.#fail(1007, "Text message is not UTF-8");
+                    }
+                    this.#events.message(text);
+                }
+                else
+                    this.#events.message(data);
+            }
+        }
+        return true;
+    }
+}
+function concat(parts, size) {
+    const out = new Uint8Array(size);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.byteLength;
+    }
+    return out;
+}
+//# sourceMappingURL=websocket.js.map

package/dist/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -11,6 +11,7 @@ Key rules: routes are private unless `auth: "public"`; validate input with `t.*`
 - [Schemas](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/schema.md): t.* types, modifiers, validation, JSON Schema
 - [Models and database](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/database.md): model(), queries, adapters, db push, transactions
 - [Routes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/routes.md): options, handler context, return values, errors, middleware, deprecated routes (Deprecation and Sunset headers), API versions with apiVersion("v1", routes) and an OpenAPI document per version
+- [WebSockets](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/websockets.md): route.ws(path, { message, auth, rateLimit }).handle(fn) with the same auth, permissions and rate limits as HTTP routes, JSON messages validated and handled in order, ctx.socket, origin checks, on Node.js, Bun and Deno
 - [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, permissions() with can() and authorize() and the route permission option, bearer API keys, passwords
 - [AI](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/ai.md): providers, aliases and fallback, structured output, streaming, embeddings, usage and budgets
 - [Modules](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/modules.md): module("billing", { imports, models, routes, jobs, provides }) splits a large app into feature modules with explicit dependencies, createApp({ modules }), checked at startup and shown in describe
@@ -25,6 +26,7 @@ Key rules: routes are private unless `auth: "public"`; validate input with `t.*`
 - [Security](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/security.md): secure defaults and security headers (createApp({ secureHeaders }))
 - [Observability](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/observability.md): request ids (X-Request-Id, ctx.requestId), request logs and JSON logs with createApp({ logging: { format: "json", requests: true } }), your own logger, Prometheus metrics with createApp({ metrics: { token } })
 - [Deployment](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/deploy.md): Node, Bun, Deno, edge, health and readiness endpoints, graceful shutdown with app.close()
+- [Performance](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/performance.md): reproducible throughput and latency benchmark against Fastify, Hono, Express and NestJS (npm run bench:perf) and the latest results
 - [Support policy](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/support.md): semantic versioning, which versions get fixes, LTS after 1.0, deprecation rules and supported runtime, database and framework versions
 - [Error codes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/errors.md): every ILxxxx code with its fix
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserlessapi/inferlo",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The enterprise-ready TypeScript backend framework, with AI models built in: routing, validation, PostgreSQL and migrations, auth, rate limiting, jobs, OpenAPI and MCP, plus Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible models.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,22 @@
       "types": "./dist/ai/public.d.ts",
       "default": "./dist/ai/public.js"
     },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "default": "./dist/astro.js"
+    },
+    "./authjs": {
+      "types": "./dist/authjs.d.ts",
+      "default": "./dist/authjs.js"
+    },
+    "./azure": {
+      "types": "./dist/azure.d.ts",
+      "default": "./dist/azure.js"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth.d.ts",
+      "default": "./dist/better-auth.js"
+    },
     "./elysia": {
       "types": "./dist/elysia.d.ts",
       "default": "./dist/elysia.js"
@@ -79,6 +95,10 @@
       "types": "./dist/nextjs.d.ts",
       "default": "./dist/nextjs.js"
     },
+    "./passport": {
+      "types": "./dist/passport.d.ts",
+      "default": "./dist/passport.js"
+    },
     "./nestjs": {
       "types": "./dist/nestjs.d.ts",
       "default": "./dist/nestjs.js"
@@ -103,9 +123,17 @@
       "types": "./dist/db/postgres.d.ts",
       "default": "./dist/db/postgres.js"
     },
+    "./postgres-js": {
+      "types": "./dist/postgres-js.d.ts",
+      "default": "./dist/postgres-js.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "default": "./dist/langchain.js"
     }
   },
   "bin": {
@@ -121,32 +149,53 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli/main.js",
     "prepare": "npm run build",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk && tsc --noEmit -p examples/with-hono && tsc --noEmit -p examples/with-express && tsc --noEmit -p examples/with-fastify && tsc --noEmit -p examples/with-elysia && tsc --noEmit -p examples/with-nestjs && tsc --noEmit -p examples/with-trpc && tsc --noEmit -p examples/with-adonisjs && tsc --noEmit -p examples/with-tsed && tsc --noEmit -p examples/with-encore && tsc --noEmit -p examples/with-koa && tsc --noEmit -p examples/with-nextjs && tsc --noEmit -p examples/with-nitro && tsc --noEmit -p examples/with-sveltekit && tsc --noEmit -p examples/with-react-router && tsc --noEmit -p examples/with-lambda && tsc --noEmit -p examples/with-hapi",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk && tsc --noEmit -p examples/with-hono && tsc --noEmit -p examples/with-express && tsc --noEmit -p examples/with-fastify && tsc --noEmit -p examples/with-elysia && tsc --noEmit -p examples/with-nestjs && tsc --noEmit -p examples/with-trpc && tsc --noEmit -p examples/with-adonisjs && tsc --noEmit -p examples/with-tsed && tsc --noEmit -p examples/with-encore && tsc --noEmit -p examples/with-koa && tsc --noEmit -p examples/with-nextjs && tsc --noEmit -p examples/with-nitro && tsc --noEmit -p examples/with-sveltekit && tsc --noEmit -p examples/with-react-router && tsc --noEmit -p examples/with-lambda && tsc --noEmit -p examples/with-hapi && tsc --noEmit -p examples/with-azure && tsc --noEmit -p examples/with-cloud-run-functions && tsc --noEmit -p examples/with-cloudflare-workers && tsc --noEmit -p examples/with-vercel && tsc --noEmit -p examples/with-netlify && tsc --noEmit -p examples/with-astro && tsc --noEmit -p examples/with-drizzle && tsc --noEmit -p examples/with-typeorm && tsc --noEmit -p examples/with-kysely && tsc --noEmit -p examples/with-sequelize && tsc --noEmit -p examples/with-knex && tsc --noEmit -p examples/with-postgres-js && tsc --noEmit -p examples/with-mikro-orm && tsc --noEmit -p examples/with-better-auth && node examples/with-prisma/generate.ts && tsc --noEmit -p examples/with-prisma",
     "test": "node --test --test-reporter=spec \"test/**/*.test.ts\" \"examples/*/test/*.test.ts\"",
     "test:bun": "bun test test/",
+    "test:deno": "deno test -A --no-check --ignore=test/tsed.test.ts test/ && deno test -A --no-check --ignore=examples/with-tsed examples/ && deno test -A --no-check --unsafe-proto test/tsed.test.ts examples/with-tsed/",
     "llms": "node scripts/build-llms.ts",
     "check": "npm run typecheck && npm test && node scripts/build-llms.ts --check",
-    "bench": "node bench/run.ts"
+    "bench": "node bench/run.ts",
+    "bench:perf": "node bench/perf/run.ts",
+    "bench:perf:check": "node bench/perf/check.ts"
   },
   "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
     "@opentelemetry/api": ">=1.3.0",
-    "pg": ">=8"
+    "pg": ">=8",
+    "postgres": ">=3.4.0"
   },
   "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
     "@opentelemetry/api": {
       "optional": true
     },
     "pg": {
       "optional": true
+    },
+    "postgres": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@adonisjs/core": "^6.21.0",
+    "@ai-sdk/openai-compatible": "^3.0.85",
+    "@auth/core": "^0.41.3",
+    "@azure/functions": "^4.17.0",
+    "@google-cloud/functions-framework": "^5.0.5",
     "@hapi/hapi": "^21.4.13",
+    "@hono/node-server": "^2.1.6",
+    "@langchain/core": "^1.3.5",
+    "@mikro-orm/core": "^7.2.8",
+    "@mikro-orm/postgresql": "^7.2.8",
     "@nestjs/common": "^12.3.3",
     "@nestjs/core": "^12.3.3",
     "@nestjs/platform-express": "^12.3.3",
     "@opentelemetry/api": "^1.10.0",
+    "@prisma/adapter-pg": "^7.10.1",
+    "@prisma/client": "^7.10.1",
     "@sveltejs/kit": "^2.70.3",
     "@trpc/server": "^11.24.0",
     "@tsed/core": "^8.45.0",
@@ -155,24 +204,47 @@
     "@tsed/platform-http": "^8.45.0",
     "@tsed/platform-params": "^8.45.0",
     "@tsed/schema": "^8.45.0",
+    "@types/autocannon": "^7.12.7",
     "@types/express": "^5.0.6",
+    "@types/express-session": "^1.19.0",
     "@types/koa": "^3.0.3",
     "@types/node": "^22.18.0",
+    "@types/oidc-provider": "^9.13.1",
+    "@types/passport": "^1.0.17",
+    "@types/passport-local": "^1.0.38",
     "@types/pg": "^8.15.0",
+    "ai": "^7.0.163",
+    "astro": "^7.4.7",
+    "autocannon": "^8.0.0",
+    "better-auth": "^1.7.18",
+    "drizzle-orm": "^0.45.4",
     "elysia": "^1.4.30",
     "encore.dev": "^1.58.8",
     "express": "^5.3.0",
+    "express-session": "^1.19.0",
     "fastify": "^5.12.8",
     "h3": "^2.0.8",
     "hono": "^4.13.16",
+    "knex": "^3.3.0",
     "koa": "^3.3.0",
+    "kysely": "^0.29.8",
+    "miniflare": "^4.20260730.0",
     "next": "^16.4.5",
+    "oidc-provider": "^9.13.3",
+    "passport": "^0.7.0",
+    "passport-local": "^1.0.0",
     "pg": "^8.16.0",
+    "postgres": "^4.1.0",
+    "prisma": "^7.10.1",
     "react": "^19.3.1",
     "react-router": "^8.5.1",
+    "redis": "^6.3.1",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
-    "typescript": "^5.9.3"
+    "sequelize": "^6.37.8",
+    "typeorm": "^1.1.2",
+    "typescript": "^5.9.3",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"

package/templates/app/AGENTS.md

@@ -30,24 +30,28 @@ Do not finish until `inferlo check` passes.
 ## Rules
 
 1. **One way to do each thing.** Routes: `route.get/post/put/patch/delete(path, options).handle(fn)`. Validation: `t.*` schemas. Database: `db.<table>.<method>`. AI: `ai.generate` / `ai.stream` / `ai.embed`.
-2. **Routes are private by default.** A route without `auth` needs a signed-in user. Use `auth: "public"` only for routes anyone may call, and `auth: "<role>"` for role checks. Browser sign-in uses cookie sessions: `export const session = sessions({ secret: settings.SESSION_SECRET, user: ({ userId }, { db }) => ... })`, `createApp({ auth: session })`, `await session.signIn(ctx, user.id)` in the login route and `session.signOut(ctx)` in logout; browsers send the CSRF token in `X-CSRF-Token` or a `_csrf` form field on POST, PUT, PATCH and DELETE (403 IL3005 without it).
-3. **Validate every input with a schema.** `body`, `query` and `params` options. Reuse model schemas: `Ticket.pick("title", "body")`, `Ticket.omit("ownerId")`, `.partial()` for PATCH.
+2. **Routes are private by default.** A route without `auth` needs a signed-in user. Use `auth: "public"` only for routes anyone may call, and `auth: "<role>"` for role checks. Browser sign-in uses cookie sessions: `export const session = sessions({ secret: settings.SESSION_SECRET, user: ({ userId }, { db }) => ... })`, `createApp({ auth: session })`, `await session.signIn(ctx, user.id)` in the login route and `session.signOut(ctx)` in logout; browsers send the CSRF token in `X-CSRF-Token` or a `_csrf` form field on POST, PUT, PATCH and DELETE (403 IL3005 without it). Company single sign-on (Okta, Entra ID, Google Workspace, Keycloak) for browser apps is `export const sso = oidc({ issuer, clientId, clientSecret, session, userId: (claims, { db }) => ... })` with `routes: [..., sso]`, ending in that session (sign out with a POST form to `sso.logoutPath` with the `_csrf` field, which also signs out at the provider; Google's `hd` and Entra ID's `domain_hint` go in `authorizationParams`); return `null` from `userId` for unknown users and trust `claims.email` only when `claims.email_verified` is true. APIs whose users sign in with an identity provider (Auth0, Okta, Entra ID, Keycloak, Clerk) check its access tokens with `auth: jwt({ issuer, audience, user: (claims) => ({ id: claims.sub, roles: [] }) })`; never decode or verify JWTs by hand. Apps that sign in with Better Auth keep it and use `const session = betterAuthSession(auth, { user: ({ user }) => ({ id: user.id, email: user.email, roles: [] }) })` from `@browserlessapi/inferlo/better-auth` with `createApp({ auth: session, middleware: [session.middleware] })`; never write a second sign-in system next to it. Apps on Auth.js do the same with `authJsSession(Auth, authConfig)` from `@browserlessapi/inferlo/authjs` (add `id: token.sub` to the session in `callbacks.session`). Express apps on Passport.js mount the app with `toNodeHandler(app)` after `passport.session()` and use `auth: passportSession({ user: (u) => ({ id: u.id, email: u.email, roles: [] }) })` from `@browserlessapi/inferlo/passport`.
+3. **Validate every input with a schema.** `body`, `query` and `params` options. Reuse model schemas: `Ticket.pick("title", "body")`, `Ticket.omit("ownerId")`, `.partial()` for PATCH. File uploads: `body: t.object({ avatar: t.file({ maxBytes: 2_000_000, types: ["image/png", "image/jpeg"] }) })` gives the handler a `File` (clients send `FormData`); several files are `t.array(t.file()).max(10)`. Never put `t.file()` in a model: keep the file with `ctx.storage` (`` await storage.put(`avatars/${user.id}`, body.avatar) ``, needs `createApp({ storage: diskStorage({ dir: "./uploads" }) })`, `memoryStorage()` in tests) and its key in a `t.string()`; build keys from ids, never from the client's file name.
 4. **Check ownership.** Fetch with `db.x.get(id)` (throws 404) and compare `ownerId` to `user.id`; throw `notFound()` when it does not match, so other users' ids are not revealed. When more than one rule decides access (owners, admins, teams), define named permissions once in `src/permissions.ts` with `export const access = permissions({ "notes.update": ({ user, note }) => note.ownerId === user.id || (user.roles ?? []).includes("admin") })`, pass `permissions: access` to `createApp`, and call `await access.authorize("notes.update", { user, note })` in routes and jobs (403 IL3004 when denied). Permissions that need only the user go on the route: `{ permission: "reports.view" }`; add `permissions: typeof access` to `Register` (with `import type`) so permission names are type-checked. When changes must be on record (who changed what), add `AuditLog` to the models and call `await audit("notes.update", { model: "notes", before: note, after: updated })` after the change, in routes and jobs (jobs pass `userId`).
 5. **Related rows:** a `t.ref` field named `<name>Id` is a relation: `db.notes.findMany({ include: { owner: true } })` adds `note.owner` with one extra query, and `db.users.findMany({ include: { notes: true } })` adds `user.notes` (the rows that point to each user). Never load related rows in a loop. For lists clients page through, use `db.notes.paginate({ where, orderBy: { createdAt: "desc" }, cursor: query.cursor, limit: query.limit })`, which returns `{ items, nextCursor }`.
-6. **Never write raw SQL with string concatenation.** Use the table methods. If you really need SQL, use `db.$sql(text, params)` with `$1` placeholders.
+6. **Never write raw SQL with string concatenation.** Use the table methods. If you really need SQL, use `db.$sql(text, params)` with `$1` placeholders. Code that takes a pg client (Drizzle, Kysely, plain `pg`, and Knex queries with `.connection(client)`) gets it from `db.$pgClient()`, and inside `db.$transaction(async (tx) => ...)` from `tx.$pgClient()`, so it runs in the same transaction. Apps on postgres.js run Inferlo on their `sql` instance with `postgres({ pool: postgresJsPool(sql) })` from `@browserlessapi/inferlo/postgres-js` (never a second pool), and inside a transaction use `const { sql } = await tx.$pgClient<PostgresJsClient<ReservedSql>>()`. Prisma, TypeORM, Sequelize and MikroORM cannot join an Inferlo transaction: for a write across a Prisma, TypeORM, Sequelize or MikroORM table and an Inferlo model, use `db.$transaction` and write the other table with `tx.$sql`. Apps on MikroORM must set `schemaGenerator: { skipTables: [...models.map((m) => m.name), /^inferlo_/, "audit_log"] }`, or MikroORM's schema update drops Inferlo's tables.
 7. **Model ids, timestamps:** every model already has `id`, `createdAt`, `updatedAt`. Never define them or send them as input.
 8. **New field?** Add it to the model in `src/models.ts`, then run `npx inferlo db push` in development, or `npx inferlo db migrate <name>` to write a migration file for production (applied with `npx inferlo db migrate --apply`). Use `.optional()` or `.default()` for new fields on existing tables. Never edit `migrations/snapshot.json`, and never edit a migration file that has been applied (`--apply` warns with IL4018 and does not run the change): put changes in a new migration. Removing a model or field needs `npx inferlo db migrate <name> --allow-drop` (it deletes that data); never use it for a rename. Changing a field's type or default, making it required or optional, or changing an enum's values needs `--allow-change`; give a newly required field a `.default()` so existing NULL rows get a value, and before removing an enum value add an `UPDATE` in the new migration file (before its `ADD CONSTRAINT`) that moves rows off it (IL4021).
 9. **New resource?** `npx inferlo add resource <plural_name>` generates the model and CRUD routes. Then edit them.
-10. **AI calls** use aliases from `src/app.ts` (`model: "fast"`), never hard-coded provider model ids in routes. Use `output: schema` for structured data and `for: user.id` so usage is tracked per user. To let the model act, pass routes as tools: `ai.generate({ prompt, tools: [createNote, getNote], for: user.id })`. Each tool call runs as the current user with that route's auth and validation. For work that is not a route (an external API, a calculation), make a function tool: `tool("getWeather", { description, input: t.object({ ... }) }).handle(async ({ input }) => ...)`. To send images: `ai.generate({ prompt, images: [{ url }] })` or `[{ base64, mediaType: "image/png" }]`. Give routes that call AI models, send email or check passwords a `rateLimit: { max, per, by }` (IL2005 is the 429 it returns).
+10. **AI calls** use aliases from `src/app.ts` (`model: "fast"`), never hard-coded provider model ids in routes. Use `output: schema` for structured data and `for: user.id` so usage is tracked per user. A provider without a built-in adapter (Mistral, Bedrock, Azure, Vertex, Groq, ...) is added through its Vercel AI SDK package: `providers: { mistral: aiSdk(createMistral({ apiKey: settings.MISTRAL_API_KEY })) }`, then aliases name `"mistral:<model id>"`. When the app uses LangChain agents, give them Inferlo's model and tools: `toLangChainModel(ai, { model: "fast", for: user.id })` and `toLangChainTools([getWeather, createNote], { ai })` from `@browserlessapi/inferlo/langchain`, never a second set of provider keys. To let the model act, pass routes as tools: `ai.generate({ prompt, tools: [createNote, getNote], for: user.id })`. Each tool call runs as the current user with that route's auth and validation. For work that is not a route (an external API, a calculation), make a function tool: `tool("getWeather", { description, input: t.object({ ... }) }).handle(async ({ input }) => ...)`. To send images: `ai.generate({ prompt, images: [{ url }] })` or `[{ base64, mediaType: "image/png" }]`. Give routes that call AI models, send email or check passwords a `rateLimit: { max, per, by }` (IL2005 is the 429 it returns). Streaming to a chat UI built with the Vercel AI SDK (`useChat`): `route.post("/chat", { body: uiChatBody }).handle(({ body, ai, user }) => ai.stream({ model: "fast", messages: fromUIMessages(body.messages), for: user.id }).toResponse({ format: "ai-sdk" }))`.
 11. **Errors:** throw `notFound()`, `forbidden()`, `badRequest()` or `httpError(status, message)`. Every Inferlo error has a code (ILxxxx), a fix and a docs link: read the fix before changing code.
 12. **Imports:** relative imports end in `.ts` (`import { Note } from "../models.ts"`).
 13. **Configuration:** read environment variables only through `settings` from `src/config.ts`. A new variable is a new field in its `t.object({ ... })` schema (`.default(...)` or `.optional()` unless the app cannot start without it), and API keys, passwords and connection URLs go in `secrets` so they are never logged. Never read `process.env` in routes.
 14. **Expose to AI agents:** add `tool: true` to a route to make it an MCP tool at `/mcp`. Same auth applies.
-15. **Slow work after the response** (email, slow AI calls) is a background job: `export const x = job("send-email", { input: t.object({ ... }) }).handle(async ({ input, db, ai }) => { ... })` in `src/jobs.ts`, registered with `createApp({ jobs: [jobs] })`, queued with `await ctx.jobs.enqueue(x, { ... })`. Pass ids in the input, not rows. In tests, run queued jobs with `await app.jobs.runDue()`. Jobs run in the server process (`app.jobs.start()` in `src/server.ts`); with `createApp({ jobQueue: { store: "database" } })` they are kept in Postgres and `npm run worker` (`inferlo worker`) runs them in separate processes. Scheduled work is a cron next to its job: `export const nightly = cron("0 3 * * *", cleanupJob)` (UTC; the job's input must be `t.object({})`).
+15. **Slow work after the response** (email, slow AI calls) is a background job: `export const x = job("send-email", { input: t.object({ ... }) }).handle(async ({ input, db, ai }) => { ... })` in `src/jobs.ts`, registered with `createApp({ jobs: [jobs] })`, queued with `await ctx.jobs.enqueue(x, { ... })`. Pass ids in the input, not rows. In tests, run queued jobs with `await app.jobs.runDue()`. Jobs run in the server process (`app.jobs.start()` in `src/server.ts`); with `createApp({ jobQueue: { store: "database" } })` they are kept in Postgres (or with `createApp({ redis, jobQueue: { store: "redis" } })` in Redis) and `npm run worker` (`inferlo worker`) runs them in separate processes. Scheduled work is a cron next to its job: `export const nightly = cron("0 3 * * *", cleanupJob)` (UTC; the job's input must be `t.object({})`). When other parts of the app react to something that happened, publish an event instead of enqueuing each job: `export const orderPaid = event("order.paid", { payload: t.object({ ... }) })` in `src/events.ts`, jobs subscribed with `on(orderPaid, sendReceipt)` (the job's input is `orderPaid.payload`) in `src/jobs.ts`, and `await ctx.events.publish(orderPaid, { ... })` after the change is saved. To send events to other services, give each service a `name` and set `createApp({ name, redis, events: { transport: "redis" } })`; subscribers use the same `on(event, job)`.
 16. **Security headers and health:** every response already gets security headers (CSP, HSTS over HTTPS, nosniff, frame and referrer policies) and `GET /health` and `GET /ready` are built in (`health: true` in `src/app.ts`). Change a header with `createApp({ secureHeaders: { "Content-Security-Policy": "..." } })` instead of setting it in every route, never turn them all off without a proxy that adds them, and never add your own `/health` route. On SIGTERM, `src/server.ts` calls `app.close()`, which finishes in-flight requests and jobs first. Prometheus metrics (`GET /metrics`: requests, jobs, AI calls, tokens and cost) are served when `METRICS_TOKEN` is set; never add your own `/metrics` route.
 17. **Large apps: feature modules.** When the app grows to several features, group each feature's models, routes and jobs in `src/<feature>/module.ts` with `export const billing = module("billing", { imports: [users], models: [...], routes: [routes], jobs: [jobs], provides: { createInvoice } })` and register it with `createApp({ modules: [users, billing] })`. A module that uses another module's models or `provides` lists it in `imports` (IL6023 and IL6024 tell you when one is missing). Call other modules only through their `provides`; never import their internal files. Keep every model in `Register` in `src/models.ts`.
 18. **Replacing a route:** do not delete a route clients use. Add the new one and mark the old one `deprecated: { since: "YYYY-MM-DD", sunset: "YYYY-MM-DD", link: "https://..." }` in its options; it then sends the standard Deprecation and Sunset headers and is marked in OpenAPI and MCP. Remove it after the sunset date. For a breaking change to many routes, publish a new API version instead: `createApp({ routes: [apiVersion("v1", [notesV1]), apiVersion("v2", [notes])] })` serves them under `/v1` and `/v2`, each with its own OpenAPI document (`/v1/openapi.json`); write route paths without the version prefix.
 19. **Caching:** for results that are slow or expensive to compute, use the built-in cache instead of a module-level `Map`: `` return cache.getOrSet(`notes:stats:${user.id}`, { ttlMs: 60_000, tags: ["notes"] }, () => computeStats(db, user.id)) `` in routes and jobs (`ctx.cache`), and `await cache.invalidate("notes")` after notes change. `ttlMs` is required; put the user id in the key of anything that differs per user; values come back as JSON (dates as strings). To cache a whole GET route instead, add the route option `cache: { ttlMs: 60_000, tags: ["notes"] }` (one response per user by default; `by: "public"` only for data that is the same for everyone) and invalidate the tag where the data changes. With several instances, use `createApp({ cache: { store: "database" } })`.
+20. **Calling another Inferlo service:** `const tickets = serviceClient({ baseUrl: settings.TICKETS_URL, token: settings.TICKETS_TOKEN })`, then in a handler `await tickets.call(getTicket, { params: { id }, ctx })` with the other service's route imported, so the call is typed. Catch `ServiceCallError` and check `error.remoteStatus` for answers you expect (404). Never build these URLs with `fetch` by hand. When the app uses `tracing: { api: otel }`, pass the same `tracing` to `serviceClient` so calls join the trace.
+21. **Data of many organisations (multi-tenant):** give the signed-in user a `tenantId` (the organisation's id) and make tables whose rows belong to one organisation tenant-scoped: `model("projects", { ... }, { tenant: true })`. `ctx.db` then filters every query by and stamps every insert with the user's tenant, so never add `tenantId` to a `where`, a body schema or an insert. Jobs queued (or events published) by a request run for the request's tenant: their `ctx.db` is scoped the same way, so do not pass the tenant id in the job input. In scripts use `app.db.$tenant(tenantId).projects`, and `app.jobs.enqueue(job, input, { tenantId })`. For limits and caches shared by an organisation use `rateLimit: { max, per, by: "tenant" }` and `cache: { ttlMs, by: "tenant" }`; `ctx.audit` records the tenant itself.
+22. **Live updates over WebSockets:** `export const chat = route.ws("/chat", { message: t.object({ text: t.string().max(2000) }), rateLimit: { max: 60, per: "minute" } }).handle(async ({ message, user, db, socket }) => ...)` in a routes file, registered like other routes. Return a value to reply with JSON, or call `socket.send(data)` for several messages; stream a model's answer with `await socket.stream(ai.stream({ model: "fast", prompt, for: user.id }))`. Auth works as for HTTP routes (browsers authenticate with cookie sessions); never add a second WebSocket server or library. For live updates, ``socket.join(`project:${id}`)`` in the WebSocket handler (after checking the user may see it) and ``await sockets.broadcast(`project:${id}`, data)`` from any route, WebSocket handler or job; rooms are per tenant, and with more than one instance add `sockets: { transport: "redis", subscriber: await redis.duplicate().connect() }` next to `redis` in createApp. Test with `await app.listen(0)` and `new WebSocket(url)`.
+23. **Response schemas:** give routes whose answer clients rely on a `response` schema (`route.get("/me", { response: t.object({ id: t.uuid(), email: t.email(), name: t.string() }) })`) and return exactly those fields, never a whole row. Outside production Inferlo checks answers against it and logs IL2016 for a missing, wrong or extra field; tests use `createApp({ validateResponses: "error" })` so a mismatch fails.
 
 ## Testing
 

package/templates/app/test/notes.test.ts

@@ -11,6 +11,8 @@ function makeApp() {
     routes: [notes],
     db: memory(),
     auth: { resolve: () => null },
+    // An answer that does not match its route's response schema fails the test (500 IL2016).
+    validateResponses: "error",
     ai: { providers: { mock: mockProvider({ respond: () => '{"summary":"A short note."}' }) }, models: { fast: "mock:test" } },
   });
 }