@jini-ai/http-kit 0.3.1 → 0.3.3

package/dist/run-stream.d.ts

@@ -1,60 +0,0 @@
-/**
- * @module run-stream
- *
- * An encoder-driven SSE run-stream route: subscribes to a run via `@jini-ai/daemon`'s
- * `RunLifecycle.stream`, pipes every event through a composition-root-supplied protocol encoder,
- * and writes each non-null event to the SSE response opened by `createSseResponse`.
- * `handleRunStreamRequest` is the core
- * — it only ever touches `node:http`'s `IncomingMessage`/`ServerResponse` — and
- * `registerRunStreamRoute` below is Express's own thin mounting glue (Express's `Request`/
- * `Response` already *are* Node's raw `http.IncomingMessage`/`http.ServerResponse`, so resolving
- * `req.params.runId` and handing the request/response straight through is the whole job).
- */
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { RunLifecycle } from '@jini-ai/daemon';
-import type { RunProtocolEvent } from '@jini-ai/protocol';
-import type { Express } from 'express';
-/** Backward-compatible route path used by the AG-UI composition. The handler itself is encoder-agnostic. */
-export declare const RUN_STREAM_ROUTE_PATH = "/api/runs/:runId/agui-stream";
-export interface RunStreamEncoder {
-    encode(event: RunProtocolEvent, context: {
-        readonly runId: string;
-    }): unknown | null;
-}
-export interface RunStreamInternalErrorContext {
-    readonly source: 'encoder' | 'lifecycle' | 'route';
-    readonly runId: string;
-    readonly error: unknown;
-}
-export interface RunStreamDeps {
-    readonly lifecycle: RunLifecycle;
-    /** Protocol adapter supplied by the composition root (for example `createGenUiEncoder()`). */
-    readonly encoder: RunStreamEncoder;
-    /** Host-owned sink for failures that must not escape an async Express handler. Defaults to `console.error`. */
-    readonly onInternalError?: (context: RunStreamInternalErrorContext) => void;
-}
-/**
- * Handles one encoded SSE run-stream request end to end. Opens the SSE connection immediately (an
- * SSE endpoint commits to `text/event-stream` headers before it can know whether `runId` is
- * valid), then subscribes to the run: a replay-then-live-subscribe `unknown-run`/`replay-gap`/
- * `invalid-cursor` result is reported as one `{ error }` SSE data event before closing (there is
- * no JSON-status-code channel left once SSE headers are already committed). On the happy path,
- * every event `RunLifecycle` delivers is encoded and forwarded; the connection closes itself once
- * the run's own terminal `'end'` event has been forwarded (a driver's contract with
- * `RunLifecycle` guarantees no further events follow a run's `'end')`, so nothing is lost by
- * closing right after it). If the client disconnects first, `createSseResponse`'s own
- * `req.on('close', ...)` fires first, which (via `onClose` here) unsubscribes from the run so a
- * disconnected client never leaves a dangling `RunLifecycle` subscriber.
- *
- * @param req - The raw request `createSseResponse` opens the stream against.
- * @param res - The raw response `createSseResponse` opens the stream against.
- * @param runId - The run to stream, already resolved by the caller's transport-specific glue.
- * @param deps.lifecycle - The `RunLifecycle` to subscribe to.
- * @param deps.encoder - The protocol adapter chosen by the composition root.
- * @complexity O(1) plus the supplied encoder's per-event cost and `RunLifecycle.stream`'s replay cost.
- * @overallScore 100/100
- */
-export declare function handleRunStreamRequest(req: IncomingMessage, res: ServerResponse, runId: string, deps: RunStreamDeps): Promise<void>;
-/** Mounts the encoder-driven SSE run-stream route on `app`. */
-export declare function registerRunStreamRoute(app: Express, deps: RunStreamDeps): void;
-//# sourceMappingURL=run-stream.d.ts.map

package/dist/run-stream.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-stream.d.ts","sourceRoot":"","sources":["../src/run-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAyB,MAAM,iBAAiB,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAG1D,4GAA4G;AAC5G,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,+GAA+G;IAC/G,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,IAAI,CAAC;CAC7E;AAwBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAiB9E"}

package/dist/run-stream.js

