keri-ts 1.0.0 → 2.0.0

package/esm/keri/npm/src/app/querying.js

@@ -1,775 +0,0 @@
-import { concatBytes } from "cesr-ts";
-import { call, resource } from "effection";
-import { Deck } from "../core/deck.js";
-import { ValidationError } from "../core/errors.js";
-import { Roles } from "../core/roles.js";
-import { Schemes } from "../core/schemes.js";
-import { chunkBytes, streamBytes } from "./byte-source.js";
-import { postCesr } from "./cesr-egress.js";
-import { introduce } from "./forwarding.js";
-import { consumeMailboxSse } from "./mailbox-sse.js";
-import { flattenRoleUrls } from "./mailboxing.js";
-import { defaultRuntimeServices } from "./runtime-services.js";
-import { runtimeTurn } from "./runtime-turn.js";
-import { converseCesrTcp } from "./tcp-conversation.js";
-/**
- * Query/reply correspondence helpers for the Gate E runtime.
- *
- * KERIpy correspondence:
- * - `keri.app.querying` hosts the `KeyStateNoticer`, `LogQuerier`,
- *   `SeqNoQuerier`, and `AnchorQuerier` doers
- * - `keri.app.agenting.WitnessInquisitor` chooses an honest remote attester
- *   when a query is finally emitted
- *
- * `keri-ts` keeps the same behavioral split but makes the ownership seam more
- * explicit:
- * - `QueryCoordinator` owns correspondence, signed query packets and joined
- *   response I/O using concrete Reactor and clock/HTTP dependencies
- * - `Hab.processCuesIter()` remains the cue-to-wire interpreter for already
- *   complete cues
- *
- * Non-goals:
- * - this module never receives a parent AgentRuntime or discovers sibling services
- * - this module does not guess across multiple local habitats
- * - this module does not turn watcher/query selection into generic cue logic
- */
-/**
- * Preferred remote-attester role order for runtime-generated queries.
- *
- * `keri-ts` intentionally chooses a deterministic first-available endpoint
- * instead of KERIpy's random witness/controller/agent selection. That keeps
- * tests and maintainer reasoning stable at the correspondence layer.
- */
-const QUERY_ROLE_PRIORITY = [Roles.controller, Roles.agent, Roles.witness];
-/** Copy only the owned query-body level without erasing its route/payload relationship. */
-function copyQuery(instruction) {
-    switch (instruction.route) {
-        case "logs":
-            return { route: "logs", q: { ...instruction.q } };
-        case "ksn":
-            return { route: "ksn", q: { ...instruction.q } };
-        case "tels":
-        case "tsn":
-            return { route: instruction.route, q: { ...instruction.q } };
-    }
-}
-/**
- * Return the sole local habitat when exactly one exists.
- *
- * Honesty rule:
- * - one habitat means runtime may safely use it as an implicit signer
- * - more than one habitat means runtime must not guess
- */
-function soleHab(hby) {
-    const habitats = hby.habs.values();
-    const first = habitats.next();
-    return first.done || !habitats.next().done ? null : first.value;
-}
-/** Parse one hex sequence number field from key-state/query payloads. */
-function parseHexOrdinal(value) {
-    if (typeof value !== "string" || value.length === 0) {
-        return null;
-    }
-    const parsed = parseInt(value, 16);
-    return Number.isNaN(parsed) ? null : parsed;
-}
-/** Encode one non-negative sequence number in KERI hex-ordinal form. */
-function encodeHexOrdinal(num) {
-    return Math.max(0, num).toString(16);
-}
-/**
- * KERIpy-style noticer that starts with a `ksn` query and upgrades to a
- * `logs` query when the remote key state is ahead of local accepted state.
- *
- * Start condition:
- * - caller wants authoritative remote key state for one AID
- *
- * Completion condition:
- * - accepted local key state is at or beyond the remote `ksn.s`
- *
- * Emitted query shape:
- * - first `ksn` with `{ fn: "0", s: "0" }`
- * - later `logs` through `LogQuerier` if remote state is ahead
- */
-export class KeyStateNoticer {
-    constructor(pre, { signer, wits } = {}) {
-        Object.defineProperty(this, "pre", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "signer", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "wits", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "done", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "queried", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "logQuerier", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: null
-        });
-        this.pre = pre;
-        this.signer = signer;
-        this.wits = wits ? [...wits] : undefined;
-    }
-    observe(cue, coordinator) {
-        if (this.done || cue.kin !== "keyStateSaved" || cue.ksn.i !== this.pre) {
-            return;
-        }
-        const local = coordinator.hby.db.getKever(this.pre);
-        const remoteSn = parseHexOrdinal(cue.ksn.s);
-        if (!local || remoteSn === null) {
-            return;
-        }
-        if (local.sn < remoteSn) {
-            if (!this.logQuerier || this.logQuerier.targetSn < remoteSn) {
-                this.logQuerier = new LogQuerier(this.pre, remoteSn, {
-                    signer: this.signer,
-                    wits: this.wits,
-                });
-            }
-            this.logQuerier.tick(coordinator);
-            return;
-        }
-        this.done = true;
-    }
-    tick(coordinator) {
-        if (this.done) {
-            return;
-        }
-        if (!this.queried) {
-            coordinator.enqueue({
-                pre: this.pre,
-                route: "ksn",
-                q: { fn: "0", s: "0" },
-                signer: this.signer,
-                wits: this.wits,
-            });
-            this.queried = true;
-        }
-        if (this.logQuerier) {
-            this.logQuerier.tick(coordinator);
-            if (this.logQuerier.done) {
-                this.done = true;
-            }
-        }
-    }
-}
-/**
- * KERIpy-style log querier that waits until local accepted key state reaches a
- * target sequence number.
- *
- * Start condition:
- * - caller already knows the remote target sequence number
- *
- * Completion condition:
- * - local accepted key state reaches `targetSn`
- *
- * Emitted query shape:
- * - `logs` with `{ fn: "0", s: "0" }`
- */
-export class LogQuerier {
-    constructor(pre, targetSn, { signer, wits } = {}) {
-        Object.defineProperty(this, "pre", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "targetSn", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "signer", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "wits", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "done", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "queried", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        this.pre = pre;
-        this.targetSn = targetSn;
-        this.signer = signer;
-        this.wits = wits ? [...wits] : undefined;
-    }
-    observe(_cue, _coordinator) {
-        return;
-    }
-    tick(coordinator) {
-        if (this.done) {
-            return;
-        }
-        if (!this.queried) {
-            coordinator.enqueue({
-                pre: this.pre,
-                route: "logs",
-                q: { fn: "0", s: "0" },
-                signer: this.signer,
-                wits: this.wits,
-            });
-            this.queried = true;
-        }
-        const local = coordinator.hby.db.getKever(this.pre);
-        if (local && local.sn >= this.targetSn) {
-            this.done = true;
-        }
-    }
-}
-/**
- * Query helper that waits until local accepted key state reaches one sequence
- * number threshold.
- *
- * Start condition:
- * - caller wants logs replayed until local state reaches `targetSn`
- *
- * Completion condition:
- * - local accepted key state reaches `targetSn`
- *
- * Emitted query shape:
- * - `logs` with explicit `fn` and `s`
- */
-export class SeqNoQuerier {
-    constructor(pre, targetSn, { fn = 0, signer, wits, } = {}) {
-        Object.defineProperty(this, "pre", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "targetSn", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "fn", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "signer", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "wits", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "done", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "queried", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        this.pre = pre;
-        this.targetSn = targetSn;
-        this.fn = fn;
-        this.signer = signer;
-        this.wits = wits ? [...wits] : undefined;
-    }
-    observe(_cue, _coordinator) {
-        return;
-    }
-    tick(coordinator) {
-        if (this.done) {
-            return;
-        }
-        if (!this.queried) {
-            coordinator.enqueue({
-                pre: this.pre,
-                route: "logs",
-                q: {
-                    fn: encodeHexOrdinal(this.fn),
-                    s: encodeHexOrdinal(this.targetSn),
-                },
-                signer: this.signer,
-                wits: this.wits,
-            });
-            this.queried = true;
-        }
-        const local = coordinator.hby.db.getKever(this.pre);
-        if (local && local.sn >= this.targetSn) {
-            this.done = true;
-        }
-    }
-}
-/**
- * Query helper that waits until local state contains an anchored event seal.
- *
- * Start condition:
- * - caller needs proof of one anchored seal in the queried prefix's KEL
- *
- * Completion condition:
- * - local DB can resolve a sealing event for the requested anchor
- *
- * Emitted query shape:
- * - `logs` from `{ fn: "0", s: "0", a: anchor }`
- */
-export class AnchorQuerier {
-    constructor(pre, anchor, { signer, wits } = {}) {
-        Object.defineProperty(this, "pre", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "anchor", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "signer", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "wits", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "done", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "queried", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        this.pre = pre;
-        this.anchor = { i: anchor.i, s: anchor.s, d: anchor.d };
-        this.signer = signer;
-        this.wits = wits ? [...wits] : undefined;
-    }
-    observe(_cue, _coordinator) {
-        return;
-    }
-    tick(coordinator) {
-        if (this.done)
-            return;
-        if (coordinator.hby.db.fetchLastSealingEventByEventSeal(this.pre, this.anchor)) {
-            this.done = true;
-            return;
-        }
-        if (this.queried)
-            return;
-        // A retired witness may never learn the seal. Ask every current candidate once.
-        // With no endpoints, retain one ordinary request for deferred resolution.
-        const attesters = coordinator.attestersFor(this.pre, { signer: this.signer, wits: this.wits });
-        for (const src of attesters.length ? attesters : [undefined]) {
-            coordinator.enqueue({
-                pre: this.pre,
-                route: "logs",
-                q: { fn: "0", s: "0", a: { ...this.anchor } },
-                signer: this.signer,
-                src,
-                wits: this.wits,
-            });
-        }
-        this.queried = true;
-    }
-}
-/**
- * Resolve the actual transport URL for one query destination AID.
- *
- * Transport policy:
- * - explicit witness-targeted queries resolve directly from the witness AID's
- *   `locs.` replies because KERIpy witness inquiries do not depend on the
- *   queried controller advertising witness end roles
- * - prefer direct controller/agent/witness URLs when the chosen destination
- *   matches an advertised end role
- * - in mailbox-only topologies, allow queries addressed to the controller AID
- *   to ride the first mailbox endpoint URL
- */
-function resolveQueryDestinationUrl(hab, queriedPre, destination, { explicitWitness = false, } = {}) {
-    if (explicitWitness) {
-        const urls = hab.fetchUrls(destination);
-        return urls[Schemes.https] ?? urls[Schemes.http] ?? urls[Schemes.tcp] ?? null;
-    }
-    const ends = hab.endsFor(queriedPre);
-    for (const role of [Roles.controller, Roles.agent, Roles.witness]) {
-        const endpoint = flattenRoleUrls(ends[role]).find((entry) => entry.eid === destination);
-        if (endpoint) {
-            return endpoint.url;
-        }
-    }
-    if (destination === queriedPre) {
-        return flattenRoleUrls(ends[Roles.mailbox])[0]?.url ?? null;
-    }
-    return null;
-}
-/**
- * Runtime query side-effect owner.
- *
- * Responsibilities:
- * - turn incomplete portable `query` cues into honest outbound `qry` wire
- *   packets when a local habitat and remote attester can be resolved
- * - host KERIpy-style query continuations such as `KeyStateNoticer`
- */
-export class QueryCoordinator {
-    /** Inspect deferred work without exposing queue mutation outside its owner. */
-    get pending() {
-        return this.requests;
-    }
-    constructor(hby, { reactor, services = defaultRuntimeServices, hab = null }) {
-        Object.defineProperty(this, "hby", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "reactor", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "services", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "deliveries", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new Deck()
-        });
-        Object.defineProperty(this, "delivering", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "output", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "outputJoined", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "requests", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new Deck()
-        });
-        Object.defineProperty(this, "closed", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: false
-        });
-        Object.defineProperty(this, "hab", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "continuations", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        this.hby = hby;
-        this.reactor = reactor;
-        this.services = services;
-        this.hab = hab;
-    }
-    /** Select the local habitat used when queued requests have no explicit signer. */
-    configure({ hab = null } = {}) {
-        this.hab = hab;
-    }
-    /** Register one persistent key-state continuation. */
-    watchKeyState(pre, options = {}) {
-        this.compactContinuations();
-        const noticer = new KeyStateNoticer(pre, options);
-        this.continuations.push(noticer);
-        return noticer;
-    }
-    /** Register one persistent logs-until-sequence continuation. */
-    watchSeqNo(pre, sn, options = {}) {
-        this.compactContinuations();
-        const querier = new SeqNoQuerier(pre, sn, options);
-        this.continuations.push(querier);
-        return querier;
-    }
-    /** Register one persistent logs-until-anchor continuation. */
-    watchAnchor(pre, anchor, options = {}) {
-        this.compactContinuations();
-        const querier = new AnchorQuerier(pre, anchor, options);
-        this.continuations.push(querier);
-        return querier;
-    }
-    /** Return true while continuations or unsent queries are still pending. */
-    hasPendingWork() {
-        this.compactContinuations();
-        return !this.requests.empty || this.continuations.length > 0 || this.hasPendingDelivery;
-    }
-    /**
-     * Queue for later resolution/delivery: copy the top level/witness list only.
-     * Nested query values remain borrowed immutable data until consumption or joined close retires the record.
-     */
-    enqueue(request) {
-        if (this.closed)
-            throw new Error("Query coordinator is closed");
-        this.requests.append({
-            ...request,
-            ...copyQuery(request),
-            wits: request.wits ? [...request.wits] : undefined,
-        });
-    }
-    /** Prepare routed query cues before source removal, or retain unresolved requests for a later turn. */
-    enqueueCue(cue, hab) {
-        if (this.closed)
-            throw new Error("Query coordinator is closed");
-        if (!cue.route || !cue.pre)
-            return;
-        const { kin: _, ...request } = cue;
-        const selected = { ...request, signer: request.signer ?? hab?.pre };
-        if (!this.prepareRequest(selected))
-            this.enqueue(selected);
-    }
-    /** Include live query I/O and unsent packets in convergence. */
-    get hasPendingDelivery() {
-        return this.delivering || !this.deliveries.empty;
-    }
-    /** Join each real response before removing its captured packet; failed/cancelled sends retain exact bytes. */
-    deliverOnce() {
-        // deno-lint-ignore no-this-alias -- The operation owns one finite output pass.
-        const self = this;
-        return call(function* () {
-            if (self.delivering || self.closed)
-                return;
-            self.delivering = true;
-            const active = self.output = new AbortController();
-            let complete;
-            self.outputJoined = new Promise((resolve) => complete = resolve);
-            yield* resource(function* (provide) {
-                try {
-                    yield* provide();
-                }
-                finally {
-                    self.delivering = false;
-                    self.output = undefined;
-                    self.outputJoined = undefined;
-                    complete();
-                }
-            });
-            const count = self.deliveries.length;
-            for (let index = 0; index < count && !self.closed; index++) {
-                const packet = self.deliveries.peekHead();
-                if (!packet)
-                    break;
-                active.signal.throwIfAborted();
-                yield* call(() => self.postQueryMessage(packet, active));
-                active.signal.throwIfAborted();
-                self.deliveries.pull();
-            }
-        });
-    }
-    /** One delivery scope owns upload frames and all response readers through completion or cancellation. */
-    *postQueryMessage(delivery, controller) {
-        const reactor = this.reactor, services = this.services;
-        if (new URL(delivery.url).protocol === "tcp:") {
-            yield* converseCesrTcp(delivery.url, delivery.body, {
-                clock: services.clock,
-                signal: controller.signal,
-                replies: { reactor, local: true },
-            });
-            return;
-        }
-        yield* postCesr(delivery.url, (signal) => chunkBytes(delivery.body, { signal }), {
-            bodyMode: delivery.bodyMode,
-            destination: delivery.destination,
-            services,
-            signal: controller.signal,
-        }, function* (response) {
-            if (response.headers.get("Content-Type")?.toLowerCase().startsWith("text/event-stream")) {
-                yield* consumeMailboxSse(response, new AbortController(), function* (message) {
-                    yield* reactor.process((signal) => chunkBytes(message.msg, { signal }), {
-                        signal: controller.signal,
-                    });
-                }, { idleTimeoutMs: 500, maxDurationMs: 5_000, services, signal: controller.signal });
-            }
-            else {
-                yield* reactor.process((signal) => streamBytes(response.body, { signal }), {
-                    signal: controller.signal,
-                });
-            }
-        });
-    }
-    /** Sign and queue one initial pass; unresolved requests rotate and appended work waits for the next turn. */
-    *processPending() {
-        if (this.closed)
-            return;
-        this.tickContinuations();
-        const count = this.requests.length;
-        for (let index = 0; index < count; index++) {
-            const request = this.requests.peekHead();
-            if (!request)
-                break;
-            if (this.prepareRequest(request))
-                this.requests.pull();
-            else {
-                this.requests.pull();
-                this.requests.append(request);
-            }
-        }
-        this.tickContinuations();
-    }
-    /** Abort and join real output before clearing packets and correspondence. */
-    *close() {
-        this.closed = true;
-        this.output?.abort();
-        if (this.outputJoined)
-            yield* call(() => this.outputJoined);
-        this.requests.clear();
-        this.deliveries.clear();
-        this.continuations = [];
-    }
-    /** Continuous background query worker for long-lived runtime hosts. */
-    *queryDo() {
-        while (true) {
-            yield* this.processPending();
-            yield* runtimeTurn();
-        }
-    }
-    /**
-     * Resolve the habitat that is allowed to sign the outbound query.
-     *
-     * Resolution order:
-     * - explicitly selected local signer (unavailable means unresolved, never fallback)
-     * - runtime-configured habitat
-     * - sole local habitat
-     */
-    configuredHab(signer) {
-        return signer === undefined ? this.hab ?? soleHab(this.hby) : this.hby.habs.get(signer) ?? null;
-    }
-    /** Observe retained cue evidence after its immediate destination transfer. */
-    observeCue(cue) {
-        for (const continuation of this.continuations)
-            continuation.observe(cue, this);
-        this.compactContinuations();
-    }
-    tickContinuations() {
-        for (const continuation of this.continuations)
-            continuation.tick(this);
-        this.compactContinuations();
-    }
-    compactContinuations() {
-        this.continuations = this.continuations.filter((continuation) => !continuation.done);
-    }
-    /** Capture the selected signer's query, introduction and endpoint before retiring its source request. */
-    prepareRequest(request) {
-        const hab = this.configuredHab(request.signer);
-        if (!hab)
-            return false;
-        const destination = request.src
-            ?? this.attestersFor(request.pre, { signer: hab.pre, wits: request.wits })[0];
-        if (!destination)
-            return false;
-        const url = resolveQueryDestinationUrl(hab, request.pre, destination, {
-            explicitWitness: request.wits?.includes(destination) ?? false,
-        });
-        if (!url)
-            throw new ValidationError(`No endpoint URL found for query destination ${destination}.`);
-        const message = hab.query(request.pre, destination, copyQuery(request));
-        const intro = introduce(hab, destination);
-        this.deliveries.push({ url, body: concatBytes(intro, message), bodyMode: this.hby.cesrBodyMode, destination });
-        return true;
-    }
-    /** Return eligible attester IDs in role priority; explicit witness overrides retain caller order. */
-    attestersFor(pre, { signer, wits } = {}) {
-        if (wits && wits.length > 0) {
-            // Explicit watcher/witness overrides outrank endpoint-role lookup.
-            return [...wits];
-        }
-        const hab = this.configuredHab(signer);
-        if (!hab)
-            return [];
-        const ends = hab.endsFor(pre);
-        for (const role of QUERY_ROLE_PRIORITY) {
-            const roleEnds = ends[role];
-            if (!roleEnds) {
-                continue;
-            }
-            // Keep stable candidate order; ordinary requests still select the first ID.
-            const eids = Object.keys(roleEnds).sort();
-            if (eids.length > 0)
-                return eids;
-        }
-        if ((ends[Roles.mailbox] && Object.keys(ends[Roles.mailbox]).length > 0)
-            && this.hby.db.getKever(pre)) {
-            // Mailbox-only topologies still query the controller AID itself; the
-            // mailbox role affects delivery transport, not the attester identity.
-            return [pre];
-        }
-        return [];
-    }
-}