run402 1.50.0 → 1.51.0

package/sdk/dist/namespaces/deploy.js

@@ -18,7 +18,7 @@
  * See `unified-deploy` and `cas-content` capability specs for normative
  * behavior; this file is the implementation.
  */
-import { ApiError, Run402DeployError, } from "../errors.js";
+import { ApiError, NetworkError, Run402DeployError, } from "../errors.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const PLAN_BODY_LIMIT_BYTES = 5 * 1024 * 1024;
 const COMMIT_POLL_INITIAL_MS = 1_000;
@@ -115,8 +115,21 @@ export class Deploy {
      * via the auto-resume worker.)
      */
     async resume(operationId, opts = {}) {
+        if (!operationId || !operationId.startsWith("op_")) {
+            throw new Run402DeployError(`Invalid operation id: "${operationId}"`, {
+                code: "OPERATION_NOT_FOUND",
+                retryable: false,
+                context: "resuming deploy operation",
+            });
+        }
         const emit = makeEmitter(opts.onEvent);
-        const snapshot = await this.client.request(`/deploy/v2/operations/${operationId}/resume`, { method: "POST", context: "resuming deploy operation" });
+        let snapshot;
+        try {
+            snapshot = await this.client.request(`/deploy/v2/operations/${encodeURIComponent(operationId)}/resume`, { method: "POST", context: "resuming deploy operation" });
+        }
+        catch (err) {
+            throw translateDeployError(err, "resume", null, operationId);
+        }
         return await pollSnapshotUntilReady(this.client, snapshot, {}, emit, opts.project);
     }
     /**
@@ -128,6 +141,50 @@ export class Deploy {
         const headers = opts.project ? await apikeyHeaders(this.client, opts.project) : {};
         return this.client.request(`/deploy/v2/operations/${operationId}`, { headers, context: "fetching deploy operation" });
     }
+    /**
+     * List recent deploy operations for a project. The endpoint requires
+     * `apikey` auth, so `project` is required. `limit` is forwarded to the
+     * gateway as a query string when set; the gateway picks a default
+     * otherwise.
+     */
+    async list(opts) {
+        const headers = await apikeyHeaders(this.client, opts.project);
+        const qs = new URLSearchParams();
+        if (opts.limit !== undefined)
+            qs.set("limit", String(opts.limit));
+        const path = qs.toString().length > 0
+            ? `/deploy/v2/operations?${qs.toString()}`
+            : `/deploy/v2/operations`;
+        return this.client.request(path, {
+            headers,
+            context: "listing deploy operations",
+        });
+    }
+    /**
+     * Fetch the synthesized phase event stream for an operation. Returns the
+     * events the gateway has recorded so far — useful for inspecting a deploy
+     * after the fact, or resuming an event subscription from a different
+     * process. For live subscription during an in-flight deploy, use
+     * {@link Deploy.start} and iterate `op.events()`.
+     *
+     * The endpoint requires `apikey` auth, so `project` is required.
+     */
+    async events(operationId, opts) {
+        if (!operationId || !operationId.startsWith("op_")) {
+            throw new Run402DeployError(`Invalid operation id: "${operationId}"`, {
+                code: "OPERATION_NOT_FOUND",
+                retryable: false,
+                context: "fetching deploy events",
+            });
+        }
+        const headers = await apikeyHeaders(this.client, opts.project);
+        try {
+            return await this.client.request(`/deploy/v2/operations/${encodeURIComponent(operationId)}/events`, { headers, context: "fetching deploy events" });
+        }
+        catch (err) {
+            throw translateDeployError(err, "events", null, operationId);
+        }
+    }
     /**
      * Fetch a release by id. (Endpoint may not be live in early v2 builds —
      * falls through to the gateway's standard 404 handling in that case.)
@@ -200,6 +257,20 @@ async function commitInternal(client, planId, idempotencyKey) {
     }
 }
 async function uploadMissing(client, projectId, presence, byteReaders, emit) {
+    // Surface CAS dedup hits so agents can distinguish "N files were already
+    // present" from "nothing happened". The gateway reports both present and
+    // missing refs in `missing_content`; emit a skipped event for each present
+    // one before short-circuiting on a fully-deduped plan. (#124, #134)
+    const skipped = presence.filter((p) => p.present);
+    for (const p of skipped) {
+        const reader = byteReaders.get(p.sha256);
+        emit({
+            type: "content.upload.skipped",
+            label: reader?.label ?? p.sha256,
+            sha256: p.sha256,
+            reason: "present",
+        });
+    }
     // Filter to refs the gateway reported as missing for this project.
     const needsUpload = presence.filter((p) => !p.present);
     if (needsUpload.length === 0)
@@ -235,7 +306,7 @@ async function uploadMissing(client, projectId, presence, byteReaders, emit) {
             });
         }
         const bytes = await reader();
-        await uploadOne(client.fetch, session, bytes);
+        await uploadOneWithRetry(client.fetch, session, bytes);
         // Per-session completion — promotes the staged object to CAS via
         // services/cas-promote.ts. The plan-level `/content/v1/plans/:id/commit`
         // call below is the plan-level finalize; per-session promotion happens
@@ -270,6 +341,27 @@ async function uploadMissing(client, projectId, presence, byteReaders, emit) {
     // above; this call is the plan-level idempotency anchor.
     await client.request(`/content/v1/plans/${encodeURIComponent(planRes.plan_id)}/commit`, { method: "POST", headers, body: {}, context: "committing content upload" });
 }
+// Wrap `uploadOne` with exponential backoff for retryable failures.
+// `putToS3` raises Run402DeployError(retryable: true) for transient network
+// drops and 5xx/403 responses; one network blip should not fail the entire
+// deploy. Cap at 3 attempts (1 initial + 2 retries) with delays 1s, 2s.
+// Non-retryable errors (4xx other than 403, internal SDK invariants) bubble
+// up on the first attempt. See GH-140.
+async function uploadOneWithRetry(fetchFn, session, bytes) {
+    const MAX_ATTEMPTS = 3;
+    for (let attempt = 1;; attempt++) {
+        try {
+            await uploadOne(fetchFn, session, bytes);
+            return;
+        }
+        catch (err) {
+            const retryable = err instanceof Run402DeployError && err.retryable;
+            if (!retryable || attempt >= MAX_ATTEMPTS)
+                throw err;
+            await sleep(1000 * Math.pow(2, attempt - 1)); // 1s, 2s
+        }
+    }
+}
 async function uploadOne(fetchFn, entry, bytes) {
     if (entry.mode === "single") {
         if (entry.parts.length !== 1) {
@@ -397,12 +489,35 @@ async function pollSnapshotUntilReady(client, initial, diff, emit, projectId) {
         };
         return map[status] ?? null;
     };
+    // Close out the previously-emitted phase as `done` (or `failed`) before
+    // emitting the next phase's `started` event. Skips when there's no prior
+    // phase, when the prior emission wasn't a `started` event (e.g. the
+    // `activation_pending` path which already emits `failed`), or when the
+    // prior phase string equals the next phase. (#135)
+    const closePreviousPhase = (nextPhase, closeStatus = "done") => {
+        if (lastPhaseEmitted === null)
+            return;
+        const prev = phaseFor(lastPhaseEmitted);
+        if (!prev || prev.type !== "commit.phase")
+            return;
+        if (prev.status !== "started")
+            return;
+        if (nextPhase !== undefined && prev.phase === nextPhase)
+            return;
+        emit({ type: "commit.phase", phase: prev.phase, status: closeStatus });
+    };
     while (true) {
         if (lastPhaseEmitted !== snapshot.status) {
             const ev = phaseFor(snapshot.status);
-            if (ev)
+            if (ev) {
+                if (ev.type === "commit.phase")
+                    closePreviousPhase(ev.phase);
                 emit(ev);
-            lastPhaseEmitted = snapshot.status;
+                lastPhaseEmitted = snapshot.status;
+            }
+            // If `ev` is null (status not in the phase map, e.g. "ready"), leave
+            // lastPhaseEmitted pointing at the prior in-flight phase so the
+            // terminal-success closePreviousPhase() below can emit its `done`.
         }
         if (snapshot.status === SUCCESS_STATUS) {
             if (!snapshot.release_id || !snapshot.urls) {
@@ -414,6 +529,7 @@ async function pollSnapshotUntilReady(client, initial, diff, emit, projectId) {
                     context: "polling deploy",
                 });
             }
+            closePreviousPhase();
             emit({ type: "ready", releaseId: snapshot.release_id, urls: snapshot.urls });
             return {
                 release_id: snapshot.release_id,
@@ -423,6 +539,7 @@ async function pollSnapshotUntilReady(client, initial, diff, emit, projectId) {
             };
         }
         if (TERMINAL_STATUSES.includes(snapshot.status)) {
+            closePreviousPhase(undefined, "failed");
             throw translateGatewayError(snapshot.error, snapshot.status, snapshot.plan_id, snapshot.operation_id);
         }
         if (Date.now() - start > COMMIT_POLL_TIMEOUT_MS) {
@@ -508,6 +625,12 @@ async function startInternal(client, spec, opts) {
                     const queue = [...buffered];
                     let resolveNext = null;
                     let done = false;
+                    // If a terminal event was already buffered before this iterator
+                    // attached (e.g. iteration starts after `await op.result()`
+                    // resolved), we'll go done after the queue drains. Without this,
+                    // late iteration would hang forever waiting for an emit that
+                    // will never come.
+                    const terminalAlreadyBuffered = buffered.some((ev) => ev.type === "ready");
                     const subscriber = (ev) => {
                         const waiter = resolveNext;
                         if (waiter) {
@@ -525,21 +648,26 @@ async function startInternal(client, spec, opts) {
                         }
                     };
                     subscribers.push(subscriber);
-                    // Surface terminal failure as iterator end.
-                    resultPromise.catch(() => {
+                    // Wake up on either success or failure of the result promise
+                    // so an iterator attached after termination always exits.
+                    const finalize = () => {
                         done = true;
                         if (resolveNext) {
                             const r = resolveNext;
                             resolveNext = null;
                             r({ value: undefined, done: true });
                         }
-                    });
+                    };
+                    resultPromise.then(finalize, finalize);
                     return {
                         next() {
                             if (queue.length > 0) {
                                 return Promise.resolve({ value: queue.shift(), done: false });
                             }
-                            if (done) {
+                            // After queue drain, if we already saw the terminal event
+                            // in the initial buffer (or the result promise has
+                            // resolved/rejected), we're done.
+                            if (done || terminalAlreadyBuffered) {
                                 return Promise.resolve({
                                     value: undefined,
                                     done: true,
@@ -569,22 +697,30 @@ function validateSpec(spec) {
     if (!spec || typeof spec !== "object") {
         throw new Run402DeployError("ReleaseSpec must be an object", {
             code: "INVALID_SPEC",
+            phase: "validate",
+            resource: "spec",
             retryable: false,
+            fix: { action: "set_field", path: "" },
             context: "validating spec",
         });
     }
     if (!spec.project || typeof spec.project !== "string") {
         throw new Run402DeployError("ReleaseSpec.project is required", {
             code: "INVALID_SPEC",
+            phase: "validate",
+            resource: "spec.project",
             retryable: false,
+            fix: { action: "set_field", path: "project" },
             context: "validating spec",
         });
     }
     if (spec.subdomains?.set && spec.subdomains.set.length > 1) {
         throw new Run402DeployError("subdomains.set accepts at most one subdomain per project; multi-subdomain support is not yet available", {
             code: "SUBDOMAIN_MULTI_NOT_SUPPORTED",
+            phase: "validate",
             resource: "subdomains.set",
             retryable: false,
+            fix: { action: "set_field", path: "subdomains.set" },
             context: "validating spec",
         });
     }
@@ -708,8 +844,10 @@ async function normalizeMigration(client, projectId, m, remember) {
     if (!m.id) {
         throw new Run402DeployError("MigrationSpec.id is required", {
             code: "INVALID_SPEC",
+            phase: "validate",
             resource: "database.migrations",
             retryable: false,
+            fix: { action: "set_field", path: "database.migrations[].id" },
             context: "validating spec",
         });
     }
@@ -730,8 +868,13 @@ async function normalizeMigration(client, projectId, m, remember) {
     else {
         throw new Run402DeployError(`MigrationSpec ${m.id} must include sql or sql_ref`, {
             code: "INVALID_SPEC",
+            phase: "validate",
             resource: `database.migrations.${m.id}`,
             retryable: false,
+            fix: {
+                action: "set_field",
+                path: `database.migrations.${m.id}.sql`,
+            },
             context: "validating spec",
         });
     }
@@ -1037,9 +1180,19 @@ function translateDeployError(err, phase, planId, operationId) {
             context: err.context,
         });
     }
-    // Re-throw other Run402Error subclasses (PaymentRequired, Unauthorized,
-    // NetworkError, etc.) as-is — the consumer handles them at a different
-    // layer than deploy-state-machine errors.
+    if (err instanceof NetworkError) {
+        return new Run402DeployError(err.message, {
+            code: "NETWORK_ERROR",
+            phase,
+            retryable: true,
+            operationId,
+            planId,
+            context: phase,
+        });
+    }
+    // Re-throw other Run402Error subclasses (PaymentRequired, Unauthorized, etc.)
+    // as-is — the consumer handles them at a different layer than
+    // deploy-state-machine errors.
     if (err instanceof Error) {
         return new Run402DeployError(err.message, {
             code: "INTERNAL_ERROR",
@@ -1070,9 +1223,20 @@ function extractGatewayError(body) {
     if (body.error &&
         typeof body.error === "object" &&
         typeof body.error.code === "string") {
-        return body.error;
+        const nested = body.error;
+        return {
+            ...nested,
+            category: nested.category ?? stringField(body, "category"),
+            retryable: nested.retryable ?? booleanField(body, "retryable"),
+            safe_to_retry: nested.safe_to_retry ?? booleanField(body, "safe_to_retry"),
+            mutation_state: nested.mutation_state ?? stringField(body, "mutation_state"),
+            trace_id: nested.trace_id ?? stringField(body, "trace_id"),
+            details: nested.details ?? objectField(body, "details"),
+            next_actions: nested.next_actions ?? arrayField(body, "next_actions"),
+        };
     }
     if (typeof body.code === "string") {
+        const details = objectField(body, "details");
         const out = { code: body.code };
         if (typeof body.message === "string") {
             out.message = body.message;
@@ -1080,25 +1244,73 @@ function extractGatewayError(body) {
         else if (typeof body.error === "string") {
             out.message = body.error;
         }
+        else if (typeof details?.message === "string") {
+            out.message = details.message;
+        }
         else {
             out.message = `Deploy error: ${body.code}`;
         }
-        if (typeof body.phase === "string")
-            out.phase = body.phase;
-        if (typeof body.resource === "string")
-            out.resource = body.resource;
-        if (typeof body.retryable === "boolean")
-            out.retryable = body.retryable;
-        if (body.fix !== undefined)
-            out.fix = body.fix;
-        if (Array.isArray(body.logs))
-            out.logs = body.logs;
-        if (typeof body.rolled_back === "boolean")
-            out.rolled_back = body.rolled_back;
+        const phase = stringField(body, "phase") ?? stringField(details, "phase");
+        const resource = stringField(body, "resource") ?? stringField(details, "resource");
+        const retryable = booleanField(body, "retryable") ?? booleanField(details, "retryable");
+        const rolledBack = booleanField(body, "rolled_back") ?? booleanField(details, "rolled_back");
+        const operationId = stringField(body, "operation_id") ?? stringField(details, "operation_id");
+        const planId = stringField(body, "plan_id") ?? stringField(details, "plan_id");
+        const fix = body.fix !== undefined ? body.fix : details?.fix;
+        const logs = arrayField(body, "logs") ?? arrayField(details, "logs");
+        if (phase !== undefined)
+            out.phase = phase;
+        if (resource !== undefined)
+            out.resource = resource;
+        if (retryable !== undefined)
+            out.retryable = retryable;
+        if (typeof body.category === "string")
+            out.category = body.category;
+        if (typeof body.safe_to_retry === "boolean")
+            out.safe_to_retry = body.safe_to_retry;
+        if (typeof body.mutation_state === "string")
+            out.mutation_state = body.mutation_state;
+        if (typeof body.trace_id === "string")
+            out.trace_id = body.trace_id;
+        if (details !== null)
+            out.details = details;
+        if (Array.isArray(body.next_actions))
+            out.next_actions = body.next_actions;
+        if (fix !== undefined)
+            out.fix = fix;
+        if (logs !== undefined)
+            out.logs = logs;
+        if (rolledBack !== undefined)
+            out.rolled_back = rolledBack;
+        if (operationId !== undefined)
+            out.operation_id = operationId;
+        if (planId !== undefined)
+            out.plan_id = planId;
+        out.source_body = body;
         return out;
     }
     return null;
 }
+function stringField(obj, key) {
+    return obj && typeof obj === "object" && typeof obj[key] === "string"
+        ? obj[key]
+        : undefined;
+}
+function booleanField(obj, key) {
+    return obj && typeof obj === "object" && typeof obj[key] === "boolean"
+        ? obj[key]
+        : undefined;
+}
+function objectField(obj, key) {
+    const value = obj && typeof obj === "object" ? obj[key] : undefined;
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function arrayField(obj, key) {
+    const value = obj && typeof obj === "object" ? obj[key] : undefined;
+    return Array.isArray(value) ? value : undefined;
+}
 function translateGatewayError(gw, phase, planId, operationId) {
     if (!gw) {
         return new Run402DeployError("Deploy failed without a structured error", {
@@ -1110,17 +1322,36 @@ function translateGatewayError(gw, phase, planId, operationId) {
             context: phase,
         });
     }
+    // Normalize the gateway code to the SCREAMING_SNAKE_CASE convention used
+    // by `Run402DeployErrorCode`. Some gateway routes return lowercase
+    // (`operation_not_found`) while services return uppercase
+    // (`OPERATION_NOT_FOUND`); consumers expect the canonical uppercase form.
+    const normalizedCode = gw.code.toUpperCase();
+    // Prefer body-supplied ids — the gateway is the authoritative source for
+    // which operation/plan an error belongs to. The caller-provided arguments
+    // are only used as a fallback (e.g., commit failures where the call site
+    // already knows the plan id but the body omits it).
+    const details = objectField(gw, "details");
+    const opId = (gw && gw.operation_id) ??
+        stringField(details, "operation_id") ??
+        operationId;
+    const pId = (gw && gw.plan_id) ??
+        stringField(details, "plan_id") ??
+        planId;
+    const body = gw.source_body ?? gw;
+    const fix = (gw.fix ?? details?.fix ?? null);
+    const logs = (gw.logs ?? arrayField(details, "logs") ?? null);
     return new Run402DeployError(gw.message ?? `Deploy failed: ${gw.code}`, {
-        code: gw.code,
-        phase: gw.phase ?? phase,
-        resource: gw.resource ?? null,
+        code: normalizedCode,
+        phase: gw.phase ?? stringField(details, "phase") ?? phase,
+        resource: gw.resource ?? stringField(details, "resource") ?? null,
         retryable: gw.retryable ?? false,
-        operationId,
-        planId,
-        fix: (gw.fix ?? null),
-        logs: gw.logs ?? null,
-        rolledBack: gw.rolled_back ?? false,
-        body: gw,
+        operationId: opId,
+        planId: pId,
+        fix,
+        logs,
+        rolledBack: gw.rolled_back ?? booleanField(details, "rolled_back") ?? false,
+        body,
         context: phase,
     });
 }