keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/transport/http-client.js

@@ -0,0 +1,172 @@
+/** Native HTTP request construction, byte I/O and joined attempt cleanup. */
+import { call, resource, scoped } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { abortable } from "../runtime/abortable.js";
+import { collectBytes } from "./byte-source.js";
+import { TransportError } from "./transport-error.js";
+/**
+ * Own the native Request, fetch and response reader for one attempt.
+ * Construction errors remain outside network classification. Native fetch/read
+ * errors retain their causes as TransportError. Consumer execution remains outside
+ * those catches; scope exit aborts and joins I/O before releasing its reader.
+ * Protocol consumers never receive the native Response.
+ */
+export class FetchHttpClient {
+    /**
+     * Consume finite bytes and finish the request scope before returning a completed response.
+     *
+     * @param url Absolute HTTP(S) URL; invalid URL/request construction fails before fetch.
+     * @param init Prepared method, headers, finite body and cancellation; omitted values use native Request defaults.
+     * @returns Status, headers and complete owned bytes after request cleanup.
+     * @throws Validation/construction errors remain caller errors; native fetch/body failures are TransportError with cause. Cancellation and cleanup failures remain visible.
+     */
+    request(url, init = {}) {
+        const open = this.open.bind(this);
+        return scoped(function* () {
+            const response = yield* open(url, init);
+            const body = yield* abortable((signal) => collectBytes(response.body(signal)), init.signal ?? undefined);
+            return { status: response.status, ok: response.ok, headers: response.headers, body };
+        });
+    }
+    /**
+     * Acquire headers and lend response bytes until the enclosing Effection scope ends.
+     * Validate Request before fetch; scope exit aborts unread I/O, joins pending
+     * fetch/read work and releases the reader. Consumer failures stay outside the
+     * transport catches. The response must not escape this scope.
+     *
+     * @param url Absolute HTTP(S) endpoint without embedded credentials.
+     * @param init Prepared method, headers, finite body and optional upstream cancellation; native Request defaults apply.
+     * @returns Metadata and one borrowed body source; status success does not prove body completion.
+     * @throws Validation errors precede network execution. Native fetch/read failures retain their cause in TransportError; cancellation and distinct cleanup failures propagate.
+     */
+    open(url, init = {}) {
+        return resource(function* (provide) {
+            const controller = new AbortController();
+            const signal = init.signal ? AbortSignal.any([controller.signal, init.signal]) : controller.signal;
+            // These handles let scope teardown join native work before releasing the reader.
+            let fetching;
+            let reader;
+            let reading;
+            let failure;
+            let bodySignal;
+            /** A borrowing parser must interrupt its read before child teardown tries to join it. */
+            const abortBody = () => controller.abort(bodySignal.reason);
+            /**
+             * Classify only native fetch/read failures, preserving exact caller cancellation.
+             * @param cause Native rejection; consumer/parser exceptions never enter this helper.
+             * @param message Operation detail to combine with the endpoint URL.
+             * @returns Original cancellation reason or a TransportError retaining cause.
+             */
+            const transportFailure = (cause, message) => signal.aborted && cause === signal.reason ? cause : new TransportError(`${message} for ${url}`, { cause });
+            try {
+                signal.throwIfAborted();
+                const endpoint = new URL(url);
+                if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password) {
+                    throw new ValidationError("HTTP output requires an HTTP(S) URL without credentials");
+                }
+                // Construction errors are caller errors, before native network classification.
+                const request = new Request(url, { ...init, signal, body: init.body });
+                fetching = fetch(request).catch((cause) => {
+                    throw transportFailure(cause, "HTTP request failed");
+                });
+                const response = yield* call(() => fetching);
+                signal.throwIfAborted();
+                yield* provide({
+                    status: response.status,
+                    ok: response.ok,
+                    headers: response.headers,
+                    /**
+                     * Borrow the native response reader for this request scope.
+                     * Early iterator return aborts the request; the enclosing owner joins cleanup.
+                     *
+                     * @param consumerSignal Optional consumer cancellation; abort interrupts this request and any pending read.
+                     * @returns A single-consumer iterable of byte chunks, valid only while the request scope remains open.
+                     */
+                    body(consumerSignal) {
+                        if (reader)
+                            throw new Error("HTTP response body already acquired");
+                        bodySignal = consumerSignal;
+                        bodySignal?.addEventListener("abort", abortBody, { once: true });
+                        if (bodySignal?.aborted)
+                            abortBody();
+                        reader = response.body?.getReader();
+                        return {
+                            /** Pull ordinary chunks; consumer execution stays outside the transport catch. */
+                            async *[Symbol.asyncIterator]() {
+                                try {
+                                    signal.throwIfAborted();
+                                    while (reader) {
+                                        signal.throwIfAborted();
+                                        reading = reader.read().catch((cause) => {
+                                            // Node 20 Fetch replaces the supplied reason with a native AbortError during body reads.
+                                            if (signal.aborted && cause instanceof DOMException && cause.name === "AbortError") {
+                                                throw signal.reason;
+                                            }
+                                            throw transportFailure(cause, "HTTP response body failed");
+                                        });
+                                        let result;
+                                        try {
+                                            result = await reading;
+                                        }
+                                        catch (error) {
+                                            failure = { error };
+                                            throw error;
+                                        }
+                                        finally {
+                                            reading = undefined;
+                                        }
+                                        signal.throwIfAborted();
+                                        if (result.done)
+                                            return;
+                                        yield result.value;
+                                    }
+                                }
+                                finally {
+                                    // Early iterator return stops the native response; the request scope joins it.
+                                    controller.abort();
+                                }
+                            },
+                        };
+                    },
+                });
+            }
+            catch (error) {
+                failure = { error };
+                throw error;
+            }
+            finally {
+                // Fetch abort also stops unread bodies. Do not create a second cancellation path.
+                controller.abort();
+                const cleanup = [];
+                yield* call(async () => {
+                    for (const pending of [fetching, reading]) {
+                        try {
+                            await pending;
+                        }
+                        catch (error) {
+                            if (error !== signal.reason && error !== failure?.error)
+                                cleanup.push(error);
+                        }
+                    }
+                    try {
+                        reader?.releaseLock();
+                    }
+                    catch (error) {
+                        cleanup.push(error);
+                    }
+                    bodySignal?.removeEventListener("abort", abortBody);
+                });
+                // Throw outside the Promise leaf so Effection teardown preserves genuine cleanup failures.
+                if (cleanup.length) {
+                    if (failure && failure.error !== signal.reason)
+                        cleanup.unshift(failure.error);
+                    // deno-lint-ignore no-unsafe-finally -- A joined cleanup failure must remain visible during halt.
+                    if (cleanup.length === 1)
+                        throw cleanup[0];
+                    // deno-lint-ignore no-unsafe-finally -- Preserve the primary failure alongside distinct cleanup failure.
+                    throw new AggregateError(cleanup, "HTTP request and cleanup failed", { cause: cleanup[0] });
+                }
+            }
+        });
+    }
+}

