@browserlessapi/inferlo 0.3.0 → 0.5.0

package/dist/app.d.ts

@@ -8,6 +8,11 @@ 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 RateLimitConfig } from "./rate-limit.ts";
+import { type AppJobs, type JobQueueConfig, type JobSource } from "./jobs.ts";
+import { type LogFields, type LoggingConfig } from "./logging.ts";
+import { type MetricsConfig } from "./metrics.ts";
+import { type SecureHeadersConfig } from "./secure-headers.ts";
 export interface AuthConfig {
     /** Return the signed-in user for this request, or null. */
     resolve(req: Request, ctx: {
@@ -28,11 +33,48 @@ export interface MiddlewareContext {
     req: Request;
     url: URL;
     state: Record<string, unknown>;
+    /** This request's id, sent back in the X-Request-Id header and added to its log entries. */
+    requestId: string;
 }
 export type Middleware = (ctx: MiddlewareContext, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Where the app writes logs. fields holds structured values such as requestId (a request's log entries)
+ * or method, path, status and durationMs (request logs); loggers that only take two arguments ignore them.
+ */
 export interface Logger {
-    info(message: string, data?: unknown): void;
-    error(message: string, data?: unknown): void;
+    info(message: string, data?: unknown, fields?: LogFields): void;
+    error(message: string, data?: unknown, fields?: LogFields): void;
+}
+/** A readiness check: resolve (or return) when the dependency is usable, throw when it is not. */
+export type HealthCheck = () => unknown | Promise<unknown>;
+export interface HealthConfig {
+    /** Liveness endpoint: 200 while the process can answer requests. Default "/health". */
+    path?: string;
+    /** Readiness endpoint: 200 when every check passes, 503 otherwise. Default "/ready". */
+    readyPath?: string;
+    /** Your own checks, by name ("database" and "ai" are built in): { redis: () => redis.ping() }. */
+    checks?: Record<string, HealthCheck>;
+    /** Time each check may take before it fails. Default 5000 ms. */
+    timeoutMs?: number;
+}
+export interface CheckResult {
+    status: "ok" | "error";
+    durationMs: number;
+    /** "Check failed." unless the check threw an exposed InferloError (httpError) or exposeErrors is on. */
+    error?: string;
+}
+export interface CloseOptions {
+    /**
+     * Keep serving requests for this long after /ready starts answering 503, so load balancers stop sending
+     * traffic first (for example a few seconds more than the readiness probe period). Default 0.
+     */
+    delayMs?: number;
+    /** Longest wait for in-flight requests, waitUntil tasks and the running job before closing anyway. Default 10000. */
+    timeoutMs?: number;
+}
+export interface ReadinessReport {
+    status: "ready" | "not_ready";
+    checks: Record<string, CheckResult>;
 }
 /** Anything that contains routes: a route, an array, or a module (import * as tickets from "./routes/tickets.ts"). */
 export type RouteSource = RouteDef | readonly RouteSource[] | {
@@ -45,6 +87,10 @@ export interface AppConfig<Models extends readonly AnyModel[]> {
     description?: string;
     models?: Models;
     routes?: RouteSource[];
+    /** Background jobs and crons: jobs, cron(schedule, job) values, arrays or modules (import * as jobs from "./jobs.ts"). */
+    jobs?: JobSource[];
+    /** Where queued jobs are kept: { store: "memory" } (default) or { store: "database" } (Postgres table inferlo_jobs, shared by every instance). */
+    jobQueue?: JobQueueConfig;
     /** Database adapter. Default: memory(). Use postgres() from "@browserlessapi/inferlo/postgres" in production. */
     db?: Adapter;
     auth?: AuthConfig;
@@ -57,9 +103,51 @@ export interface AppConfig<Models extends readonly AnyModel[]> {
     mcp?: string | false;
     /** Maximum request body in bytes. Default 1 MiB. */
     maxBodySize?: number;
+    /** Where route rateLimit counts are kept: { store: "memory" } (default) or { store: "database" } (Postgres, shared by every instance). */
+    rateLimit?: RateLimitConfig;
+    /**
+     * Behind a load balancer or proxy that sets X-Forwarded-For: true uses its first address as the client IP
+     * (for rateLimit by "ip"). Default false, because clients can send that header themselves.
+     */
+    trustProxy?: boolean;
+    /**
+     * Health endpoints for load balancers and orchestrators: GET /health (liveness) and GET /ready (readiness:
+     * the database, the AI configuration and your checks). Public, never cached. Off by default.
+     */
+    health?: boolean | HealthConfig;
+    /**
+     * Security headers sent on every response that does not set them itself: Content-Security-Policy,
+     * Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy, Referrer-Policy, X-Content-Type-Options,
+     * X-Frame-Options, and Strict-Transport-Security over HTTPS. Change one by name, false leaves it out:
+     * { "X-Frame-Options": "SAMEORIGIN", "Content-Security-Policy": false }. false sends none. Default true.
+     */
+    secureHeaders?: boolean | SecureHeadersConfig;
+    /**
+     * Longest time in milliseconds a route may take (reading the body and running the handler) before it answers
+     * 503 IL2007 and ctx.signal is aborted. Routes can set their own timeoutMs. false turns it off. Default 60000.
+     */
+    requestTimeoutMs?: number | 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
+     * strings: redact: [settings, process.env.WEBHOOK_SECRET]. They are replaced with "[redacted]".
+     */
+    redact?: readonly (string | object | undefined | null)[];
     /** Include error messages of unexpected (500) errors in responses. Default false. */
     exposeErrors?: boolean;
+    /** Your own logger (for example pino or winston): { info(message, data, fields), error(message, data, fields) }. */
     logger?: Logger;
+    /**
+     * The built-in logger's format ("text" or "json", one object per line) and request logs (requests: true logs
+     * each request's id, method, path, status and duration). Every response has an X-Request-Id header.
+     */
+    logging?: LoggingConfig;
+    /**
+     * Prometheus metrics at GET /metrics: requests by route and status with durations, job runs, and AI calls,
+     * tokens and cost per alias. { token } requires Authorization: Bearer <token>; without it the endpoint is
+     * public, so keep it off the internet. Off by default.
+     */
+    metrics?: boolean | MetricsConfig;
 }
 export interface RequestOptions {
     method?: Method | Lowercase<Method> | "OPTIONS" | "HEAD";
@@ -78,6 +166,8 @@ export interface App<Models extends readonly AnyModel[]> {
     readonly models: Models;
     readonly db: Db<Models>;
     readonly ai: AI;
+    /** Background jobs: app.jobs.enqueue(job, input), app.jobs.start() to run them, app.jobs.runDue() in tests. */
+    readonly jobs: AppJobs;
     /** 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 }). */
@@ -87,6 +177,16 @@ export interface App<Models extends readonly AnyModel[]> {
         port: number;
         close(): Promise<void>;
     }>;
+    /** Run the readiness checks (the same report as GET /ready, also when health is off). */
+    checkReady(): Promise<ReadinessReport>;
+    /** True once app.close() was called: /ready answers 503. */
+    readonly closing: boolean;
+    /**
+     * Graceful shutdown, for SIGTERM: /ready answers 503, then (after delayMs) new requests get 503 IL2006,
+     * in-flight requests, waitUntil tasks and the job workers from app.jobs.start() finish (up to timeoutMs),
+     * servers from app.listen() close, then the database. Calling it again returns the same promise.
+     */
+    close(options?: CloseOptions): Promise<void>;
     /** Machine-readable map of the whole app: routes, models, auth and AI. */
     describe(): AppDescription;
     openapi(): Record<string, unknown>;