@akanjs/devkit 3.1.0-rc.0 → 3.1.0-rc.2

package/cloud/globalConfig.ts

@@ -54,8 +54,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}${url.pathname.replace(/\/+$/, "")}`
+      : host.replace(/\/+$/, "");
   }
   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,13 +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[] = [];
-  putStatuses: number[] = [];
-  commitAnswers: number[] = [];
+  readonly registrations: Record<string, 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;
 
@@ -35,7 +37,9 @@ class FakeAkasys {
     this.requests.length = 0;
     this.puts.length = 0;
     this.commits.length = 0;
+    this.registrations.length = 0;
     this.putStatuses = [];
+    this.stallPuts = false;
     this.commitAnswers = [];
     this.requestRefusal = null;
   }
@@ -59,23 +63,42 @@ 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 };
       this.commits.push(uploadId);
-      const answer = this.commitAnswers.shift();
-      if (answer) return Response.json({ error: "release.error.uploadCommitInProgress" }, { status: answer });
+      const answer = this.#answer();
+      if (answer) return answer;
       return Response.json({ ...this.release, uploadId });
     }
+    if (url.pathname === "/api/registerAppBinary/project-1") {
+      const form = await request.formData();
+      this.registrations.push(
+        Object.fromEntries(
+          [...form.entries()].map(([key, value]) => [key, typeof value === "string" ? value : "<file>"]),
+        ),
+      );
+      return this.#answer() ?? Response.json({ id: "binary-1" });
+    }
     return new Response("not found", { status: 404 });
   }
+
+  #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 };
@@ -87,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 () => {
@@ -97,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,
@@ -105,91 +128,178 @@ 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");
+    cloudHost.commitAnswers = [[409, "release.error.uploadEmbedded"]];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("uploadEmbedded");
+    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");
+    cloudHost.commitAnswers = [524, 409];
+    const upload = new UpdatePackUpload(api, "project-1", quick);
+    const binary = await upload.stage(archive, fields).then((packUploadId) =>
+      upload.settle(() =>
+        api.registerAppBinary("project-1", {
+          appName: "lu",
+          target: "default",
+          distribution: "playTesting",
+          bundle: new Blob(["{}"]),
+          packUploadId,
+          channel: "develop",
+        }),
+      ),
+    );
+
+    expect(binary).toEqual({ id: "binary-1" });
+    expect(cloudHost.commits).toEqual([]);
+    expect(cloudHost.registrations).toHaveLength(3);
+    expect(cloudHost.registrations[2]).toEqual({
+      appName: "lu",
+      target: "default",
+      distribution: "playTesting",
+      channel: "develop",
+      bundle: "<file>",
+      packUploadId: "upload-1",
+    });
+  });
+
+  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([]);
   });
 });

package/cloud/updatePackUpload.ts

@@ -1,22 +1,30 @@
 import { Logger, sleep } from "akanjs/common";
 import type { BunFile } from "bun";
-import { CloudApi, type CloudRecord, type UpdateUploadRequest } from "./cloudApi";
+import type { CloudApi, CloudRecord, UpdateUploadRequest } from "./cloudApi";
+import { CloudHttpError } from "./cloudHttpError";
 
 interface UpdatePackUploadOptions {
   putRetryMs?: number;
+  putTimeoutMs?: number;
   commitRetryMs?: number;
   cutOffWindowMs?: number;
   commitLimitMs?: number;
 }
 
 //* akasys sits behind Cloudflare's 100 s request cut, so the pack goes straight to its staging bucket and akasys
-//* only sees two small JSON calls: request a presigned PUT, then commit the object, which akasys re-hashes.
+//* only sees small calls: request a presigned PUT, then commit the object, or register a binary with it as its
+//* embedded pack; either re-hashes it, and an upload is used once, one way.
 export class UpdatePackUpload {
   static readonly maxBytes = 200 * 1024 * 1024;
   static readonly #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
+  //? A stalled PUT never fails on its own, so each try ends once the pack would be through even at this crawl.
+  static readonly #putFloorBytesPerSecond = 64 * 1024;
+  //? Storage's Retry-After is honoured up to this: past it the presigned URL may lapse, and a fresh one is asked for.
+  static readonly #maxPutRetryAfterMs = 60_000;
   readonly #api: CloudApi;
   readonly #devProjectId: string;
   readonly #putRetryMs: number;
+  readonly #putTimeoutMs: number;
   readonly #commitRetryMs: number;
   readonly #cutOffWindowMs: number;
   readonly #commitLimitMs: number;
@@ -26,6 +34,7 @@ export class UpdatePackUpload {
     devProjectId: string,
     {
       putRetryMs = 1_000,
+      putTimeoutMs = 60_000,
       commitRetryMs = 10_000,
       cutOffWindowMs = 15 * 60_000,
       commitLimitMs = 60 * 60_000,
@@ -34,12 +43,19 @@ export class UpdatePackUpload {
     this.#api = api;
     this.#devProjectId = devProjectId;
     this.#putRetryMs = putRetryMs;
+    this.#putTimeoutMs = putTimeoutMs;
     this.#commitRetryMs = commitRetryMs;
     this.#cutOffWindowMs = cutOffWindowMs;
     this.#commitLimitMs = commitLimitMs;
   }
 
   async send(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<CloudRecord> {
+    const uploadId = await this.stage(archive, fields);
+    return await this.settle(() => this.#api.commitUpdateUpload(this.#devProjectId, uploadId));
+  }
+
+  /** Puts the pack in the project's staging storage and answers the upload id a commit or a registration names. */
+  async stage(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<string> {
     const file = Bun.file(archive);
     if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
       throw new Error(`The pack archive is ${file.size} bytes; a project takes 1 byte to 200 MiB.`);
@@ -50,7 +66,7 @@ export class UpdatePackUpload {
     for (let ticket = 1; ; ticket++) {
       const { uploadId, uploadUrl, contentType } = await this.#request(upload);
       const status = await this.#put(uploadUrl, contentType, file);
-      if (status >= 200 && status < 300) return await this.#commit(uploadId);
+      if (status >= 200 && status < 300) return uploadId;
       if (status !== 403 || ticket === 2)
         throw new Error(`The storage refused the pack upload (${status ? `HTTP ${status}` : "no response"}).`);
     }
@@ -59,10 +75,9 @@ export class UpdatePackUpload {
   async #request(upload: UpdateUploadRequest) {
     return await this.#api.requestUpdateUpload(this.#devProjectId, upload).catch((error: unknown) => {
       //? A server older than staged uploads has no such route: its 404 is a page, where every refusal is an Err key.
-      const message = error instanceof Error ? error.message : String(error);
-      if (CloudApi.statusOf(error) === 404 && !/"error"\s*:\s*"[\w$-]+\.error\.[\w$-]+"/.test(message))
+      if (error instanceof CloudHttpError && error.status === 404 && !error.errKey)
         throw new Error(
-          "The project's server does not take direct pack uploads yet: update akasys and try again, or upload the pack from the project's release screen.",
+          "The project's server does not take direct pack uploads yet: update Akan Cloud and try again, or upload the pack from the project's release screen.",
         );
       throw error;
     });
@@ -71,45 +86,67 @@ export class UpdatePackUpload {
   // The URL signs only its host: an unsigned x-amz-* header (a checksum included) makes storage refuse the PUT.
   // A Bun fetch error names the URL, a bearer credential, so nothing but the status leaves this method.
   async #put(url: string, contentType: string, file: BunFile) {
+    const timeoutMs = this.#putTimeoutMs + Math.ceil((file.size / UpdatePackUpload.#putFloorBytesPerSecond) * 1000);
     for (let retry = 0; ; retry++) {
-      const status = await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": contentType } })
+      const { status, retryAfterMs } = await fetch(url, {
+        method: "PUT",
+        body: file,
+        headers: { "Content-Type": contentType },
+        signal: AbortSignal.timeout(timeoutMs),
+      })
         .then(async (response) => {
           await response.arrayBuffer().catch(() => undefined);
-          return response.status;
+          return {
+            status: response.status,
+            retryAfterMs: CloudHttpError.retryAfterMs(response.headers.get("retry-after")),
+          };
         })
-        .catch(() => 0);
+        .catch(() => ({ status: 0, retryAfterMs: null }));
       if (retry === 3 || !UpdatePackUpload.#transientPut.has(status)) return status;
-      await sleep(this.#putRetryMs * (retry + 1));
+      await sleep(
+        Math.max(this.#putRetryMs * (retry + 1), Math.min(retryAfterMs ?? 0, UpdatePackUpload.#maxPutRetryAfterMs)),
+      );
     }
   }
 
-  // The server finishes a commit whoever stopped listening, and the same id answers the same release afterwards.
-  // A 409 is a live claim the server heartbeats, so only the overall limit bounds it; a run of cut-offs with no 409
-  // between them may be a server that died, whose claim lapses within minutes, so that run gets the shorter window.
-  async #commit(uploadId: string) {
+  /**
+   * Sends `call`, which consumes a staged upload, until the server answers it: the server finishes whoever stopped
+   * listening, and the same upload id answers the same record afterwards.
+   */
+  // `uploadCommitInProgress` is a live claim the server heartbeats, so only the overall limit bounds it; a run of
+  // cut-offs with none between them may be a server that died, whose claim lapses within minutes: the shorter window.
+  async settle<T>(call: () => Promise<T>): Promise<T> {
     const limit = performance.now() + this.#commitLimitMs;
     let cutOffSince: number | null = null;
     for (;;) {
       try {
-        return await this.#api.commitUpdateUpload(this.#devProjectId, uploadId);
+        return await call();
       } catch (error) {
         const now = performance.now();
-        if (CloudApi.statusOf(error) === 409) cutOffSince = null;
+        if (UpdatePackUpload.#inProgress(error)) cutOffSince = null;
         else if (UpdatePackUpload.#cutOff(error)) cutOffSince ??= now;
         else throw error;
         const deadline = cutOffSince === null ? limit : Math.min(limit, cutOffSince + this.#cutOffWindowMs);
-        if (now + this.#commitRetryMs > deadline) throw error;
-        Logger.rawLog(
-          `The project is still taking the pack; asking again in ${Math.round(this.#commitRetryMs / 1000)}s.`,
-        );
-        await sleep(this.#commitRetryMs);
+        const waitMs = Math.max(this.#commitRetryMs, (error instanceof CloudHttpError && error.retryAfterMs) || 0);
+        if (now + waitMs > deadline) throw error;
+        Logger.rawLog(`The project is still taking the pack; asking again in ${Math.round(waitMs / 1000)}s.`);
+        await sleep(waitMs);
       }
     }
   }
 
