@kindgi/handler-runtime 0.0.0-bootstrap.0 → 0.1.0

package/dist/pack-service/service.js

@@ -0,0 +1,341 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The pack service: an HTTP server that runs a pack's code — its tool
+ * handlers and guardrail checks — for a Kindgi runtime, speaking pack
+ * protocol v2 (`../protocol.ts`).
+ *
+ * Long-lived and warm: modules are imported once (at `prewarm`) and
+ * reused across calls, and calls run concurrently up to a cap. Handler
+ * console output goes to the process's own stdout/stderr and can never
+ * corrupt a response.
+ *
+ * Routes:
+ *   - `POST /v1/invoke` (token)  — body: a `PackRequest`; 200 with a `PackResponse`
+ *   - `GET  /v1/info`   (token)  — the pack's identity, protocol, tools and checks,
+ *                                  and the required env names it lacks (`missingEnv`)
+ *   - `GET  /healthz`            — the process is up
+ *   - `GET  /readyz`             — prewarmed, not draining, and (under the
+ *                                  `strict` env check) every required env name set
+ *
+ * Non-2xx statuses are transport-level only: 401 (token), 404, 405, 413
+ * (body too large), 415 (not JSON), 503 with `Retry-After` (not ready,
+ * draining or at the concurrency cap), and 500 if the service itself
+ * fails while handling a call.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { runCheck, runHandler } from '../handler-runner.js';
+import { missingPackEnv } from '../pack-env.js';
+import { PACK_HEADERS, PACK_PROTOCOL_VERSION, packError, parsePackRequest, } from '../protocol.js';
+const DEFAULT_MAX_CONCURRENCY = 32;
+const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 120_000;
+export function createPackService(options) {
+    const maxConcurrency = options.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const logger = options.logger ?? (() => undefined);
+    const importModule = options.importModule ?? ((p) => import(pathToFileURL(p).href));
+    const expectedToken = Buffer.from(options.token);
+    const tools = new Map(options.index.tools.map((t) => [t.id, t]));
+    const checks = new Map(options.index.guardrails.map((g) => [g.checkId ?? g.id, g]));
+    let inFlight = 0;
+    let ready = false;
+    let draining = false;
+    const envCheck = options.envCheck ?? 'strict';
+    const missingEnv = missingPackEnv(options.index.env, options.env ?? process.env);
+    if (missingEnv.length > 0)
+        logger({ kind: 'missing-env', check: envCheck, names: missingEnv });
+    /** Why the service can't take calls now, or `undefined` when it can. */
+    function notReady() {
+        if (draining)
+            return unavailable('draining');
+        if (envCheck === 'strict' && missingEnv.length > 0) {
+            return unavailable('missing env', { missingEnv });
+        }
+        if (!ready)
+            return unavailable('not ready');
+        return undefined;
+    }
+    function authorized(req) {
+        const got = req.headers[PACK_HEADERS.token];
+        if (typeof got !== 'string')
+            return false;
+        const buf = Buffer.from(got);
+        return buf.length === expectedToken.length && timingSafeEqual(buf, expectedToken);
+    }
+    async function prewarm() {
+        const failures = [];
+        const targets = [
+            ...[...tools.values()].map((t) => ({ id: t.id, modulePath: t.modulePath, check: false })),
+            ...[...checks.entries()].map(([id, g]) => ({
+                id,
+                modulePath: g.checkModulePath,
+                check: true,
+            })),
+        ];
+        for (const target of targets) {
+            try {
+                await importModule(options.resolveModule(target.modulePath));
+            }
+            catch (cause) {
+                failures.push(packError('handler-import-failed', `${target.id}: ${describe(cause)}`, {
+                    ...(target.check ? { checkId: target.id } : { toolId: target.id }),
+                }));
+            }
+        }
+        ready = failures.length === 0;
+        return failures;
+    }
+    async function drain(graceMs) {
+        draining = true;
+        const deadline = Date.now() + graceMs;
+        while (inFlight > 0 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 25));
+        }
+    }
+    function info() {
+        return {
+            protocol: PACK_PROTOCOL_VERSION,
+            packId: options.index.packId,
+            packVersion: options.index.packVersion,
+            artifactVersion: options.index.artifactVersion,
+            tools: [...tools.values()].map((t) => ({
+                id: t.id,
+                ...(t.version && { version: t.version }),
+            })),
+            checks: [...checks.keys()],
+            missingEnv,
+        };
+    }
+    function callTool(message, signal) {
+        const tool = tools.get(message.tool.id);
+        if (tool === undefined) {
+            return Promise.resolve(packError('tool-not-in-pack', `This pack has no tool "${message.tool.id}"`, {
+                toolId: message.tool.id,
+            }));
+        }
+        if (message.tool.version !== undefined && message.tool.version !== tool.version) {
+            return Promise.resolve(packError('tool-version-mismatch', `Tool "${tool.id}" is ${tool.version ?? 'unversioned'} in this pack; the caller asked for ${message.tool.version}`, { toolId: tool.id }));
+        }
+        return runHandler({
+            tool: {
+                id: tool.id,
+                modulePath: options.resolveModule(tool.modulePath),
+                inputSchema: tool.input,
+                outputSchema: tool.output,
+            },
+            input: message.input,
+            ctx: { ...message.ctx, abortSignal: signal },
+            importHandler: (p) => importModule(p),
+        }).then((r) => r.kind === 'ok'
+            ? { v: PACK_PROTOCOL_VERSION, kind: 'result', output: r.value }
+            : fromHandlerError(r.error, { toolId: tool.id }));
+    }
+    function callCheck(message, signal) {
+        const guardrail = checks.get(message.check.id);
+        if (guardrail === undefined) {
+            return Promise.resolve(packError('check-not-in-pack', `This pack has no check "${message.check.id}"`, {
+                checkId: message.check.id,
+            }));
+        }
+        return runCheck({
+            check: { id: message.check.id, modulePath: options.resolveModule(guardrail.checkModulePath) },
+            config: message.config,
+            trace: message.trace,
+            abortSignal: signal,
+            importCheck: (p) => importModule(p),
+        }).then((r) => r.kind === 'ok'
+            ? { v: PACK_PROTOCOL_VERSION, kind: 'check-result', result: r.value }
+            : fromHandlerError(r.error, { checkId: message.check.id }));
+    }
+    /** Why a call can't be taken right now, if it can't. */
+    function refuseInvoke(req) {
+        const unready = notReady();
+        if (unready !== undefined)
+            return unready;
+        if (inFlight >= maxConcurrency)
+            return unavailable('overloaded');
+        if (!(req.headers['content-type'] ?? '').includes('application/json')) {
+            return { status: 415, body: { error: 'Content-Type must be application/json' } };
+        }
+        return undefined;
+    }
+    async function invoke(req, res) {
+        const refused = refuseInvoke(req);
+        if (refused !== undefined) {
+            reply(res, refused);
+            return;
+        }
+        inFlight += 1;
+        const started = Date.now();
+        try {
+            const body = await readBody(req, maxBodyBytes);
+            const response = body === undefined ? undefined : await dispatch(req, res, body);
+            if (res.writableEnded || res.destroyed)
+                return;
+            reply(res, response === undefined
+                ? { status: 413, body: { error: 'Request body too large' } }
+                : {
+                    status: 200,
+                    body: response,
+                    headers: {
+                        [PACK_HEADERS.durationMs]: String(Date.now() - started),
+                        [PACK_HEADERS.artifactVersion]: options.index.artifactVersion,
+                    },
+                });
+        }
+        finally {
+            inFlight -= 1;
+        }
+    }
+    async function dispatch(req, res, body) {
+        let json;
+        try {
+            json = JSON.parse(body);
+        }
+        catch {
+            return packError('malformed-message', 'Request body is not valid JSON');
+        }
+        const parsed = parsePackRequest(json);
+        if (parsed.kind === 'err')
+            return parsed.error;
+        const message = parsed.value;
+        const target = message.kind === 'invoke' ? 'tool' : 'check';
+        const id = message.kind === 'invoke' ? message.tool.id : message.check.id;
+        const controller = new AbortController();
+        const timeoutMs = parseTimeout(req.headers[PACK_HEADERS.timeoutMs]) ?? defaultTimeoutMs;
+        const timer = setTimeout(() => controller.abort('deadline-exceeded'), timeoutMs);
+        // The caller gave up (closed the connection) before we answered.
+        res.on('close', () => {
+            if (!res.writableEnded)
+                controller.abort('cancelled');
+        });
+        const started = Date.now();
+        const work = message.kind === 'invoke'
+            ? callTool(message, controller.signal)
+            : callCheck(message, controller.signal);
+        const outcome = await Promise.race([work, aborted(controller.signal, id, target)]);
+        clearTimeout(timer);
+        if (controller.signal.aborted) {
+            void work.then(() => logger({ kind: 'handler-finished-late', target, id, afterMs: Date.now() - started }));
+        }
+        logger({
+            kind: 'call',
+            target,
+            id,
+            durationMs: Date.now() - started,
+            outcome: outcome.kind === 'error' ? outcome.code : 'ok',
+        });
+        return outcome;
+    }
+    /** The transport-level answer for a request before any route runs, if any. */
+    function refuseRequest(req, route) {
+        if (route === undefined)
+            return { status: 404, body: { error: `No route ${req.url ?? '/'}` } };
+        if (req.method !== route.method)
+            return { status: 405, body: { error: `Use ${route.method}` } };
+        if (route.auth && !authorized(req))
+            return { status: 401, body: { error: 'Bad pack token' } };
+        return undefined;
+    }
+    function probe(name) {
+        if (name === 'healthz')
+            return { status: 200, body: { status: 'ok' } };
+        if (name === 'readyz')
+            return notReady() ?? { status: 200, body: { status: 'ready' } };
+        return { status: 200, body: info() };
+    }
+    function handle(req, res) {
+        const route = ROUTES[(req.url ?? '/').split('?')[0] ?? ''];
+        const refused = refuseRequest(req, route);
+        if (refused !== undefined || route === undefined) {
+            reply(res, refused ?? { status: 404, body: {} });
+            return;
+        }
+        if (route.name !== 'invoke') {
+            reply(res, probe(route.name));
+            return;
+        }
+        void invoke(req, res).catch((cause) => {
+            if (!res.writableEnded)
+                reply(res, { status: 500, body: { error: describe(cause) } });
+        });
+    }
+    return {
+        handle,
+        prewarm,
+        drain,
+        inFlight: () => inFlight,
+        ready: () => notReady() === undefined,
+    };
+}
+const ROUTES = {
+    '/v1/invoke': { name: 'invoke', method: 'POST', auth: true },
+    '/v1/info': { name: 'info', method: 'GET', auth: true },
+    '/healthz': { name: 'healthz', method: 'GET', auth: false },
+    '/readyz': { name: 'readyz', method: 'GET', auth: false },
+};
+function aborted(signal, id, target) {
+    return new Promise((resolve) => {
+        const settle = () => {
+            const reason = signal.reason === 'deadline-exceeded' ? 'deadline-exceeded' : 'cancelled';
+            const message = reason === 'deadline-exceeded' ? `${id} passed its deadline` : `${id} was cancelled`;
+            resolve(packError(reason, message, target === 'tool' ? { toolId: id } : { checkId: id }));
+        };
+        if (signal.aborted)
+            settle();
+        else
+            signal.addEventListener('abort', settle, { once: true });
+    });
+}
+function fromHandlerError(error, ids) {
+    return packError(error.code, error.message, {
+        ...ids,
+        ...(error.cause !== undefined && { cause: error.cause }),
+        ...(error.issues !== undefined && { issues: error.issues }),
+    });
+}
+function parseTimeout(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const ms = Number(raw);
+    return Number.isInteger(ms) && ms > 0 ? ms : undefined;
+}
+/** The body as text, or `undefined` once it exceeds `limit` (the rest is drained). */
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit)
+                tooLarge = true;
+            if (!tooLarge)
+                chunks.push(chunk);
+        });
+        req.on('end', () => resolve(tooLarge ? undefined : Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function unavailable(reason, details) {
+    return { status: 503, body: { error: reason, ...details }, headers: { 'retry-after': '1' } };
+}
+function reply(res, r) {
+    sendJson(res, r.status, r.body, r.headers);
+}
+function sendJson(res, status, body, headers = {}) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(text),
+        ...headers,
+    });
+    res.end(text);
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+//# sourceMappingURL=service.js.map

