@browserlessapi/inferlo 0.5.0 → 0.7.0

package/dist/azure.js

@@ -0,0 +1,119 @@
+import { clientIps } from "./client-ip.js";
+import { InferloError } from "./errors.js";
+const fix = 'Pass the app from createApp: handler: toAzureHandler(app, { prefix: "/api" }), with route: "{*path}" on azure.http(...).';
+/** The caller's address: the last X-Forwarded-For entry, which the Azure front end adds, without its port. */
+function azureClientIp(forwarded) {
+    const last = forwarded?.split(",").pop()?.trim();
+    if (!last)
+        return undefined;
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(last);
+    if (bracketed)
+        return bracketed[1];
+    // IPv4 with a port ("203.0.113.9:51234"); a bare IPv6 address has more than one colon and no port.
+    const v4 = /^(\d{1,3}(?:\.\d{1,3}){3})(?::\d+)?$/.exec(last);
+    return v4 ? v4[1] : last;
+}
+async function toRequest(request, prefix) {
+    const headers = new Headers();
+    for (const [name, value] of request.headers)
+        headers.append(name, value);
+    const original = new URL(request.url);
+    // The Functions host runs behind a TLS front end: use the scheme and host the caller used.
+    const forwardedProto = headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+    const proto = forwardedProto === "https" || forwardedProto === "http" ? forwardedProto : original.protocol.slice(0, -1);
+    const host = headers.get("x-forwarded-host")?.split(",")[0]?.trim() || headers.get("host") || original.host;
+    let url;
+    try {
+        url = new URL(`${proto}://${host}`);
+    }
+    catch {
+        url = new URL(original.origin);
+    }
+    url.pathname = original.pathname;
+    url.search = original.search;
+    const path = url.pathname;
+    if (prefix && (path === prefix || path.startsWith(prefix + "/")))
+        url.pathname = path.slice(prefix.length) || "/";
+    const method = request.method.toUpperCase();
+    const body = method === "GET" || method === "HEAD" ? undefined : new Uint8Array(await request.arrayBuffer());
+    const result = new Request(url, { method, headers, body: body && body.length ? body : undefined });
+    const ip = azureClientIp(headers.get("x-forwarded-for"));
+    if (ip)
+        clientIps.set(result, ip);
+    return result;
+}
+const SAME_SITE = { strict: "Strict", lax: "Lax", none: "None" };
+/** Parses a Set-Cookie header into the Cookie object Azure Functions sends (it would keep only one Set-Cookie header). */
+function parseSetCookie(header) {
+    const [pair, ...attributes] = header.split(";");
+    const eq = pair.indexOf("=");
+    if (eq < 1)
+        return undefined;
+    const cookie = { name: pair.slice(0, eq).trim(), value: pair.slice(eq + 1).trim() };
+    for (const attribute of attributes) {
+        const at = attribute.indexOf("=");
+        const key = (at === -1 ? attribute : attribute.slice(0, at)).trim().toLowerCase();
+        const value = at === -1 ? "" : attribute.slice(at + 1).trim();
+        if (key === "domain" && value)
+            cookie.domain = value;
+        else if (key === "path" && value)
+            cookie.path = value;
+        else if (key === "expires" && value) {
+            const time = Date.parse(value);
+            if (!Number.isNaN(time))
+                cookie.expires = new Date(time);
+        }
+        else if (key === "max-age" && /^-?\d+$/.test(value))
+            cookie.maxAge = Number(value);
+        else if (key === "secure")
+            cookie.secure = true;
+        else if (key === "httponly")
+            cookie.httpOnly = true;
+        else if (key === "samesite" && SAME_SITE[value.toLowerCase()])
+            cookie.sameSite = SAME_SITE[value.toLowerCase()];
+    }
+    return cookie;
+}
+function toResponseInit(response, method) {
+    const headers = {};
+    for (const [name, value] of response.headers)
+        if (name !== "set-cookie")
+            headers[name] = value;
+    const cookies = [];
+    for (const header of response.headers.getSetCookie()) {
+        const cookie = parseSetCookie(header);
+        if (cookie)
+            cookies.push(cookie);
+    }
+    const init = { status: response.status, headers, cookies };
+    if (response.body && method !== "HEAD")
+        init.body = response.body;
+    return init;
+}
+/**
+ * An Azure Functions v4 HTTP trigger handler that runs a whole Inferlo app:
+ * azure.http("inferlo", { route: "{*path}", methods: [...], authLevel: "anonymous", handler: toAzureHandler(app, { prefix: "/api" }) }).
+ */
+export function toAzureHandler(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5026", "toAzureHandler() needs an Inferlo app (the value returned by createApp).", { fix });
+    }
+    if (options === null ||
+        typeof options !== "object" ||
+        Object.keys(options).some((key) => key !== "prefix") ||
+        (options.prefix !== undefined && (typeof options.prefix !== "string" || !options.prefix.startsWith("/")))) {
+        throw new InferloError("IL5026", 'toAzureHandler() options are { prefix }, and prefix starts with /, such as "/api".', { fix });
+    }
+    const prefix = (options.prefix ?? "").replace(/\/+$/, "").replace(/\/{2,}/g, "/");
+    return async (request) => {
+        const r = request;
+        if (!r || typeof r.method !== "string" || typeof r.url !== "string" || typeof r.arrayBuffer !== "function" || !r.headers) {
+            throw new InferloError("IL5026", "The handler from toAzureHandler() received something that is not an Azure Functions HTTP request.", {
+                fix: "Use it as the handler of an HTTP trigger: azure.http(name, { route: \"{*path}\", handler: toAzureHandler(app, { prefix: \"/api\" }) }). Other triggers (queues, timers, blobs) need their own handler.",
+            });
+        }
+        const response = await app.fetch(await toRequest(request, prefix));
+        return toResponseInit(response, request.method.toUpperCase());
+    };
+}
+//# sourceMappingURL=azure.js.map