package/esm/keri/npm/src/app/transport/http-messenger.js

@@ -0,0 +1,52 @@
+import { chunkBytes } from "./byte-source.js";
+import { attemptPostCesr } from "./cesr-egress.js";
+/**
+ * Send ordinary signed messages as ordered HTTP POSTs and finish response cleanup.
+ * Producers own preparation and Poster owns queued work. This component needs no
+ * Habery, protocol processor, parser state, timer or response history.
+ *
+ * Corresponds to the ordinary POST role of KERIpy HTTPMessenger. Complete CESR
+ * frames become separate POSTs: original signed body in the request body, text
+ * attachments in CESR-ATTACHMENT. Only the recognized pre-intake media refusal
+ * permits a second attempt with legacy media metadata. Successful response bytes
+ * are drained and discarded; protocol receiving belongs to independent intake.
+ */
+export class HTTPMessenger {
+    /** Bind one endpoint and request metadata; construction performs no I/O. */
+    constructor(url, http, options = {}) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: url
+        });
+        Object.defineProperty(this, "http", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: http
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+    }
+    /**
+     * Send resident signed bytes through the same parser/request path as sendSource.
+     * Keep the input unchanged until completion. A complete result proves transport
+     * completion, not remote verification, storage, approval or a processed reply.
+     */
+    send(msg, options = {}) {
+        return this.sendSource((signal) => chunkBytes(msg, { signal }), options);
+    }
+    /**
+     * Iterate ordinary messages into POSTs; this is not whole-stream PUT delivery.
+     * A later malformed message cannot prevent an earlier valid POST. Parser,
+     * transport, source and cleanup failures propagate; HTTP refusal is typed data.
+     */
+    sendSource(source, options = {}) {
+        return attemptPostCesr(this.url, source, this.http, { ...this.options, ...options });
+    }
+}