+  //? Not every 409: an upload already committed or embedded is answered 409 too, and asking again changes nothing.
+  static #inProgress(error: unknown) {
+    return (
+      error instanceof CloudHttpError && error.status === 409 && !!error.errKey?.endsWith(".uploadCommitInProgress")
+    );
+  }
+
   static #cutOff(error: unknown) {
-    const status = CloudApi.statusOf(error);
-    if (status === null) return !(error instanceof SyntaxError);
+    if (!(error instanceof CloudHttpError)) return !(error instanceof SyntaxError);
+    const { status, errKey } = error;
+    //? A gateway with no replica ready answers 503; the server's own 503 names an Err key and is a final refusal.
+    if (status === 503) return errKey === null || errKey === "base.error.serverUnavailable";
     return status === 502 || status === 504 || (status >= 520 && status <= 527);
   }
 }

package/commandDecorators/argMeta.ts

@@ -49,11 +49,15 @@ export interface ArgMeta<Context = CommandContext> {
   idx: number;
   type: ArgType;
 }
+export interface InternalArgOption {
+  nullable?: boolean;
+  onlyApp?: boolean;
+}
 export interface InternalArgMeta {
   key: string;
   idx: number;
   type: InternalArgType;
-  option?: { nullable?: boolean };
+  option?: InternalArgOption;
 }
 
 export const getArgMetas = (
@@ -69,9 +73,11 @@ export const getArgMetas = (
 export interface InternalArgToken<T = unknown, Type extends InternalArgType = InternalArgType> {
   type: Type;
   _value: T;
+  option?: InternalArgOption;
 }
 
-const createInternalArgToken = <T, Type extends InternalArgType>(type: Type) => ({ type }) as InternalArgToken<T, Type>;
+const createInternalArgToken = <T, Type extends InternalArgType>(type: Type, option?: InternalArgOption) =>
+  (option ? { type, option } : { type }) as InternalArgToken<T, Type>;
 
 export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPrimitiveArgType => {
   if (type === String) return "string";
@@ -93,6 +99,9 @@ export type Lib = LibExecutor;
 export const Sys = createInternalArgToken<SysExecutor, "Sys">("Sys");
 export type Sys = SysExecutor;
 
+/** Sys, except that a one-app workspace given no name means its app, as with App. */
+export const SysOrOnlyApp = createInternalArgToken<SysExecutor, "Sys">("Sys", { onlyApp: true });
+
 export const Exec = createInternalArgToken<Executor, "Exec">("Exec");
 export type Exec = Executor;