mercury-composable 4.12.1

package/dist/src/envelope.js

@@ -0,0 +1,227 @@
+/**
+ * EventEnvelope and the standard wire format codec.
+ *
+ * Implements the language-neutral standard format from the Mercury Composable
+ * "Event Envelope Wire Format" reference: one MsgPack map with descriptive
+ * string keys, no MsgPack extension types. Optional fields are omitted when
+ * unset; absent and nil are equivalent; unknown keys are ignored; timestamps
+ * travel as ISO-8601 UTC strings with millisecond precision.
+ *
+ * Integer handling: 64-bit integers are decoded exactly — values beyond
+ * Number.MAX_SAFE_INTEGER surface as BigInt; smaller ones as number. BigInt
+ * values encode as int64.
+ *
+ * The classic compact format (single-character map keys) is detected from the
+ * first map key and rejected with CompactFormatError.
+ */
+import { Decoder, Encoder } from '@msgpack/msgpack';
+import { randomUUID } from 'node:crypto';
+import { CompactFormatError } from './exceptions.js';
+const encoder = new Encoder({ useBigInt64: true, ignoreUndefined: true });
+const decoder = new Decoder({ useBigInt64: true });
+/** ISO-8601 UTC with millisecond precision, e.g. 2026-07-21T12:00:00.000Z */
+export function isoUtc(date) {
+    return (date ?? new Date()).toISOString();
+}
+/** Normalize a payload for the wire: Date -> ISO string, safe BigInt -> number. */
+function sanitize(value) {
+    if (value instanceof Date)
+        return isoUtc(value);
+    if (typeof value === 'bigint')
+        return value; // encodes exactly as int64
+    if (Array.isArray(value))
+        return value.map(sanitize);
+    if (value instanceof Uint8Array)
+        return value;
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v !== undefined)
+                out[k] = sanitize(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** Decoded values: BigInt within the safe range becomes number. */
+function normalize(value) {
+    if (typeof value === 'bigint') {
+        return value <= BigInt(Number.MAX_SAFE_INTEGER) && value >= -BigInt(Number.MAX_SAFE_INTEGER)
+            ? Number(value) : value;
+    }
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value instanceof Uint8Array)
+        return value;
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = normalize(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** Render a scalar as text: primitives via String, structures via JSON. */
+export function asText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'bigint'
+        || typeof value === 'boolean' || typeof value === 'symbol') {
+        // positively narrowed to primitives - negating typeof on 'unknown' would
+        // widen to '{}' and re-admit objects (the S6551 trap)
+        return String(value);
+    }
+    if (typeof value === 'function')
+        return value.toString();
+    return value === undefined ? 'undefined' : JSON.stringify(value);
+}
+function asStringMap(value) {
+    const result = {};
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = asText(v);
+        }
+    }
+    return result;
+}
+export class EventEnvelope {
+    id = randomUUID().replaceAll('-', '');
+    to;
+    sender; // wire field "from"
+    replyTo;
+    cid;
+    traceId;
+    tracePath;
+    spanId;
+    status; // undefined encodes as absent (default 200)
+    headers = {};
+    body = undefined;
+    execTime;
+    roundTrip;
+    tags = {};
+    annotations = {};
+    stack;
+    objType;
+    exception; // language-native, opaque here
+    constructor(to, body, headers) {
+        this.to = to;
+        this.body = body;
+        if (headers)
+            this.headers = { ...headers };
+    }
+    // fluent helpers mirroring the engine API vocabulary
+    setTo(route) { this.to = route; return this; }
+    setFrom(route) { this.sender = route; return this; }
+    setHeader(key, value) { this.headers[key] = String(value); return this; }
+    setBody(body) { this.body = body; return this; }
+    setStatus(status) { this.status = Math.trunc(status); return this; }
+    setCorrelationId(cid) { this.cid = cid; return this; }
+    setTrace(traceId, tracePath) {
+        this.traceId = traceId;
+        this.tracePath = tracePath;
+        return this;
+    }
+    setSpanId(spanId) {
+        this.spanId = spanId;
+        return this;
+    }
+    setReplyTo(route) { this.replyTo = route; return this; }
+    getStatus() { return this.status ?? 200; }
+    hasError() { return this.getStatus() >= 400; }
+    toMap() {
+        const result = { id: this.id, headers: { ...this.headers } };
+        const optional = [
+            ['to', this.to], ['from', this.sender], ['reply_to', this.replyTo],
+            ['cid', this.cid], ['trace_id', this.traceId], ['trace_path', this.tracePath],
+            ['span_id', this.spanId], ['status', this.status], ['body', sanitize(this.body)],
+            ['exec_time', this.execTime], ['round_trip', this.roundTrip],
+            ['stack', this.stack], ['obj_type', this.objType], ['exception', this.exception]
+        ];
+        for (const [key, value] of optional) {
+            if (value !== undefined && value !== null)
+                result[key] = value;
+        }
+        if (Object.keys(this.tags).length)
+            result.tags = { ...this.tags };
+        if (Object.keys(this.annotations).length)
+            result.annotations = sanitize(this.annotations);
+        return result;
+    }
+    toBytes() {
+        // fresh copy: the encoder reuses an internal buffer, and a concrete
+        // ArrayBuffer-backed Uint8Array satisfies fetch's BodyInit typing
+        return new Uint8Array(encoder.encode(this.toMap()));
+    }
+    /** The optional wire fields that arrive as strings (wire key -> assignment). */
+    static copyStringFields(data, event) {
+        if (typeof data.to === 'string')
+            event.to = data.to;
+        if (typeof data.from === 'string')
+            event.sender = data.from;
+        if (typeof data.reply_to === 'string')
+            event.replyTo = data.reply_to;
+        if (typeof data.cid === 'string')
+            event.cid = data.cid;
+        if (typeof data.trace_id === 'string')
+            event.traceId = data.trace_id;
+        if (typeof data.trace_path === 'string')
+            event.tracePath = data.trace_path;
+        if (typeof data.span_id === 'string')
+            event.spanId = data.span_id;
+        if (typeof data.stack === 'string')
+            event.stack = data.stack;
+        if (typeof data.obj_type === 'string')
+            event.objType = data.obj_type;
+    }
+    /** The optional numeric fields (absent and nil are equivalent on the wire). */
+    static copyNumericFields(data, event) {
+        if (data.status !== undefined && data.status !== null)
+            event.status = Number(data.status);
+        if (data.exec_time !== undefined && data.exec_time !== null) {
+            event.execTime = Number(data.exec_time);
+        }
+        if (data.round_trip !== undefined && data.round_trip !== null) {
+            event.roundTrip = Number(data.round_trip);
+        }
+    }
+    static fromMap(data) {
+        const event = new EventEnvelope();
+        if (data.id !== undefined && data.id !== null)
+            event.id = asText(data.id);
+        EventEnvelope.copyStringFields(data, event);
+        EventEnvelope.copyNumericFields(data, event);
+        event.headers = asStringMap(data.headers);
+        if (data.body !== undefined)
+            event.body = normalize(data.body);
+        if (data.tags !== undefined && data.tags !== null)
+            event.tags = asStringMap(data.tags);
+        if (data.annotations !== undefined && data.annotations !== null) {
+            event.annotations = normalize(data.annotations);
+        }
+        if (data.exception instanceof Uint8Array)
+            event.exception = data.exception;
+        return event;
+    }
+    static fromBytes(data) {
+        let decoded;
+        try {
+            decoded = decoder.decode(data);
+        }
+        catch (e) {
+            throw new Error(`Unable to decode event envelope - ${e.message}`);
+        }
+        if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) {
+            throw new Error('Unable to decode event envelope - not a MsgPack map');
+        }
+        const keys = Object.keys(decoded);
+        if (keys.length === 0) {
+            throw new Error('Unable to decode event envelope - empty map');
+        }
+        if (keys[0].length === 1) {
+            throw new CompactFormatError('Compact event envelope format is not supported - ' +
+                'use the standard format (event.over.http.format=standard)');
+        }
+        return EventEnvelope.fromMap(decoded);
+    }
+}

