@solana-mobile/dapp-store-publishing-tools 0.16.0 → 1.0.0

package/src/portal/workflow/lifecycle.ts

@@ -0,0 +1,435 @@
+import { randomUUID } from "node:crypto";
+
+import type {
+  PublicationBundle,
+  PublicationCleanupReleaseResult,
+  PublicationGetSessionInput,
+  PublicationSession,
+} from "../types.js";
+import type {
+  PublicationResumeInput,
+  PublicationWorkflowClient,
+  PublicationWorkflowInput,
+  PublicationWorkflowOptions,
+  PublicationWorkflowPollOptions,
+} from "./contracts.js";
+import { runPublicationWorkflow } from "./execution.js";
+import { waitForIngestionSessionReady } from "./ingestion.js";
+import { logWorkflowInfo } from "./logging.js";
+import {
+  hasResolvableReleaseMetadataUri,
+  normalizePublicationBundle,
+  validatePublicationBundle,
+  withPublicationBundleIdentifiers,
+} from "./state/bundle.js";
+import { normalizePublicationSession } from "./state/session.js";
+import { preparePublicationSource } from "./source/preparation.js";
+
+function normalizeWorkflowError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function resolvePublicationSessionLookup(input: {
+  publicationSessionId?: string | null;
+  releaseId?: string;
+}): PublicationGetSessionInput {
+  if (input.publicationSessionId) {
+    return {
+      publicationSessionId: input.publicationSessionId,
+    };
+  }
+
+  if (!input.releaseId) {
+    throw new Error(
+      "releaseId is required when publicationSessionId is absent"
+    );
+  }
+
+  return {
+    releaseId: input.releaseId,
+  };
+}
+
+async function loadPublicationSession(
+  client: PublicationWorkflowClient,
+  input: {
+    publicationSessionId?: string | null;
+    releaseId?: string;
+    existingSession?: PublicationSession;
+    startMessage: string;
+    completeMessage: string;
+  },
+  options: PublicationWorkflowOptions
+): Promise<PublicationSession> {
+  logWorkflowInfo(options.logger, input.startMessage, {
+    step: "session.load",
+    status: "running",
+    releaseId: input.releaseId,
+    publicationSessionId: input.publicationSessionId ?? undefined,
+  });
+
+  const publicationSession =
+    input.existingSession ??
+    normalizePublicationSession(
+      await client.getPublicationSession(
+        resolvePublicationSessionLookup({
+          publicationSessionId: input.publicationSessionId,
+          releaseId: input.releaseId,
+        })
+      )
+    );
+
+  logWorkflowInfo(options.logger, input.completeMessage, {
+    step: "session.load",
+    status: "complete",
+    releaseId: publicationSession.releaseId,
+    publicationSessionId: publicationSession.id,
+    stage: publicationSession.stage,
+  });
+
+  return publicationSession;
+}
+
+async function loadPublicationBundle(
+  client: PublicationWorkflowClient,
+  input: {
+    releaseId: string;
+    publicationSessionId?: string | null;
+    ingestionSessionId?: string | null;
+    existingBundle?: PublicationBundle | null;
+    existingSession?: PublicationSession;
+  },
+  options: PublicationWorkflowOptions
+): Promise<PublicationBundle> {
+  logWorkflowInfo(options.logger, "Loading publication bundle", {
+    step: "bundle.load",
+    status: "running",
+    releaseId: input.releaseId,
+  });
+
+  const publicationBundle =
+    input.existingBundle &&
+    hasResolvableReleaseMetadataUri(input.existingBundle, input.existingSession)
+      ? input.existingBundle
+      : withPublicationBundleIdentifiers(
+          normalizePublicationBundle(
+            await client.getPublicationBundle({
+              releaseId: input.releaseId,
+            })
+          ),
+          {
+            releaseId: input.releaseId,
+            publicationSessionId: input.publicationSessionId ?? null,
+            ingestionSessionId: input.ingestionSessionId ?? null,
+          }
+        );
+
+  validatePublicationBundle(publicationBundle);
+
+  logWorkflowInfo(options.logger, "Publication bundle loaded", {
+    step: "bundle.load",
+    status: "complete",
+    releaseId: input.releaseId,
+    androidPackage: publicationBundle.release.androidPackage,
+    versionName: publicationBundle.release.versionName,
+  });
+
+  return publicationBundle;
+}
+
+async function recoverPublicationResult(
+  client: PublicationWorkflowClient,
+  releaseId: string,
+  input: Pick<PublicationWorkflowInput, "signer" | "attestationClient">,
+  options: PublicationWorkflowOptions
+) {
+  logWorkflowInfo(options.logger, "Recovering final publication state", {
+    step: "cleanup.recover",
+    status: "running",
+    releaseId,
+  });
+
+  const publicationSession = normalizePublicationSession(
+    await client.getPublicationSession({
+      releaseId,
+    })
+  );
+  const publicationBundle = withPublicationBundleIdentifiers(
+    normalizePublicationBundle(
+      await client.getPublicationBundle({
+        releaseId,
+      })
+    ),
+    {
+      releaseId,
+      publicationSessionId: publicationSession.id,
+      ingestionSessionId: publicationSession.ingestionSessionId ?? null,
+    }
+  );
+
+  logWorkflowInfo(options.logger, "Recovered final publication state", {
+    step: "cleanup.recover",
+    status: "complete",
+    releaseId,
+    publicationSessionId: publicationSession.id,
+    stage: publicationSession.stage,
+  });
+
+  return runPublicationWorkflow(
+    client,
+    publicationBundle,
+    input.signer,
+    input.attestationClient,
+    publicationSession,
+    options.logger
+  );
+}
+
+async function cleanupFailedRelease(
+  client: PublicationWorkflowClient,
+  releaseId: string,
+  error: Error,
+  options: PublicationWorkflowOptions
+): Promise<PublicationCleanupReleaseResult | null> {
+  if (!client.cleanupRelease) {
+    return null;
+  }
+
+  options.logger?.warn?.("Rolling back failed publication release", {
+    step: "cleanup.release",
+    status: "running",
+    releaseId,
+    error: error.message,
+  });
+
+  const cleanupResult = await client.cleanupRelease({
+    releaseId,
+  });
+
+  const message =
+    cleanupResult.action === "deleted"
+      ? "Failed publication release cleaned up"
+      : "Publication already reached the submitted state; preserving release";
+
+  logWorkflowInfo(options.logger, message, {
+    step: "cleanup.release",
+    status: "complete",
+    releaseId,
+    action: cleanupResult.action,
+  });
+
+  return cleanupResult;
+}
+
+export const createPublicationWorkflow = (
+  client: PublicationWorkflowClient,
+  options: PublicationWorkflowOptions = {}
+) => {
+  const pollOptions: PublicationWorkflowPollOptions = {
+    pollIntervalMs: options.pollIntervalMs ?? 2500,
+    // Large APK ingestion can legitimately take tens of minutes once upload,
+    // managed-storage download, hashing, aapt2, and apksigner are included.
+    // Keep the default wait aligned with the portal queue headroom instead of
+    // failing after only ~5 minutes.
+    maxPollAttempts: options.maxPollAttempts ?? 1080,
+  };
+
+  return {
+    async startPublication(input: PublicationWorkflowInput) {
+      let createdReleaseId: string | undefined;
+      let createdIngestionSessionId: string | undefined;
+
+      try {
+        logWorkflowInfo(options.logger, "Preparing publication source", {
+          step: "source.prepare",
+          status: "running",
+        });
+
+        const source = await preparePublicationSource(
+          client,
+          input.source,
+          options.logger
+        );
+
+        logWorkflowInfo(options.logger, "Creating ingestion session", {
+          step: "ingestion.create",
+          status: "running",
+        });
+
+        const ingestionSession = await client.createIngestionSession({
+          source,
+          whatsNew: input.whatsNew,
+          idempotencyKey: input.idempotencyKey ?? randomUUID(),
+          ...(input.dappId ? { dappId: input.dappId } : {}),
+        });
+
+        createdReleaseId =
+          ingestionSession.releaseId ??
+          ingestionSession.bundle?.releaseId ??
+          undefined;
+        createdIngestionSessionId = ingestionSession.id?.trim();
+
+        if (!createdIngestionSessionId) {
+          throw new Error(
+            "Portal createIngestionSession did not return an ingestion session id"
+          );
+        }
+
+        logWorkflowInfo(options.logger, "Ingestion session created", {
+          step: "ingestion.create",
+          status: "complete",
+          ingestionSessionId: createdIngestionSessionId,
+          releaseId: createdReleaseId,
+        });
+
+        const readySession = await waitForIngestionSessionReady(
+          client,
+          createdIngestionSessionId,
+          pollOptions,
+          options.logger
+        );
+
+        const releaseId =
+          readySession.releaseId ?? readySession.bundle?.releaseId ?? undefined;
+        if (!releaseId) {
+          throw new Error(
+            "Publication ingestion completed without a release identifier"
+          );
+        }
+        createdReleaseId = releaseId;
+
+        const readyPublicationSession = readySession.publicationSession
+          ? normalizePublicationSession(readySession.publicationSession)
+          : undefined;
+
+        const readyPublicationBundle = readySession.bundle
+          ? withPublicationBundleIdentifiers(
+              normalizePublicationBundle(readySession.bundle),
+              {
+                releaseId,
+                publicationSessionId: readySession.publicationSessionId ?? null,
+                ingestionSessionId: readySession.id,
+              }
+            )
+          : null;
+
+        const publicationBundle = await loadPublicationBundle(
+          client,
+          {
+            releaseId,
+            publicationSessionId: readySession.publicationSessionId ?? null,
+            ingestionSessionId: readySession.id,
+            existingBundle: readyPublicationBundle,
+            existingSession: readyPublicationSession,
+          },
+          options
+        );
+
+        const publicationSession = await loadPublicationSession(
+          client,
+          {
+            releaseId,
+            publicationSessionId: readySession.publicationSessionId ?? null,
+            existingSession: readyPublicationSession,
+            startMessage: "Loading publication session",
+            completeMessage: "Publication session loaded",
+          },
+          options
+        );
+
+        return await runPublicationWorkflow(
+          client,
+          publicationBundle,
+          input.signer,
+          input.attestationClient,
+          publicationSession,
+          options.logger
+        );
+      } catch (error) {
+        const normalizedError = normalizeWorkflowError(error);
+
+        if (!createdReleaseId && createdIngestionSessionId) {
+          try {
+            const failedIngestionSession = await client.getIngestionSession({
+              sessionId: createdIngestionSessionId,
+              ingestionSessionId: createdIngestionSessionId,
+            });
+            createdReleaseId =
+              failedIngestionSession.releaseId ??
+              failedIngestionSession.bundle?.releaseId ??
+              undefined;
+          } catch {
+            // Ignore follow-up lookup failures and rethrow the original error.
+          }
+        }
+
+        if (!createdReleaseId) {
+          throw normalizedError;
+        }
+
+        try {
+          const cleanupResult = await cleanupFailedRelease(
+            client,
+            createdReleaseId,
+            normalizedError,
+            options
+          );
+
+          if (cleanupResult?.action === "preservedSubmitted") {
+            return await recoverPublicationResult(
+              client,
+              createdReleaseId,
+              input,
+              options
+            );
+          }
+        } catch (cleanupError) {
+          const normalizedCleanupError = normalizeWorkflowError(cleanupError);
+          throw new Error(
+            `${normalizedError.message} Cleanup also failed for release ${createdReleaseId}: ${normalizedCleanupError.message}`
+          );
+        }
+
+        throw normalizedError;
+      }
+    },
+
+    async resumePublication(input: PublicationResumeInput) {
+      if (!input.publicationSessionId && !input.releaseId) {
+        throw new Error(
+          "Publication session id or release id is required to resume a publication"
+        );
+      }
+
+      const publicationSession = await loadPublicationSession(
+        client,
+        {
+          publicationSessionId: input.publicationSessionId ?? null,
+          releaseId: input.releaseId,
+          startMessage: "Loading existing publication session",
+          completeMessage: "Existing publication session loaded",
+        },
+        options
+      );
+
+      const publicationBundle = await loadPublicationBundle(
+        client,
+        {
+          releaseId: publicationSession.releaseId,
+          publicationSessionId: publicationSession.id,
+          ingestionSessionId: publicationSession.ingestionSessionId ?? null,
+        },
+        options
+      );
+
+      return runPublicationWorkflow(
+        client,
+        publicationBundle,
+        input.signer,
+        input.attestationClient,
+        publicationSession,
+        options.logger
+      );
+    },
+  };
+};

