limen-ai 1.0.0

package/dist/substrate/transport/stream_parser.js

@@ -0,0 +1,280 @@
+/**
+ * Stream parsers for SSE and NDJSON protocols.
+ * S ref: §27 (Streaming Protocol), §25.4 (LLM Gateway)
+ *
+ * Phase: 5A (Sprint 5A — Shared Transport Infrastructure)
+ * Implements:
+ *   parseSSEStream() — Server-Sent Events parser
+ *   parseNDJSONStream() — Newline-Delimited JSON parser
+ *
+ * Security constraints enforced:
+ *   C-SEC-P5-10: 1MB max line length
+ *   C-SEC-P5-11: 100K max events
+ *   C-SEC-P5-12: 30s stall detection
+ *   C-SEC-P5-13: Resource cleanup on abort
+ *
+ * I-01: No external dependencies. Uses Web Streams API (Node.js >= 22).
+ */
+// ─── Constants ───
+/** C-SEC-P5-10: Maximum line length (1MB) */
+const MAX_LINE_BYTES = 1_048_576;
+/** C-SEC-P5-11: Maximum number of events */
+const MAX_EVENT_COUNT = 100_000;
+/** C-SEC-P5-12: Stall detection timeout (30 seconds) */
+const STALL_TIMEOUT_MS = 30_000;
+// ─── Error Helper ───
+class TransportStreamError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TransportStreamError';
+        this.code = code;
+    }
+}
+// ─── Text Decoder for Streaming ───
+const decoder = new TextDecoder();
+// ─── SSE Parser ───
+/**
+ * Parse a Server-Sent Events stream.
+ * S ref: §27 (streaming protocol)
+ *
+ * Follows the SSE specification:
+ * - Lines starting with ':' are comments (ignored)
+ * - Empty lines dispatch the current event
+ * - 'data:' field accumulates (multi-line data joined with \n)
+ * - 'event:', 'id:', 'retry:' fields parsed
+ * - [DONE] sentinel in data terminates the stream
+ *
+ * Security:
+ * - C-SEC-P5-10: Lines > 1MB throw TRANSPORT_SSE_LINE_TOO_LONG
+ * - C-SEC-P5-11: > 100K events throw TRANSPORT_SSE_MAX_EVENTS
+ * - C-SEC-P5-12: 30s with no data throws TRANSPORT_STALL_DETECTED
+ * - C-SEC-P5-13: Abort signal cancels cleanly with reader release
+ *
+ * @param body - ReadableStream from fetch response
+ * @param signal - Optional AbortSignal for cancellation
+ * @param time - Optional TimeProvider for clock injection (Hard Stop #7)
+ */
+export async function* parseSSEStream(body, signal, time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    const reader = body.getReader();
+    let eventCount = 0;
+    let lastDataTime = clock.nowMs();
+    // Current event being accumulated
+    let currentEvent = '';
+    let currentData = [];
+    let currentId;
+    let currentRetry;
+    // Line buffer for partial reads
+    let buffer = '';
+    try {
+        while (true) {
+            // C-SEC-P5-13: Check abort signal
+            if (signal?.aborted) {
+                return;
+            }
+            // C-SEC-P5-12: Stall detection
+            const elapsed = clock.nowMs() - lastDataTime;
+            if (elapsed > STALL_TIMEOUT_MS) {
+                throw new TransportStreamError('TRANSPORT_STALL_DETECTED', `SSE stream stalled: no data for ${elapsed}ms (limit: ${STALL_TIMEOUT_MS}ms)`);
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            lastDataTime = clock.nowMs();
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete lines
+            let newlineIdx;
+            while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIdx).replace(/\r$/, '');
+                buffer = buffer.slice(newlineIdx + 1);
+                // C-SEC-P5-10: Max line length
+                if (line.length > MAX_LINE_BYTES) {
+                    throw new TransportStreamError('TRANSPORT_SSE_LINE_TOO_LONG', `SSE line exceeds maximum length: ${line.length} bytes (limit: ${MAX_LINE_BYTES})`);
+                }
+                // Empty line dispatches the current event
+                if (line === '') {
+                    if (currentData.length > 0) {
+                        // C-SEC-P5-11: Max event count
+                        eventCount++;
+                        if (eventCount > MAX_EVENT_COUNT) {
+                            throw new TransportStreamError('TRANSPORT_SSE_MAX_EVENTS', `SSE event count exceeds maximum: ${eventCount} (limit: ${MAX_EVENT_COUNT})`);
+                        }
+                        const data = currentData.join('\n');
+                        // [DONE] sentinel terminates stream
+                        if (data === '[DONE]') {
+                            return;
+                        }
+                        yield {
+                            event: currentEvent,
+                            data,
+                            ...(currentId !== undefined ? { id: currentId } : {}),
+                            ...(currentRetry !== undefined ? { retry: currentRetry } : {}),
+                        };
+                    }
+                    // Reset for next event
+                    currentEvent = '';
+                    currentData = [];
+                    currentId = undefined;
+                    currentRetry = undefined;
+                    continue;
+                }
+                // Comment lines (start with ':')
+                if (line.startsWith(':')) {
+                    continue;
+                }
+                // Parse field:value
+                const colonIdx = line.indexOf(':');
+                let field;
+                let value_str;
+                if (colonIdx === -1) {
+                    field = line;
+                    value_str = '';
+                }
+                else {
+                    field = line.slice(0, colonIdx);
+                    // Skip leading space after colon per SSE spec
+                    value_str = line.slice(colonIdx + 1);
+                    if (value_str.startsWith(' ')) {
+                        value_str = value_str.slice(1);
+                    }
+                }
+                switch (field) {
+                    case 'data':
+                        currentData.push(value_str);
+                        break;
+                    case 'event':
+                        currentEvent = value_str;
+                        break;
+                    case 'id':
+                        currentId = value_str;
+                        break;
+                    case 'retry': {
+                        const parsed = parseInt(value_str, 10);
+                        if (!isNaN(parsed) && parsed >= 0) {
+                            currentRetry = parsed;
+                        }
+                        break;
+                    }
+                    // Unknown fields are ignored per SSE spec
+                }
+            }
+            // C-SEC-P5-10: Check buffer length for incomplete lines
+            if (buffer.length > MAX_LINE_BYTES) {
+                throw new TransportStreamError('TRANSPORT_SSE_LINE_TOO_LONG', `SSE line buffer exceeds maximum length: ${buffer.length} bytes (limit: ${MAX_LINE_BYTES})`);
+            }
+        }
+        // Process any remaining data in buffer (final event without trailing newline)
+        if (currentData.length > 0) {
+            eventCount++;
+            if (eventCount > MAX_EVENT_COUNT) {
+                throw new TransportStreamError('TRANSPORT_SSE_MAX_EVENTS', `SSE event count exceeds maximum: ${eventCount} (limit: ${MAX_EVENT_COUNT})`);
+            }
+            const data = currentData.join('\n');
+            if (data !== '[DONE]') {
+                yield {
+                    event: currentEvent,
+                    data,
+                    ...(currentId !== undefined ? { id: currentId } : {}),
+                    ...(currentRetry !== undefined ? { retry: currentRetry } : {}),
+                };
+            }
+        }
+    }
+    finally {
+        // C-SEC-P5-13: Always release the reader
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Reader may already be released if stream was cancelled
+        }
+    }
+}
+// ─── NDJSON Parser ───
+/**
+ * Parse a Newline-Delimited JSON stream.
+ * S ref: §27 (streaming protocol)
+ *
+ * Each line is a complete JSON object. Empty lines are skipped.
+ *
+ * Security:
+ * - C-SEC-P5-10: Lines > 1MB throw TRANSPORT_NDJSON_LINE_TOO_LONG
+ * - C-SEC-P5-12: 30s with no data throws TRANSPORT_STALL_DETECTED
+ * - C-SEC-P5-13: Abort signal cancels cleanly with reader release
+ *
+ * @param body - ReadableStream from fetch response
+ * @param signal - Optional AbortSignal for cancellation
+ * @param time - Optional TimeProvider for clock injection (Hard Stop #7)
+ */
+export async function* parseNDJSONStream(body, signal, time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    const reader = body.getReader();
+    let lastDataTime = clock.nowMs();
+    let buffer = '';
+    try {
+        while (true) {
+            // C-SEC-P5-13: Check abort signal
+            if (signal?.aborted) {
+                return;
+            }
+            // C-SEC-P5-12: Stall detection
+            const elapsed = clock.nowMs() - lastDataTime;
+            if (elapsed > STALL_TIMEOUT_MS) {
+                throw new TransportStreamError('TRANSPORT_STALL_DETECTED', `NDJSON stream stalled: no data for ${elapsed}ms (limit: ${STALL_TIMEOUT_MS}ms)`);
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            lastDataTime = clock.nowMs();
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete lines
+            let newlineIdx;
+            while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIdx).replace(/\r$/, '');
+                buffer = buffer.slice(newlineIdx + 1);
+                // C-SEC-P5-10: Max line length
+                if (line.length > MAX_LINE_BYTES) {
+                    throw new TransportStreamError('TRANSPORT_NDJSON_LINE_TOO_LONG', `NDJSON line exceeds maximum length: ${line.length} bytes (limit: ${MAX_LINE_BYTES})`);
+                }
+                // Skip empty lines
+                if (line.trim() === '')
+                    continue;
+                try {
+                    yield JSON.parse(line);
+                }
+                catch (parseErr) {
+                    throw new TransportStreamError('TRANSPORT_JSON_PARSE_ERROR', `NDJSON parse error: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+                }
+            }
+            // C-SEC-P5-10: Check buffer length for incomplete lines
+            if (buffer.length > MAX_LINE_BYTES) {
+                throw new TransportStreamError('TRANSPORT_NDJSON_LINE_TOO_LONG', `NDJSON line buffer exceeds maximum length: ${buffer.length} bytes (limit: ${MAX_LINE_BYTES})`);
+            }
+        }
+        // Process remaining data (final line without trailing newline)
+        if (buffer.trim() !== '') {
+            if (buffer.length > MAX_LINE_BYTES) {
+                throw new TransportStreamError('TRANSPORT_NDJSON_LINE_TOO_LONG', `NDJSON line exceeds maximum length: ${buffer.length} bytes (limit: ${MAX_LINE_BYTES})`);
+            }
+            try {
+                yield JSON.parse(buffer);
+            }
+            catch (parseErr) {
+                throw new TransportStreamError('TRANSPORT_JSON_PARSE_ERROR', `NDJSON parse error: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+            }
+        }
+    }
+    finally {
+        // C-SEC-P5-13: Always release the reader
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Reader may already be released if stream was cancelled
+        }
+    }
+}
+// ─── Exported for testing ───
+export { TransportStreamError, MAX_LINE_BYTES, MAX_EVENT_COUNT, STALL_TIMEOUT_MS };
+//# sourceMappingURL=stream_parser.js.map

