@browserlessapi/inferlo 0.4.0 → 0.6.0

package/dist/sessions.js

@@ -0,0 +1,171 @@
+import { safeEqual } from "./auth.js";
+import { InferloError } from "./errors.js";
+const DAY = 86_400_000;
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const MAX_FORM_BYTES = 64 * 1024;
+const fix = 'Pass sessions({ secret: config.SESSION_SECRET, user: ({ userId }, { db }) => db.users.find(userId) }) with a secret of at least 32 random characters (openssl rand -base64 32).';
+/** Signed cookie sessions with CSRF protection: createApp({ auth: sessions({ secret, user }) }). */
+export function sessions(options) {
+    if (!options || typeof options !== "object")
+        throw new InferloError("IL6029", "sessions() needs { secret, user }.", { fix });
+    const secrets = typeof options.secret === "string" ? [options.secret] : Array.isArray(options.secret) ? [...options.secret] : [];
+    if (!secrets.length || secrets.some((s) => typeof s !== "string" || s.length < 32)) {
+        throw new InferloError("IL6029", "sessions() secret must be a string of at least 32 characters (or a list of them, newest first).", { fix });
+    }
+    if (typeof options.user !== "function")
+        throw new InferloError("IL6029", "sessions() needs a user({ userId }, { db }) function that loads the signed-in user.", { fix });
+    const maxAgeMs = options.maxAgeMs ?? 7 * DAY;
+    if (!Number.isInteger(maxAgeMs) || maxAgeMs < 60_000 || maxAgeMs > 400 * DAY) {
+        throw new InferloError("IL6029", "sessions() maxAgeMs must be a whole number of milliseconds from 60000 (1 minute) to 34560000000 (400 days).", { fix });
+    }
+    const cookie = options.cookie ?? {};
+    const name = cookie.name ?? "inferlo_session";
+    if (!/^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/.test(name))
+        throw new InferloError("IL6029", `sessions() cookie name "${name}" is not a valid cookie name.`, { fix: 'Use letters, digits, "-" and "_", such as "app_session".' });
+    if (cookie.sameSite !== undefined && cookie.sameSite !== "lax" && cookie.sameSite !== "strict") {
+        throw new InferloError("IL6029", 'sessions() cookie.sameSite must be "lax" or "strict".', { fix: 'Use sameSite: "lax" (the default) or "strict".' });
+    }
+    for (const key of ["domain", "path"]) {
+        const value = cookie[key];
+        if (value !== undefined && (typeof value !== "string" || !value || /[;,\s]/.test(value))) {
+            throw new InferloError("IL6029", `sessions() cookie.${key} must be a non-empty string without spaces, commas or semicolons.`, { fix });
+        }
+    }
+    const csrfName = `${name}_csrf`;
+    const sameSite = cookie.sameSite === "strict" ? "Strict" : "Lax";
+    const path = cookie.path ?? "/";
+    const keys = secrets.map((secret) => crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]));
+    const sign = async (key, text) => base64url(new Uint8Array(await crypto.subtle.sign("HMAC", await key, new TextEncoder().encode(text))));
+    const csrfFor = (sessionId) => sign(keys[0], `csrf.${sessionId}`);
+    const attributes = (url, httpOnly, maxAge) => {
+        const local = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        const secure = cookie.secure ?? !local;
+        return [`Path=${path}`, cookie.domain ? `Domain=${cookie.domain}` : "", `Max-Age=${maxAge}`, httpOnly ? "HttpOnly" : "", secure ? "Secure" : "", `SameSite=${sameSite}`].filter(Boolean).join("; ");
+    };
+    /** The verified session of a request, or null. */
+    const read = async (req) => {
+        const value = readCookie(req.headers.get("cookie"), name);
+        if (!value)
+            return null;
+        const [version, payload, signature, extra] = value.split(".");
+        if (version !== "v1" || !payload || !signature || extra !== undefined)
+            return null;
+        let valid = false;
+        for (const key of keys)
+            if (safeEqual(await sign(key, `v1.${payload}`), signature))
+                valid = true;
+        if (!valid)
+            return null;
+        try {
+            const parsed = JSON.parse(new TextDecoder().decode(unbase64url(payload)));
+            if (typeof parsed.u !== "string" || typeof parsed.s !== "string" || typeof parsed.i !== "number" || typeof parsed.e !== "number")
+                return null;
+            if (parsed.e <= Date.now())
+                return null;
+            return { data: { userId: parsed.u, issuedAt: parsed.i }, sessionId: parsed.s };
+        }
+        catch {
+            return null;
+        }
+    };
+    const session = {
+        async resolve(req, { db }) {
+            const current = await read(req);
+            if (!current)
+                return null;
+            if (!SAFE_METHODS.has(req.method.toUpperCase())) {
+                const sent = req.headers.get("x-csrf-token") ?? (await formField(req, "_csrf"));
+                if (!sent || !safeEqual(sent, await csrfFor(current.sessionId))) {
+                    throw new InferloError("IL3005", "Missing or invalid CSRF token.", {
+                        status: 403,
+                        fix: "Send the session's CSRF token in an X-CSRF-Token header (from session.signIn or the " + csrfName + " cookie) or a _csrf form field (from session.csrfToken(req)).",
+                    });
+                }
+            }
+            return (await options.user(current.data, { db, req })) ?? null;
+        },
+        roles: options.roles,
+        async signIn(ctx, userId) {
+            if (typeof userId !== "string" || !userId)
+                throw new InferloError("IL6029", "session.signIn(ctx, userId) needs the user's id as a non-empty string.", { fix: "Call it after checking the password: await session.signIn(ctx, user.id)." });
+            if (!ctx || typeof ctx.header !== "function" || !(ctx.url instanceof URL))
+                throw new InferloError("IL6029", "session.signIn(ctx, userId) needs the route context.", { fix: "Pass the handler's context: route.post(\"/login\", ...).handle(async (ctx) => { await session.signIn(ctx, user.id) })." });
+            const now = Date.now();
+            const sessionId = base64url(crypto.getRandomValues(new Uint8Array(18)));
+            const payload = base64url(new TextEncoder().encode(JSON.stringify({ u: userId, s: sessionId, i: now, e: now + maxAgeMs })));
+            const value = `v1.${payload}.${await sign(keys[0], `v1.${payload}`)}`;
+            const csrfToken = await csrfFor(sessionId);
+            const seconds = Math.floor(maxAgeMs / 1000);
+            ctx.header("set-cookie", `${name}=${value}; ${attributes(ctx.url, true, seconds)}`);
+            ctx.header("set-cookie", `${csrfName}=${csrfToken}; ${attributes(ctx.url, false, seconds)}`);
+            return { csrfToken };
+        },
+        signOut(ctx) {
+            if (!ctx || typeof ctx.header !== "function" || !(ctx.url instanceof URL))
+                throw new InferloError("IL6029", "session.signOut(ctx) needs the route context.", { fix: "Pass the handler's context: session.signOut(ctx)." });
+            ctx.header("set-cookie", `${name}=; ${attributes(ctx.url, true, 0)}`);
+            ctx.header("set-cookie", `${csrfName}=; ${attributes(ctx.url, false, 0)}`);
+        },
+        async csrfToken(req) {
+            const current = await read(req);
+            return current ? csrfFor(current.sessionId) : null;
+        },
+    };
+    return Object.freeze(session);
+}
+function readCookie(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const i = part.indexOf("=");
+        if (i > 0 && part.slice(0, i).trim() === name)
+            return part.slice(i + 1).trim();
+    }
+    return undefined;
+}
+/** A field of a URL-encoded form body, read from a copy of the request (at most 64 KiB) so the route can still read it. */
+async function formField(req, field) {
+    if (!(req.headers.get("content-type") ?? "").toLowerCase().includes("application/x-www-form-urlencoded"))
+        return null;
+    if (Number(req.headers.get("content-length") ?? "0") > MAX_FORM_BYTES)
+        return null;
+    // Cloned before req.body is touched: on Bun 1.3, a body stream read before clone() comes back empty.
+    const body = req.clone().body;
+    if (!body)
+        return null;
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (size <= MAX_FORM_BYTES) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    if (size > MAX_FORM_BYTES)
+        return null;
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new URLSearchParams(new TextDecoder().decode(bytes)).get(field);
+}
+function base64url(bytes) {
+    let text = "";
+    for (const b of bytes)
+        text += String.fromCharCode(b);
+    return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unbase64url(text) {
+    const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (text.length % 4)) % 4);
+    return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

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