package/esm/keri/npm/src/app/transport/http-stream-messenger.js

@@ -0,0 +1,60 @@
+import { buildCesrStreamRequest, CESR_ATTACHMENT_HEADER, CESR_DESTINATION_HEADER } from "./cesr-http.js";
+/**
+ * Bind one complete prepared payload to KERIpy-style HTTPStreamMessenger PUT.
+ * This component does not inspect CESR frames or own a producer queue. The
+ * producer prepares introductions, genus transitions and any sealing before
+ * construction; send owns only the actual request and joined response cleanup.
+ */
+export class HTTPStreamMessenger {
+    /** Construction borrows a finite payload; its producer must not mutate it during delivery. */
+    constructor(url, http, payload, options = {}) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: url
+        });
+        Object.defineProperty(this, "http", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: http
+        });
+        Object.defineProperty(this, "payload", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: payload
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+    }
+    /**
+     * Send exactly one PUT without parsing, re-encoding or fallback to POST.
+     * Return ordinary owned response bytes after request cleanup; HTTP success
+     * alone does not establish protocol acceptance. Cancellation/failures propagate.
+     * Non-success status is returned to the caller as HttpResponse for interpretation.
+     * The complete payload is the body with explicit length; CESR-ATTACHMENT is
+     * removed because this is not ordinary detached-attachment POST framing.
+     */
+    send(options = {}) {
+        const prepared = buildCesrStreamRequest(this.payload, this.options);
+        const headers = new Headers(this.options.headers);
+        headers.delete(CESR_DESTINATION_HEADER);
+        for (const [key, value] of Object.entries(prepared.headers))
+            headers.set(key, value);
+        headers.delete(CESR_ATTACHMENT_HEADER);
+        headers.set("Content-Length", String(this.payload.byteLength));
+        return this.http.request(this.url, {
+            method: "PUT",
+            headers,
+            body: prepared.body,
+            redirect: "manual",
+            signal: options.signal,
+        });
+    }
+}

package/esm/keri/npm/src/app/transport/httping.js