package/dist/substrate/transport/stream_parser.js.map

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

package/dist/substrate/transport/transport_engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Core transport engine for LLM HTTP communication.
+ * S ref: §25.4 (LLM Gateway), I-01 (no SDK deps), I-04 (provider independence)
+ *
+ * Phase: 5A (Sprint 5A — Shared Transport Infrastructure)
+ * Implements: createTransportEngine() factory
+ *
+ * Behaviors:
+ *   execute() — non-streaming: fetch + retry (2 retries / 3 total, 120s cap, 60s Retry-After cap)
+ *   executeStream() — streaming: fetch + NO retry after first byte, tiered timeouts
+ *   shutdown() — abort all in-flight requests, reject new requests
+ *
+ * Security constraints enforced:
+ *   C-SEC-P5-06: Response size limit 10MB
+ *   C-SEC-P5-07: JSON parse safety
+ *   C-SEC-P5-15: Circuit breaker checked BEFORE each retry
+ *   C-SEC-P5-19: TLS enforcement for non-local URLs
+ *   C-SEC-P5-20: Shutdown support (GATEWAY_SHUTTING_DOWN)
+ *   CR-1 / C-SEC-P5-04: API key resolved ONCE at adapter creation
+ *   CR-2: Retry-After > 60s → hard error
+ *   CR-3: Streaming timeouts (30s first-byte, 30s stall, 10min total)
+ *
+ * Hard Stop #7: All temporal logic uses TimeProvider.
+ */
+import type { TransportEngine, TransportEngineOptions, TransportErrorCode } from './transport_types.js';
+/** Maximum number of retries for non-streaming requests (2 retries = 3 total attempts) */
+declare const MAX_RETRIES = 2;
+/** Total duration cap for non-streaming requests: 120 seconds */
+declare const DURATION_CAP_MS = 120000;
+/** Maximum Retry-After value: 60 seconds (CR-2) */
+declare const MAX_RETRY_AFTER_MS = 60000;
+/** Response size limit: 10MB (C-SEC-P5-06) */
+declare const MAX_RESPONSE_BYTES = 10485760;
+/** Streaming: first-byte timeout 30s (CR-3) */
+declare const STREAM_FIRST_BYTE_TIMEOUT_MS = 30000;
+/** Streaming: stall detection timeout 30s (CR-3) */
+declare const STREAM_STALL_TIMEOUT_MS = 30000;
+/** Streaming: total duration cap 10 minutes (CR-3) */
+declare const STREAM_TOTAL_TIMEOUT_MS = 600000;
+declare class TransportError extends Error {
+    readonly code: TransportErrorCode;
+    constructor(code: TransportErrorCode, message: string);
+}
+/**
+ * Create a transport engine instance.
+ * S ref: §25.4, C-07 (Object.freeze)
+ *
+ * @param options - Configuration options including time provider, health updater, circuit breaker
+ */
+export declare function createTransportEngine(options?: TransportEngineOptions): TransportEngine;
+export { TransportError, MAX_RETRIES, DURATION_CAP_MS, MAX_RETRY_AFTER_MS, MAX_RESPONSE_BYTES };
+export { STREAM_FIRST_BYTE_TIMEOUT_MS, STREAM_STALL_TIMEOUT_MS, STREAM_TOTAL_TIMEOUT_MS };
+//# sourceMappingURL=transport_engine.d.ts.map

package/dist/substrate/transport/transport_engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport_engine.d.ts","sourceRoot":"","sources":["../../../src/substrate/transport/transport_engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAKV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAEnB,MAAM,sBAAsB,CAAC;AAI9B,0FAA0F;AAC1F,QAAA,MAAM,WAAW,IAAI,CAAC;AAEtB,iEAAiE;AACjE,QAAA,MAAM,eAAe,SAAU,CAAC;AAEhC,mDAAmD;AACnD,QAAA,MAAM,kBAAkB,QAAS,CAAC;AAElC,8CAA8C;AAC9C,QAAA,MAAM,kBAAkB,WAAa,CAAC;AAEtC,+CAA+C;AAC/C,QAAA,MAAM,4BAA4B,QAAS,CAAC;AAE5C,oDAAoD;AACpD,QAAA,MAAM,uBAAuB,QAAS,CAAC;AAEvC,sDAAsD;AACtD,QAAA,MAAM,uBAAuB,SAAU,CAAC;AAIxC,cAAM,cAAe,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;gBACtB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAKtD;AA8FD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAiavF;AAGD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;AAChG,OAAO,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,CAAC"}