package/dist/sveltekit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Inferlo inside SvelteKit (2 and 3) server routes, without a runtime dependency on SvelteKit:
+ *
+ *   // src/routes/api/[...path]/+server.ts
+ *   import { toSvelteKitHandlers } from "@browserlessapi/inferlo/sveltekit";
+ *   import { app } from "$lib/server/inferlo";
+ *
+ *   export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app, { prefix: "/api" });
+ *
+ *   // src/hooks.server.ts: event.locals.ai in load functions, form actions and +server.ts files
+ *   import { inferloAI } from "@browserlessapi/inferlo/sveltekit";
+ *   export const handle = inferloAI(ai);
+ *
+ * It never loads the router, database or jobs code.
+ */
+import type { AI } from "./ai/index.ts";
+import type { App as InferloApp } from "./app.ts";
+declare global {
+    namespace App {
+        interface Locals {
+            /** The AI client from the inferloAI() handle hook of @browserlessapi/inferlo/sveltekit. */
+            ai: AI;
+        }
+    }
+}
+/** The parts of a SvelteKit RequestEvent Inferlo uses. */
+export interface SvelteKitEventLike {
+    /** The incoming Web request. */
+    request: Request;
+    /** The client IP from the adapter; called once per request, and errors (some adapters have none) are ignored. */
+    getClientAddress?: () => string;
+    /** event.locals, where the inferloAI() hook puts ai. */
+    locals: object;
+}
+/** A SvelteKit request handler, to export from a +server.ts file. */
+export type SvelteKitRequestHandler = (event: SvelteKitEventLike) => Promise<Response>;
+/** One request handler per HTTP method and a fallback for every other method, to export from +server.ts. */
+export interface SvelteKitHandlers {
+    GET: SvelteKitRequestHandler;
+    POST: SvelteKitRequestHandler;
+    PUT: SvelteKitRequestHandler;
+    PATCH: SvelteKitRequestHandler;
+    DELETE: SvelteKitRequestHandler;
+    HEAD: SvelteKitRequestHandler;
+    OPTIONS: SvelteKitRequestHandler;
+    fallback: SvelteKitRequestHandler;
+}
+export interface SvelteKitHandlersOptions {
+    /**
+     * The URL path of the route folder, removed before the app routes the request: "/api" for
+     * src/routes/api/[...path]/+server.ts. Requests outside it keep their path. Include SvelteKit's paths.base if set.
+     */
+    prefix?: string;
+}
+/** A SvelteKit handle hook: export const handle = inferloAI(ai), or sequence(inferloAI(ai), ...) to combine it. */
+export type SvelteKitHandle = (input: {
+    event: {
+        locals: object;
+    };
+    resolve: (event: any, opts?: any) => Response | Promise<Response>;
+}) => Response | Promise<Response>;
+/**
+ * Request handlers that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP) from a
+ * SvelteKit rest route: export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app).
+ */
+export declare function toSvelteKitHandlers(app: Pick<InferloApp<any>, "fetch">, options?: SvelteKitHandlersOptions): SvelteKitHandlers;
+/**
+ * A SvelteKit handle hook that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.locals.ai, for load functions, form actions and +server.ts files: export const handle = inferloAI(ai) in
+ * src/hooks.server.ts, or sequence(inferloAI(ai), yourHandle).
+ */
+export declare function inferloAI(ai: AI): SvelteKitHandle;