package/dist/pack-service/service.js.map

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

package/dist/pack-service/supervisor.d.ts

@@ -0,0 +1,138 @@
+import type { Result } from '@kindgi/types';
+export interface PackServiceSupervisorOptions {
+    /**
+     * The pack-service process as an argv — the program, then its arguments.
+     * The supervisor appends `--index`, `--module-root` and `--host`. Any pack
+     * service with that process contract works (`pack-protocol.schema.json`):
+     *
+     *   - Node: `[process.execPath, '--enable-source-maps', <@kindgi/handler-runtime/pack-service-main>]`
+     *   - Python: `[<the pack's python>, '-m', 'kindgi.pack', 'serve']`
+     */
+    readonly command: readonly [string, ...string[]];
+    /** Where the index's module paths resolve — the pack directory. */
+    readonly moduleRoot: string;
+    /** The child's whole environment, read at every start. */
+    readonly env: () => Promise<Readonly<Record<string, string>>>;
+    /** Where the front listens. Default `127.0.0.1`. */
+    readonly host?: string;
+    /** The front's port. Default `0`: any free port, fixed while the front listens. */
+    readonly port?: number;
+    /**
+     * The token callers of the front send. Default: a new random one for
+     * each supervisor. Pass the previous supervisor's (with its `port`) so
+     * a caller started with both, such as a runtime running from source
+     * for `kindgi dev --runtime-url`, keeps reaching the front across
+     * restarts. At least 32 URL-safe base64 characters.
+     */
+    readonly token?: string;
+    /** Each line pack code writes; the service's own JSON log lines arrive as `onEvent`. */
+    readonly onLog?: (line: string, stream: 'stdout' | 'stderr') => void;
+    readonly onEvent?: (event: PackServiceSupervisorEvent) => void;
+    /** How long a child may take to listen. Default 60 000 ms. */
+    readonly bootTimeoutMs?: number;
+    /**
+     * How long a stopping child may drain before it is killed. Default: the
+     * child's own drain (`PACK_SERVICE_DRAIN_MS`) plus 2 s, so a call the
+     * child would still finish is never cut off by the kill.
+     */
+    readonly stopGraceMs?: number;
+    /** Restarts after a child exits on its own, before giving up. Default 3. */
+    readonly maxRestarts?: number;
+    /** Wait before such a restart. Default 500 ms. */
+    readonly restartDelayMs?: number;
+    /** Largest request body the front accepts. Default 10 MiB (the pack service's own limit). */
+    readonly maxBodyBytes?: number;
+}
+export type PackServiceSupervisorEvent = {
+    readonly kind: 'started';
+    readonly port: number;
+    readonly indexPath: string;
+} | {
+    readonly kind: 'boot-failed';
+    readonly problems: readonly string[];
+} | {
+    readonly kind: 'exited';
+    readonly code: number | null;
+    readonly signal: string | null;
+} | {
+    readonly kind: 'restarting';
+    readonly attempt: number;
+} | {
+    readonly kind: 'gave-up';
+    readonly attempts: number;
+}
+/** One of the service's own JSON log lines (a call, draining, …). */
+ | {
+    readonly kind: 'log';
+    readonly event: Readonly<Record<string, unknown>>;
+};
+export interface BootFailure {
+    readonly problems: readonly string[];
+}
+/** One call to forward: a request body and the call's options. */
+export interface PackRelayCall {
+    readonly route: 'invoke' | 'info';
+    /** The protocol v2 request (JSON text) for `invoke`; absent for `info`. */
+    readonly body?: string;
+    /** Cancels the call: the child sees its connection close. */
+    readonly signal?: AbortSignal;
+    /** The call's deadline, passed on to the child. */
+    readonly timeoutMs?: number;
+    readonly runId?: string;
+    readonly requestId?: string;
+    /** The caller's protocol version (`kindgi-protocol`), passed on as is. */
+    readonly protocol?: string;
+}
+/**
+ * What became of a forwarded call:
+ *   - `answer` — the child answered (any status, passed through as is);
+ *   - `unavailable` — not delivered (no child serving, or the connection
+ *     was refused), so it provably did not run and may be retried;
+ *   - `failed` — delivered, but no answer came back (the child died
+ *     mid-call); it may have run, so it must not be retried;
+ *   - `cancelled` — the caller cancelled it.
+ */
+export type PackRelayOutcome = {
+    readonly kind: 'answer';
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+} | {
+    readonly kind: 'cancelled';
+};
+/** Forwards calls to the serving child. */
+export interface PackRelay {
+    /** Whether a child is serving. */
+    readonly serving: () => boolean;
+    forward(call: PackRelayCall): Promise<PackRelayOutcome>;
+}
+export interface PackServiceSupervisor {
+    /** The token callers send (`kindgi-pack-token`); the children use it too. */
+    readonly token: string;
+    /** Forwards one call to the serving child; the front's HTTP listener uses it. */
+    readonly relay: PackRelay;
+    /** Open the front. Idempotent: later calls return the same address. */
+    listen(): Promise<{
+        readonly url: string;
+        readonly port: number;
+    }>;
+    /**
+     * Boot a child on `indexPath` and switch calls to it once it listens.
+     * On failure the previous child, if any, keeps serving.
+     */
+    start(indexPath: string): Promise<Result<{
+        readonly port: number;
+    }, BootFailure>>;
+    /** Stop the serving child; the front then answers 503. */
+    stop(): Promise<void>;
+    /** Stop the serving child and close the front. */
+    close(): Promise<void>;
+}
+export declare function createPackServiceSupervisor(options: PackServiceSupervisorOptions): PackServiceSupervisor;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/pack-service/supervisor.d.ts.map

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