keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/{mailbox-director.js → mailbox/mailbox-director.js}

@@ -1,26 +1,10 @@
-/**
- * Runtime-composed mailbox publication, query, and stream coordination.
- *
- * KERIpy correspondence:
- * - gathers responsibilities that KERIpy spreads across `Mailboxer`,
- *   mailbox iterables, and indirect-mode query handling
- *
- * Boundary rule:
- * - this module is mailbox storage/query infrastructure, not the general
- *   responder path
- * - non-`stream` cue delivery such as `reply`, `replay`, `receipt`, and
- *   `witness` belongs in `Respondant`
- *
- * Current `keri-ts` difference:
- * - one runtime host receives an explicit mailbox sidecar instead of
- *   discovering mailbox storage through `Habery`
- */
-import { ResourceAdmissionError, ResourceLimitError, ResourcePolicy } from "cesr-ts";
-import { CueDeck } from "../core/cue-admission.js";
-import { ValidationError } from "../core/errors.js";
+import { Deck } from "../../core/deck.js";
+import { ValidationError } from "../../core/errors.js";
 import { mailboxQueryTopics, mailboxTopicKey, updateMailboxRemoteCursor } from "./mailboxing.js";
 /** Shared encoder for SSE mailbox stream framing. */
 const textEncoder = new TextEncoder();