package/src/portal/workflow/logging.ts

@@ -0,0 +1,17 @@
+import type { PublicationWorkflowLogger } from "../types.js";
+
+export function logWorkflowInfo(
+  logger: PublicationWorkflowLogger | undefined,
+  message: string,
+  metadata?: Record<string, unknown>
+) {
+  logger?.info?.(message, metadata);
+}
+
+export function logWorkflowDebug(
+  logger: PublicationWorkflowLogger | undefined,
+  message: string,
+  metadata?: Record<string, unknown>
+) {
+  logger?.debug?.(message, metadata);
+}

package/src/portal/workflow/source/files.ts

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { basename } from "node:path";
+
+export function ensureApkFileName(fileName: string): string {
+  return /\.apk$/i.test(fileName) ? fileName : `${fileName}.apk`;
+}
+
+export function inferFileNameFromUrl(url: string): string {
+  try {
+    const pathname = new URL(url).pathname;
+    const fileName = basename(pathname);
+    return fileName.length > 0 ? fileName : "release.apk";
+  } catch {
+    return "release.apk";
+  }
+}
+
+export function normalizeLocalFileAccessError(
+  filePath: string,
+  error: unknown
+): Error {
+  const code =
+    error && typeof error === "object" && "code" in error
+      ? String((error as { code?: unknown }).code || "")
+      : "";
+
+  if (code === "EPERM" || code === "EACCES") {
+    return new Error(
+      `Cannot read local APK at ${filePath}. macOS denied access to this location (${code}). Move the APK out of Downloads into your workspace or another accessible folder, or grant this app Full Disk Access, then retry.`
+    );
+  }
+
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export async function hashFileSha256(filePath: string): Promise<string> {
+  const hash = createHash("sha256");
+
+  try {
+    for await (const chunk of createReadStream(filePath)) {
+      hash.update(chunk);
+    }
+  } catch (error) {
+    throw normalizeLocalFileAccessError(filePath, error);
+  }
+
+  return hash.digest("hex");
+}

package/src/portal/workflow/source/preparation.ts

@@ -0,0 +1,189 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { Transform } from "node:stream";
+
+import type {
+  PublicationCreateIngestionSessionInput,
+  PublicationSource,
+  PublicationWorkflowLogger,
+} from "../../types.js";
+import type { PublicationWorkflowClient } from "../contracts.js";
+import { logWorkflowDebug, logWorkflowInfo } from "../logging.js";
+import {
+  ensureApkFileName,
+  hashFileSha256,
+  inferFileNameFromUrl,
+  normalizeLocalFileAccessError,
+} from "./files.js";
+
+const DEFAULT_APK_CONTENT_TYPE = "application/vnd.android.package-archive";
+
+async function uploadLocalApkToPortal(
+  client: PublicationWorkflowClient,
+  source: Extract<PublicationSource, { kind: "apk-file" }>,
+  logger?: PublicationWorkflowLogger
+): Promise<PublicationCreateIngestionSessionInput["source"]> {
+  const createUploadTarget = client.createUploadTarget;
+  if (!createUploadTarget) {
+    throw new Error(
+      "Local apk-file sources require a createUploadTarget client method"
+    );
+  }
+
+  const fileStat = await stat(source.filePath).catch((error) => {
+    throw normalizeLocalFileAccessError(source.filePath, error);
+  });
+  const contentType = source.mimeType ?? DEFAULT_APK_CONTENT_TYPE;
+  const fileHash = await hashFileSha256(source.filePath);
+  const fileName = ensureApkFileName(
+    source.fileName || basename(source.filePath)
+  );
+
+  logWorkflowInfo(logger, "Uploading APK to portal storage", {
+    step: "source.upload",
+    status: "running",
+    fileName,
+    filePath: source.filePath,
+    fileSize: fileStat.size,
+  });
+
+  const uploadTarget = await createUploadTarget({
+    fileHash,
+    fileExtension: "apk",
+    contentType,
+  });
+
+  const totalBytes = fileStat.size;
+  let uploadedBytes = 0;
+  let lastLoggedBytes = 0;
+  let lastLoggedAt = 0;
+
+  const emitUploadProgress = (force = false) => {
+    const now = Date.now();
+    const progress = totalBytes > 0 ? uploadedBytes / totalBytes : 1;
+    const byteDelta = uploadedBytes - lastLoggedBytes;
+    const minByteDelta = Math.max(256 * 1024, Math.floor(totalBytes * 0.01));
+    const shouldLog =
+      force ||
+      uploadedBytes >= totalBytes ||
+      now - lastLoggedAt >= 250 ||
+      byteDelta >= minByteDelta;
+
+    if (!shouldLog) {
+      return;
+    }
+
+    lastLoggedAt = now;
+    lastLoggedBytes = uploadedBytes;
+
+    logWorkflowDebug(logger, "Uploading APK to portal storage", {
+      step: "source.upload",
+      status: "running",
+      fileName,
+      filePath: source.filePath,
+      fileSize: totalBytes,
+      bytesUploaded: uploadedBytes,
+      bytesTotal: totalBytes,
+      stepProgress: progress,
+    });
+  };
+
+  const uploadBody = createReadStream(source.filePath).pipe(
+    new Transform({
+      transform(chunk, _encoding, callback) {
+        uploadedBytes += chunk.length;
+        emitUploadProgress();
+        callback(null, chunk);
+      },
+    })
+  );
+
+  const uploadResponse = await fetch(uploadTarget.uploadUrl, {
+    method: "PUT",
+    headers: {
+      "content-type": contentType,
+      "content-length": String(totalBytes),
+    },
+    body: uploadBody,
+    duplex: "half",
+  } as RequestInit & { duplex: "half" });
+
+  if (!uploadResponse.ok) {
+    throw new Error(
+      `Failed to upload APK to portal storage: ${uploadResponse.status} ${uploadResponse.statusText}`
+    );
+  }
+
+  uploadedBytes = totalBytes;
+  emitUploadProgress(true);
+
+  logWorkflowInfo(logger, "APK uploaded to portal storage", {
+    step: "source.upload",
+    status: "complete",
+    fileName,
+    publicUrl: uploadTarget.publicUrl,
+  });
+
+  return {
+    kind: "portalUpload",
+    releaseFileUrl: uploadTarget.publicUrl,
+    releaseFileName: fileName,
+    releaseFileSize: fileStat.size,
+    releaseFileHash: fileHash,
+    contentType,
+  };
+}
+
+export async function preparePublicationSource(
+  client: PublicationWorkflowClient,
+  source: PublicationSource,
+  logger?: PublicationWorkflowLogger
+): Promise<PublicationCreateIngestionSessionInput["source"]> {
+  switch (source.kind) {
+    case "portalUpload":
+      logWorkflowInfo(logger, "Using portal-hosted APK source", {
+        step: "source.ready",
+        status: "complete",
+        fileName: source.releaseFileName,
+      });
+      return source;
+    case "externalUrl":
+      logWorkflowInfo(logger, "Using external APK URL", {
+        step: "source.ready",
+        status: "complete",
+        fileName: source.releaseFileName ?? inferFileNameFromUrl(source.apkUrl),
+        apkUrl: source.apkUrl,
+      });
+      return source;
+    case "existingRelease":
+      logWorkflowInfo(logger, "Using an existing release as the source", {
+        step: "source.ready",
+        status: "complete",
+        sourceReleaseId: source.sourceReleaseId,
+      });
+      return source;
+    case "apk-url":
+      logWorkflowInfo(logger, "Preparing external APK URL", {
+        step: "source.ready",
+        status: "running",
+        fileName:
+          source.fileName ??
+          inferFileNameFromUrl(source.canonicalUrl ?? source.url),
+        apkUrl: source.canonicalUrl ?? source.url,
+      });
+      return {
+        kind: "externalUrl",
+        apkUrl: source.canonicalUrl ?? source.url,
+        releaseFileName:
+          source.fileName ??
+          inferFileNameFromUrl(source.canonicalUrl ?? source.url),
+      };
+    case "apk-file":
+      return uploadLocalApkToPortal(client, source, logger);
+    default: {
+      const exhaustiveCheck: never = source;
+      return exhaustiveCheck;
+    }
+  }
+}