@@ -0,0 +1,57 @@
+/** HTTP caller policies; the composed client owns native requests, readers and cleanup. */
+import { call, resource } from "effection";
+/**
+ * Acquire headers under the mailbox's existing timeout-as-no-response policy.
+ * The timer ends at headers, while the client resource remains live in this
+ * caller scope for body consumption. Only this timer's exact abort becomes null;
+ * external abort, native I/O and cleanup failures remain visible.
+ *
+ * @param http Borrowed HTTP implementation selected by composition.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param url Absolute HTTP(S) endpoint.
+ * @param init Prepared request fields and optional upstream cancellation.
+ * @param timeoutMs Header-acquisition window in milliseconds; body consumption has its own caller policy.
+ * @returns Scoped response after headers, or null only for this owner's header timeout.
+ */
+export function requestWithHeaderTimeout(http, clock, url, init, timeoutMs) {
+    return resource(function* (provide) {
+        const controller = new AbortController();
+        const signal = init.signal ? AbortSignal.any([controller.signal, init.signal]) : controller.signal;
+        let timer;
+        let timedOut = false;
+        /** Header acquisition clears its timer without ending the owning request scope. */
+        const clearTimer = () => {
+            if (timer !== undefined)
+                clock.clearTimeout(timer);
+            timer = undefined;
+        };
+        try {
+            signal.throwIfAborted();
+            timer = clock.setTimeout(() => {
+                if (!signal.aborted) {
+                    timedOut = true;
+                    controller.abort();
+                }
+            }, timeoutMs);
+            try {
+                // Keep acquisition failure inside an error boundary without closing a successful body early.
+                yield* call(function* () {
+                    const response = yield* http.open(url, { ...init, signal });
+                    clearTimer();
+                    yield* provide(response);
+                });
+            }
+            catch (error) {
+                if (!timedOut || error !== controller.signal.reason)
+                    throw error;
+                clearTimer();
+                yield* provide(null);
+                return;
+            }
+        }
+        finally {
+            clearTimer();
+            controller.abort();
+        }
+    });
+}

package/esm/keri/npm/src/app/transport/message-source.js

@@ -0,0 +1,77 @@
+/** Buffered input iteration and joined parser/source cleanup shared by concrete input owners. */
+import { parse } from "cesr-ts";
+import { call, ensure, on, race } from "effection";
+import { rethrowCleanupFailure } from "../runtime/abortable.js";
+/**
+ * Consume complete frames through the supplied input-owned Kevery and shared protocol owner.
+ * A pending read is joined before iterator return; cancellation cannot resume the
+ * caller after disposal. The owning input operation borrows processors and acquires
+ * no stores, queues, transport services or background workers here.
+ *
+ * @param source Creates the input byte source with this operation's abort signal; each source must honor cancellation.
+ * @param protocol Borrowed dispatcher over synchronous domain commits and correlated cue publication.
+ * @param kvy Input-owned KEL processor bound to the same store, reply verifier and cue flow.
+ * @param options Dispatch policy and optional upstream cancellation; defaults follow the shared processor.
+ * @throws Parsing, dispatch and cleanup failures propagate after the pending pull and iterator cleanup join.
+ */
+export function* processMessages(source, protocol, kvy, options = {}) {
+    const input = call(function* () {
+        const controller = new AbortController();
+        const signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+        try {
+            signal.throwIfAborted();
+            const frames = parse(source(signal));
+            let pending;
+            // This earlier resource joins I/O after dispatch/read children have stopped.
+            yield* ensure(function* () {
+                try {
+                    if (pending) {
+                        try {
+                            yield* call(() => pending);
+                        }
+                        catch (error) {
+                            rethrowCleanupFailure(error, signal);
+                        }
+                    }
+                }
+                finally {
+                    yield* call(() => frames.return());
+                }
+            });
+            while (true) {
+                signal.throwIfAborted();
+                pending = frames.next();
+                let result;
+                try {
+                    result = yield* call(() => pending);
+                }
+                catch (error) {
+                    pending = undefined; // Already reported; the parser has joined its source cleanup.
+                    throw error;
+                }
+                pending = undefined;
+                signal.throwIfAborted();
+                if (result.done)
+                    return;
+                yield* protocol.dispatch(result.value, options, kvy);
+            }
+        }
+        finally {
+            controller.abort();
+        }
+    });
+    if (options.signal) {
+        const signal = options.signal;
+        yield* race([
+            input,
+            call(function* () {
+                const abort = yield* on(signal, "abort");
+                signal.throwIfAborted();
+                yield* abort.next();
+                throw signal.reason;
+            }),
+        ]);
+    }
+    else
+        yield* input;
+}

package/esm/keri/npm/src/app/transport/messengering.js

