@catalyst-cloud/cli 0.14.6 → 0.14.8

package/dist/events-cloud-tail.js

@@ -0,0 +1,146 @@
+import { cloudEvents } from "./events-cloud.js";
+// A lease causation names its ticket: `lease:<ticket>/<phase>#<nonce>` (event-index/fields.ts).
+const CAUSED_BY_LEASE = /^lease:([^/]+)\/[^#]+#/;
+// The index stores at most this many UTF-8 bytes of ticket; a longer value is not indexed.
+const MAX_INDEXED_TICKET_BYTES = 64;
+function boundedTicket(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    return new TextEncoder().encode(value).length > MAX_INDEXED_TICKET_BYTES ? null : value;
+}
+/** The ticket an event is about, resolved exactly as the cloud's event index resolves it
+ *  (catalyst-cloud apps/mirror/src/event-index/fields.ts): a `ticket` entity's id, then
+ *  `payload.ticket`, then the lease that caused it, each at most 64 bytes. A body-unavailable stub
+ *  carries the index's own `ticket`. Nothing else counts, so `--from-cache` matches exactly what the
+ *  cloud path returns. */
+export function eventTicket(event) {
+    const e = event;
+    if (e.bodyUnavailable === true)
+        return boundedTicket(e.ticket);
+    const fromEntity = e.entity?.type === "ticket" ? boundedTicket(e.entity.id) : null;
+    const payload = e.payload && typeof e.payload === "object" ? e.payload : undefined;
+    const lease = typeof e.causationId === "string" ? CAUSED_BY_LEASE.exec(e.causationId) : null;
+    return fromEntity ?? boundedTicket(payload?.ticket) ?? boundedTicket(lease?.[1]);
+}
+/** The type and ticket filter, the same on the cloud and the local cache paths. */
+export function eventMatches(filter) {
+    const ticket = filter.ticket?.toUpperCase();
+    return (event) => (!filter.type || event.type === filter.type) &&
+        (!ticket || eventTicket(event)?.toUpperCase() === ticket);
+}
+function pipeClosed(error) {
+    const code = error?.code;
+    return code === "EPIPE" || code === "ERR_STREAM_DESTROYED";
+}
+// Resolves once the line has left this process, so a consumer sees it before the next is read.
+function writeLine(out, line, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return resolve();
+        const abort = () => resolve();
+        signal.addEventListener("abort", abort, { once: true });
+        const settle = (error) => {
+            signal.removeEventListener("abort", abort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        try {
+            out.write(line, (error) => settle(error));
+        }
+        catch (error) {
+            settle(error);
+        }
+    });
+}
+/** Print every matching cloud event as one NDJSON line until aborted, matched, or the pipe closes. */
+export async function tailCloudEvents(ctx, options, deps = {}) {
+    const { out } = options;
+    const filter = options.filter ?? {};
+    const filtered = eventMatches(filter);
+    const matches = (event) => filtered(event) && (options.where?.(event) ?? true);
+    const reader = new AbortController();
+    const stop = () => reader.abort(options.signal.reason);
+    if (options.signal.aborted)
+        stop();
+    else
+        options.signal.addEventListener("abort", stop, { once: true });
+    let closed = false;
+    let failure;
+    const broken = (error) => {
+        if (pipeClosed(error))
+            closed = true;
+        else
+            failure ??= error;
+        reader.abort(error);
+    };
+    out.on("error", broken);
+    let cursor = options.after;
+    let written = 0;
+    let matched;
+    // The server narrows what it sends when it can; every event is still matched here.
+    const serverFilter = {
+        ...(filter.type ? { type: filter.type } : {}),
+        ...(filter.ticket ? { ticket: filter.ticket.toUpperCase() } : {}),
+    };
+    try {
+        const events = (deps.events ?? cloudEvents)(ctx, { after: options.after, filter: serverFilter, signal: reader.signal }, deps);
+        for await (const event of events) {
+            if (reader.signal.aborted)
+                break;
+            // A reconnect may replay what was already printed; the sequence is the identity.
+            if (cursor !== undefined && event.sequence <= cursor)
+                continue;
+            if (matches(event)) {
+                await writeLine(out, `${JSON.stringify(event)}\n`, reader.signal);
+                // Aborted mid-write: the line was not confirmed, so it does not move the cursor.
+                if (reader.signal.aborted)
+                    break;
+                written += 1;
+                cursor = event.sequence;
+                if (options.once) {
+                    matched = event;
+                    break;
+                }
+            }
+            else
+                cursor = event.sequence;
+        }
+    }
+    catch (error) {
+        if (pipeClosed(error))
+            closed = true;
+        else if (!reader.signal.aborted)
+            failure ??= error;
+    }
+    finally {
+        options.signal.removeEventListener("abort", stop);
+        reader.abort();
+        // After EPIPE the stream can still emit its error; the listener stays so that cannot crash.
+        if (!closed)
+            out.off("error", broken);
+    }
+    if (failure !== undefined)
+        throw failure;
+    if (matched)
+        return { outcome: "matched", cursor, written, event: matched };
+    if (closed)
+        return { outcome: "closed", cursor, written };
+    return { outcome: options.signal.aborted ? "aborted" : "ended", cursor, written };
+}
+/** Print the first matching cloud event and stop, or report a timeout with nothing printed. */
+export async function waitForCloudEvent(ctx, options, deps = {}) {
+    const timer = new AbortController();
+    const timeout = setTimeout(() => timer.abort(new Error("event wait timed out")), options.timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timer.signal]) : timer.signal;
+    try {
+        const result = await tailCloudEvents(ctx, { after: options.after, filter: options.filter, out: options.out, signal, where: options.predicate, once: true }, deps);
+        if (result.outcome === "aborted" && timer.signal.aborted && !options.signal?.aborted)
+            return { ...result, outcome: "timeout" };
+        return result;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}