unfazed 0.8.0 → 0.8.1

package/dist/unfazed.js

@@ -464,9 +464,24 @@ export class Unfazed {
      * the account already holds its cap of waits in progress (16), it polls
      * instead (`waitOptions.mode: "poll"` forces that), every 0.5 s backing
      * off to 3 s by default.
+     *
+     * Pass a {@link CommitDeploymentTarget} instead of an id to wait for the
+     * deploy a git import makes of a commit — a restore, a push or a sync
+     * deploys before any id exists. The wait covers the import too, and
+     * {@link UnfazedDeployError} carries the import's error when it failed on
+     * the commit.
+     *
+     * ```ts
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha });
+     * await unfazed.waitForDeployment({
+     *   workspaceId: back.workspaceID, gitCommit: back.sha, alias: back.deployAlias, after: back.waitAfter,
+     * });
+     * ```
      */
-    async waitForDeployment(deploymentId, waitOptions = {}) {
-        return (await this.#waitTerminal(deploymentId, waitOptions)).deployment;
+    async waitForDeployment(target, waitOptions = {}) {
+        if (typeof target !== "string")
+            return (await this.#commitWait(target, waitOptions)).deployment;
+        return (await this.#waitTerminal(target, waitOptions)).deployment;
     }
     async #waitTerminal(deploymentId, waitOptions) {
         const now = waitOptions.now ?? (() => Date.now());
@@ -518,7 +533,11 @@ export class Unfazed {
                 }
                 throw e;
             }
+            // By id the platform always answers the deployment; null is only for a
+            // wait by commit before the import made it.
             const d = answer.deployment;
+            if (!d)
+                throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
             last = d;
             if (answer.timedOut) {
                 landing = d.status === "READY";
@@ -529,6 +548,61 @@ export class Unfazed {
             throw new UnfazedDeployError("FAILED", deploymentId, d, `unfazed: deployment ${deploymentId} ${d.status}${d.error ? `: ${d.error}` : ""}`);
         }
     }
+    /**
+     * The server-side wait by commit: for the import to make the commit's
+     * deployment, then for it, one budget for both. There is nothing cheaper to
+     * poll, so a refusal past the platform's cap on waits in progress backs off
+     * (0.5 s up to 3 s) and asks again.
+     */
+    async #commitWait(target, waitOptions) {
+        const resolved = resolveWaitOptions(waitOptions);
+        const deadline = resolved.now() + resolved.timeoutMs;
+        const commit = target.gitCommit.slice(0, 7);
+        const what = `the deploy of ${commit}${target.alias ? ` to ${target.alias}` : ""}`;
+        let last = null;
+        let status = "IMPORTING";
+        let backoff = 500;
+        for (let requests = 1;; requests++) {
+            if (resolved.signal?.aborted)
+                throw new UnfazedTimeoutError("unfazed: wait aborted");
+            const remaining = deadline - resolved.now();
+            if (requests > 1 && remaining <= 0) {
+                throw new UnfazedDeployError("TIMEOUT", last?.id ?? "", last, `unfazed: ${what} still ${status} after ${resolved.timeoutMs}ms`);
+            }
+            const seconds = Math.max(1, Math.min(SERVER_WAIT_SECONDS, Math.ceil(remaining / 1000)));
+            let answer;
+            try {
+                answer = (await this.client.query(ops.WaitForCommitDeploymentDocument, {
+                    workspaceID: target.workspaceId,
+                    gitCommit: target.gitCommit,
+                    alias: target.alias ?? null,
+                    after: target.after ?? null,
+                    timeoutSeconds: seconds,
+                }, { ...(resolved.signal ? { signal: resolved.signal } : {}), timeoutMs: (seconds + 30) * 1000 })).waitForDeployment;
+            }
+            catch (e) {
+                if (!isTooManyWaits(e))
+                    throw e;
+                await resolved.sleep(Math.max(0, Math.min(backoff, deadline - resolved.now())), resolved.signal);
+                backoff = Math.min(backoff * 1.5, 3_000);
+                continue;
+            }
+            const d = answer.deployment;
+            status = answer.status;
+            if (d)
+                last = d;
+            if (answer.timedOut)
+                continue;
+            if (!d) {
+                // Not timed out and no deployment: the import failed on the commit
+                // and nothing imports any more, so no deployment of it is coming.
+                throw new UnfazedDeployError("FAILED", "", null, `unfazed: the import of ${commit} failed${answer.importError ? `: ${answer.importError}` : ""}`);
+            }
+            if (d.status === "READY")
+                return { deployment: d, requests };
+            throw new UnfazedDeployError("FAILED", d.id, d, `unfazed: deployment ${d.id} (${what}) ${d.status}${d.error ? `: ${d.error}` : ""}`);
+        }
+    }
     async #pollWait(deploymentId, waitOptions) {
         const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
         const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
@@ -557,12 +631,16 @@ export class Unfazed {
         return { deployment: full, requests: requests + 1, mode: "poll" };
     }
     /**
-     * The platform's measured phases of a deploy ({@link PlatformTimings}),
-     * from its timing events. Null when it recorded none (a deploy that is
-     * still building, or one from before timings existed).
+     * The platform's measured phases of a deploy ({@link PlatformTimings}), as
+     * it parses them from all of the deployment's timing events
+     * (`Deployment.timings`). Null when it recorded none (a deploy that is
+     * still building, or one from before timings existed), or for a deployment
+     * you cannot see.
      */
     async getDeploymentTimings(deploymentId, options) {
-        return parseDeploymentTimings(await this.getEvents(deploymentId, 100, options));
+        const data = await this.client.query(ops.DeploymentTimingsDocument, { id: deploymentId }, options);
+        const timings = data.deployment?.timings;
+        return timings ? toPlatformTimings(timings) : null;
     }
     /**
      * The timings of a deploy that just went READY. `deployment.phases` is
@@ -964,9 +1042,12 @@ export class Unfazed {
      * When the app deploys every push (`deploys: true`), the new commit is
      * imported and deployed like a push. That deploy is queued behind the
      * restore, so the platform answers before it exists; with `wait: true` the
-     * SDK waits for the import of the new commit and resolves with the
-     * deployments it made (READY), or throws {@link UnfazedDeployError} with
-     * the import's error.
+     * SDK waits for it by commit on the platform ({@link Unfazed.waitForDeployment}
+     * with `gitCommit: sha`, `alias: deployAlias`, `after: waitAfter`) and
+     * resolves with it READY, or throws {@link UnfazedDeployError} with its
+     * build error or the import's. A link with unfazed.json `apps[]` names no
+     * `deployAlias` and deploys once per app: then it follows the import until
+     * every deployment it made is done.
      *
      * ```ts
      * const page = await unfazed.listCommits(ws.id);
@@ -985,18 +1066,19 @@ export class Unfazed {
         const restored = data.restoreAppVersion;
         if (!options.wait || !restored.deploys)
             return restored;
-        return {
-            ...restored,
-            deployments: await this.#waitForImport(options.workspaceId, restored.sha, {
-                ...options.waitOptions,
-                ...(options.signal ? { signal: options.signal } : {}),
-            }),
-        };
+        const waitOptions = { ...options.waitOptions, ...(options.signal ? { signal: options.signal } : {}) };
+        if (restored.deployAlias) {
+            const { deployment } = await this.#commitWait({ workspaceId: restored.workspaceID, gitCommit: restored.sha, alias: restored.deployAlias, after: restored.waitAfter }, waitOptions);
+            return { ...restored, deployments: [deployment] };
+        }
+        return { ...restored, deployments: await this.#waitForImport(restored.workspaceID, restored.sha, waitOptions) };
     }
     /**
      * Waits until the app's git link has imported `sha` (READY: its deploys
      * are done) and returns the deployments of that commit; throws on a FAILED
-     * import of it.
+     * import of it. Only for a restore whose link names no alias (unfazed.json
+     * `apps[]`): the wait by commit waits for one app's deploy, and which apps
+     * a commit deploys is known only once its import is done.
      */
     async #waitForImport(workspaceId, sha, waitOptions) {
         const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
@@ -1443,51 +1525,123 @@ function toDeploymentEvent(event) {
         message: event.message,
         vmID: event.vmID ?? null,
         metadata: event.metadata ?? null,
+        timings: event.timings ? toPlatformTimings(event.timings) : null,
         createdAt: event.createdAt,
     };
 }
+const BUILD_FINISHED_EVENT = "deployment.build_finished";
+const DEPLOY_PHASES_EVENT = "deployment.phases";
 /**
- * A deploy's phases from its events: `deployment.phases` (written when it went
- * READY: build, promotion and its split, total) over `deployment.build_finished`
- * (the build VM's own phases). Every `*_ms` field becomes a number. Null when
- * neither event is there.
+ * A duration as the platform accepts one: a whole, non-negative number of
+ * milliseconds (a number, or a string of digits as metadata carries it). A
+ * fraction or anything else is not a duration; a negative one is a clock gone
+ * backwards. Both are dropped, as the platform drops them.
  */
-export function parseDeploymentTimings(events) {
-    const latest = (type) => [...events].reverse().find((e) => e.type === type)?.metadata ?? null;
-    const build = latest("deployment.build_finished");
-    const ready = latest("deployment.phases");
-    if (!build && !ready)
+function durationMs(value) {
+    let n;
+    if (typeof value === "number")
+        n = value;
+    else if (typeof value === "string" && /^[+-]?\d+$/.test(value.trim()))
+        n = Number(value.trim());
+    else
         return null;
-    const merged = { ...build, ...ready };
-    const ms = (name) => {
-        const value = merged[`${name}_ms`];
-        if (value === undefined)
-            return null;
-        const n = Number(value);
-        return Number.isFinite(n) ? n : null;
-    };
+    return Number.isSafeInteger(n) && n >= 0 ? n + 0 : null; // + 0: -0 is 0
+}
+/** The platform's structured timings, with every duration checked like the metadata's. */
+function toPlatformTimings(t) {
     const phases = {};
-    for (const [key, value] of Object.entries(merged)) {
-        if (!key.endsWith("_ms"))
-            continue;
-        const name = key.slice(0, -3);
-        if (name === "total" || name === "build" || name === "promote")
-            continue;
-        const n = Number(value);
-        if (Number.isFinite(n))
-            phases[name] = n;
+    if (t.phases && typeof t.phases === "object") {
+        for (const [name, value] of Object.entries(t.phases)) {
+            const ms = durationMs(value);
+            if (ms !== null)
+                phases[name] = ms;
+        }
     }
-    const memory = Number(merged["build_memory_mib"]);
+    const memory = durationMs(t.buildMemoryMiB);
     return {
-        totalMs: ready ? ms("total") : null,
-        buildMs: ms("build"),
-        promoteMs: ms("promote"),
+        totalMs: durationMs(t.totalMs),
+        buildMs: durationMs(t.buildMs),
+        promoteMs: durationMs(t.promoteMs),
         phases,
-        buildMode: merged["build_mode"] ?? null,
-        artifactTransport: merged["artifact_transport"] ?? null,
-        buildMemoryMiB: Number.isFinite(memory) && merged["build_memory_mib"] !== undefined ? memory : null,
+        buildMode: t.buildMode || null,
+        artifactTransport: t.artifactTransport || null,
+        buildMemoryMiB: memory ? memory : null,
     };
 }
+/**
+ * Timing-event metadata read exactly as the platform reads it
+ * (internal/usecases/deploy_timings.go): every `<name>_ms` that is a whole,
+ * non-negative number; `total` only from the READY summary.
+ */
+function timingsFromMetadata(metadata, ready) {
+    const out = {
+        totalMs: null,
+        buildMs: null,
+        promoteMs: null,
+        phases: {},
+        buildMode: metadata["build_mode"] || null,
+        artifactTransport: metadata["artifact_transport"] || null,
+        buildMemoryMiB: null,
+    };
+    for (const [key, raw] of Object.entries(metadata)) {
+        if (!key.endsWith("_ms") || key === "_ms")
+            continue;
+        const ms = durationMs(raw);
+        if (ms === null)
+            continue;
+        const name = key.slice(0, -3);
+        if (name === "total") {
+            if (ready)
+                out.totalMs = ms;
+        }
+        else if (name === "build")
+            out.buildMs = ms;
+        else if (name === "promote")
+            out.promoteMs = ms;
+        else
+            out.phases[name] = ms;
+    }
+    const memory = durationMs(metadata["build_memory_mib"]);
+    if (memory)
+        out.buildMemoryMiB = memory;
+    return out;
+}
+/**
+ * A deploy's phases from its events, as the platform reads them: the latest
+ * `deployment.phases` (written when it went READY: build, promotion and its
+ * split, total) over the latest `deployment.build_finished` (the build VM's
+ * own phases). It prefers the `timings` the platform parsed into each event
+ * ({@link Unfazed.getEvents} reads them); events without them (an older
+ * platform, events built by hand) are parsed from their `*_ms` metadata the
+ * same way. Durations are whole, non-negative milliseconds: anything else is
+ * dropped, as the platform drops it. Null when neither event is there.
+ */
+export function parseDeploymentTimings(events) {
+    const latest = (type) => {
+        const event = [...events].reverse().find((e) => e.type === type);
+        return event && (event.timings || event.metadata) ? event : null;
+    };
+    const build = latest(BUILD_FINISHED_EVENT);
+    const ready = latest(DEPLOY_PHASES_EVENT);
+    if (!build && !ready)
+        return null;
+    if ((!build || build.timings) && (!ready || ready.timings)) {
+        const b = build?.timings ? toPlatformTimings(build.timings) : null;
+        const r = ready?.timings ? toPlatformTimings(ready.timings) : null;
+        return {
+            totalMs: r?.totalMs ?? null,
+            buildMs: r?.buildMs ?? b?.buildMs ?? null,
+            promoteMs: r?.promoteMs ?? b?.promoteMs ?? null,
+            phases: { ...b?.phases, ...r?.phases },
+            buildMode: r?.buildMode ?? b?.buildMode ?? null,
+            artifactTransport: r?.artifactTransport ?? b?.artifactTransport ?? null,
+            buildMemoryMiB: r?.buildMemoryMiB ?? b?.buildMemoryMiB ?? null,
+        };
+    }
+    // The platform merges the two events' metadata, the READY summary's values
+    // over the build's, and parses the result.
+    return timingsFromMetadata({ ...build?.metadata, ...ready?.metadata }, ready !== null);
+}
 function errorGroupInput(ref) {
     return { workspaceID: ref.workspaceId, alias: ref.alias, groupID: ref.groupId };
 }