@@ -0,0 +1,68 @@
+/**
+ * Concrete messenger factories corresponding to KERIpy agenting.messengerFrom
+ * and streamMessengerFrom. Callers resolve identity roles/relay policy first;
+ * these functions choose only among the supplied transport URLs and open no I/O.
+ *
+ * Ordinary messages and opaque streams are different producer operations. They
+ * do not select a stored framing preference or acquire workers, stores or queues.
+ */
+import { ValidationError } from "../../core/errors.js";
+import { HTTPMessenger } from "./http-messenger.js";
+import { HTTPStreamMessenger } from "./http-stream-messenger.js";
+import { TCPMessenger } from "./tcp-messenger.js";
+import { TCPStreamMessenger } from "./tcp-stream-messenger.js";
+/** Choose HTTPS, HTTP, then TCP and reject a mismatched advertised scheme before I/O. */
+function endpointFrom(urls) {
+    for (const scheme of ["https", "http", "tcp"]) {
+        const value = urls[scheme];
+        if (value === undefined)
+            continue;
+        const endpoint = new URL(value);
+        if (endpoint.protocol !== `${scheme}:` || endpoint.username || endpoint.password) {
+            throw new ValidationError(`Invalid ${scheme} messenger endpoint: ${value}`);
+        }
+        if (scheme === "tcp" && (!endpoint.port || Number(endpoint.port) < 1 || Number(endpoint.port) > 65535)) {
+            throw new ValidationError(`TCP messenger endpoint requires a valid port: ${value}`);
+        }
+        return endpoint;
+    }
+    throw new ValidationError("No supported messenger endpoint is available.");
+}
+/**
+ * Bind ordinary signed-message delivery to the first present HTTPS/HTTP/TCP URL.
+ * A malformed higher-priority URL fails rather than falling through to another
+ * transport. There is no network retry or endpoint discovery at this boundary.
+ *
+ * @param destination Remote AID carried in the HTTP CESR-DESTINATION header.
+ * @param urls Already resolved endpoints, keyed by their actual scheme.
+ * @param http Borrowed HTTP implementation, used only for an HTTP(S) selection.
+ * @param clock Borrowed deadline clock, used only for a TCP selection.
+ * @param headers Additional HTTP headers, such as Authorization; ignored by TCP.
+ * @returns A transmit-only messenger; caller runs send and owns its lifetime.
+ */
+export function messengerFrom(destination, urls, http, clock, headers) {
+    const endpoint = endpointFrom(urls);
+    if (endpoint.protocol === "tcp:")
+        return new TCPMessenger(endpoint.href, clock);
+    return new HTTPMessenger(endpoint.href, http, { destination, headers });
+}
+/**
+ * Bind one prepared opaque payload to HTTP PUT or raw TCP delivery.
+ * No parser, re-signing or fallback to ordinary POST is introduced. This follows
+ * KERIpy's separate stream factory; "stream" describes the transport operation,
+ * while this API borrows finite resident bytes.
+ *
+ * @param destination Remote AID carried in HTTP framing; not a receipt/acceptance claim.
+ * @param urls Resolved endpoints, with the same fail-fast preference as messengerFrom.
+ * @param payload Complete prepared wire; caller must keep it unchanged until send finishes.
+ * @param http Borrowed HTTP service for a possible PUT.
+ * @param clock Borrowed clock for possible TCP connection/drain deadlines.
+ * @param headers Additional HTTP headers; ignored by TCP.
+ * @returns An unstarted messenger with no receive loop or scheduling ownership.
+ */
+export function streamMessengerFrom(destination, urls, payload, http, clock, headers) {
+    const endpoint = endpointFrom(urls);
+    if (endpoint.protocol === "tcp:")
+        return new TCPStreamMessenger(endpoint.href, clock, payload);
+    return new HTTPStreamMessenger(endpoint.href, http, payload, { destination, headers });
+}

package/esm/keri/npm/src/app/{socket-source.js → transport/socket-source.js}

