@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.10

package/cloud/cloudHttpError.ts

@@ -0,0 +1,54 @@
+import { isRecord } from "akanjs/common";
+
+//? The body is kept whole for reading the server's answer; only the message is cut, as it lands in a terminal.
+export class CloudHttpError extends Error {
+  static readonly #errKey = /^[\w$-]+\.error\.[\w$-]+$/;
+
+  override readonly name = "CloudHttpError";
+
+  constructor(
+    readonly status: number,
+    readonly statusText: string,
+    readonly url: string,
+    readonly body: string,
+    readonly headers: Headers = new Headers(),
+  ) {
+    super(`${status} ${statusText} from ${url}: ${body.slice(0, 200)}`);
+  }
+
+  static async of(response: Response, url: string) {
+    return new CloudHttpError(response.status, response.statusText, url, await response.text(), response.headers);
+  }
+
+  static statusOf(error: unknown) {
+    return error instanceof CloudHttpError ? error.status : null;
+  }
+
+  /** The `error` of a JSON refusal: an Err key from the server itself, or whatever a proxy put there. */
+  get error(): string | null {
+    try {
+      const parsed: unknown = JSON.parse(this.body);
+      return isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** `error` when it is an Err key (`release.error.uploadCommitInProgress`), which only the server's own answer names. */
+  get errKey(): string | null {
+    const { error } = this;
+    return error && CloudHttpError.#errKey.test(error) ? error : null;
+  }
+
+  get retryAfterMs(): number | null {
+    return CloudHttpError.retryAfterMs(this.headers.get("retry-after"));
+  }
+
+  /** Retry-After in milliseconds from now: whole seconds, or an HTTP date. */
+  static retryAfterMs(header: string | null): number | null {
+    const value = header?.trim() ?? "";
+    if (!value) return null;
+    const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(ms) ? Math.max(0, ms) : null;
+  }
+}

package/cloud/cloudUpdates.ts

@@ -0,0 +1,138 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { NativeEnv } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import { type MobilePlatform, resolveMobileTargets } from "../mobile/mobileTarget";
+import { NativeApp } from "../mobile/nativeApp";
+import { NativePublicEnv } from "../mobile/nativePublicEnv";
+import { type NativeUpdatePack, UpdatePackFolder } from "../mobile/updatePackFolder";
+import { type AppBinaryDistribution, CloudApi } from "./cloudApi";
+import { UpdatePackUpload } from "./updatePackUpload";
+
+//* A phone app's over-the-air updates through an Akan Cloud project, which keeps the signing key: a pack uploaded for
+//* it to sign and publish, and the store build a pack of the same commit is embedded in.
+export class CloudUpdates {
+  constructor(
+    readonly cloudApi: CloudApi,
+    readonly devProjectId: string,
+  ) {}
+
+  /** The bundle.json the target's last `akan release-<platform>` wrote. */
+  static async storeBundlePath(app: App, target: string | undefined, platform: MobilePlatform) {
+    const [mobileTarget] = await resolveMobileTargets(app, target);
+    if (!mobileTarget) throw new Error(`Native target '${target}' was not found.`);
+    return path.join(new NativeApp(app, mobileTarget).outDir(platform), UpdatePackFolder.bundleFile);
+  }
+
+  /** A pack `akan pack-update` wrote, refused unless it is this app's and agrees with every flag given beside it. */
+  static async readPack(
+    app: App,
+    dir: string,
+    {
+      platform,
+      target,
+      env,
+      allowLocalRelease,
+    }: { platform: MobilePlatform | null; target: string | null; env: NativeEnv | null; allowLocalRelease: boolean },
+  ) {
+    const pack = await UpdatePackFolder.read(dir);
+    const what = `The pack in ${pack.out} is ${pack.app} ${pack.target} ${pack.platform} --env ${pack.env}`;
+    if (pack.app !== app.name) throw new Error(`${what}, not ${app.name}'s.`);
+    if (platform && platform !== pack.platform) throw new Error(`${what}, not ${platform}.`);
+    if (env && env !== pack.env) throw new Error(`${what}, not --env ${env}.`);
+    if (target) {
+      const targets = (await resolveMobileTargets(app, target)).map(({ name }) => name);
+      if (targets.length !== 1 || targets[0] !== pack.target)
+        throw new Error(`${what}, not --target ${target} (${targets.join(", ")}).`);
+    }
+    if (pack.env === "local" && !allowLocalRelease)
+      throw new Error(
+        `${what}, and a local pack is blocked. Pass --allow-local-release only for explicit local release testing.`,
+      );
+    return pack;
+  }
+
+  async push(pack: NativeUpdatePack, { channel, notes }: { channel: string | null; notes: string | null }) {
+    const target = channel ?? pack.channel;
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const release = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
+        .send(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel: target, notes })
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a pack is uploaded by a project member signed in with `akan login`");
+        });
+      const label = `${pack.app} ${pack.target} ${pack.platform} on channel ${target}: release ${release.id}`;
+      if (release.status === "rejected")
+        throw new ExitCodeError(
+          `The project rejected ${label}:\n${(release.problems ?? []).map((problem) => `  - ${problem}`).join("\n")}`,
+          2,
+        );
+      if (release.status === "published")
+        Logger.rawLog(`Published ${label} (${pack.files} files, native API ${pack.nativeApi}).`);
+      else
+        Logger.rawLog(
+          `Staged ${label} (${pack.files} files, native API ${pack.nativeApi}). Publish it from the project's release screen.`,
+        );
+      return release;
+    });
+  }
+
+  //? The store build first, then a pack of the same commit: a server that registers the binary checks the pack runs in it.
+  async registerBinary(
+    app: App,
+    pack: NativeUpdatePack,
+    { distribution, env }: { distribution: AppBinaryDistribution; env: NativeEnv },
+  ) {
+    const { cloudApi, devProjectId } = this;
+    const bundlePath = await CloudUpdates.storeBundlePath(app, pack.target, pack.platform);
+    const bundleFile = Bun.file(bundlePath);
+    const rebuild = `akan release-${pack.platform} ${app.name} --target ${pack.target} --env ${env}`;
+    if (!(await bundleFile.exists())) throw new Error(`No store build at ${bundlePath}: run \`${rebuild}\` first.`);
+    const bundle = await UpdatePackFolder.readBundle(bundlePath);
+    if (!bundle.updates)
+      throw new Error(`The store build at ${bundlePath} takes no updates: give the target native.updates.`);
+    const packBundle = path.join(pack.out, UpdatePackFolder.bundleFile);
+    const envProblem = await NativePublicEnv.problemAgainst(bundlePath, packBundle);
+    if (envProblem) throw new ExitCodeError(`The pack in ${pack.out} cannot run in the store build: ${envProblem}.`, 2);
+    //? Every native build of the target rewrites this file, so a debug or another env's build replaces the release's.
+    if (bundle.web.hash !== pack.webHash)
+      throw new Error(
+        `The store build at ${bundlePath} is not this commit's --env ${env} build: its web bundle differs from the pack's. Run \`${rebuild}\`, then register that build.`,
+      );
+    const compat = await NativeApp.compareBundles(app.cwdPath, bundlePath, packBundle);
+    const verdict = UpdatePackFolder.storeBuildVerdict(
+      { out: pack.out, compat: { against: bundlePath, ...compat } },
+      `Run \`${rebuild}\`, then register that build.`,
+    );
+    if (verdict) throw verdict;
+    if (bundle.updates.channel !== pack.channel)
+      throw new Error(
+        `The store build at ${bundlePath} reads updates channel ${bundle.updates.channel}, and this commit's --env ${env} pack is for ${pack.channel}. Run \`${rebuild}\`, then register that build.`,
+      );
+    const { channel } = pack;
+    const upload = new UpdatePackUpload(cloudApi, devProjectId);
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const binary = await upload
+        .stage(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel, notes: null })
+        .then((packUploadId) =>
+          upload.settle(() =>
+            cloudApi.registerAppBinary(devProjectId, {
+              appName: pack.app,
+              target: pack.target,
+              distribution,
+              bundle: bundleFile,
+              packUploadId,
+              channel,
+            }),
+          ),
+        )
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a binary is registered by a project member signed in with `akan login`");
+        });
+      Logger.rawLog(
+        `Registered ${pack.app} ${pack.target} ${pack.platform} (${distribution}): binary ${binary.id}, native API ${pack.nativeApi}.`,
+      );
+      return binary;
+    });
+  }
+}