package/dist/sveltekit.js

@@ -0,0 +1,68 @@
+import { assertAIClient } from "./ai-client.js";
+import { clientIps } from "./client-ip.js";
+import { InferloError } from "./errors.js";
+import { normalizePrefix, stripPrefix } from "./serve.js";
+const fix = 'Pass the app from createApp and the route folder\'s path: export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: "/api" }).';
+/**
+ * Request handlers that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP) from a
+ * SvelteKit rest route: export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app).
+ */
+export function toSvelteKitHandlers(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5022", "toSvelteKitHandlers() needs an Inferlo app (the value returned by createApp).", { fix });
+    }
+    if (options === null || typeof options !== "object" || (options.prefix !== undefined && (typeof options.prefix !== "string" || !options.prefix.startsWith("/")))) {
+        throw new InferloError("IL5022", 'toSvelteKitHandlers() prefix must be a path that starts with /, such as "/api".', { fix });
+    }
+    const prefix = normalizePrefix(options.prefix);
+    const handle = async (event) => {
+        const incoming = event?.request;
+        if (!(incoming instanceof Request)) {
+            throw new InferloError("IL5022", "toSvelteKitHandlers()'s handlers were called with something that is not a SvelteKit request event.", {
+                fix: "Export them from a +server.ts file so SvelteKit calls them: export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: \"/api\" }).",
+            });
+        }
+        let request = incoming;
+        if (prefix) {
+            const url = new URL(incoming.url);
+            const stripped = stripPrefix(url.pathname, prefix);
+            if (stripped !== null) {
+                url.pathname = stripped;
+                const hasBody = incoming.body !== null && incoming.method !== "GET" && incoming.method !== "HEAD";
+                const init = {
+                    method: incoming.method,
+                    headers: incoming.headers,
+                    body: hasBody ? incoming.body : undefined,
+                    signal: incoming.signal,
+                    redirect: incoming.redirect,
+                };
+                if (hasBody)
+                    init.duplex = "half";
+                request = new Request(url, init);
+            }
+        }
+        try {
+            const ip = event.getClientAddress?.();
+            if (typeof ip === "string" && ip)
+                clientIps.set(request, ip);
+        }
+        catch {
+            // The adapter cannot tell the client address (for example while prerendering).
+        }
+        return app.fetch(request);
+    };
+    return Object.freeze({ GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle, HEAD: handle, OPTIONS: handle, fallback: handle });
+}
+/**
+ * A SvelteKit handle hook that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.locals.ai, for load functions, form actions and +server.ts files: export const handle = inferloAI(ai) in
+ * src/hooks.server.ts, or sequence(inferloAI(ai), yourHandle).
+ */
+export function inferloAI(ai) {
+    assertAIClient(ai, 'Pass createAI({ providers, models }) from "@browserlessapi/inferlo/ai", or an Inferlo app\'s app.ai: export const handle = inferloAI(ai).');
+    return ({ event, resolve }) => {
+        event.locals.ai = ai;
+        return resolve(event);
+    };
+}
+//# sourceMappingURL=sveltekit.js.map