package/dist/src/event-stream.d.ts

@@ -0,0 +1,120 @@
+import { EventEnvelope } from './envelope.js';
+import { FunctionRegistry } from './registry.js';
+/** reserved envelope header (internal protocol, never on the HTTP wire) */
+export declare const X_EVENT_STREAM = "x-event-stream";
+/** optional companion on a data event: maps to the SSE "event:" field */
+export declare const X_EVENT_NAME = "x-event-name";
+/** marker vocabulary - deliberately the engines' ObjectStream vocabulary */
+export declare const DATA = "data";
+export declare const EOF = "eof";
+export declare const EXCEPTION = "exception";
+/**
+ * reserved SSE event name of the envelope-mode wire dialect: a frame with
+ * this name carries one base64-encoded serialized EventEnvelope
+ */
+export declare const ENVELOPE = "envelope";
+export declare const X_TTL = "x-ttl";
+export declare const TEXT_EVENT_STREAM = "text/event-stream";
+export declare const STREAM_CALLER_REQUIRED = "Streaming function requires a caller that accepts text/event-stream";
+/** The x-event-stream marker (lowercased), or undefined for an unmarked envelope. */
+export declare function streamSignal(event: EventEnvelope): string | undefined;
+/** The x-event-name companion header (the SSE "event:" field), if any. */
+export declare function streamEventName(event: EventEnvelope): string | undefined;
+/** The message text of an unmarked error reply (objects render as JSON). */
+export declare function errorText(body: unknown): string;
+/** The standard error key-values: '{"type": "error", "status": n, "message": text}' */
+export declare function errorBody(status: number, message: string): Record<string, unknown>;
+/** An in-band exception envelope with the standard error body. */
+export declare function exceptionEnvelope(status: number, message: string): EventEnvelope;
+/** One SSE frame: optional "event:" line, one "data:" line per text line. */
+export declare function sseFrame(eventName: string | undefined, text: string): Buffer;
+/**
+ * One envelope-mode wire frame: the envelope serialized verbatim - with the
+ * host-internal addressing cleared, because the consuming relay rewrites
+ * addressing to the original caller - as base64 under the reserved name.
+ */
+export declare function envelopeFrame(event: EventEnvelope): Buffer;
+/**
+ * A data segment may ride a raw SSE frame only when the frame carries it
+ * losslessly: a 200 status, no custom envelope headers, a user event name
+ * clear of the reserved word, and a text (or empty) body without a carriage
+ * return - SSE normalizes line endings. Everything else takes the
+ * envelope-frame escape hatch.
+ */
+export declare function rawStreamable(event: EventEnvelope): boolean;
+/**
+ * One envelope-mode data frame: the first event always rides an envelope
+ * frame (it carries the head control); a losslessly raw-able text segment
+ * rides a raw frame; a bare no-op segment carries nothing.
+ */
+export declare function dataFrame(event: EventEnvelope, firstFrame: boolean): Buffer;
+/**
+ * SSE keep-alive comment interval in ms (`event.stream.keep.alive`,
+ * default 30s; 0 disables - the engines' config key).
+ */
+export declare function keepAliveMs(): number;
+/**
+ * Incremental SSE frame parser: byte-level line split (a newline is a single
+ * byte, so this is UTF-8 safe), one-leading-space value strip, comment/id/
+ * retry suppression, multi-line data joined per the SSE specification.
+ * Mirrors the engines' parsers.
+ */
+export declare class SseParser {
+    private pending;
+    private dataLines;
+    private eventName;
+    /** Feed one body chunk; return the completed [event_name, data] events. */
+    feed(chunk: Uint8Array): Array<[string | undefined, string]>;
+    /**
+     * One SSE line: a blank line dispatches the pending event; a comment line
+     * (leading colon) is consumed, never forwarded; id, retry and unknown
+     * fields are ignored (SSE specification).
+     */
+    private onLine;
+}
+/**
+ * Producer helper for a multi-shot reply - the engines' exact API.
+ *
+ * Only an interceptor function can stream: it receives the raw envelope, so
+ * the caller-provided reply address travels the engines' way
+ * (EventStreamWriter.fromRequest(event) reads reply_to and the correlation
+ * id). Segments route to the LOCAL reply address through the primitive event
+ * bus - simple routing to a local function or reply sink, never across the
+ * wire (cross-wire replies ride the Event-over-HTTP SSE response, exactly as
+ * on the engines).
+ */
+export declare class EventStreamWriter {
+    private readonly registry;
+    private readonly replyTo;
+    private readonly cid;
+    private firstStatus;
+    private firstContentType;
+    private firstTtlSeconds;
+    private headSent;
+    private isClosed;
+    constructor(replyTo: string | undefined, correlationId?: string, registry?: FunctionRegistry);
+    /**
+     * Create a writer from the incoming request envelope (the usual form for
+     * an interceptor function).
+     */
+    static fromRequest(event: EventEnvelope, registry?: FunctionRegistry): EventStreamWriter;
+    /**
+     * Optional head control carried by the first outgoing event: response
+     * status, content type, and an optional idle-allowance override in seconds
+     * between segments.
+     */
+    first(status: number, contentType: string, ttlSeconds?: number): this;
+    /** Send one `data` segment (text, bytes, object, array - any payload). */
+    write(segment: unknown): void;
+    /** Send one named segment - the name maps to the SSE "event:" field. */
+    writeNamed(eventName: string, segment: unknown): void;
+    /** Declare end of transmission, with optional trailing metadata. */
+    close(trailingMetadata?: unknown): void;
+    /** Declare an in-band failure and end the stream. */
+    fail(error: Error): void;
+    /** True when the stream has been closed or failed. */
+    get closed(): boolean;
+    private send;
+    private envelope;
+    private emit;
+}