package/dist/azure.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Application cache: ctx.cache in routes and jobs, app.cache everywhere else.
+ *
+ *   const stats = await cache.getOrSet("stats:daily", { ttlMs: 60_000, tags: ["tickets"] }, () => computeStats(db));
+ *   await cache.invalidate("tickets"); // after a ticket changes
+ *
+ * Values are stored as JSON, in memory (one process, the default) or in the app's Postgres database (shared by
+ * every instance), chosen with createApp({ cache: { store } }).
+ */
+import type { Adapter } from "./db/types.ts";
+export interface CacheConfig {
+    /**
+     * Where entries are kept. "memory" (default): in this process, for one instance and tests.
+     * "database": in the inferlo_cache table of the app's Postgres database, shared by every instance.
+     * "redis": in the Redis of createApp({ redis }), shared by every instance.
+     */
+    store?: "memory" | "database" | "redis";
+    /** Most entries the memory store keeps; the least recently used go first. Default 10000. */
+    maxEntries?: number;
+}
+export interface CacheSetOptions {
+    /** How long the entry is kept, in milliseconds (at least 1, at most 365 days). */
+    ttlMs: number;
+    /** Tags for cache.invalidate(tag), for example ["tickets", `user:${user.id}`]. */
+    tags?: readonly string[];
+}
+export interface Cache {
+    /** Where entries are kept: "memory", "database" or "redis". */
+    readonly store: "memory" | "database" | "redis";
+    /** The cached value, or undefined when there is none or it expired. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Store a JSON value (not undefined; use null for "nothing") for ttlMs. Dates are stored as ISO strings. */
+    set(key: string, value: unknown, options: CacheSetOptions): Promise<void>;
+    /**
+     * The cached value, or else the result of compute(), stored for ttlMs. Concurrent calls for the same key in this
+     * process share one compute() call. Errors from compute() are thrown and nothing is stored.
+     */
+    getOrSet<T>(key: string, options: CacheSetOptions, compute: () => T | Promise<T>): Promise<T>;
+    /** Remove one entry. */
+    delete(key: string): Promise<void>;
+    /** Remove every entry stored with any of these tags. */
+    invalidate(tags: string | readonly string[]): Promise<void>;
+    /** Remove every entry. */
+    clear(): Promise<void>;
+}
+/** Where a Cache keeps its entries, as JSON text. */
+export interface CacheStore {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, json: string, ttlMs: number, tags: readonly string[]): Promise<void>;
+    delete(key: string): Promise<void>;
+    invalidate(tags: readonly string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Check createApp({ cache }) at startup. Raises IL6028. */
+export declare function resolveCacheConfig(config: unknown): {
+    store: "memory" | "database" | "redis";
+    maxEntries: number;
+};
+/** A Cache over a store: checks keys, options and values, stores JSON, shares concurrent getOrSet calls. */
+export declare function createCache(store: CacheStore, name: "memory" | "database" | "redis"): Cache;
+/** Entries in this process, least recently used removed first once maxEntries is reached. */
+export declare function memoryCacheStore(maxEntries?: number, now?: () => number): CacheStore;
+/** Entries in the inferlo_cache table (created on first use), shared by every instance of the app. */
+export declare function databaseCacheStore(adapter: Adapter): CacheStore;
+/** The route option cache: route.get("/tickets/stats", { cache: { ttlMs: 60_000, tags: ["tickets"] } }). */
+export interface RouteCache {
+    /** How long a response is kept, in milliseconds (at least 1, at most 365 days). */
+    ttlMs: number;
+    /**
+     * Who shares a cached response. "user" (default): each signed-in user gets their own (requests without a user
+     * share one). "tenant": the users of one tenant (organisation) share one, in multi-tenant apps (users without a
+     * tenant get their own). "public": every caller gets the same response; only for data that does not depend on
+     * the user.
+     */
+    by?: "user" | "tenant" | "public";
+    /** Tags for ctx.cache.invalidate(tag), so a change removes the cached responses at once. */
+    tags?: readonly string[];
+}
+/** Check a route's cache option at startup. Raises IL6028. */
+export declare function checkRouteCache(option: unknown, method: string, where: string): void;
+/** A cached route response: the handler's JSON result and the headers it set itself. */
+export interface CachedResponse {
+    body: unknown;
+    headers: [string, string][];
+    etag: string;
+}
+/**
+ * The cache key of one request to a cached route: the route, who shares the response (the user, the tenant or
+ * everyone) and the full URL path and
+ * query (sorted, so ?a=1&b=2 and ?b=2&a=1 share an entry), hashed to a short key.
+ */
+export declare function routeCacheKey(method: string, path: string, option: RouteCache, userId: string | undefined, url: URL, tenantId?: string | null): Promise<string>;
+/** A weak ETag for a JSON body. */
+export declare function etagFor(json: string): Promise<string>;
+/** True when an If-None-Match header lists the ETag (or is *). */
+export declare function etagMatches(ifNoneMatch: string | null, etag: string): boolean;

package/dist/cache.js

@@ -0,0 +1,247 @@
+import { InferloError } from "./errors.js";
+const MAX_TTL_MS = 365 * 86_400_000;
+const bad = (message, fix) => new InferloError("IL6028", message, { fix });
+/** Check createApp({ cache }) at startup. Raises IL6028. */
+export function resolveCacheConfig(config) {
+    if (config === undefined)
+        return { store: "memory", maxEntries: 10_000 };
+    const c = config;
+    const fix = 'Use createApp({ cache: { store: "memory" } }) (the default, with an optional maxEntries), { store: "database" } or { store: "redis" }.';
+    if (typeof c !== "object" || c === null || Array.isArray(c))
+        throw bad("createApp({ cache }) must be an object.", fix);
+    for (const key of Object.keys(c))
+        if (key !== "store" && key !== "maxEntries")
+            throw bad(`Unknown cache option "${key}".`, fix);
+    const store = c.store ?? "memory";
+    if (store !== "memory" && store !== "database" && store !== "redis")
+        throw bad(`Invalid cache store ${JSON.stringify(store)}.`, fix);
+    const maxEntries = c.maxEntries ?? 10_000;
+    if (!Number.isInteger(maxEntries) || maxEntries < 1)
+        throw bad("cache maxEntries must be a whole number of at least 1.", fix);
+    if (store !== "memory" && c.maxEntries !== undefined)
+        throw bad("cache maxEntries only applies to the memory store.", `Remove maxEntries from createApp({ cache: { store: "${store}" } }).`);
+    return { store, maxEntries };
+}
+function checkKey(key) {
+    if (typeof key !== "string" || key.length === 0 || key.length > 512) {
+        throw bad(`A cache key must be a string of 1 to 512 characters, got ${typeof key === "string" ? `${key.length} characters` : typeof key}.`, 'Use a short, stable key such as `ticket:${id}`.');
+    }
+}
+function checkTags(tags) {
+    const list = typeof tags === "string" ? [tags] : tags;
+    if (!Array.isArray(list) || list.some((t) => typeof t !== "string" || t.length === 0 || t.length > 256)) {
+        throw bad("Cache tags must be strings of 1 to 256 characters.", 'Use tags: ["tickets", `user:${user.id}`] and cache.invalidate("tickets").');
+    }
+    return list;
+}
+function checkOptions(options) {
+    const o = options;
+    if (typeof o !== "object" || o === null || !Number.isInteger(o.ttlMs) || o.ttlMs < 1 || o.ttlMs > MAX_TTL_MS) {
+        throw bad("Cache entries need ttlMs, a whole number of milliseconds from 1 to 365 days.", 'Pass { ttlMs: 60_000 } (one minute), optionally with tags: ["tickets"].');
+    }
+    return { ttlMs: o.ttlMs, tags: o.tags === undefined ? [] : checkTags(o.tags) };
+}
+function toJSON(key, value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (error) {
+        throw bad(`The value for cache key "${key}" cannot be stored as JSON: ${error.message}`, "Cache plain objects, arrays, strings, numbers, booleans and null.");
+    }
+    if (json === undefined)
+        throw bad(`The value for cache key "${key}" is ${value === undefined ? "undefined" : typeof value}, which cannot be cached.`, "Cache null for \"nothing\", or a plain JSON value.");
+    return json;
+}
+/** A Cache over a store: checks keys, options and values, stores JSON, shares concurrent getOrSet calls. */
+export function createCache(store, name) {
+    const running = new Map();
+    const cache = {
+        store: name,
+        async get(key) {
+            checkKey(key);
+            const json = await store.get(key);
+            return json === undefined ? undefined : JSON.parse(json);
+        },
+        async set(key, value, options) {
+            checkKey(key);
+            const { ttlMs, tags } = checkOptions(options);
+            await store.set(key, toJSON(key, value), ttlMs, tags);
+        },
+        async getOrSet(key, options, compute) {
+            checkKey(key);
+            const { ttlMs, tags } = checkOptions(options);
+            if (typeof compute !== "function")
+                throw bad("cache.getOrSet needs a function that computes the value.", "Use cache.getOrSet(key, { ttlMs }, () => compute()).");
+            const pending = running.get(key);
+            if (pending)
+                return pending;
+            const work = (async () => {
+                const json = await store.get(key);
+                if (json !== undefined)
+                    return JSON.parse(json);
+                const value = await compute();
+                const text = toJSON(key, value);
+                await store.set(key, text, ttlMs, tags);
+                // Callers get the stored form, so a cache hit and a miss return the same thing (dates as strings).
+                return JSON.parse(text);
+            })();
+            running.set(key, work);
+            try {
+                return await work;
+            }
+            finally {
+                running.delete(key);
+            }
+        },
+        async delete(key) {
+            checkKey(key);
+            await store.delete(key);
+        },
+        async invalidate(tags) {
+            const list = checkTags(tags);
+            if (list.length)
+                await store.invalidate(list);
+        },
+        async clear() {
+            await store.clear();
+        },
+    };
+    return Object.freeze(cache);
+}
+/** Entries in this process, least recently used removed first once maxEntries is reached. */
+export function memoryCacheStore(maxEntries = 10_000, now = Date.now) {
+    const entries = new Map();
+    return {
+        async get(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return undefined;
+            entries.delete(key);
+            if (entry.expiresAt <= now())
+                return undefined;
+            entries.set(key, entry); // most recently used last
+            return entry.json;
+        },
+        async set(key, json, ttlMs, tags) {
+            entries.delete(key);
+            entries.set(key, { json, expiresAt: now() + ttlMs, tags });
+            if (entries.size > maxEntries) {
+                const time = now();
+                for (const [k, v] of entries)
+                    if (v.expiresAt <= time)
+                        entries.delete(k);
+                for (const k of entries.keys()) {
+                    if (entries.size <= maxEntries)
+                        break;
+                    entries.delete(k);
+                }
+            }
+        },
+        async delete(key) {
+            entries.delete(key);
+        },
+        async invalidate(tags) {
+            for (const [k, v] of entries)
+                if (v.tags.some((t) => tags.includes(t)))
+                    entries.delete(k);
+        },
+        async clear() {
+            entries.clear();
+        },
+    };
+}
+/** Entries in the inferlo_cache table (created on first use), shared by every instance of the app. */
+export function databaseCacheStore(adapter) {
+    const sql = adapter.sql?.bind(adapter);
+    if (!sql) {
+        throw bad(`cache store "database" needs a Postgres database, but the app uses the ${adapter.dialect} adapter.`, 'Use postgres() from "@browserlessapi/inferlo/postgres" for createApp({ db }), or cache: { store: "memory" }.');
+    }
+    let ready;
+    const create = () => sql('CREATE TABLE IF NOT EXISTS "inferlo_cache" ("key" text PRIMARY KEY, "value" text NOT NULL, "tags" text[] NOT NULL DEFAULT \'{}\', "expires_at" timestamptz NOT NULL)')
+        .then(() => sql('CREATE INDEX IF NOT EXISTS "inferlo_cache_tags" ON "inferlo_cache" USING gin ("tags")'))
+        .catch(
+    // Two instances creating the table at the same moment: the other one won.
+    () => sql('SELECT 1 FROM "inferlo_cache" LIMIT 1'));
+    const query = async (text, params = []) => {
+        ready ??= create().catch((error) => {
+            ready = undefined;
+            throw error;
+        });
+        await ready;
+        return sql(text, params);
+    };
+    let writes = 0;
+    return {
+        async get(key) {
+            const rows = await query('SELECT "value" FROM "inferlo_cache" WHERE "key" = $1 AND "expires_at" > now()', [key]);
+            return rows.length ? String(rows[0].value) : undefined;
+        },
+        async set(key, json, ttlMs, tags) {
+            await query(`INSERT INTO "inferlo_cache" ("key", "value", "tags", "expires_at") VALUES ($1, $2, $3::text[], now() + $4 * interval '1 millisecond')
+         ON CONFLICT ("key") DO UPDATE SET "value" = EXCLUDED."value", "tags" = EXCLUDED."tags", "expires_at" = EXCLUDED."expires_at"`, [key, json, [...tags], ttlMs]);
+            // Expired rows are never read; remove them now and then so the table does not grow without bound.
+            if (++writes % 100 === 0)
+                await query('DELETE FROM "inferlo_cache" WHERE "expires_at" <= now()');
+        },
+        async delete(key) {
+            await query('DELETE FROM "inferlo_cache" WHERE "key" = $1', [key]);
+        },
+        async invalidate(tags) {
+            await query('DELETE FROM "inferlo_cache" WHERE "tags" && $1::text[]', [[...tags]]);
+        },
+        async clear() {
+            await query('DELETE FROM "inferlo_cache"');
+        },
+    };
+}
+/** Check a route's cache option at startup. Raises IL6028. */
+export function checkRouteCache(option, method, where) {
+    const o = option;
+    const problems = [];
+    if (method !== "GET")
+        problems.push("only GET routes can be cached");
+    if (typeof o !== "object" || o === null)
+        problems.push("it must be an object");
+    else {
+        for (const key of Object.keys(o))
+            if (key !== "ttlMs" && key !== "by" && key !== "tags")
+                problems.push(`unknown option "${key}"`);
+        if (!Number.isInteger(o.ttlMs) || o.ttlMs < 1 || o.ttlMs > MAX_TTL_MS)
+            problems.push("ttlMs must be a whole number of milliseconds from 1 to 365 days");
+        if (o.by !== undefined && o.by !== "user" && o.by !== "tenant" && o.by !== "public")
+            problems.push('by must be "user", "tenant" or "public"');
+        if (o.tags !== undefined && (!Array.isArray(o.tags) || o.tags.some((t) => typeof t !== "string" || t.length === 0 || t.length > 256)))
+            problems.push("tags must be strings of 1 to 256 characters");
+    }
+    if (problems.length) {
+        throw bad(`Invalid cache option on ${where}: ${problems.join(", ")}.`, 'Use route.get(path, { cache: { ttlMs: 60_000, by: "user", tags: ["tickets"] } }).');
+    }
+}
+const base64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+async function sha256(text) {
+    return base64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+}
+/**
+ * The cache key of one request to a cached route: the route, who shares the response (the user, the tenant or
+ * everyone) and the full URL path and
+ * query (sorted, so ?a=1&b=2 and ?b=2&a=1 share an entry), hashed to a short key.
+ */
+export async function routeCacheKey(method, path, option, userId, url, tenantId) {
+    const by = option.by ?? "user";
+    const who = by === "public" ? "public" : by === "tenant" && tenantId ? `tenant:${tenantId}` : userId === undefined ? "anonymous" : `user:${userId}`;
+    const query = [...url.searchParams].sort(([a, x], [b, y]) => (a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0));
+    return `route:${await sha256(JSON.stringify([method, path, who, url.pathname, query]))}`;
+}
+/** A weak ETag for a JSON body. */
+export async function etagFor(json) {
+    return `W/"${(await sha256(json)).slice(0, 27)}"`;
+}
+/** True when an If-None-Match header lists the ETag (or is *). */
+export function etagMatches(ifNoneMatch, etag) {
+    if (!ifNoneMatch)
+        return false;
+    const bare = (tag) => tag.trim().replace(/^W\//, "");
+    return ifNoneMatch.split(",").some((tag) => tag.trim() === "*" || bare(tag) === bare(etag));
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/cli/main.js

@@ -109,9 +109,24 @@ async function cmdDescribe(args) {
     const app = await loadApp(args);
     const d = app.describe();
     print(d, Boolean(args.flags.json), () => {
-        const lines = [`${d.name} ${d.version}  (inferlo ${d.inferlo}, db: ${d.database}, auth: ${d.auth ? "on" : "off"})`, "", "Models"];
+        const lines = [`${d.name} ${d.version}  (inferlo ${d.inferlo}, db: ${d.database}, auth: ${d.auth ? "on" : "off"})`];
+        if (d.modules?.length) {
+            lines.push("", "Modules");
+            for (const m of d.modules) {
+                lines.push(`  ${m.name}${m.imports.length ? `  imports: ${m.imports.join(", ")}` : ""}${m.description ? `  ${m.description}` : ""}`);
+                const parts = [
+                    m.models.length ? `models: ${m.models.join(", ")}` : "",
+                    m.routes.length ? `routes: ${m.routes.length}` : "",
+                    m.jobs.length ? `jobs: ${m.jobs.join(", ")}` : "",
+                    m.provides.length ? `provides: ${m.provides.join(", ")}` : "",
+                ].filter(Boolean);
+                if (parts.length)
+                    lines.push(`    ${parts.join("; ")}`);
+            }
+        }
+        lines.push("", "Models");
         for (const m of d.models) {
-            lines.push(`  ${m.name}`);
+            lines.push(`  ${m.name}${m.module ? `  [${m.module}]` : ""}${m.tenant ? "  (tenant-scoped)" : ""}`);
             for (const [k, f] of Object.entries(m.fields)) {
                 const extra = [f.required ? "required" : "", f.unique ? "unique" : "", f.references ? `-> ${f.references}` : "", f.values ? f.values.join("|") : ""].filter(Boolean).join(", ");
                 lines.push(`    ${k.padEnd(16)} ${f.type}${extra ? `  (${extra})` : ""}`);
@@ -119,7 +134,7 @@ async function cmdDescribe(args) {
         }
         lines.push("", "Routes");
         for (const r of d.routes)
-            lines.push(`  ${r.method.padEnd(6)} ${r.path.padEnd(28)} auth=${r.auth}${r.tool ? `  tool=${r.tool}` : ""}${r.deprecated ? `  deprecated${r.deprecated !== true && r.deprecated.sunset ? ` (sunset ${r.deprecated.sunset})` : ""}` : ""}${r.name ? `  (${r.name})` : ""}`);
+            lines.push(`  ${r.method.padEnd(6)} ${r.path.padEnd(28)} auth=${r.auth}${r.permission ? `  permission=${r.permission}` : ""}${r.cache ? `  cache=${r.cache.ttlMs}ms/${r.cache.by}` : ""}${r.tool ? `  tool=${r.tool}` : ""}${r.deprecated ? `  deprecated${r.deprecated !== true && r.deprecated.sunset ? ` (sunset ${r.deprecated.sunset})` : ""}` : ""}${r.name ? `  (${r.name})` : ""}${r.module ? `  [${r.module}]` : ""}`);
         if (d.jobs?.length) {
             lines.push("", `Jobs (queue: ${d.jobQueue})`);
             for (const j of d.jobs)
@@ -129,7 +144,13 @@ async function cmdDescribe(args) {
         }
         lines.push("", `AI: ${d.ai.configured ? Object.entries(d.ai.aliases).map(([a, ids]) => `${a} = ${ids.join(" > ")}`).join("; ") || "configured" : "not configured"}`);
         if (d.endpoints.openapi)
-            lines.push(`OpenAPI: ${d.endpoints.openapi}`);
+            lines.push(`OpenAPI: ${d.endpoints.openapi}${d.versions?.some((v) => v.openapi) ? ` (per version: ${d.versions.map((v) => v.openapi).filter(Boolean).join(", ")})` : ""}`);
+        if (d.permissions?.length)
+            lines.push(`Permissions: ${d.permissions.map((p) => (p.roles ? `${p.name} (${p.roles.join(", ")})` : p.name)).join(", ")}`);
+        if (d.versions?.length)
+            lines.push(`API versions: ${d.versions.map((v) => v.name).join(", ")}`);
+        if (d.cache)
+            lines.push(`Cache: ${d.cache}`);
         if (d.endpoints.mcp)
             lines.push(`MCP: ${d.endpoints.mcp}`);
         if (d.endpoints.health)
@@ -311,9 +332,9 @@ async function cmdWorker(args) {
             fix: 'Define jobs with job("name", { input }).handle(fn) in src/jobs.ts and register them: createApp({ jobs: [jobs] }).',
         });
     }
-    if (app.jobs.queue !== "database") {
-        throw new InferloError("IL8008", `inferlo worker needs the database job queue, but the app keeps jobs in ${app.jobs.queue}, where a separate process cannot see them.`, {
-            fix: 'Use createApp({ jobQueue: { store: "database" }, db: postgres({ url }) }), or run jobs in the server process with app.jobs.start().',
+    if (app.jobs.queue !== "database" && app.jobs.queue !== "redis") {
+        throw new InferloError("IL8008", `inferlo worker needs a shared job queue (database or Redis), but the app keeps jobs in ${app.jobs.queue}, where a separate process cannot see them.`, {
+            fix: 'Use createApp({ jobQueue: { store: "database" }, db: postgres({ url }) }) or createApp({ redis, jobQueue: { store: "redis" } }), or run jobs in the server process with app.jobs.start().',
         });
     }
     const say = (event, text) => console.log(json ? JSON.stringify({ ok: true, event, jobs: names, queue: app.jobs.queue }) : text);