package/cloud/configLock.ts

@@ -36,7 +36,8 @@ export class ConfigLock {
 
   static async #take(lockPath: string) {
     const handle = await open(lockPath, "wx", 0o600).catch((error: NodeJS.ErrnoException) => {
-      if (error.code === "EEXIST") return null;
+      // Windows answers EPERM, not EEXIST, while a released lock file is still pending delete behind an open handle.
+      if (error.code === "EEXIST" || (process.platform === "win32" && error.code === "EPERM")) return null;
       throw error;
     });
     if (!handle) return false;

package/cloud/globalConfig.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { GlobalConfig } from "./globalConfig";
+
+const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
+
+describe("GlobalConfig", () => {
+  test("hostFor spells --host the way the workspace's cloud.host is spelled, so one login serves both", async () => {
+    for (const given of ["https://cloud.example.com/", "https://Cloud.Example.com:443", "https://cloud.example.com//"])
+      expect(await GlobalConfig.hostFor(workspace(null), given)).toBe("https://cloud.example.com");
+    expect(await GlobalConfig.hostFor(workspace("https://cloud.example.com"), "https://cloud.example.com/")).toBe(
+      await GlobalConfig.hostFor(workspace("https://cloud.example.com"), null),
+    );
+    expect(await GlobalConfig.hostFor(workspace(null), "https://example.com/cloud/")).toBe("https://example.com/cloud");
+    expect(await GlobalConfig.hostFor(workspace(null), "http://localhost:8283/")).toBe("http://localhost:8283");
+    expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
+  });
+});

package/cloud/globalConfig.ts

@@ -1,4 +1,5 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
+import { trimTrailingSlashes } from "akanjs/common";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -54,8 +55,14 @@ export class GlobalConfig {
     });
   }
   static async hostFor(workspace: { getConfig(): Promise<{ cloudHost: string | null }> }, host?: string | null) {
-    if (host) return host;
-    return (await workspace.getConfig()).cloudHost ?? GlobalConfig.akanCloudHost;
+    return GlobalConfig.#normalizeHost(host || ((await workspace.getConfig()).cloudHost ?? GlobalConfig.akanCloudHost));
+  }
+  //? A login is stored under the host string, so `--host` and the workspace's `cloud.host` must spell one cloud alike.
+  static #normalizeHost(host: string) {
+    const url = URL.canParse(host) ? new URL(host) : null;
+    return url && (url.protocol === "https:" || url.protocol === "http:")
+      ? `${url.origin}${trimTrailingSlashes(url.pathname)}`
+      : trimTrailingSlashes(host);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();