@@ -1,108 +0,0 @@
-import { createSseResponse } from './raw-sse.js';
-/** Backward-compatible route path used by the AG-UI composition. The handler itself is encoder-agnostic. */
-export const RUN_STREAM_ROUTE_PATH = '/api/runs/:runId/agui-stream';
-function reportRunStreamInternalError(deps, source, runId, error) {
-    const context = { source, runId, error };
-    try {
-        if (deps.onInternalError) {
-            deps.onInternalError(context);
-        }
-        else {
-            // eslint-disable-next-line no-console
-            console.error(`[@jini-ai/http-kit] internal error (run-stream:${source}, runId=${runId})`, error);
-        }
-    }
-    catch (sinkError) {
-        // A diagnostic sink must never turn an already-contained stream failure into an unhandled
-        // rejection of its own.
-        // eslint-disable-next-line no-console
-        console.error(`[@jini-ai/http-kit] internal error sink failed (run-stream:${source}, runId=${runId})`, sinkError);
-    }
-}
-/**
- * Handles one encoded SSE run-stream request end to end. Opens the SSE connection immediately (an
- * SSE endpoint commits to `text/event-stream` headers before it can know whether `runId` is
- * valid), then subscribes to the run: a replay-then-live-subscribe `unknown-run`/`replay-gap`/
- * `invalid-cursor` result is reported as one `{ error }` SSE data event before closing (there is
- * no JSON-status-code channel left once SSE headers are already committed). On the happy path,
- * every event `RunLifecycle` delivers is encoded and forwarded; the connection closes itself once
- * the run's own terminal `'end'` event has been forwarded (a driver's contract with
- * `RunLifecycle` guarantees no further events follow a run's `'end')`, so nothing is lost by
- * closing right after it). If the client disconnects first, `createSseResponse`'s own
- * `req.on('close', ...)` fires first, which (via `onClose` here) unsubscribes from the run so a
- * disconnected client never leaves a dangling `RunLifecycle` subscriber.
- *
- * @param req - The raw request `createSseResponse` opens the stream against.
- * @param res - The raw response `createSseResponse` opens the stream against.
- * @param runId - The run to stream, already resolved by the caller's transport-specific glue.
- * @param deps.lifecycle - The `RunLifecycle` to subscribe to.
- * @param deps.encoder - The protocol adapter chosen by the composition root.
- * @complexity O(1) plus the supplied encoder's per-event cost and `RunLifecycle.stream`'s replay cost.
- * @overallScore 100/100
- */
-export async function handleRunStreamRequest(req, res, runId, deps) {
-    let unsubscribe;
-    const connection = createSseResponse(req, res, {
-        onClose: () => unsubscribe?.(),
-    });
-    const encoder = deps.encoder;
-    let result;
-    try {
-        result = await deps.lifecycle.stream(runId, (event) => {
-            if (connection.closed)
-                return;
-            try {
-                const encoded = encoder.encode(event, { runId });
-                if (encoded != null)
-                    connection.send(encoded);
-                if (event.kind === 'end')
-                    connection.close();
-            }
-            catch (error) {
-                reportRunStreamInternalError(deps, 'encoder', runId, error);
-                connection.close();
-            }
-        });
-    }
-    catch (error) {
-        reportRunStreamInternalError(deps, 'lifecycle', runId, error);
-        connection.close();
-        return;
-    }
-    if (result.kind !== 'ok') {
-        connection.send({ error: result.kind });
-        connection.close();
-        return;
-    }
-    // Assigned even when the run was already terminal (in which case the driver-facing 'end' event
-    // was already replayed synchronously above, already closing the connection, and `unsubscribe`
-    // here is `RunLifecycle`'s own no-op stub for that case) — keeping this assignment unconditional
-    // avoids a branch whose two arms would otherwise do the same thing.
-    unsubscribe = result.unsubscribe;
-    // The raw request can close while RunLifecycle is still awaiting durable replay. In that
-    // window `onClose` runs before `unsubscribe` exists, so clean up immediately once it arrives.
-    if (connection.closed)
-        unsubscribe();
-}
-/** Mounts the encoder-driven SSE run-stream route on `app`. */
-export function registerRunStreamRoute(app, deps) {
-    app.get(RUN_STREAM_ROUTE_PATH, async (req, res) => {
-        // `:runId` is a required path segment of RUN_STREAM_ROUTE_PATH — this handler is only ever
-        // reached via a URL that already matched it, so the param is always present at runtime even
-        // though @types/express types every param as possibly `undefined` in general.
-        const runId = req.params.runId;
-        try {
-            await handleRunStreamRequest(req, res, runId, deps);
-        }
-        catch (error) {
-            reportRunStreamInternalError(deps, 'route', runId, error);
-            if (!res.headersSent) {
-                res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: 'an internal error occurred' } });
-            }
-            else if (!res.writableEnded) {
-                res.end();
-            }
-        }
-    });
-}
-//# sourceMappingURL=run-stream.js.map

package/dist/run-stream.js.map

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