@@ -5,6 +5,11 @@ const readers = new WeakSet();
  * Socket/OS buffers and a returned native view can have larger backing; copied output is independent.
  * Abort, failure or early return destroys and joins the socket. Genuine receive EOF leaves its writable
  * half intact; the caller must own later socket errors, output drain and final close (allowHalfOpen).
+ *
+ * @param socket Borrowed binary socket with no competing readable/data consumer; receive ownership is acquired on first pull.
+ * @param options Required abort signal and optional positive chunk size in bytes; default 65536.
+ * @returns An exclusive iterator allowing one pending next call; each chunk owns its backing buffer.
+ * @throws Competing readers, text/object-mode sockets, invalid chunk sizes, I/O and cleanup failures.
  */
 export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
     if (!Number.isSafeInteger(maxChunkBytes) || maxChunkBytes < 1) {
@@ -17,6 +22,10 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
     let pending;
     /** Wake the sole pending pull without starting another socket read. */
     const readable = () => wake?.();
+    /**
+     * Preserve the first read failure and wake the pending pull to report it.
+     * @param error Socket error or exact owner cancellation reason.
+     */
     const fail = (error) => {
         if (!failed) {
             failed = true;
@@ -24,10 +33,12 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
         }
         readable();
     };
+    /** Mark genuine receive EOF without closing the writable half. */
     const end = () => {
         ended = true;
         readable();
     };
+    /** Settle native close and report premature closure to any pending pull. */
     const close = () => {
         closed = true;
         if (!ended && !socket.readableEnded)
@@ -35,7 +46,11 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
         finishClose?.();
         readable();
     };
-    /** Keep error/close listeners until destruction joins; EOF only releases readable ownership. */
+    /**
+     * Keep error/close listeners until destruction joins; EOF only releases read ownership.
+     * @param eof True only after genuine receive EOF, preserving the writable half.
+     * @returns Shared cleanup promise; repeated calls join the same cleanup.
+     */
     const cleanup = (eof = false) => closing ??= (async () => {
         if (!started)
             return;
@@ -55,6 +70,7 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
             readers.delete(socket);
         }
     })();
+    /** Interrupt the blocked pull now; its next/return owner joins the cleanup promise. */
     const abort = () => {
         fail(signal.reason);
         // The original Promise stays owned by next()/return(), which join and propagate cleanup errors.
@@ -91,7 +107,11 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
         else
             socket.resume();
     };
-    /** Read only available bytes, so a short fragment does not wait for a full chunk or EOF. */
+    /**
+     * Read only available bytes, so a short fragment does not wait for a full chunk or EOF.
+     * @returns One copied binary chunk or EOF after releasing read ownership.
+     * @throws Original read failure after cleanup, or an aggregate retaining distinct cleanup failure.
+     */
     const pull = async () => {
         try {
             if (!started)
@@ -139,6 +159,11 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
         }
     };
     return {
+        /**
+         * Perform the sole pending pull, acquiring readable ownership lazily.
+         *
+         * @returns The next copied chunk or EOF; overlapping calls reject.
+         */
         next() {
             if (busy)
                 return Promise.reject(new Error("Concurrent socket pull"));
@@ -147,6 +172,13 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
             busy = true;
             return pending = pull();
         },
+        /**
+         * Stop iteration early and join socket destruction.
+         * A source never pulled owns no socket resources; genuine EOF has already
+         * released readable ownership while preserving the writable half.
+         *
+         * @returns EOF after any acquired socket cleanup and outstanding pull join.
+         */
         async return() {
             done = true;
             if (started) {
@@ -156,6 +188,11 @@ export function socketBytes(socket, { signal, maxChunkBytes = 64 * 1024 }) {
             }
             return { done: true, value: undefined };
         },
+        /**
+         * Expose the same reader to for-await iteration; do not create a second consumer.
+         *
+         * @returns This single-consumer iterator.
+         */
         [Symbol.asyncIterator]() {
             return this;
         },