package/cloud/index.ts

@@ -1,4 +1,7 @@
 export * from "./cloudApi";
+export * from "./cloudHttpError";
+export * from "./cloudUpdates";
 export * from "./constants";
 export * from "./globalConfig";
+export * from "./pipelineSecrets";
 export * from "./updatePackUpload";

package/cloud/pipelineSecrets.ts

@@ -0,0 +1,114 @@
+import { capitalize, Logger, PipelineNames } from "akanjs/common";
+import { CloudApi, type PipelineSecretListing } from "./cloudApi";
+
+//* The named secrets an Akan Cloud project hands its pipeline: written and removed by name, listed without values.
+export class PipelineSecrets {
+  static readonly #secretBytes = 64 * 1024;
+  //? The branches Akan Cloud deploys (its BranchType): a secret scoped to any other is refused by the server.
+  static readonly #secretBranches = ["debug", "develop", "main"];
+  static readonly #secretsUnavailable = "The server is not configured for pipeline secrets yet";
+
+  constructor(
+    readonly cloudApi: CloudApi,
+    readonly devProjectId: string,
+  ) {}
+
+  //* Never an argument: a value on the command line lands in shell history and in any `ps` listing.
+  static async readValue(name: string, file: string | null) {
+    const raw = file
+      ? await Bun.file(file).text()
+      : process.stdin.isTTY
+        ? await (await import("@inquirer/prompts")).password({
+            message: `Value of ${name} (hidden; it can never be read back)`,
+            mask: "*",
+          })
+        : await PipelineSecrets.#readStdin(name);
+    const value = raw.replace(/\r?\n$/, "");
+    if (!value) throw new Error(`The value of ${name} is empty.`);
+    const bytes = new TextEncoder().encode(value).length;
+    if (bytes > PipelineSecrets.#secretBytes)
+      throw new Error(`The value of ${name} is ${bytes} bytes, over ${PipelineSecrets.#secretBytes}.`);
+    return value;
+  }
+
+  static async #readStdin(name: string) {
+    process.stderr.write(`Reading the value of ${name} from stdin until it closes (or pass --file <path>).\n`);
+    return await Bun.stdin.text();
+  }
+
+  async upload({ name, branch, value }: { name: string; branch: string | null; value: string }) {
+    PipelineSecrets.assertName(name);
+    PipelineSecrets.assertBranch(branch);
+    const saved = await this.cloudApi
+      .uploadSecret(this.devProjectId, { scope: branch ?? "*", name, value })
+      .catch((error: unknown) => {
+        throw CloudApi.refusal(error, "a secret is written by a project member signed in with `akan login`", {
+          unavailable: PipelineSecrets.#secretsUnavailable,
+        });
+      });
+    Logger.rawLog(
+      `Saved ${saved.name} for ${saved.scope === "*" ? "every branch" : `branch ${saved.scope}`}. Builds that start from now on use it.`,
+    );
+  }
+
+  async list(branch: string | null) {
+    PipelineSecrets.assertBranch(branch);
+    const listed = await this.cloudApi.listSecrets(this.devProjectId).catch((error: unknown) => {
+      throw CloudApi.refusal(error, "the secrets are listed for a project member", {
+        unavailable: PipelineSecrets.#secretsUnavailable,
+      });
+    });
+    const secrets = listed.filter((secret) => !branch || secret.scope === "*" || secret.scope === branch);
+    Logger.rawLog(PipelineSecrets.format(secrets));
+  }
+
+  async remove({ name, branch }: { name: string; branch: string | null }) {
+    PipelineSecrets.assertName(name);
+    PipelineSecrets.assertBranch(branch);
+    const removed = await this.cloudApi
+      .removeSecret(this.devProjectId, { scope: branch ?? "*", name })
+      .catch((error: unknown) => {
+        throw CloudApi.refusal(error, "a secret is removed by a project member signed in with `akan login`", {
+          unavailable: PipelineSecrets.#secretsUnavailable,
+        });
+      });
+    Logger.rawLog(
+      removed
+        ? `Removed ${name} for ${branch ? `branch ${branch}` : "every branch"}.`
+        : `No ${name} for ${branch ? `branch ${branch}` : "every branch"} to remove.`,
+    );
+  }
+
+  static format(secrets: PipelineSecretListing[]) {
+    if (!secrets.length) return "No pipeline secrets.";
+    const rows = [...secrets]
+      .sort((a, b) => a.name.localeCompare(b.name) || a.scope.localeCompare(b.scope))
+      .map((secret) =>
+        [secret.name, secret.scope === "*" ? "every branch" : secret.scope, secret.updatedAt, secret.updatedBy].map(
+          (cell) => String(cell ?? "-"),
+        ),
+      );
+    const header = ["NAME", "SCOPE", "UPDATED", "BY"];
+    const widths = header.map((title, column) =>
+      Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0)),
+    );
+    return [header, ...rows]
+      .map((row) =>
+        row
+          .map((cell, column) => cell.padEnd(widths[column] ?? 0))
+          .join("  ")
+          .trimEnd(),
+      )
+      .join("\n");
+  }
+
+  static assertName(name: string) {
+    const problem = PipelineNames.secretNameError(name);
+    if (problem) throw new Error(`${capitalize(problem)}.`);
+  }
+
+  static assertBranch(branch: string | null) {
+    if (branch !== null && !PipelineSecrets.#secretBranches.includes(branch))
+      throw new Error(`--branch ${branch} is not a deployed branch: ${PipelineSecrets.#secretBranches.join(", ")}.`);
+  }
+}

