@thenavidm/slipway 0.1.0

package/dist/jobs.js

@@ -0,0 +1,247 @@
+/**
+ * Work that takes longer than a client waits for one call.
+ *
+ * Clients stop waiting on a tool after about a minute, and some much sooner,
+ * so a render, an export or a long sync cannot simply run inside the call.
+ * A job tool starts the work and waits a bounded time. A job that finishes in
+ * time comes back with its result, as any call would. One that does not comes
+ * back as a job the caller checks with a generated `<name>_status` tool, so a
+ * model never polls blind and a script never guesses at a status endpoint.
+ *
+ * Two kinds:
+ * - the service runs the job and has its own status endpoint (`id`, `status`
+ *   and `done` say how to read it), or
+ * - the handler itself is slow (`background: true`), and Slipway runs it in
+ *   this process and keeps its result for an hour.
+ */
+import { randomBytes } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { ApiError, CanceledError, NotFoundError, RateLimitError, toSlipwayError } from "./errors.js";
+/** A client stops waiting on a call after about a minute, so no call waits longer than this. */
+export const MAX_WAIT_SECONDS = 55;
+export const DEFAULT_WAIT_SECONDS = 25;
+const DEFAULT_POLL_MS = 2_000;
+const MIN_POLL_MS = 250;
+export function isBackground(job) {
+    return job.background === true;
+}
+export function waitSecondsFor(job) {
+    const wanted = job.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+    return Math.max(0, Math.min(MAX_WAIT_SECONDS, Math.floor(wanted)));
+}
+export function pollMsFor(job) {
+    return Math.max(MIN_POLL_MS, job.pollMs ?? DEFAULT_POLL_MS);
+}
+export function readJobId(job, started) {
+    let value;
+    if (typeof job.id === "function")
+        value = job.id(started);
+    else {
+        value = started;
+        for (const part of job.id.split(".").filter(Boolean)) {
+            value = value !== null && typeof value === "object" ? value[part] : undefined;
+        }
+    }
+    return typeof value === "string" && value ? value : typeof value === "number" ? String(value) : undefined;
+}
+/** The longest delay a Node timer takes. Anything longer fires after 1 ms instead. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * Wait until `finished` settles or `ms` passes, whichever is first. Infinity
+ * waits for as long as it takes. Resolves true when it finished. A canceled
+ * call stops waiting at once.
+ */
+export async function waitFor(finished, ms, signal) {
+    let settled = false;
+    const done = finished.then(() => void (settled = true), () => void (settled = true));
+    if (ms <= 0)
+        return settled;
+    let timer;
+    let onAbort;
+    const stop = new Promise((resolve) => {
+        if (Number.isFinite(ms))
+            timer = setTimeout(resolve, Math.min(ms, MAX_TIMER_MS));
+        if (signal) {
+            onAbort = () => resolve();
+            if (signal.aborted)
+                resolve();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+    try {
+        await Promise.race([done, stop]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (signal && onAbort)
+            signal.removeEventListener("abort", onAbort);
+    }
+    if (!settled && signal?.aborted)
+        throw new CanceledError("Stopped waiting for the job.");
+    return settled;
+}
+/** Sleep between status checks, cut short by a canceled call. */
+export async function pause(ms, signal) {
+    try {
+        await sleep(Math.min(ms, MAX_TIMER_MS), undefined, signal ? { signal } : undefined);
+    }
+    catch {
+        throw new CanceledError("Stopped waiting for the job.");
+    }
+}
+/** A failed service job, reported with the status that says why. */
+export function jobFailed(tool, id, status) {
+    return new ApiError(`${tool} job ${id} failed.`, { details: status });
+}
+/**
+ * Background jobs of one process.
+ *
+ * Bounded both ways: at most 100 run at once, and a finished job is kept for
+ * an hour, so a server that runs for weeks never grows without limit. Ids are
+ * random, so one caller cannot read another's job by counting.
+ */
+export class JobRegistry {
+    jobs = new Map();
+    static MAX_RUNNING = 100;
+    static KEEP_MS = 60 * 60_000;
+    static MAX_KEPT = 500;
+    start(tool, work) {
+        this.prune();
+        const running = [...this.jobs.values()].filter((entry) => entry.state === "running").length;
+        if (running >= JobRegistry.MAX_RUNNING) {
+            throw new RateLimitError(`${running} background jobs are already running. Wait for some to finish.`);
+        }
+        const entry = { id: `job_${randomBytes(12).toString("hex")}`, tool, startedAt: Date.now(), state: "running", finished: Promise.resolve() };
+        const report = (update) => {
+            entry.progress = update;
+            entry.listener?.(update);
+        };
+        entry.finished = (async () => {
+            try {
+                entry.result = await work(report);
+                entry.state = "done";
+            }
+            catch (error) {
+                entry.error = toSlipwayError(error);
+                entry.state = "failed";
+            }
+            finally {
+                entry.finishedAt = Date.now();
+                entry.listener = undefined;
+            }
+        })();
+        this.jobs.set(entry.id, entry);
+        return entry;
+    }
+    get(id, tool) {
+        this.prune();
+        const entry = this.jobs.get(id);
+        if (!entry || entry.tool !== tool) {
+            throw new NotFoundError(`No ${tool} job ${id} in this server.`, {
+                hint: "Background jobs live in the server that started them, for an hour after they finish. Start it again if the server restarted.",
+            });
+        }
+        return entry;
+    }
+    prune() {
+        const now = Date.now();
+        for (const [id, entry] of this.jobs) {
+            if (entry.finishedAt !== undefined && now - entry.finishedAt > JobRegistry.KEEP_MS)
+                this.jobs.delete(id);
+        }
+        // Oldest finished first, when there are too many to keep.
+        if (this.jobs.size > JobRegistry.MAX_KEPT) {
+            for (const [id, entry] of this.jobs) {
+                if (this.jobs.size <= JobRegistry.MAX_KEPT)
+                    break;
+                if (entry.state !== "running")
+                    this.jobs.delete(id);
+            }
+        }
+    }
+}
+/** A background job as its caller sees it. Throws the job's own error once it failed. */
+export function backgroundResult(entry, check) {
+    if (entry.state === "failed")
+        throw entry.error;
+    const done = entry.state === "done";
+    return {
+        job_id: entry.id,
+        tool: entry.tool,
+        done,
+        ...(done ? { result: entry.result } : {}),
+        ...(entry.progress ? { progress: entry.progress } : {}),
+        started_at: new Date(entry.startedAt).toISOString(),
+        ...(entry.finishedAt !== undefined ? { finished_at: new Date(entry.finishedAt).toISOString() } : {}),
+        ...(done ? {} : { check }),
+    };
+}
+/** Start or check a job, and wait for it as long as this call may. */
+export async function runJob(call) {
+    if (isBackground(call.job))
+        return runBackground(call);
+    return runServiceJob(call, call.job);
+}
+async function runBackground(call) {
+    let entry;
+    if (call.start) {
+        const start = call.start;
+        entry = call.registry.start(call.jobTool, (report) => {
+            // The job outlives the call that started it, so it gets its own signal.
+            const signal = call.timeoutMs ? AbortSignal.timeout(call.timeoutMs) : new AbortController().signal;
+            return call.untilAborted(Promise.resolve(start(call.context(signal, report))), signal);
+        });
+    }
+    else {
+        entry = call.registry.get(call.jobId, call.jobTool);
+    }
+    if (entry.progress)
+        call.progress(entry.progress);
+    entry.listener = call.progress;
+    try {
+        await waitFor(entry.finished, call.waitMs, call.waitSignal);
+    }
+    finally {
+        if (entry.listener === call.progress)
+            entry.listener = undefined;
+    }
+    return backgroundResult(entry, call.check(entry.id));
+}
+async function runServiceJob(call, job) {
+    const read = (id) => {
+        const signal = call.requestSignal();
+        return call.untilAborted(Promise.resolve(job.status(id, call.context(signal, call.progress))), signal);
+    };
+    let id;
+    let status;
+    if (call.start) {
+        const signal = call.requestSignal();
+        status = await call.untilAborted(Promise.resolve(call.start(call.context(signal, call.progress))), signal);
+        const found = readJobId(job, status);
+        if (!found) {
+            throw new ApiError(`${call.jobTool} started a job but returned no job id${typeof job.id === "string" ? ` at '${job.id}'` : ""}.`, { details: status });
+        }
+        id = found;
+    }
+    else {
+        id = call.jobId;
+        status = await read(id);
+    }
+    const deadline = call.waitMs === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Date.now() + call.waitMs;
+    for (;;) {
+        const update = job.progress?.(status);
+        if (update)
+            call.progress(update);
+        if (job.done(status)) {
+            if (job.failed?.(status))
+                throw jobFailed(call.jobTool, id, status);
+            return { job_id: id, tool: call.jobTool, done: true, status };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return { job_id: id, tool: call.jobTool, done: false, status, check: call.check(id) };
+        await pause(Math.min(pollMsFor(job), remaining), call.waitSignal);
+        status = await read(id);
+    }
+}

package/dist/openapi.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Tools from an OpenAPI document.
+ *
+ * An API that publishes OpenAPI already says what every operation takes. This
+ * turns each operation into a tool with that input, the risk its HTTP method
+ * implies, and its tags as toolsets, so a large API becomes a server and a CLI
+ * without a hand-written tool per endpoint. The tools join the same list as
+ * hand-written ones and go through the same guard.
+ *
+ * A generated tool is only as trustworthy as the document it came from, so a
+ * document can be pinned by hash: a changed document refuses to build until
+ * someone has looked at what changed and updated the pin.
+ */
+import { type JsonSchema } from "./schema.js";
+import { type Risk, type Tool, type ToolContext } from "./tool.js";
+export type OperationParameter = {
+    /** The parameter's name in the API. */
+    name: string;
+    in: "path" | "query" | "header";
+    required: boolean;
+    /** The input property that carries it. */
+    property: string;
+    /** How the value is written, as the document says: form and deepObject in a query, simple in a path or header. */
+    style: string;
+    explode: boolean;
+};
+export type Operation = {
+    operationId: string;
+    /** Upper case: GET, POST. */
+    method: string;
+    /** The path template: /pets/{petId}. */
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    deprecated: boolean;
+    parameters: OperationParameter[];
+    /**
+     * The request body, and how the input carries it: spread into the input's
+     * own properties, or as one `body` property. `fields` maps each input
+     * property back to the body field it carries, which differs where a field's
+     * own name was taken.
+     */
+    body?: {
+        contentType: string;
+        required: boolean;
+        spread: boolean;
+        fields: Record<string, string>;
+    };
+    /** The tool's input, as JSON Schema 2020-12. */
+    input: JsonSchema;
+    /** The JSON schema of a successful response, when the document gives one. */
+    output?: JsonSchema;
+};
+/** What one call sends, split the way HTTP carries it. */
+export type OperationInput = {
+    path: Record<string, unknown>;
+    query: Record<string, unknown>;
+    headers: Record<string, string>;
+    body?: unknown;
+};
+/** Runs one operation. `httpExecutor` covers JSON and form APIs; write your own for anything else. */
+export type Executor<Ctx> = (operation: Operation, input: OperationInput, ctx: ToolContext<Ctx>) => unknown | Promise<unknown>;
+export type FromOpenAPIOptions<Ctx> = {
+    execute: Executor<Ctx>;
+    /** Only these operations, by operationId, or the ones a test accepts. */
+    include?: readonly string[] | ((operation: Operation) => boolean);
+    /** Tool names by operationId, where the generated one reads badly. */
+    names?: Record<string, string>;
+    /** Risk by operationId, where the method misleads: a POST that only searches is a read. */
+    risk?: Record<string, Risk>;
+    /** Refuse to build from a document whose hash differs. `slipway openapi <file>` prints the hash to pin. */
+    pin?: {
+        sha256: string;
+    };
+    /** Declare each operation's documented JSON response as the tool's output. Off by default, since APIs often return more than they document. */
+    typedOutput?: boolean;
+    /** Put before every tool name, to keep two APIs in one app apart. */
+    prefix?: string;
+};
+export type SkippedOperation = {
+    method: string;
+    path: string;
+    operationId?: string;
+    reason: string;
+};
+/** The hash to pin a document by: the same for the same content, however its keys were ordered. */
+export declare function openapiHash(document: unknown): string;
+/**
+ * An OpenAPI schema as JSON Schema 2020-12: `nullable` becomes a null type,
+ * 3.0's boolean exclusive bounds become numbers, `example` becomes
+ * `examples`, and keys that only mean something to OpenAPI are dropped.
+ * Properties the server sets itself (`readOnly`) leave a request's input.
+ */
+export declare function toJsonSchema(node: unknown, forInput: boolean): unknown;
+/**
+ * operationId as a tool name: listPets and pets.list become list_pets and
+ * pets_list. A name past the 64 characters clients allow keeps its start and
+ * ends in a short hash of the id, so two long ids that begin alike stay
+ * two names, and the same id always gets the same one.
+ */
+export declare function toolName(id: string): string;
+/** Every operation in a document, as tools would see it, and the ones that cannot become tools, with why. */
+export declare function readOperations(document: unknown, options?: {
+    typedOutput?: boolean;
+}): {
+    operations: Operation[];
+    skipped: SkippedOperation[];
+};
+/** Split a tool's arguments back into what goes in the path, the query, the headers and the body. */
+export declare function splitInput(operation: Operation, args: Record<string, unknown>): OperationInput;
+/** Build a tool for every operation in an OpenAPI 3 document. Throws on a pinned document that changed. */
+export declare function fromOpenAPI<Ctx>(document: unknown, options: FromOpenAPIOptions<Ctx>): Tool<Ctx>[];
+/** A form body, with nested objects and lists in the bracket style form APIs read: `metadata[plan]=pro`, `items[0][price]=...`. */
+export declare function formEncode(body: unknown): string;
+export type HttpExecutorOptions<Ctx> = {
+    /** Where the API lives: https://api.example.com/v1. Plain http only reaches this machine. */
+    baseUrl: string | ((ctx: ToolContext<Ctx>) => string);
+    /** Headers every call sends, such as the credentials. Register those as secrets on the app, so they are masked. */
+    headers?: (ctx: ToolContext<Ctx>) => Record<string, string | undefined> | Promise<Record<string, string | undefined>>;
+    fetch?: typeof fetch;
+};
+/**
+ * Calls the API over HTTP. Errors come back as Slipway errors with the API's
+ * own message and status, so a model can act on a 404 or a 429 like any other.
+ */
+export declare function httpExecutor<Ctx>(options: HttpExecutorOptions<Ctx>): Executor<Ctx>;