@zapier/zapier-sdk-cli 0.44.1 → 0.45.0

package/dist/src/utils/triggerDrain.js

@@ -0,0 +1,351 @@
+/**
+ * Shared CLI helpers for the `drain-trigger-inbox` and
+ * `watch-trigger-inbox` commands. Both wrap the eager SDK callback API
+ * and dispatch on the same flag set: interactive default (TTY),
+ * `--exec` (binary + argv, no shell), `--exec-shell` (shell handler),
+ * `--json` (drain: collect-and-print; watch: NDJSON streaming).
+ */
+import { spawn } from "child_process";
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { ZapierAbortDrainSignal, ZapierReleaseTriggerMessageSignal, } from "@zapier/zapier-sdk";
+import { ZapierCliValidationError } from "./errors";
+/**
+ * Marker error thrown by `createInteractiveCallback` when the user
+ * picks "Skip (let lease expire)". The SDK treats it like any other
+ * Error subclass — leave-leased per default `releaseOnError: false`
+ * — so the lease-timeout recovery path is preserved. The CLI uses
+ * the marker type to distinguish a deliberate skip from an unhandled
+ * exception when counting summary lines. Not a `ZapierSignal`: the
+ * SDK's signal-handling auto-releases the message, which is exactly
+ * what skip-expire does *not* want.
+ */
+export class CliSkipLeaseExpireError extends Error {
+    constructor() {
+        super("user skipped (let lease expire)");
+        this.name = "CliSkipLeaseExpireError";
+    }
+}
+/**
+ * Prompts the user per message. Choices:
+ *
+ * - **Ack**: returns normally so the SDK acks the message.
+ * - **Skip (release after draining)**: throws
+ *   `ZapierReleaseTriggerMessageSignal`. The SDK marks the message for
+ *   release; the actual release call is deferred until the drain
+ *   finishes so the same drain doesn't immediately re-lease it. After
+ *   drain ends, the message returns to `available` for a future drain
+ *   run or another consumer.
+ * - **Skip (let lease expire)**: throws `CliSkipLeaseExpireError` so
+ *   the SDK leaves the message leased (it's not a `ZapierSignal`,
+ *   so the SDK's catch-all "leave on error" path applies); the lease
+ *   timeout (~5 min default) is the recovery path. Use this when you
+ *   want backpressure on reprocessing. The CLI catches the marker
+ *   to count it as a skip in the drain summary.
+ * - **Quit**: throws `ZapierAbortDrainSignal` so the SDK stops draining
+ *   after the current batch finishes (in-flight callbacks complete;
+ *   not-yet-started messages in the batch are released).
+ *
+ * Ctrl-C during the prompt is translated to `ZapierAbortDrainSignal`
+ * (same as Quit) — inquirer raises `ExitPromptError`, which we catch
+ * and re-throw as the abort signal.
+ */
+export function createInteractiveCallback() {
+    let messageNumber = 0;
+    return async (message) => {
+        messageNumber++;
+        const attrs = message.message_attributes;
+        console.log(`\n${chalk.bold(`Message #${messageNumber}`)} ${chalk.dim(message.id)} ` +
+            `${chalk.dim(`(lease #${attrs.lease_count})`)}`);
+        if (attrs.error_message) {
+            console.log(chalk.yellow(`  upstream error: ${attrs.error_message}`));
+        }
+        if (attrs.possible_duplicate_data) {
+            console.log(chalk.yellow("  possible duplicate data"));
+        }
+        while (true) {
+            let action;
+            try {
+                const answer = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "action",
+                        message: "Action?",
+                        choices: [
+                            { name: "Ack (remove from inbox)", value: "ack" },
+                            {
+                                name: "Skip (release after draining)",
+                                value: "skip-release",
+                            },
+                            { name: "Skip (let lease expire)", value: "skip-expire" },
+                            { name: "View payload", value: "view" },
+                            { name: "Quit", value: "quit" },
+                        ],
+                    },
+                ]);
+                action = answer.action;
+            }
+            catch (error) {
+                // Inquirer raises `ExitPromptError` on Ctrl-C / Ctrl-D / ESC.
+                // Translate to the SDK abort signal so the drain stops cleanly.
+                if (error instanceof Error && error.name === "ExitPromptError") {
+                    throw new ZapierAbortDrainSignal("user pressed Ctrl-C");
+                }
+                throw error;
+            }
+            if (action === "view") {
+                console.log(chalk.dim(JSON.stringify(message.payload, null, 2)));
+                continue;
+            }
+            if (action === "ack") {
+                return;
+            }
+            if (action === "skip-release") {
+                throw new ZapierReleaseTriggerMessageSignal("user skipped (release)");
+            }
+            if (action === "skip-expire") {
+                throw new CliSkipLeaseExpireError();
+            }
+            if (action === "quit") {
+                throw new ZapierAbortDrainSignal("user requested quit");
+            }
+        }
+    };
+}
+/**
+ * Writes one JSON object per line to stdout (NDJSON) for piping. Acks
+ * each message after the write resolves; if stdout is closed mid-drain
+ * (broken pipe), the write throws and the message stays unacked.
+ *
+ * The write callback alone provides backpressure: it doesn't fire until
+ * the chunk is fully committed to the underlying resource, so awaiting
+ * it pauses the drain when stdout is busy. No separate `drain` listener
+ * needed — and adding one would race with the callback (drain fires at
+ * highWaterMark, callback fires after full commit; if drain wins, the
+ * later callback's error gets dropped on the floor).
+ */
+export function createNdjsonCallback() {
+    return (message) => new Promise((resolve, reject) => {
+        process.stdout.write(JSON.stringify(message) + "\n", (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * Run a subprocess per message, piping the message JSON to the
+ * subprocess on stdin. Exit code 0 acks the message (resolves);
+ * non-zero rejects so the SDK leaves it unacked.
+ *
+ * When `shell` is true (used by `runShellCommand`), Node picks the
+ * platform's default shell (`sh` on POSIX, `cmd.exe` on Windows) and
+ * pipelines/redirects/expansions work everywhere. When false (used by
+ * `runExecCommand`), the binary is invoked directly with argv passed
+ * literally — no shell parsing, no glob expansion.
+ *
+ * Threads through the abort signal so a Ctrl-C during forever-watch
+ * cleanly terminates in-flight subprocesses rather than leaving them
+ * orphaned. On abort, the subprocess is killed and the close-event
+ * rejects with `ZapierAbortDrainSignal` so the SDK stops cleanly
+ * rather than recording the kill as a handler error.
+ */
+function runSubprocess(options) {
+    const { command, args, shell, label, message, signal } = options;
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            shell,
+            stdio: ["pipe", "inherit", "inherit"],
+        });
+        let abortListener;
+        if (signal) {
+            if (signal.aborted) {
+                child.kill();
+            }
+            else {
+                abortListener = () => {
+                    child.kill();
+                };
+                signal.addEventListener("abort", abortListener, { once: true });
+            }
+        }
+        child.on("error", (err) => {
+            if (signal && abortListener) {
+                signal.removeEventListener("abort", abortListener);
+            }
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (signal && abortListener) {
+                signal.removeEventListener("abort", abortListener);
+            }
+            if (signal?.aborted) {
+                reject(new ZapierAbortDrainSignal(`${label} aborted`));
+                return;
+            }
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${label} exited with code ${code} for message ${message.id}`));
+        });
+        // Subprocess can exit before reading stdin (e.g. `exit 0`), which
+        // breaks the pipe and surfaces EPIPE on the stdin stream. Exit code
+        // drives the outcome, so a write racing with subprocess exit isn't
+        // a failure. Swallow EPIPE; let other errors reject.
+        child.stdin.on("error", (err) => {
+            if (err.code !== "EPIPE")
+                reject(err);
+        });
+        child.stdin.end(JSON.stringify(message) + "\n");
+    });
+}
+export function runShellCommand(command, message, signal) {
+    return runSubprocess({
+        command,
+        args: [],
+        shell: true,
+        label: "exec-shell",
+        message,
+        signal,
+    });
+}
+/**
+ * Run a binary per message with no shell interpretation. `argv[0]` is
+ * the executable; the rest are passed literally as argv to the child.
+ * Otherwise identical to `runShellCommand`: stdin = message JSON, exit
+ * code 0 acks, non-zero rejects, abort signal kills the child.
+ */
+export function runExecCommand(argv, message, signal) {
+    if (argv.length === 0) {
+        return Promise.reject(new Error("exec requires at least one element (the binary)"));
+    }
+    const [command, ...args] = argv;
+    return runSubprocess({
+        command,
+        args,
+        shell: false,
+        label: "exec",
+        message,
+        signal,
+    });
+}
+function describeReason(reason) {
+    return reason instanceof Error ? reason.message : String(reason);
+}
+/**
+ * Print a single per-message error to stderr. Used as the live
+ * `onError` body so failures surface as they happen (vs accumulated
+ * and dumped at the end, which is broken for `watch-trigger-inbox`
+ * where "the end" is Ctrl-C).
+ */
+export function printDrainError(reason, message) {
+    console.error(chalk.red(`Error processing ${message.id}: ${describeReason(reason)}`));
+}
+/**
+ * One-line summary printed when the CLI finished a drain in a mode
+ * where the data array is uninformative (interactive, exec, exec-shell).
+ * Both the bounded and forever variants use the same format.
+ *
+ * `skipped` is the interactive-mode count of user-driven Skip choices
+ * (release-after-draining + let-lease-expire). Omitted when zero so the
+ * subprocess modes — which have no skip semantics — keep their original
+ * two-part summary.
+ */
+export function printDrainSummary(counts) {
+    const skipped = counts.skipped ?? 0;
+    const total = counts.fulfilled + counts.rejected + skipped;
+    const parts = [`${counts.fulfilled} fulfilled`];
+    if (skipped > 0)
+        parts.push(`${skipped} skipped`);
+    parts.push(`${counts.rejected} rejected`);
+    console.log(chalk.dim(`\nProcessed ${total} message${total === 1 ? "" : "s"} (${parts.join(", ")}).`));
+}
+/**
+ * Warn on stderr that interactive mode is overriding an explicit
+ * `continueOnError: false`. Only fires when the caller (programmatic
+ * SDK consumer or future flag form that takes `=false`) opted into
+ * fail-fast — bare `--continue-on-error` flag absence leaves it
+ * `undefined` and doesn't trigger this. Interactive mode mechanically
+ * requires continue-on-error: the "Skip (let lease expire)" choice
+ * throws a plain Error to leave the message leased, and a fail-fast
+ * drain would tear down on the first skip.
+ */
+export function warnInteractiveContinueOnErrorOverride() {
+    console.warn(chalk.yellow('Note: continueOnError=false is overridden to true in interactive mode (the "Skip (let lease expire)" choice would otherwise terminate the drain).'));
+}
+/**
+ * Throw a CliValidationError if the current process isn't attached to
+ * a real terminal on both stdin and stdout. Used by the interactive
+ * default to fail fast with a useful message instead of letting
+ * inquirer fall over later.
+ */
+export function requireInteractiveTty(commandName) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new ZapierCliValidationError(`${commandName} needs an interactive terminal by default. ` +
+            "Pass --exec '<bin>' (with optional `-- args...`) or " +
+            "--exec-shell '<cmd>' to run a script per message, " +
+            "or --json for non-interactive output.");
+    }
+}
+/**
+ * Reject more than one of `--exec`, `--exec-shell`, and `--json`.
+ * Each is a non-interactive output path and choosing implicitly is
+ * ambiguous.
+ */
+export function rejectExecJsonMutex(opts) {
+    const picked = [
+        opts.exec ? "--exec" : null,
+        opts.execShell ? "--exec-shell" : null,
+        opts.json ? "--json" : null,
+    ].filter((x) => x !== null);
+    if (picked.length > 1) {
+        throw new ZapierCliValidationError(`${picked.join(", ")} are mutually exclusive. Pick one.`);
+    }
+}
+/**
+ * Pull argv tokens after the first `--` separator out of `process.argv`.
+ * Returns `[]` when there's no `--`. Used by drain/watch to append
+ * post-`--` args to the `--exec` binary, mirroring `xargs`, `gh`, and
+ * `npm run -- ...` semantics.
+ *
+ * Read from `process.argv` rather than threading via cli-generator
+ * because Commander already consumes `--` at parse time and there's
+ * no per-command API for "the args after `--`" exposed through the
+ * SDK options object.
+ */
+export function getPostDashArgs(argv = process.argv) {
+    const idx = argv.indexOf("--");
+    if (idx === -1)
+        return [];
+    return argv.slice(idx + 1);
+}
+/**
+ * Combine an optional user signal with an internal one (typically the
+ * SIGINT controller) into a single AbortSignal that fires when either
+ * source aborts. Returns a `dispose` to detach the listeners; safe to
+ * call regardless of whether the combined signal fired.
+ *
+ * Plain shape rather than the SDK's `combineAbortSignals`, which works
+ * over `DisposableAbortSignal` handles and returns a different shape.
+ */
+export function combineSignals(a, b) {
+    if (!a) {
+        return { signal: b, dispose: () => undefined };
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    if (a.aborted || b.aborted)
+        controller.abort();
+    else {
+        a.addEventListener("abort", onAbort, { once: true });
+        b.addEventListener("abort", onAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            a.removeEventListener("abort", onAbort);
+            b.removeEventListener("abort", onAbort);
+        },
+    };
+}