package/cloud/updatePackUpload.test.ts

@@ -13,14 +13,15 @@ interface Put {
   body: Uint8Array;
 }
 
-class FakeAkasys {
+class FakeCloudHost {
   readonly server: ReturnType<typeof Bun.serve>;
   readonly requests: Record<string, unknown>[] = [];
   readonly puts: Put[] = [];
   readonly commits: string[] = [];
   readonly registrations: Record<string, string>[] = [];
-  putStatuses: number[] = [];
-  commitAnswers: (number | [number, string])[] = [];
+  putStatuses: (number | Response)[] = [];
+  stallPuts: boolean = false;
+  commitAnswers: (number | [number, string] | Response)[] = [];
   release: Record<string, unknown> = { id: "release-1", status: "published", problems: [] };
   requestRefusal: Response | null = null;
 
@@ -38,6 +39,7 @@ class FakeAkasys {
     this.commits.length = 0;
     this.registrations.length = 0;
     this.putStatuses = [];
+    this.stallPuts = false;
     this.commitAnswers = [];
     this.requestRefusal = null;
   }
@@ -61,7 +63,9 @@ class FakeAkasys {
         headers: Object.fromEntries(request.headers),
         body: new Uint8Array(await request.arrayBuffer()),
       });
-      return new Response(null, { status: this.putStatuses.shift() ?? 200 });
+      if (this.stallPuts) return await new Promise<Response>(() => undefined);
+      const answer = this.putStatuses.shift() ?? 200;
+      return answer instanceof Response ? answer : new Response(null, { status: answer });
     }
     if (url.pathname === "/api/commitUpdateUpload/project-1") {
       const { uploadId } = (await request.json()) as { uploadId: string };
@@ -85,15 +89,16 @@ class FakeAkasys {
   #answer() {
     const answer = this.commitAnswers.shift();
     if (!answer) return null;
+    if (answer instanceof Response) return answer;
     const [status, key] = typeof answer === "number" ? [answer, "release.error.uploadCommitInProgress"] : answer;
     return Response.json({ error: key }, { status });
   }
 }
 
 const makeDir = tempDirs("akan-update-upload-");
