@elysra/tungsten-runtime 0.0.0-stage → 0.1.1

package/dist/streams.js

@@ -0,0 +1,96 @@
+import { hasOwn } from "./util.js";
+/** The key of {@link EventStream.on} handlers that receives every event no
+ * other handler took. */
+export const ANY_EVENT = "*";
+export class EventStream {
+    #source;
+    #abort;
+    #cancelled = false;
+    /** @param source the items of the stream
+     * @param abort aborts the request the source reads (closes the connection) */
+    constructor(source, abort) {
+        this.#source = source;
+        this.#abort = abort;
+    }
+    /** Whether {@link cancel} was called. */
+    get cancelled() {
+        return this.#cancelled;
+    }
+    /** Close the connection and end the stream: a pending or later read ends
+     * without a failure item. Safe to call more than once. */
+    cancel() {
+        if (this.#cancelled)
+            return;
+        this.#cancelled = true;
+        this.#abort();
+        this.#source.return(undefined).catch(() => undefined);
+    }
+    async *[Symbol.asyncIterator]() {
+        try {
+            for (;;) {
+                const next = await this.#source.next();
+                if (next.done === true || this.#cancelled)
+                    return;
+                yield next.value;
+            }
+        }
+        finally {
+            this.#abort();
+            await this.#source.return(undefined).catch(() => undefined);
+        }
+    }
+    /** Read the stream to its end and call the handler named like each event
+     * (`handlers.message_delta` for `event: message_delta`; events without a
+     * name are `message`), else `handlers["*"]`. A handler that throws or
+     * rejects ends the stream (the connection is closed) and the error
+     * propagates. Resolves to the number of events delivered. */
+    async on(handlers) {
+        let count = 0;
+        let reconnects = 0;
+        for await (const item of this) {
+            if (!item.ok)
+                return { ok: false, error: item.error, partial: count, reconnects };
+            reconnects = item.meta.reconnects;
+            const handler = hasOwn(handlers, item.event) ? handlers[item.event] : handlers[ANY_EVENT];
+            count += 1;
+            await handler?.(item.value, { value: item.value, event: item.event, id: item.id, retry: item.retry });
+        }
+        return { ok: true, value: count, reconnects };
+    }
+    /** Read the stream to its end and fold the events into one value
+     * (concatenating text deltas, say). `partial` of a failure is the value
+     * folded so far. */
+    async reduce(fold, initial) {
+        let accumulator = initial;
+        let reconnects = 0;
+        for await (const item of this) {
+            if (!item.ok)
+                return { ok: false, error: item.error, partial: accumulator, reconnects };
+            reconnects = item.meta.reconnects;
+            accumulator = fold(accumulator, item.value, { value: item.value, event: item.event, id: item.id, retry: item.retry });
+        }
+        return { ok: true, value: accumulator, reconnects };
+    }
+    /** Read the stream to its end into a list of the events' `data`. */
+    collect() {
+        return this.reduce((all, value) => {
+            all.push(value);
+            return all;
+        }, []);
+    }
+    /** The first event for which `predicate` holds (any event without one),
+     * then close the stream; `value` is null when the stream ends without
+     * one. */
+    async first(predicate) {
+        let reconnects = 0;
+        for await (const item of this) {
+            if (!item.ok)
+                return { ok: false, error: item.error, partial: null, reconnects };
+            reconnects = item.meta.reconnects;
+            const event = { value: item.value, event: item.event, id: item.id, retry: item.retry };
+            if (predicate === undefined || predicate(item.value, event))
+                return { ok: true, value: event, reconnects };
+        }
+        return { ok: true, value: null, reconnects };
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,88 @@
+/**
+ * One HTTP attempt: per-attempt timeout combined with the caller's signal,
+ * the body read inside the same deadline, and network failures classified
+ * by whether the request can have reached the server.
+ */
+import type { HttpMethod } from "./types.js";
+export interface AttemptRequest {
+    url: string;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    body: BodyInit | null;
+    redirect: RequestRedirect;
+    timeoutMs: number;
+    signal: AbortSignal | undefined;
+    /** Hand a `text/event-stream` answer with a 2xx status back unread, as a
+     * {@link StreamBody}; any other answer is read as usual. */
+    stream?: boolean;
+    /** With `stream`: the silence, in milliseconds, after which a read of the
+     * body reports a timeout. Default `timeoutMs`. */
+    idleMs?: number | undefined;
+    maxResponseBytes?: number | undefined;
+}
+/** What one read of an event stream gives. */
+export type StreamRead = {
+    kind: "chunk";
+    bytes: Uint8Array;
+} | {
+    kind: "end";
+}
+/** No bytes arrived within the attempt timeout. */
+ | {
+    kind: "timeout";
+}
+/** The caller's signal aborted. */
+ | {
+    kind: "aborted";
+}
+/** The connection failed or was closed before the stream ended. */
+ | {
+    kind: "lost";
+};
+/** The unread body of an event stream: chunks of bytes with an idle
+ * timeout (the attempt timeout, restarted by every read) and the caller's
+ * signal. */
+export declare class StreamBody {
+    #private;
+    constructor(reader: ReadableStreamDefaultReader<Uint8Array>, controller: AbortController, signal: AbortSignal | undefined, onAbort: () => void, idleMs: number);
+    read(): Promise<StreamRead>;
+    /** Release the connection. Safe to call more than once. */
+    close(): void;
+}
+export type AttemptOutcome = {
+    kind: "response";
+    response: Response;
+    status: number;
+    headers: Record<string, string>;
+    /** The body, or null when reading it failed. */
+    body: Uint8Array | null;
+    /** Why the body could not be read: deadline, caller abort or a broken connection. */
+    bodyFailure: "timeout" | "aborted" | "broken" | "oversized" | null;
+    /** The unread body of an event stream (`AttemptRequest.stream`); `body` is then null. */
+    stream?: StreamBody;
+}
+/** The request cannot have reached the server (DNS, refused, TLS). */
+ | {
+    kind: "not_sent";
+    detail: string;
+}
+/** Sent or possibly sent, then the connection failed without a response. */
+ | {
+    kind: "lost";
+    detail: string;
+} | {
+    kind: "timeout";
+}
+/** The caller's signal aborted; `sent` is false only when it was already aborted. */
+ | {
+    kind: "aborted";
+    sent: boolean;
+};
+/** Send once. Never throws. */
+export declare function attempt(fetchImpl: typeof fetch, req: AttemptRequest): Promise<AttemptOutcome>;
+/** Whether a `Content-Type` value is `text/event-stream` (parameters and case ignored). */
+export declare function isEventStream(contentType: string | undefined): boolean;
+/** Retry-After in milliseconds (delta seconds or HTTP date), or null. */
+export declare function parseRetryAfter(value: string | undefined, now: number): number | null;
+/** Next page URL from a `Link` header (`rel="next"`), or null. */
+export declare function nextLink(header: string | undefined): string | null;

package/dist/transport.js

@@ -0,0 +1,245 @@
+import { isRecord } from "./util.js";
+/** The unread body of an event stream: chunks of bytes with an idle
+ * timeout (the attempt timeout, restarted by every read) and the caller's
+ * signal. */
+export class StreamBody {
+    #reader;
+    #controller;
+    #signal;
+    #onAbort;
+    #idleMs;
+    #cancelRead = () => { void this.#reader.cancel().catch(() => undefined); };
+    #timedOut = false;
+    #closed = false;
+    constructor(reader, controller, signal, onAbort, idleMs) {
+        this.#reader = reader;
+        this.#controller = controller;
+        this.#signal = signal;
+        this.#onAbort = onAbort;
+        this.#idleMs = Math.max(1, idleMs);
+        signal?.addEventListener("abort", this.#cancelRead, { once: true });
+        if (signal?.aborted)
+            this.#cancelRead();
+    }
+    async read() {
+        if (this.#closed)
+            return { kind: "end" };
+        const timer = setTimeout(() => {
+            this.#timedOut = true;
+            this.#controller.abort();
+            this.#cancelRead();
+        }, this.#idleMs);
+        try {
+            const chunk = await this.#reader.read();
+            if (this.#timedOut)
+                return { kind: "timeout" };
+            if (this.#signal?.aborted)
+                return { kind: "aborted" };
+            if (chunk.done)
+                return { kind: "end" };
+            return { kind: "chunk", bytes: chunk.value };
+        }
+        catch {
+            if (this.#timedOut)
+                return { kind: "timeout" };
+            return this.#signal?.aborted === true ? { kind: "aborted" } : { kind: "lost" };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Release the connection. Safe to call more than once. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#signal?.removeEventListener("abort", this.#onAbort);
+        this.#signal?.removeEventListener("abort", this.#cancelRead);
+        this.#reader.cancel().catch(() => undefined);
+        this.#controller.abort();
+    }
+}
+/** Error codes (Node, undici, Bun, Deno) that mean nothing was sent. */
+const NOT_SENT_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EAI_FAIL",
+    "EAI_NONAME",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EHOSTDOWN",
+    "EADDRNOTAVAIL",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_INVALID_ARG",
+    "ERR_INVALID_URL",
+    "ConnectionRefused",
+    "FailedToOpenSocket",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "CERT_HAS_EXPIRED",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+function errorCodes(error) {
+    const codes = [];
+    const seen = new Set();
+    const visit = (e, depth) => {
+        if (depth > 8 || !isRecord(e) || seen.has(e))
+            return;
+        seen.add(e);
+        const record = e;
+        if (typeof record.code === "string")
+            codes.push(record.code);
+        if (typeof record.name === "string" && record.name === "NotFound")
+            codes.push("ENOTFOUND");
+        visit(record.cause, depth + 1);
+        if (Array.isArray(record.errors))
+            for (const inner of record.errors)
+                visit(inner, depth + 1);
+    };
+    visit(error, 0);
+    return codes;
+}
+function detail(error) {
+    const codes = errorCodes(error);
+    if (codes.length > 0)
+        return codes.join(", ");
+    return error instanceof Error ? error.name : "network error";
+}
+function isNotSent(error) {
+    return errorCodes(error).some((code) => NOT_SENT_CODES.has(code) || code.startsWith("ERR_TLS_") || code.startsWith("CERT_"));
+}
+/** Send once. Never throws. */
+export async function attempt(fetchImpl, req) {
+    if (req.signal?.aborted)
+        return { kind: "aborted", sent: false };
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, Math.max(1, req.timeoutMs));
+    const onAbort = () => controller.abort();
+    req.signal?.addEventListener("abort", onAbort, { once: true });
+    let handedOver = false;
+    try {
+        let response;
+        try {
+            response = await fetchImpl(req.url, {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+                redirect: req.redirect,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (timedOut)
+                return { kind: "timeout" };
+            if (req.signal?.aborted)
+                return { kind: "aborted", sent: true };
+            return isNotSent(error) ? { kind: "not_sent", detail: detail(error) } : { kind: "lost", detail: detail(error) };
+        }
+        const headers = {};
+        response.headers.forEach((value, name) => {
+            headers[name.toLowerCase()] = value;
+        });
+        if (req.stream === true && response.status >= 200 && response.status <= 299 && response.body !== null && isEventStream(headers["content-type"])) {
+            handedOver = true;
+            clearTimeout(timer);
+            const stream = new StreamBody(response.body.getReader(), controller, req.signal, onAbort, req.idleMs ?? req.timeoutMs);
+            return { kind: "response", response, status: response.status, headers, body: null, bodyFailure: null, stream };
+        }
+        let body = null;
+        let bodyFailure = null;
+        try {
+            if (req.maxResponseBytes === undefined || response.body === null) {
+                body = new Uint8Array(await response.arrayBuffer());
+            }
+            else {
+                const reader = response.body.getReader();
+                const cancel = () => { void reader.cancel().catch(() => undefined); };
+                controller.signal.addEventListener("abort", cancel, { once: true });
+                const chunks = [];
+                let size = 0;
+                try {
+                    const length = headers["content-length"];
+                    if (length !== undefined && /^\d+$/.test(length) && Number(length) > req.maxResponseBytes)
+                        bodyFailure = "oversized";
+                    while (bodyFailure === null) {
+                        const chunk = await reader.read();
+                        if (controller.signal.aborted) {
+                            bodyFailure = timedOut ? "timeout" : "aborted";
+                            break;
+                        }
+                        if (chunk.done)
+                            break;
+                        size += chunk.value.byteLength;
+                        if (size > req.maxResponseBytes) {
+                            bodyFailure = "oversized";
+                            break;
+                        }
+                        chunks.push(chunk.value);
+                    }
+                    if (bodyFailure === null) {
+                        body = new Uint8Array(size);
+                        let offset = 0;
+                        for (const chunk of chunks) {
+                            body.set(chunk, offset);
+                            offset += chunk.byteLength;
+                        }
+                    }
+                }
+                finally {
+                    controller.signal.removeEventListener("abort", cancel);
+                    if (bodyFailure !== null)
+                        await reader.cancel().catch(() => undefined);
+                    reader.releaseLock();
+                }
+            }
+        }
+        catch {
+            bodyFailure = timedOut ? "timeout" : req.signal?.aborted ? "aborted" : "broken";
+        }
+        return { kind: "response", response, status: response.status, headers, body, bodyFailure };
+    }
+    finally {
+        if (!handedOver) {
+            clearTimeout(timer);
+            req.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+/** Whether a `Content-Type` value is `text/event-stream` (parameters and case ignored). */
+export function isEventStream(contentType) {
+    return (contentType ?? "").split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+}
+/** Retry-After in milliseconds (delta seconds or HTTP date), or null. */
+export function parseRetryAfter(value, now) {
+    if (value === undefined)
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const date = Date.parse(trimmed);
+    if (Number.isNaN(date))
+        return null;
+    return Math.max(0, Math.round(date - now));
+}
+/** Next page URL from a `Link` header (`rel="next"`), or null. */
+export function nextLink(header) {
+    if (!header)
+        return null;
+    for (const part of header.split(/,(?=\s*<)/)) {
+        const match = /^\s*<([^>]*)>(.*)$/.exec(part);
+        if (!match)
+            continue;
+        const params = match[2] ?? "";
+        if (/;\s*rel\s*=\s*"?([^";]*\s)?next(\s[^";]*)?"?\s*(;|$)/i.test(params))
+            return match[1] ?? null;
+    }
+    return null;
+}