primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/function-log-tail.js

@@ -0,0 +1,262 @@
+/**
+ * The mark of a tail that has seen no row yet — CR3287-016.
+ *
+ * A ULID is 26 characters of Crockford base32, so this single character sorts
+ * below every one of them and above nothing: `idOf(row) <= EMPTY_TAIL_MARK`
+ * is false for every row, which is exactly "everything is new". It is a
+ * non-empty string, which is what keeps `followLoop` from reading it as an
+ * uninitialized tail.
+ */
+export const EMPTY_TAIL_MARK = "0";
+/**
+ * How far below the mark the walk still looks — #3448 D3448-013.
+ *
+ * #3448 mints an invocation's id BEFORE the run and writes its record at
+ * SETTLEMENT, so a record can be inserted BELOW a mark set while it was still
+ * running: A starts, B starts and settles and is emitted, A settles. Under
+ * `stop at id <= mark` A is never shown — and A is the slow, failed and
+ * timed-out invocation an operator tails for (D3448-SO-003).
+ *
+ * The bound is the longest a REQUEST record can lag its own id: the platform's
+ * 30 s request ceiling plus the token's skew grace, rounded up to a minute.
+ * Nothing below it can still be in flight, so a row older than the window is
+ * already settled and was already emitted or already skipped.
+ *
+ * A task run's slice records carry settle-time ids of their own and are
+ * unaffected — they were never out of order.
+ */
+export const TAIL_OVERLAP_MS = 60_000;
+/** Crockford base32, the alphabet a ULID's timestamp is written in. */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * The id the walk stops below, given the mark.
+ *
+ * A mark this cannot read — the empty sentinel, or a fixture's short id — is
+ * its own bound: there is no instant to widen from, so the walk stops exactly
+ * where it stopped before this change, and #3287's own fixtures are unmoved.
+ */
+export function tailLowerBound(mark) {
+    if (mark.length !== 26)
+        return mark;
+    let at = 0;
+    for (let index = 0; index < 10; index += 1) {
+        const digit = CROCKFORD.indexOf(mark[index].toUpperCase());
+        if (digit < 0)
+            return mark;
+        at = at * 32 + digit;
+    }
+    let remaining = Math.max(0, at - TAIL_OVERLAP_MS);
+    let encoded = "";
+    for (let index = 0; index < 10; index += 1) {
+        encoded = CROCKFORD[remaining % 32] + encoded;
+        remaining = Math.floor(remaining / 32);
+    }
+    return `${encoded}${"0".repeat(16)}`;
+}
+/**
+ * A bare mark stays a bare mark — the common case, and what an operator sees
+ * in a debug print. Anything more is JSON, which a ULID cannot start with, so
+ * the two are told apart by their first character.
+ */
+export function encodeTailCheckpoint(checkpoint) {
+    if (checkpoint.cursor === undefined &&
+        checkpoint.seen.length === 0 &&
+        checkpoint.floor === undefined &&
+        checkpoint.mark.length > 0) {
+        return checkpoint.mark;
+    }
+    return JSON.stringify(checkpoint);
+}
+/**
+ * A pre-#3448 checkpoint has no `seen` key and reads as an empty set, which is
+ * the honest answer: the tail that wrote it never looked below its mark, so it
+ * emitted nothing inside the window it needs to remember.
+ */
+export function decodeTailCheckpoint(token) {
+    if (token.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(token);
+            if (parsed && typeof parsed.mark === "string") {
+                const seen = Array.isArray(parsed.seen)
+                    ? parsed.seen.filter((id) => typeof id === "string")
+                    : [];
+                const floor = typeof parsed.floor === "string" ? { floor: parsed.floor } : {};
+                return typeof parsed.cursor === "string"
+                    ? { mark: parsed.mark, cursor: parsed.cursor, seen, ...floor }
+                    : { mark: parsed.mark, seen, ...floor };
+            }
+        }
+        catch {
+            // Not ours; fall through and treat it as a mark.
+        }
+    }
+    return { mark: token.length > 0 ? token : EMPTY_TAIL_MARK, seen: [] };
+}
+export function buildLogFollowSource(fetchPage, options) {
+    const { idOf, maxPagesPerTick } = options;
+    // The backlog of a walk in progress: rows newer than the mark, newest-first,
+    // collected but not yet emitted because the walk has not met the mark. Only
+    // meaningful for the mark it was collected against.
+    let pending = [];
+    let pendingMark = null;
+    return {
+        fetchAfter: async (resumeAfter) => {
+            // The bootstrap poll establishes the mark and emits nothing: a tail
+            // shows what happens FROM NOW. An empty listing is a mark too.
+            if (resumeAfter === undefined) {
+                let page = await fetchPage({});
+                const newest = page.items.length ? idOf(page.items[0]) : EMPTY_TAIL_MARK;
+                pending = [];
+                pendingMark = null;
+                // Every row that ALREADY EXISTS inside the new mark's overlap window
+                // is baseline: the tail shows what happens from now, so none of them
+                // may be re-emitted when the walk revisits the window on the next poll
+                // (#3448). One page of them is not the window — a function recording
+                // faster than a page a minute has more — so the baseline walks back
+                // through the window the same bounded way the tail itself does
+                // (CR3448-003). Reading only the first page here is what made
+                // `--follow` open with up to a minute of history on a busy function.
+                const bound = tailLowerBound(newest);
+                const seen = [];
+                let floor;
+                for (let pages = 1;; pages += 1) {
+                    let reachedBound = false;
+                    let oldest = null;
+                    for (const row of page.items ?? []) {
+                        const id = idOf(row);
+                        if (id <= bound) {
+                            reachedBound = true;
+                            break;
+                        }
+                        seen.push(id);
+                        oldest = id;
+                    }
+                    if (reachedBound || !page.nextCursor)
+                        break;
+                    if (pages >= maxPagesPerTick) {
+                        // The budget ran out with the window still open. The walk stops at
+                        // the oldest row the baseline saw rather than at the window's
+                        // edge: below it are rows this tail never recorded, and walking
+                        // over them would print them as new.
+                        floor = oldest ?? undefined;
+                        break;
+                    }
+                    page = await fetchPage({ cursor: page.nextCursor });
+                }
+                return {
+                    items: [],
+                    hasMore: false,
+                    resumeAfter: encodeTailCheckpoint({
+                        mark: newest,
+                        seen,
+                        ...(floor ? { floor } : {}),
+                    }),
+                };
+            }
+            const checkpoint = decodeTailCheckpoint(resumeAfter);
+            const { mark } = checkpoint;
+            // #3448 — the walk runs back to here, not to the mark, so a record
+            // inserted below the mark while its invocation was still running is
+            // still reached. `seen` is what keeps it from being printed twice, and
+            // the baseline's floor — set only when the bootstrap could not read the
+            // whole window — is what keeps it from reaching rows no baseline saw.
+            const windowBound = tailLowerBound(mark);
+            const lowerBound = checkpoint.floor && checkpoint.floor > windowBound
+                ? checkpoint.floor
+                : windowBound;
+            const seen = new Set(checkpoint.seen);
+            // Resume the walk only if the backlog held here is the one this
+            // checkpoint describes; otherwise start from the top.
+            let cursor;
+            if (checkpoint.cursor !== undefined && pendingMark === mark) {
+                cursor = checkpoint.cursor;
+            }
+            else {
+                pending = [];
+                pendingMark = mark;
+            }
+            // This call's rows, merged into the backlog only once the call has
+            // finished: a pager that throws mid-walk leaves the checkpoint where it
+            // was, and the retry re-reads the same pages.
+            const collected = [];
+            let reachedMark = false;
+            let pages = 0;
+            while (pages < maxPagesPerTick) {
+                const page = await fetchPage(cursor ? { cursor } : {});
+                for (const row of page.items ?? []) {
+                    const id = idOf(row);
+                    // At or below the bound is the end of the walk. For a mark this
+                    // cannot read the bound IS the mark, so the stop is byte for byte
+                    // the one #3287 wrote and its fixtures are unmoved.
+                    if (id <= lowerBound) {
+                        reachedMark = true;
+                        break;
+                    }
+                    // Inside the overlap window: new only if this tail has not already
+                    // printed it. Above the mark it always is.
+                    if (id > mark || !seen.has(id))
+                        collected.push(row);
+                }
+                pages += 1;
+                // No next page is the end of the listing, which is as far back as a
+                // walk can go: the mark's row has aged out, and everything is new.
+                if (reachedMark || !page.nextCursor) {
+                    reachedMark = true;
+                    break;
+                }
+                cursor = page.nextCursor;
+            }
+            if (!reachedMark) {
+                // Budget spent short of the mark: keep the backlog, carry the cursor,
+                // and say there is more — the loop calls again rather than waiting a
+                // whole tick, and nothing is emitted out of order or dropped.
+                pending.push(...collected);
+                return {
+                    items: [],
+                    hasMore: true,
+                    resumeAfter: encodeTailCheckpoint({
+                        mark,
+                        cursor,
+                        seen: [...seen],
+                        ...(checkpoint.floor ? { floor: checkpoint.floor } : {}),
+                    }),
+                };
+            }
+            // The backlog arrived newest-first; a tail prints oldest-first.
+            const ascending = [...pending, ...collected].reverse();
+            pending = [];
+            pendingMark = null;
+            // The mark only ever moves FORWARD (#3448). A poll that emitted nothing
+            // but a late row inserted below the mark would otherwise walk the mark
+            // backwards and re-read the same window for ever.
+            let next = mark;
+            for (const row of ascending) {
+                const id = idOf(row);
+                if (id > next)
+                    next = id;
+                seen.add(id);
+            }
+            // Prune to the new window: a row older than the overlap is settled, so
+            // the walk will never reach it again and remembering it costs storage
+            // in the checkpoint for nothing.
+            const nextBound = tailLowerBound(next);
+            // The floor outlives the mark only while it is still the tighter of the
+            // two: once the window has slid past it, it bounds nothing.
+            const nextFloor = checkpoint.floor && checkpoint.floor > nextBound ? checkpoint.floor : undefined;
+            // Strictly above the bound: a row AT it stops the walk, so remembering
+            // it would be state the walk can never consult.
+            const nextLowerBound = nextFloor ?? nextBound;
+            const remembered = [...seen].filter((id) => id > nextLowerBound).sort();
+            return {
+                items: ascending,
+                hasMore: false,
+                resumeAfter: encodeTailCheckpoint({
+                    mark: next,
+                    seen: remembered,
+                    ...(nextFloor ? { floor: nextFloor } : {}),
+                }),
+            };
+        },
+    };
+}
+//# sourceMappingURL=function-log-tail.js.map