+/** Transport pull granularity; it does not restrict complete mailbox message size. */
+const STREAM_CHUNK_BYTES = 65536;
 /**
  * Mailbox topic director for one runtime host.
  *
@@ -41,13 +25,27 @@ const textEncoder = new TextEncoder();
  *   `MailboxIterable`
  */
 export class MailboxDirector {
-    constructor(hby, { mailboxer, queryCues, topics = [], resources = new ResourcePolicy(), streamLimits = {}, maxQueryCues = 64, } = {}) {
+    /**
+     * Compose provider publication and request-owned stream tracking.
+     * Absent mailboxer disables storage/serving; correlation and topic registration
+     * remain available. A new query Deck is created only when none is supplied.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param options Optional borrowed mailbox store, exclusive query-cue Deck and initial topics; no store is opened.
+     */
+    constructor(hby, { mailboxer, queryCues, topics = [], } = {}) {
+        /**
+         * Borrowed local identities and accepted-state stores.
+         */
         Object.defineProperty(this, "hby", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Borrowed provider mailbox store, or null when this host cannot serve stored messages.
+         */
         Object.defineProperty(this, "mailboxer", {
             enumerable: true,
             configurable: true,
@@ -61,31 +59,28 @@ export class MailboxDirector {
             writable: true,
             value: void 0
         });
+        /**
+         * Registered protocol topics, copied from construction input and extended by registerTopic.
+         */
         Object.defineProperty(this, "topics", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Live response finalizers joined before the provider store can close.
+         */
         Object.defineProperty(this, "streamCleanups", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: new Set()
         });
-        Object.defineProperty(this, "resources", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "limits", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "correlationsClosed", {
+        /**
+         * Terminal stream/correlation admission state.
+         */
+        Object.defineProperty(this, "closed", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -93,43 +88,30 @@ export class MailboxDirector {
         });
         this.hby = hby;
         this.mailboxer = mailboxer ?? null;
-        if (!Number.isSafeInteger(maxQueryCues) || maxQueryCues < 0)
-            throw new RangeError("Invalid mailbox query capacity");
-        if (queryCues && queryCues.resourcePolicy !== resources)
-            throw new RangeError("Mailbox query policy mismatch");
-        this.queryCues = queryCues ?? new CueDeck(resources, maxQueryCues);
-        this.queryCues.capacity = Math.min(this.queryCues.capacity, maxQueryCues);
+        this.queryCues = queryCues ?? new Deck();
         this.topics = new Set(topics);
-        this.resources = resources;
-        this.limits = {
-            maxMessageBytes: 4 * 1024 ** 2,
-            maxChunkBytes: 65536,
-            maxTopics: 64,
-            maxMetadataBytes: 65536,
-            ...streamLimits,
-        };
-        for (const limit of Object.values(this.limits)) {
-            if (!Number.isSafeInteger(limit) || limit < 1)
-                throw new RangeError("Invalid mailbox stream limit");
-        }
-    }
-    /** Return true when provider-side mailbox storage is available. */
-    hasMailboxStore() {
-        return this.mailboxer !== null;
     }
-    /** Register one mailbox topic this runtime should poll/stream. */
+    /**
+     * Register one mailbox topic this runtime should poll/stream.
+     *
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     */
     registerTopic(topic) {
         if (topic.length > 0) {
             this.topics.add(topic);
         }
     }
-    /** Snapshot the currently configured mailbox topic set. */
+    /**
+     * Snapshot the currently configured mailbox topic set.
+     *
+     * @returns Independent array snapshot of the configured topic set.
+     */
     registeredTopics() {
         return [...this.topics];
     }
     /** Stop every request-owned mailbox stream before its backing store closes. */
     async close() {
-        this.correlationsClosed = true;
+        this.closed = true;
         const outcomes = await Promise.allSettled([...this.streamCleanups].map((cleanup) => Promise.resolve().then(cleanup)));
         const failures = outcomes.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
         try {
@@ -144,58 +126,60 @@ export class MailboxDirector {
         if (failures.length)
             throw new AggregateError(failures, "Mailbox stream cleanup failed");
     }
-    /** Reserve message-copy, emitted-chunk and metadata allowance before any stream or native row acquisition. */
-    admit() {
-        const { maxMessageBytes, maxChunkBytes, maxMetadataBytes } = this.limits;
-        const credit = this.resources.reserve({
-            streams: 1,
-            bytes: 2 * maxMessageBytes + maxChunkBytes + 4 * maxMetadataBytes + 512,
-        });
-        if (credit.kind === "refuse") {
-            throw new ResourceAdmissionError(`Mailbox stream admission refused: ${credit.reason}`, credit.reason);
-        }
-        return credit.reservation;
-    }
-    /** Bound labels/ordinals before making a cursor copy or Object.entries allocation. */
+    /**
+     * Validate exact cursor ordinals before copying the caller's query positions.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topics Topic-to-next-wanted ordinal map; each value must be a nonnegative safe integer.
+     * @returns A copied cursor map owned by this response.
+     * @throws RangeError for malformed prefix/map/ordinals.
+     */
     cursor(pre, topics) {
         if (typeof pre !== "string" || !topics || typeof topics !== "object" || Array.isArray(topics)) {
             throw new RangeError("Invalid mailbox topic metadata");
         }
-        let characters = pre.length, count = 0;
         for (const topic in topics) {
             if (!Object.hasOwn(topics, topic))
                 continue;
-            characters += topic.length;
-            if (++count > this.limits.maxTopics || 4 * characters > this.limits.maxMetadataBytes) {
-                throw new ResourceLimitError("Mailbox topic metadata exceeds configured policy");
-            }
             if (!Number.isSafeInteger(topics[topic]) || topics[topic] < 0) {
                 throw new RangeError("Invalid mailbox topic cursor");
             }
         }
-        if (4 * characters > this.limits.maxMetadataBytes) {
-            throw new ResourceLimitError("Mailbox prefix metadata exceeds configured policy");
-        }
         return { ...topics };
     }
-    /** Admit one immutable query cue before the caller removes its source owner; busy leaves that source intact. */
-    retainQueryCue(cue, onAdmissionRefusal) {
-        if (this.correlationsClosed)
+    /**
+     * Queue a query cue for correlation with its mailbox response.
+     *
+     * @param cue Authorized stream request produced by protocol processing; the director owns later correlation consumption.
+     */
+    retainQueryCue(cue) {
+        if (this.closed)
             throw new Error("Mailbox query correlation is closed");
-        this.queryCues.prepare([cue], onAdmissionRefusal).publish();
+        this.queryCues.push(cue);
     }
     /**
      * Persist one outbound mailbox payload under the ordered topic bucket for
      * `pre/topic`.
      *
      * The returned index is the newly assigned mailbox event id for that topic.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param msg Complete already-authorized wire message to persist under this recipient/topic.
+     * @returns Assigned mailbox index; persistence is not remote consumption.
      */
     publish(pre, topic, msg) {
         const idx = this.lastIndex(pre, topic) + 1;
         this.requireMailboxer().storeMsg(mailboxTopicKey(pre, topic), msg);
         return idx;
     }
-    /** Return the latest stored publication index for one topic, or `-1`. */
+    /**
+     * Return the latest stored publication index for one topic, or `-1`.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @returns Latest stored insertion ordinal, or -1 for an empty topic.
+     */
     lastIndex(pre, topic) {
         const count = this.requireMailboxer().tpcs.cntOn(mailboxTopicKey(pre, topic));
         return count > 0 ? count - 1 : -1;
@@ -205,9 +189,14 @@ export class MailboxDirector {
      *
      * The returned index is the mailbox event id that should be reflected in the
      * SSE `id:` field for the emitted message.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param from Inclusive insertion ordinal; default zero.
+     * @returns Synchronous iterator of ordinal/message pairs in storage order.
      */
-    *topicIter(pre, topic, from = 0, maxMessageBytes) {
-        for (const [idx, , msg] of this.requireMailboxer().cloneTopicIter(mailboxTopicKey(pre, topic), from, maxMessageBytes)) {
+    *topicIter(pre, topic, from = 0) {
+        for (const [idx, , msg] of this.requireMailboxer().cloneTopicIter(mailboxTopicKey(pre, topic), from)) {
             yield { idx, msg };
         }
     }
@@ -219,19 +208,27 @@ export class MailboxDirector {
      * - emit one initial `retry:` hint
      * - stream ordered mailbox payloads as `id/event/data`
      * - close once the idle window expires without new mailbox traffic
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topicCursor Next wanted insertion ordinal for each requested topic; copied before streaming.
+     * @param options SSE retry hint, local polling interval, optional idle expiry and initial hint selection.
+     * @returns Demand-driven response tracked until EOF, cancellation or director close.
      */
     streamMailbox(pre, topicCursor, options = {}) {
-        const credit = this.admit();
-        try {
-            return this.mailboxStream(pre, this.cursor(pre, topicCursor), options, () => credit.release(), true);
-        }
-        catch (error) {
-            credit.release();
-            throw error;
-        }
+        if (this.closed)
+            throw new Error("Mailbox stream is closed");
+        return this.mailboxStream(pre, this.cursor(pre, topicCursor), options, true);
     }
-    /** A query response lends its existing lease to this nested stream instead of charging it twice. */
-    mailboxStream(pre, cursors, { retryMs = 5000, pollIntervalMs = 50, idleTimeoutMs = 2000, emitRetryHeader = true, }, release, tracked) {
+    /**
+     * Own one demand-driven mailbox reader; query responses join their nested reader themselves.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param cursors Response-owned next-wanted ordinals, advanced as rows are framed.
+     * @param options Millisecond retry/poll/idle settings; null idle timeout keeps the response open.
+     * @param tracked Track direct responses here; nested query responses are joined by their outer owner.
+     * @returns SSE bytes in 64 KiB chunks; database iterators close before awaiting HTTP demand.
+     */
+    mailboxStream(pre, cursors, { retryMs = 5000, pollIntervalMs = 50, idleTimeoutMs = 2000, emitRetryHeader = true, }, tracked) {
         for (const value of [retryMs, pollIntervalMs, idleTimeoutMs]) {
             if (value !== null && (!Number.isSafeInteger(value) || value < 0)) {
                 throw new RangeError("Invalid mailbox stream timing");
@@ -249,7 +246,6 @@ export class MailboxDirector {
         let idleSince;
         let pending;
         let closing;
-        let released = false;
         /** Closing wakes a pending pull before its database owner is released. */
         const stop = () => {
             if (closed)
@@ -260,13 +256,11 @@ export class MailboxDirector {
             wake?.();
             parts = [];
         };
+        /** Remove this direct stream from shutdown tracking after its pending pull settles. */
         const finish = () => {
-            if (released)
-                return;
-            released = true;
             this.streamCleanups.delete(close);
-            release();
         };
+        /** Wake and join the pending pull once before forgetting this response owner. */
         const cleanup = () => {
             stop();
             return closing ??= Promise.resolve(pending).finally(finish);
@@ -280,6 +274,11 @@ export class MailboxDirector {
             return cleanup();
         };
         const readable = new ReadableStream({
+            /**
+             * Bind the Web stream controller before response demand begins.
+             *
+             * @param controller Web response controller retained for later pulls/shutdown.
+             */
             start(controller) {
                 stream = controller;
             },
@@ -297,7 +296,7 @@ export class MailboxDirector {
                     while (!closed) {
                         if (parts.length) {
                             const part = parts[0];
-                            const end = Math.min(part.length, offset + this.limits.maxChunkBytes);
+                            const end = Math.min(part.length, offset + STREAM_CHUNK_BYTES);
                             controller.enqueue(part.slice(offset, end));
                             offset = end;
                             if (offset === part.length) {
@@ -308,7 +307,7 @@ export class MailboxDirector {
                         }
                         for (const [topic, start] of Object.entries(cursors)) {
                             // Take one stored item, then release the LMDB iterator before suspending on HTTP demand.
-                            const items = this.topicIter(pre, topic, start, this.limits.maxMessageBytes);
+                            const items = this.topicIter(pre, topic, start);
                             let item;
                             try {
                                 item = items.next().value;
@@ -318,9 +317,6 @@ export class MailboxDirector {
                             }
                             if (!item)
                                 continue;
-                            if (item.msg.buffer.byteLength > this.limits.maxMessageBytes) {
-                                throw new ResourceLimitError("Mailbox SSE message exceeds byte limit");
-                            }
                             parts = [
                                 textEncoder.encode(`id: ${item.idx}\nevent: ${topic}\nretry: ${retryMs}\ndata: `),
                                 item.msg,
@@ -376,24 +372,16 @@ export class MailboxDirector {
      * This mirrors KERIpy `QryRpyMailboxIterable` ownership closely: the HTTP
      * route does not guess mailbox topics itself; it waits for mailbox query
      * correlation to tell it what to stream.
+     *
+     * @param said Query SAID used to locate an already-authorized stream cue; correlation alone is not authorization.
+     * @param options Retry hint and query-cue polling interval in milliseconds; defaults 5000 and 50.
+     * @returns Request-owned SSE response that waits for its cue then proxies an unbounded mailbox reader.
      */
-    streamQueryResponse(said, options = {}) {
-        if (this.correlationsClosed)
+    streamQueryResponse(said, { retryMs = 5000, pollIntervalMs = 50 } = {}) {
+        if (this.closed)
             throw new Error("Mailbox query correlation is closed");
-        const credit = this.admit();
-        try {
-            if (typeof said !== "string" || 4 * said.length > this.limits.maxMetadataBytes) {
-                throw new ResourceLimitError("Mailbox query metadata exceeds configured policy");
-            }
-            return this.queryStream(said, options, () => credit.release());
-        }
-        catch (error) {
-            credit.release();
-            throw error;
-        }
-    }
-    /** The outer query owner joins its nested reader before returning shared stream credit. */
-    queryStream(said, { retryMs = 5000, pollIntervalMs = 50, }, release) {
+        if (typeof said !== "string")
+            throw new RangeError("Invalid mailbox query SAID");
         if (!Number.isSafeInteger(retryMs) || retryMs < 0 || !Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1) {
             throw new RangeError("Invalid mailbox query timing");
         }
@@ -435,16 +423,8 @@ export class MailboxDirector {
                 catch (error) {
                     failures.push(error);
                 }
-                try {
-                    selected?.release();
-                }
-                catch (error) {
-                    if (!failures.includes(error))
-                        failures.push(error);
-                }
                 selected = undefined;
                 this.streamCleanups.delete(close);
-                release();
                 if (failures.length === 1)
                     throw failures[0];
                 if (failures.length)
@@ -461,6 +441,9 @@ export class MailboxDirector {
             return completed;
         };
         const readable = new ReadableStream({
+            /** Bind this nested response controller before the first pull.
+             * @param controller Web response controller used by pull and shutdown.
+             */
             start(controller) {
                 stream = controller;
             },
@@ -474,7 +457,7 @@ export class MailboxDirector {
                     while (!reader && !closed) {
                         selected = this.takeQueryCue(said) ?? undefined;
                         if (selected) {
-                            const cue = selected.cue;
+                            const cue = selected;
                             if (cue.kin !== "stream")
                                 throw new Error("Mailbox query owner is not a stream cue");
                             reader = this.mailboxStream(cue.pre, this.cursor(cue.pre, cue.topics), {
@@ -482,7 +465,7 @@ export class MailboxDirector {
                                 pollIntervalMs,
                                 idleTimeoutMs: null,
                                 emitRetryHeader: false,
-                            }, () => { }, false).getReader();
+                            }, false).getReader();
                             break;
                         }
                         await new Promise((resolve) => {
@@ -531,11 +514,22 @@ export class MailboxDirector {
      *
      * Stored cursor rows track the last seen index, while the wire query asks for
      * the next wanted index.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param witness Remote mailbox/witness endpoint AID, not the local signer.
+     * @returns Next-wanted ordinals (last consumed + 1, or zero) for registered topics.
      */
     remoteQueryCursor(pre, witness) {
         return mailboxQueryTopics(this.hby, pre, witness, this.topics);
     }
-    /** Persist one consumed remote mailbox index for one `(pre, witness, topic)`. */
+    /**
+     * Persist one consumed remote mailbox index for one `(pre, witness, topic)`.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param witness Remote endpoint AID.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param idx Last successfully consumed insertion ordinal, not the next requested ordinal.
+     */
     updateRemoteCursor(pre, witness, topic, idx) {
         updateMailboxRemoteCursor(this.hby, pre, witness, topic, idx);
     }
@@ -545,6 +539,9 @@ export class MailboxDirector {
      *
      * This keeps query correlation observable without consuming cues that later
      * host work still needs.
+     *
+     * @param said Exact query SAID whose stream request is sought.
+     * @returns Whether a matching request exists.
      */
     hasQueryCue(said) {
         for (const cue of this.queryCues) {
@@ -553,24 +550,34 @@ export class MailboxDirector {
         }
         return false;
     }
-    /** Select the first matching owner without re-admission or changing preceding cue order. */
+    /**
+     * Select the first matching owner without re-admission or changing preceding cue order.
+     *
+     * @param said Exact query SAID whose stream request is sought.
+     * @returns Removed matching cue, or null; other cues retain their order.
+     */
     takeQueryCue(said) {
         let preceding = 0;
         for (const cue of this.queryCues) {
             if (cue.kin === "stream" && cue.serder.said === said) {
                 const kept = [];
                 for (let i = 0; i < preceding; i++)
-                    kept.push(this.queryCues.takeOwned());
-                const selected = this.queryCues.takeOwned();
+                    kept.push(this.queryCues.pull());
+                const selected = this.queryCues.pull();
                 for (let i = kept.length - 1; i >= 0; i--)
-                    this.queryCues.requeue(kept[i]);
+                    this.queryCues.prepend(kept[i]);
                 return selected;
             }
             preceding++;
         }
         return null;
     }
-    /** Require provider mailbox storage for publication or mailbox serving. */
+    /**
+     * Require provider mailbox storage for publication or mailbox serving.
+     *
+     * @returns Borrowed provider store.
+     * @throws ValidationError when storage is absent.
+     */
     requireMailboxer() {
         if (!this.mailboxer) {
             throw new ValidationError("Provider mailbox storage is unavailable for this runtime.");