-const akasys = new FakeAkasys();
+const cloudHost = new FakeCloudHost();
 const api = new CloudApi({} as Workspace, {
-  host: akasys.host,
+  host: cloudHost.host,
   auth: { accessToken: { jwt: "jwt-1", refreshToken: null, expiresAt: null } },
 });
 const fields = { appName: "lu", target: "default", platform: "android" as const, channel: "develop", notes: null };
@@ -105,8 +110,8 @@ const archiveOf = async (bytes: string) => {
   return archive;
 };
 
-beforeEach(() => akasys.reset());
-afterAll(() => akasys.server.stop(true));
+beforeEach(() => cloudHost.reset());
+afterAll(() => cloudHost.server.stop(true));
 
 describe("UpdatePackUpload", () => {
   test("announces the archive's size and digest, PUTs it with nothing but its content type, then commits", async () => {
@@ -115,7 +120,7 @@ describe("UpdatePackUpload", () => {
     const release = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
 
     expect(release).toEqual({ id: "release-1", status: "published", problems: [], uploadId: "upload-1" });
-    expect(akasys.requests).toEqual([
+    expect(cloudHost.requests).toEqual([
       {
         ...fields,
         size: 10,
@@ -123,98 +128,129 @@ describe("UpdatePackUpload", () => {
         authorization: "Bearer jwt-1",
       },
     ]);
-    const [put] = akasys.puts;
+    const [put] = cloudHost.puts;
     expect(new TextDecoder().decode(put?.body)).toBe("pack bytes");
     expect(put?.headers["content-type"]).toBe("application/gzip");
     expect(put?.headers["content-length"]).toBe("10");
     expect(put?.headers.authorization).toBeUndefined();
     expect(Object.keys(put?.headers ?? {}).filter((name) => name.startsWith("x-amz-"))).toEqual([]);
-    expect(akasys.commits).toEqual(["upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1"]);
   });
 
   test("takes one fresh ticket when storage answers 403, and gives up on the second without naming the URL", async () => {
     const archive = await archiveOf("pack");
-    akasys.putStatuses = [403];
+    cloudHost.putStatuses = [403];
 
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-2"]);
-    expect(akasys.commits).toEqual(["upload-2"]);
+    expect(cloudHost.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-2"]);
+    expect(cloudHost.commits).toEqual(["upload-2"]);
 
-    akasys.reset();
-    akasys.putStatuses = [403, 403];
+    cloudHost.reset();
+    cloudHost.putStatuses = [403, 403];
     const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
     expect(String(refusal)).toContain("HTTP 403");
     expect(String(refusal)).not.toContain("secret-signature");
-    expect(akasys.commits).toEqual([]);
+    expect(cloudHost.commits).toEqual([]);
   });
 
   test("retries a PUT the way curl --retry does, and stops at a refusal that is not transient", async () => {
     const archive = await archiveOf("pack");
-    akasys.putStatuses = [503, 502];
+    cloudHost.putStatuses = [503, 502];
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-1", "upload-1"]);
+    expect(cloudHost.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-1", "upload-1"]);
 
-    akasys.reset();
-    akasys.putStatuses = [400];
+    cloudHost.reset();
+    cloudHost.putStatuses = [400];
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("HTTP 400");
-    expect(akasys.puts).toHaveLength(1);
+    expect(cloudHost.puts).toHaveLength(1);
   });
 
   test("asks again with the same id while the commit is cut off or still running, but not past a real answer", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [524, 409, 502];
+    cloudHost.commitAnswers = [524, 409, 502];
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.commits).toEqual(["upload-1", "upload-1", "upload-1", "upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1", "upload-1", "upload-1", "upload-1"]);
 
-    akasys.reset();
-    akasys.commitAnswers = [404];
+    cloudHost.reset();
+    cloudHost.commitAnswers = [404];
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("404");
-    expect(akasys.commits).toEqual(["upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1"]);
 
-    akasys.reset();
-    akasys.commitAnswers = Array.from({ length: 100 }, () => 524);
+    cloudHost.reset();
+    cloudHost.commitAnswers = Array.from({ length: 100 }, () => 524);
     const cutOff = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 35, commitLimitMs: 10_000 };
     await expect(new UpdatePackUpload(api, "project-1", cutOff).send(archive, fields)).rejects.toThrow("524");
-    expect(akasys.commits.length).toBeLessThan(6);
+    expect(cloudHost.commits.length).toBeLessThan(6);
   });
 
   test("keeps waiting on a live claim past the cut-off window, up to the overall limit", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [...Array.from({ length: 6 }, () => 409), 524, ...Array.from({ length: 6 }, () => 409)];
+    cloudHost.commitAnswers = [...Array.from({ length: 6 }, () => 409), 524, ...Array.from({ length: 6 }, () => 409)];
     const timing = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 25, commitLimitMs: 10_000 };
     await new UpdatePackUpload(api, "project-1", timing).send(archive, fields);
-    expect(akasys.commits).toHaveLength(14);
+    expect(cloudHost.commits).toHaveLength(14);
 
-    akasys.reset();
-    akasys.commitAnswers = Array.from({ length: 100 }, () => 409);
+    cloudHost.reset();
+    cloudHost.commitAnswers = Array.from({ length: 100 }, () => 409);
     const limited = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 10_000, commitLimitMs: 35 };
     await expect(new UpdatePackUpload(api, "project-1", limited).send(archive, fields)).rejects.toThrow("409");
-    expect(akasys.commits.length).toBeLessThan(6);
+    expect(cloudHost.commits.length).toBeLessThan(6);
+  });
+
+  test("gives up a stalled PUT after a time its size sets, and tries it again as a dropped one", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.stallPuts = true;
+
+    await expect(
+      new UpdatePackUpload(api, "project-1", { ...quick, putTimeoutMs: 50 }).send(archive, fields),
+    ).rejects.toThrow("no response");
+    expect(cloudHost.puts).toHaveLength(4);
+    expect(cloudHost.commits).toEqual([]);
+  });
+
+  test("asks again past a gateway's 503, but not past one the server answers with its own refusal", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [
+      new Response("No healthy federation child is ready", { status: 503 }),
+      [503, "base.error.serverUnavailable"],
+    ];
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+    expect(cloudHost.commits).toEqual(["upload-1", "upload-1", "upload-1"]);
+
+    cloudHost.reset();
+    cloudHost.commitAnswers = [[503, "release.error.signingUnavailable"]];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow(
+      "release.error.signingUnavailable",
+    );
+    expect(cloudHost.commits).toEqual(["upload-1"]);
   });
 
   test("tells a server without staged uploads apart from one whose 404 is a refusal", async () => {
     const archive = await archiveOf("pack");
-    akasys.requestRefusal = new Response("Not Found", { status: 404 });
+    cloudHost.requestRefusal = new Response("Not Found", { status: 404 });
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow(
       "does not take direct pack uploads yet",
     );
 
-    akasys.requestRefusal = Response.json({ error: "devProject.error.appNotFound", statusCode: 404 }, { status: 404 });
+    cloudHost.requestRefusal = Response.json(
+      { error: "devProject.error.appNotFound", statusCode: 404 },
+      { status: 404 },
+    );
     const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
     expect(String(refusal)).toContain("devProject.error.appNotFound");
-    expect(akasys.puts).toEqual([]);
+    expect(cloudHost.puts).toEqual([]);
   });
 
   test("stops at once on a 409 that is not a commit in progress: the upload is already used", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [[409, "release.error.uploadEmbedded"]];
+    cloudHost.commitAnswers = [[409, "release.error.uploadEmbedded"]];
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("uploadEmbedded");
-    expect(akasys.commits).toHaveLength(1);
+    expect(cloudHost.commits).toHaveLength(1);
   });
 
   test("stages a binary's pack and registers it by upload id, asking again while the server is still at it", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [524, 409];
+    cloudHost.commitAnswers = [524, 409];
     const upload = new UpdatePackUpload(api, "project-1", quick);
     const binary = await upload.stage(archive, fields).then((packUploadId) =>
       upload.settle(() =>
@@ -230,9 +266,9 @@ describe("UpdatePackUpload", () => {
     );
 
     expect(binary).toEqual({ id: "binary-1" });
-    expect(akasys.commits).toEqual([]);
-    expect(akasys.registrations).toHaveLength(3);
-    expect(akasys.registrations[2]).toEqual({
+    expect(cloudHost.commits).toEqual([]);
+    expect(cloudHost.registrations).toHaveLength(3);
+    expect(cloudHost.registrations[2]).toEqual({
       appName: "lu",
       target: "default",
       distribution: "playTesting",
@@ -242,9 +278,28 @@ describe("UpdatePackUpload", () => {
     });
   });
 
+  test("waits as long as storage's Retry-After asks before trying a PUT again", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.putStatuses = [new Response(null, { status: 429, headers: { "Retry-After": "1" } })];
+    const startedAt = performance.now();
+
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+
+    expect(performance.now() - startedAt).toBeGreaterThanOrEqual(950);
+    expect(cloudHost.puts).toHaveLength(2);
+  });
+
+  test("never asks again sooner than the server's Retry-After, nor past the limit it would wait to", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [new Response("busy", { status: 503, headers: { "Retry-After": "120" } })];
+
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("503");
+    expect(cloudHost.commits).toEqual(["upload-1"]);
+  });
+
   test("refuses an empty archive before asking for a ticket", async () => {
     const archive = await archiveOf("");
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("0 bytes");
-    expect(akasys.requests).toEqual([]);
+    expect(cloudHost.requests).toEqual([]);
   });
 });