package/dist/src/lib/function-log-tail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-log-tail.js","sourceRoot":"","sources":["../../../src/lib/function-log-tail.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/function-run.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Running a function from the CLI — the decisions, without the I/O (#3448,
+ * project `server-functions` phase 4).
+ *
+ * `functions invoke`, `functions start` and `functions runs wait` are three
+ * verbs over one route, and almost everything about them is a rule rather than
+ * a request: which flags may appear together, what `--input` means, which
+ * identity the call runs under, how long to wait between polls, which exit code
+ * a settled run earns, and what line to print beside each id so an operator
+ * knows the next command. Every one of those is decidable with no server, so
+ * every one of them lives here, where `cli-unit-tests` can pin it and a
+ * rejected checkpoint stays diagnosable (#3187's lesson).
+ */
+/** The verbs that run a function, for the messages that name them. */
+export type RunVerb = "invoke" | "start";
+/** Exit codes, one place, because three verbs share them. */
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+/** The wait's budget was spent with the run still in flight. */
+export declare const EXIT_TIMED_OUT = 124;
+/** Ctrl-C — the workflows group's convention (`workflows.ts`). */
+export declare const EXIT_INTERRUPTED = 130;
+export interface RunFlags {
+    input?: string;
+    user?: string;
+    as?: string;
+    timeout?: string | number;
+    contextDocId?: string;
+    runKey?: string;
+    wait?: boolean;
+    json?: boolean;
+}
+export type FlagResolution = {
+    ok: true;
+    /** `{}` when `--input` was absent; the parsed value otherwise. */
+    input: unknown;
+    identity: IdentityPlan;
+    /** Seconds, or null when the operator did not ask for a budget. */
+    timeoutSeconds: number | null;
+} | {
+    ok: false;
+    error: string;
+};
+/** Who the invocation runs as — D3448-009. */
+export type IdentityPlan = {
+    kind: "self";
+} | {
+    kind: "user";
+    userId: string;
+} | {
+    kind: "system";
+};
+/**
+ * Read the flags, and refuse BEFORE any request is made.
+ *
+ * That ordering is the point (D3448-010): an operator who typed a malformed
+ * `--input` or two identities has made a mistake the platform should never see
+ * — and a refusal that arrived after the call would be a refusal for something
+ * that had already run.
+ */
+export declare function resolveRunFlags(flags: RunFlags): FlagResolution;
+/** The two runtimes the platform runs a function under (#3482). */
+export type FunctionRuntime = "request" | "task";
+/**
+ * The runtime a function run used, read from the run row — #3482, C-6.
+ *
+ * `WorkflowRun.executionMode` is the runtime under the old word, and #3482
+ * does not rename a stored column (D3482-009; phase 7 owns the rename), so the
+ * mapping lives here, once, and every surface that says "runtime" says it the
+ * same way. `sync` is the request runtime — a webhook delivery, a
+ * `workflow.call` leaf — and `durable` is the task runtime.
+ *
+ * ABSENT means the task runtime, not "unknown": every writer of a durable row
+ * has written `durable` since #3186, and the rows that predate the column are
+ * durable runs. A row that says something else entirely is not a runtime this
+ * platform has, and answering null is how a reader learns that rather than
+ * being told a word that was never true.
+ */
+export declare function runtimeForExecutionMode(executionMode: unknown): FunctionRuntime | null;
+/**
+ * The RUNTIME cell of one `functions runs` row.
+ *
+ * Blank rather than guessed for a row this reader cannot place: `runs` pages
+ * one function's own runs, but the same shape reaches the CLI from surfaces
+ * that carry DSL rows too, and printing `task` for one would be a word about
+ * something that has no runtime at all.
+ */
+export declare function runRuntimeCell(run: {
+    executionMode?: unknown;
+} | null | undefined): string;
+/**
+ * The two slice cells of one `functions runs` row — REFRESHES and RESETS.
+ *
+ * One rule for both, because they are two facts about the same record and the
+ * distinction that matters is the same for each: a row with NO slice record
+ * gets a BLANK cell, and a record that carries no count gets `0`.
+ *
+ *   - blank means "there is no record" — a request invocation opens no lease,
+ *     and neither did any run that predates the record's own child;
+ *   - `0` means "the record says nothing happened", which for #3566 is the
+ *     answer an operator needs: a fabricated zero on a row with no record would
+ *     read as "the platform never reset this run", and the row cannot know that.
+ *
+ * A value that is not a whole number reads `0` rather than reaching the table:
+ * the cell is a count, and printing `NaN` or `two` in a column of numbers
+ * teaches an operator nothing.
+ */
+export declare function runSliceCells(run: {
+    slice?: {
+        refreshCount?: unknown;
+        resets?: unknown;
+    } | null;
+} | null | undefined): {
+    refreshes: string;
+    resets: string;
+};
+/** The JS client's schedule: 400 ms doubling to a 5 s ceiling. */
+export declare const WAIT_INITIAL_DELAY_MS = 400;
+export declare const WAIT_MAX_DELAY_MS = 5000;
+/** 15 minutes, the JS client's default. */
+export declare const WAIT_DEFAULT_TIMEOUT_SECONDS = 900;
+/**
+ * The delay before poll `attempt` (0-based).
+ *
+ * Pure and pinned, because a backoff that silently stopped backing off is a
+ * poll storm nobody notices until a long run is being asked 150 times a
+ * minute.
+ */
+export declare function waitDelayMs(attempt: number): number;
+/**
+ * A settled run's exit code — D3448-010.
+ *
+ * `completed` is 0 and everything else an operator can act on is 1. An
+ * in-flight status is null: the wait has not finished, and turning "still
+ * running" into an exit code is how a script comes to believe a run failed
+ * because it was slow.
+ */
+export declare function exitCodeForRunStatus(status: string | null | undefined): number | null;
+/** A request invocation's exit code: only `completed` is success. */
+export declare function exitCodeForInvokeStatus(status: string | null | undefined): number;
+/** One printed line: a label, an id, and the commands that take it. */
+export interface IdLines {
+    label: string;
+    value: string;
+    commands: string[];
+}
+/**
+ * Every id a verb prints is followed by the diagnostics command that takes it
+ * — the issue's own requirement, and one pure function so it is pinned.
+ *
+ * An id with no next step is an id an operator has to go and look up how to
+ * use, which is the thing this issue exists to remove.
+ */
+export declare function invokeIdLines(args: {
+    functionId: string;
+    invocationId?: string | null;
+}): IdLines[];
+export declare function startIdLines(args: {
+    functionId: string;
+    runId: string;
+}): IdLines[];
+/** The line a wait prints when it gives up, or is interrupted. */
+export declare function resumeCommand(functionId: string, runId: string): string;
+/** Render one `IdLines` as the two-or-more lines an operator reads. */
+export declare function renderIdLines(lines: IdLines[]): string[];
+/** How the identity is reported, so an operator knows who ran it. */
+export declare function describeIdentity(identity: {
+    kind: "self" | "user" | "system";
+    userId?: string | null;
+    appRole?: string | null;
+    byUserId?: string | null;
+}): string;
+/**
+ * How many EMPTY pages carrying a cursor the CLI follows before it renders.
+ *
+ * D3448-SO-006's CLI half. A filtered page holding only other runs' records
+ * comes back empty WITH a cursor, which is an intermediate page and not the
+ * end; returning on it — as `functions logs` did — reports "no logs" for a run
+ * whose records are one page further down. The server's bounded scan makes
+ * that rare; this makes it impossible to read as the end.
+ */
+export declare const MAX_AUTO_CONTINUE_PAGES = 5;
+export type PageContinuation = {
+    action: "render";
+}
+/** Follow `cursor` and try again. */
+ | {
+    action: "continue";
+    cursor: string;
+}
+/** Nothing found and the budget is spent: the empty state PLUS the cursor. */
+ | {
+    action: "exhausted";
+    cursor: string;
+};
+/**
+ * What to do with a page that came back holding nothing.
+ *
+ * A page with rows is rendered. An empty page with NO cursor is the end and is
+ * rendered too (the empty state). An empty page WITH a cursor is intermediate.
+ */
+export declare function decidePageContinuation(page: {
+    items?: unknown[];
+    nextCursor?: string | null;
+}, pagesFollowed: number): PageContinuation;
+/**
+ * `--invocation` names ONE record, so every flag that shapes a LISTING is a
+ * contradiction beside it, and `--run` is a filter a tail cannot honour (the
+ * tail walks the whole index; a run's records are a bounded set that ends).
+ */
+export declare function logsFlagConflict(flags: {
+    invocation?: string;
+    run?: string;
+    follow?: boolean;
+    cursor?: string;
+    limit?: unknown;
+}): string | null;
+/** Ten minutes — long enough for the platform's own 30 s ceiling and no more. */
+export declare const USER_TOKEN_TTL = "10m";
+/** The name the minted token carries, so an operator can find it if it leaks. */
+export declare function userTokenName(verb: RunVerb, functionKey: string, at?: Date): string;
+export interface MintedToken {
+    token: string;
+    tokenId: string;
+}
+export interface MintedTokenEffects {
+    mint: () => Promise<MintedToken>;
+    revoke: (tokenId: string) => Promise<void>;
+    warn: (message: string) => void;
+    /**
+     * Install a handler for the interrupt signals, and hand back a remover.
+     *
+     * Injected so the Ctrl-C path is decidable with no process to signal — the
+     * mistake CR3448-001 caught was proving it with a rejection, which is a
+     * DIFFERENT path: an interrupt reaches an unhandled process as termination,
+     * not as a throw.
+     */
+    onInterrupt?: (handler: () => void) => () => void;
+    /** How the process ends once the credential is gone. */
+    exit?: (code: number) => void;
+}
+/**
+ * Mint, use, revoke — and revoke on EVERY exit path.
+ *
+ * The token is a real credential for ANOTHER USER, live for ten minutes, so
+ * "every exit path" has to include the one an operator actually takes when a
+ * call is slower than they expected: Ctrl-C. A `finally` alone does not cover
+ * it — with no handler installed, Node's default terminates the process and no
+ * `finally` in it ever runs (CR3448-001) — so the wrapper handles the signal
+ * itself, revokes, and only then exits 130.
+ *
+ * A failed revoke does NOT change the exit code — the invocation happened and
+ * its outcome is the answer — but it names the token and the command that
+ * revokes it, because an un-revoked credential an operator does not know about
+ * is worse than a warning they do (edge 32).
+ *
+ * The VALUE is never returned to the caller and never printed: `use` receives
+ * it, and nothing else does.
+ */
+export declare function withMintedToken<T>(effects: MintedTokenEffects, use: (token: string) => Promise<T>): Promise<T>;
+/** What the server said, and how an operator should read it. */
+export interface RefusalAnswer {
+    httpStatus: number;
+    retryAfterSeconds: number | null;
+    body: any;
+}
+export interface RefusalLines {
+    /** The headline, on stderr. */
+    message: string;
+    /** Label/value pairs printed under it. */
+    fields: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Schema-validation details, one per line. */
+    details: string[];
+}
+/**
+ * Turn a refusal envelope into the lines an operator reads — #3448 D3448-010.
+ *
+ * Pure, because it carries the fact that makes handing the envelope back
+ * worth anything instead of throwing: a 429's `Retry-After`, which the server
+ * already worked out and which would be re-derived badly from an exception
+ * message.
+ *
+ * #3482 — there is no "Version mode" line any more. It named the mode a
+ * refused call's version was locked to, and no version is locked to anything.
+ */
+export declare function refusalLines(answer: RefusalAnswer): RefusalLines;