package/dist/sveltekit.js.map

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

package/dist/tracing.d.ts

@@ -0,0 +1,118 @@
+/**
+ * OpenTelemetry tracing, with no dependency: pass the OpenTelemetry API you already use.
+ *
+ *   import * as otel from "@opentelemetry/api";
+ *   createApp({ tracing: { api: otel } })
+ *
+ * Every request gets a server span ("GET /tickets/:id") that continues the caller's trace (W3C traceparent, through
+ * the propagator your OpenTelemetry SDK registers), runs the handler inside it so spans you or instrumentations
+ * start nest under it, and puts traceId and spanId on the request's log entries. AI calls get client spans with the
+ * model, tokens and cost (also with createAI({ tracing }) on its own), and database queries made while a request
+ * or job is traced get client spans with the table and operation. Without an SDK, the API's no-op tracer is used
+ * and nothing is recorded.
+ */
+import type { Adapter } from "./db/types.ts";
+/** The parts of a span Inferlo uses (an @opentelemetry/api Span). */
+export interface OtelSpan {
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: unknown): void;
+    updateName(name: string): unknown;
+    end(): void;
+    isRecording(): boolean;
+}
+/** The parts of @opentelemetry/api Inferlo uses: import * as otel from "@opentelemetry/api", then { api: otel }. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string, version?: string): {
+            startSpan(name: string, options?: {
+                kind?: number;
+                attributes?: Record<string, string | number | boolean>;
+            }, context?: unknown): OtelSpan;
+        };
+        setSpan(context: unknown, span: OtelSpan): unknown;
+        /** The span of a context. Database spans are only started inside one (a request or a job). */
+        getSpan?(context: unknown): OtelSpan | undefined;
+    };
+    context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    propagation: {
+        extract(context: unknown, carrier: unknown, getter?: unknown): unknown;
+        /** Writes the trace of a context into a carrier (traceparent), so a queued job continues it. */
+        inject?(context: unknown, carrier: unknown, setter?: unknown): void;
+    };
+    SpanKind: {
+        SERVER: number;
+        CLIENT?: number;
+        CONSUMER?: number;
+    };
+    SpanStatusCode: {
+        ERROR: number;
+    };
+}
+export interface TracingConfig {
+    /** The OpenTelemetry API: import * as otel from "@opentelemetry/api", then createApp({ tracing: { api: otel } }). */
+    api: OtelApi;
+    /** The tracer name. Default: the app's name (createApp), or "inferlo" (createAI on its own). */
+    tracerName?: string;
+}
+type Attributes = Record<string, string | number | boolean>;
+export interface RequestTracing {
+    /** Starts the server span of a request and runs fn inside it. */
+    run<T>(req: Request, url: URL, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+}
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export declare function checkTracing(option: unknown, where: "createApp" | "createAI"): TracingConfig | undefined;
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export declare function requestTracing(option: unknown, appName: string, appVersion: string): RequestTracing | undefined;
+/** Client spans for calls Inferlo makes: AI models and the database. */
+export interface ClientTracing {
+    /** Starts a client span under the active one. The caller ends it (with end or fail). */
+    start(name: string, attributes: Attributes): OtelSpan;
+    /** Runs fn inside a client span that is active while fn runs, and ends it; errors are recorded on it. */
+    run<T>(name: string, attributes: Attributes, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+    /** Records an error on a span and ends it. */
+    fail(span: OtelSpan, error: unknown): void;
+    /** True while a span (a request's or a job's) is active. */
+    inSpan(): boolean;
+}
+export declare function clientTracing(config: TracingConfig, defaultName: string, version?: string): ClientTracing;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export declare function traceAdapter(adapter: Adapter, tracing: ClientTracing): Adapter;
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export declare function traceFields(span: OtelSpan | undefined): {
+    traceId?: string;
+    spanId?: string;
+};
+/** The trace a queued job carries from where it was enqueued (W3C trace context). */
+export interface JobTraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+export interface JobTracing {
+    /** The trace of the active span, to store with a job that is enqueued now. Empty outside a trace. */
+    capture(): JobTraceContext;
+    /** Runs one attempt of a job in a span that continues the trace it was enqueued in (cron jobs start a new trace). */
+    run<T extends string>(job: {
+        id: string;
+        name: string;
+        attempts: number;
+        trace?: JobTraceContext;
+    }, fn: (fail: (error: unknown) => void) => Promise<T>): Promise<T>;
+}
+export declare function jobTracing(config: TracingConfig, defaultName: string, version?: string): JobTracing;
+export {};

package/dist/tracing.js

@@ -0,0 +1,204 @@
+import { InferloError } from "./errors.js";
+/** CLIENT and CONSUMER in @opentelemetry/api's SpanKind (the same in every 1.x release). */
+const CLIENT_KIND = 2;
+const CONSUMER_KIND = 4;
+/** Reads incoming trace headers (traceparent, tracestate, baggage) for the propagator. */
+const headerGetter = {
+    get(carrier, key) {
+        return carrier.get(key) ?? undefined;
+    },
+    keys(carrier) {
+        return [...carrier.keys()];
+    },
+};
+const INVALID_TRACE = "00000000000000000000000000000000";
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export function checkTracing(option, where) {
+    if (option === undefined || option === false)
+        return undefined;
+    const config = option;
+    const api = config?.api;
+    const valid = config !== null &&
+        typeof config === "object" &&
+        typeof api?.trace?.getTracer === "function" &&
+        typeof api.trace.setSpan === "function" &&
+        typeof api.context?.with === "function" &&
+        typeof api.context.active === "function" &&
+        typeof api.propagation?.extract === "function" &&
+        typeof api.SpanKind?.SERVER === "number" &&
+        typeof api.SpanStatusCode?.ERROR === "number" &&
+        (config.tracerName === undefined || (typeof config.tracerName === "string" && config.tracerName.length > 0));
+    if (!valid) {
+        throw new InferloError("IL6030", "Invalid tracing options: tracing needs { api } with the OpenTelemetry API.", {
+            fix: `Install @opentelemetry/api (and an OpenTelemetry SDK that exports the spans), then: import * as otel from "@opentelemetry/api"; ${where}({ tracing: { api: otel } }).`,
+        });
+    }
+    return config;
+}
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export function requestTracing(option, appName, appVersion) {
+    const config = checkTracing(option, "createApp");
+    if (!config)
+        return undefined;
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? appName, appVersion);
+    return {
+        run(req, url, fn) {
+            const method = req.method.toUpperCase();
+            const parent = api.propagation.extract(api.context.active(), req.headers, headerGetter);
+            const attributes = {
+                "http.request.method": method,
+                "url.path": url.pathname,
+                "url.scheme": url.protocol.replace(/:$/, ""),
+                "server.address": url.hostname,
+            };
+            if (url.port)
+                attributes["server.port"] = Number(url.port);
+            const agent = req.headers.get("user-agent");
+            if (agent)
+                attributes["user_agent.original"] = agent;
+            const span = tracer.startSpan(method, { kind: api.SpanKind.SERVER, attributes }, parent);
+            return api.context.with(api.trace.setSpan(parent, span), () => fn(span));
+        },
+    };
+}
+export function clientTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CLIENT ?? CLIENT_KIND;
+    const fail = (span, error) => {
+        span.recordException(error instanceof Error ? error : String(error));
+        const code = error?.code;
+        if (typeof code === "string")
+            span.setAttribute("error.type", code);
+        else
+            span.setAttribute("error.type", error instanceof Error ? error.name : "Error");
+        span.setStatus({ code: api.SpanStatusCode.ERROR });
+        span.end();
+    };
+    const start = (name, attributes) => tracer.startSpan(name, { kind, attributes }, api.context.active());
+    return {
+        start,
+        fail,
+        async run(name, attributes, fn) {
+            const span = start(name, attributes);
+            let result;
+            try {
+                result = await api.context.with(api.trace.setSpan(api.context.active(), span), () => fn(span));
+            }
+            catch (error) {
+                fail(span, error);
+                throw error;
+            }
+            span.end();
+            return result;
+        },
+        inSpan() {
+            if (!api.trace.getSpan)
+                return true;
+            const active = api.trace.getSpan(api.context.active());
+            return active !== undefined && active.spanContext().traceId !== INVALID_TRACE;
+        },
+    };
+}
+const SQL_OPERATION = /^\s*([a-z]+)/i;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export function traceAdapter(adapter, tracing) {
+    const system = adapter.dialect === "postgres" ? "postgresql" : adapter.dialect;
+    const traced = (operation, table, query, fn) => {
+        if (!tracing.inSpan())
+            return fn();
+        const attributes = { "db.system.name": system, "db.operation.name": operation };
+        if (table)
+            attributes["db.collection.name"] = table;
+        if (query)
+            attributes["db.query.text"] = query;
+        return tracing.run(table ? `${operation} ${table}` : operation, attributes, fn);
+    };
+    const wrapped = {
+        ...adapter,
+        insert: (model, row) => traced("INSERT", model.name, undefined, () => adapter.insert(model, row)),
+        select: (model, query) => traced("SELECT", model.name, undefined, () => adapter.select(model, query)),
+        update: (model, where, patch) => traced("UPDATE", model.name, undefined, () => adapter.update(model, where, patch)),
+        delete: (model, where) => traced("DELETE", model.name, undefined, () => adapter.delete(model, where)),
+        count: (model, where) => traced("COUNT", model.name, undefined, () => adapter.count(model, where)),
+    };
+    if (adapter.transaction)
+        wrapped.transaction = (fn) => adapter.transaction((tx) => fn(traceAdapter(tx, tracing)));
+    if (adapter.sql) {
+        wrapped.sql = (text, params) => traced((SQL_OPERATION.exec(text)?.[1] ?? "SQL").toUpperCase(), undefined, text, () => adapter.sql(text, params));
+    }
+    return wrapped;
+}
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export function traceFields(span) {
+    const context = span?.spanContext();
+    if (!context || context.traceId === INVALID_TRACE)
+        return {};
+    return { traceId: context.traceId, spanId: context.spanId };
+}
+const carrierGetter = {
+    get(carrier, key) {
+        return key === "traceparent" || key === "tracestate" ? carrier[key] : undefined;
+    },
+    keys(carrier) {
+        return Object.keys(carrier);
+    },
+};
+const TRACEPARENT = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+export function jobTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CONSUMER ?? CONSUMER_KIND;
+    return {
+        capture() {
+            if (!api.propagation.inject)
+                return {};
+            const carrier = {};
+            api.propagation.inject(api.context.active(), carrier);
+            const trace = {};
+            if (typeof carrier.traceparent === "string" && TRACEPARENT.test(carrier.traceparent)) {
+                trace.traceparent = carrier.traceparent;
+                if (typeof carrier.tracestate === "string" && carrier.tracestate.length <= 512)
+                    trace.tracestate = carrier.tracestate;
+            }
+            return trace;
+        },
+        async run(job, fn) {
+            const parent = job.trace?.traceparent ? api.propagation.extract(api.context.active(), job.trace, carrierGetter) : api.context.active();
+            const span = tracer.startSpan(`process ${job.name}`, {
+                kind,
+                attributes: {
+                    "messaging.system": "inferlo",
+                    "messaging.operation.type": "process",
+                    "messaging.destination.name": job.name,
+                    "messaging.message.id": job.id,
+                    "inferlo.job.attempt": job.attempts,
+                },
+            }, parent);
+            const fail = (error) => {
+                span.recordException(error instanceof Error ? error : String(error));
+                const code = error?.code;
+                span.setAttribute("error.type", typeof code === "string" ? code : error instanceof Error ? error.name : "Error");
+                span.setStatus({ code: api.SpanStatusCode.ERROR });
+            };
+            try {
+                const outcome = await api.context.with(api.trace.setSpan(parent, span), () => fn(fail));
+                span.setAttribute("inferlo.job.outcome", outcome);
+                return outcome;
+            }
+            catch (error) {
+                fail(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        },
+    };
+}
+//# sourceMappingURL=tracing.js.map