@verdaccio/store 9.0.0-next-9.28 → 9.0.0-next-9.30

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export { Storage } from './storage';
+export * from './stage-storage';
 export { applyManifestFilters, loadFilterPlugins } from './filter-pipeline';
 export type { Filters } from './filter-pipeline';
 export * from './lib/storage-utils';

package/build/index.js

@@ -6,8 +6,11 @@ const require_filter_pipeline = require("./filter-pipeline.js");
 const require_publish_utils = require("./lib/publish-utils.js");
 const require_versions_utils = require("./lib/versions-utils.js");
 const require_storage_utils = require("./lib/storage-utils.js");
+const require_stage_storage = require("./stage-storage.js");
 const require_storage = require("./storage.js");
+exports.STAGE_NAMESPACE = require_stage_storage.STAGE_NAMESPACE;
 exports.STORAGE = require_storage_utils.STORAGE;
+exports.StageStorage = require_stage_storage.StageStorage;
 exports.Storage = require_storage.Storage;
 exports.WHITELIST = require_storage_utils.WHITELIST;
 exports.applyManifestFilters = require_filter_pipeline.applyManifestFilters;
@@ -35,4 +38,5 @@ exports.removeLowerVersions = require_versions_utils.removeLowerVersions;
 exports.sortVersionsAndFilterInvalid = require_versions_utils.sortVersionsAndFilterInvalid;
 exports.tagVersion = require_versions_utils.tagVersion;
 exports.tagVersionNext = require_versions_utils.tagVersionNext;
+exports.toStagePackageVersion = require_stage_storage.toStagePackageVersion;
 exports.updateUpLinkMetadata = require_storage_utils.updateUpLinkMetadata;

package/build/index.mjs

@@ -2,5 +2,6 @@ import { applyManifestFilters, loadFilterPlugins } from "./filter-pipeline.mjs";
 import { isPublishablePackage } from "./lib/publish-utils.mjs";
 import { getVersion, isNewerVersion, removeLowerVersions, sortVersionsAndFilterInvalid, tagVersion, tagVersionNext } from "./lib/versions-utils.mjs";
 import { STORAGE, WHITELIST, checkPackageRemote, cleanUpLinksRef, cleanUpReadme, generatePackageTemplate, generateRevision, getLatestReadme, hasDeprecatedVersions, isDeprecatedManifest, mapManifestToSearchPackageBody, mergeUplinkTimeIntoLocal, mergeUplinkTimeIntoLocalNext, mergeVersions, normalizeContributors, normalizeDistTags, normalizePackage, prepareSearchPackage, updateUpLinkMetadata } from "./lib/storage-utils.mjs";
+import { STAGE_NAMESPACE, StageStorage, toStagePackageVersion } from "./stage-storage.mjs";
 import { Storage } from "./storage.mjs";
-export { STORAGE, Storage, WHITELIST, applyManifestFilters, checkPackageRemote, cleanUpLinksRef, cleanUpReadme, generatePackageTemplate, generateRevision, getLatestReadme, getVersion, hasDeprecatedVersions, isDeprecatedManifest, isNewerVersion, isPublishablePackage, loadFilterPlugins, mapManifestToSearchPackageBody, mergeUplinkTimeIntoLocal, mergeUplinkTimeIntoLocalNext, mergeVersions, normalizeContributors, normalizeDistTags, normalizePackage, prepareSearchPackage, removeLowerVersions, sortVersionsAndFilterInvalid, tagVersion, tagVersionNext, updateUpLinkMetadata };
+export { STAGE_NAMESPACE, STORAGE, StageStorage, Storage, WHITELIST, applyManifestFilters, checkPackageRemote, cleanUpLinksRef, cleanUpReadme, generatePackageTemplate, generateRevision, getLatestReadme, getVersion, hasDeprecatedVersions, isDeprecatedManifest, isNewerVersion, isPublishablePackage, loadFilterPlugins, mapManifestToSearchPackageBody, mergeUplinkTimeIntoLocal, mergeUplinkTimeIntoLocalNext, mergeVersions, normalizeContributors, normalizeDistTags, normalizePackage, prepareSearchPackage, removeLowerVersions, sortVersionsAndFilterInvalid, tagVersion, tagVersionNext, toStagePackageVersion, updateUpLinkMetadata };

package/build/lib/storage-utils.d.ts

@@ -61,7 +61,7 @@ export declare function updateUpLinkMetadata(uplinkName: string, manifest: Manif
     _attachments: import("@verdaccio/types").AttachMents;
     publisher?: import("@verdaccio/types").Publisher;
     publishedPackage?: string;
-    publishType?: 'publish' | 'unpublish';
+    publishType?: 'publish' | 'unpublish' | 'stage' | 'unstage';
     _uplinks: {
         [x: string]: import("@verdaccio/types").UpLinkMetadata | {
             etag: string;

package/build/stage-storage.d.ts

@@ -0,0 +1,120 @@
+import { Readable } from 'node:stream';
+import type { pluginUtils } from '@verdaccio/core';
+import type { Logger, Manifest } from '@verdaccio/types';
+/**
+ * Storage namespace holding every staged item.
+ *
+ * It is deliberately NOT registered through `storagePlugin.add()`: doing so
+ * would list it in the plugin database and leak it into search results and the
+ * web UI package list. The staged items are enumerated through {@link STAGE_INDEX}
+ * instead.
+ */
+export declare const STAGE_NAMESPACE = ".stage";
+/**
+ * Metadata of a package version awaiting review.
+ *
+ * Mirrors the `StagePackageVersion` schema documented by npmjs, plus
+ * {@link StageRecord.tarballFilename}, which is internal and must be stripped
+ * before serving the record over the API (see {@link toStagePackageVersion}).
+ */
+export interface StageRecord {
+    /** Unique identifier. Must be a UUID: the npm CLI validates the format client side. */
+    id: string;
+    packageName: string;
+    version: string;
+    /** dist-tag the version will be published under once approved. */
+    tag: string;
+    /** ISO timestamp of when the version was staged. */
+    createdAt: string;
+    /** Username of whoever staged the version. */
+    actor: string;
+    actorType: 'user';
+    access: 'public' | 'private';
+    /** sha1 of the tarball, as reported by `npm stage list`. */
+    shasum: string;
+    /** Internal: name of the tarball inside the staged item folder. */
+    tarballFilename: string;
+}
+/** Shape served to clients: {@link StageRecord} without the internal fields. */
+export type StagePackageVersion = Omit<StageRecord, 'tarballFilename'>;
+/**
+ * The publish payload kept for a staged item, minus `_attachments` (the tarball
+ * is stored separately as a real tarball, not as base64 inside this document).
+ */
+export type StagedPackument = Omit<Manifest, '_attachments'>;
+export interface AddStageInput {
+    packageName: string;
+    version: string;
+    tag: string;
+    actor: string;
+    access: 'public' | 'private';
+    shasum: string;
+    tarballFilename: string;
+    packument: StagedPackument;
+}
+export interface ListStageFilter {
+    /** Restrict the result to a single package name. */
+    packageName?: string;
+}
+/** Strip the internal fields before the record leaves the registry. */
+export declare function toStagePackageVersion(record: StageRecord): StagePackageVersion;
+/**
+ * Persistence for the staged publish workflow (`npm stage`).
+ *
+ * Everything goes through {@link pluginUtils.StorageHandler}, so it works with
+ * any storage plugin (local-storage, memory, S3, GCS) without the plugin having
+ * to know that staging exists. On disk it looks like:
+ *
+ * ```
+ * <storage>/.stage/package.json            index of every staged item
+ * <storage>/.stage/<uuid>/package.json     the staged item (record + packument)
+ * <storage>/.stage/<uuid>/<name>-<v>.tgz   the staged tarball
+ * ```
+ */
+export declare class StageStorage {
+    private readonly plugin;
+    private readonly logger;
+    /**
+     * Serializes index mutations within this process.
+     *
+     * `StorageHandler.updatePackage()` takes a lock in local-storage but releases
+     * it before we get to save, and other plugins do not lock at all, so a
+     * read-modify-write on the index would race. This keeps a single Verdaccio
+     * process consistent; several processes sharing one storage backend are NOT
+     * supported.
+     */
+    private indexQueue;
+    constructor(plugin: pluginUtils.Storage<any>, logger: Logger);
+    /** Stage a new version. Returns the persisted record, including its generated id. */
+    add(input: AddStageInput, tarball: Buffer, { signal }: {
+        signal: AbortSignal;
+    }): Promise<StageRecord>;
+    /** Every staged item, newest first, optionally narrowed to one package. */
+    list(filter?: ListStageFilter): Promise<StageRecord[]>;
+    /** A single staged item, or `undefined` when the id is unknown. */
+    get(id: string): Promise<StageRecord | undefined>;
+    /** Whether a version of a package is already staged (used to answer 409). */
+    findByVersion(packageName: string, version: string): Promise<StageRecord | undefined>;
+    /** The publish payload kept for a staged item, needed to approve it. */
+    getPackument(id: string): Promise<StagedPackument | undefined>;
+    /** Read the staged tarball as a stream. */
+    readTarball(id: string, { signal }: {
+        signal: AbortSignal;
+    }): Promise<Readable>;
+    /**
+     * Drop a staged item and its tarball.
+     *
+     * @returns `false` when the id was unknown, `true` when something was removed.
+     */
+    remove(id: string): Promise<boolean>;
+    private itemStorage;
+    private indexStorage;
+    private readDocument;
+    private readIndex;
+    /** Read-modify-write the index, serialized against other callers (see {@link indexQueue}). */
+    private updateIndex;
+    private enqueueIndexMutation;
+    private writeIndex;
+    private writeTarball;
+    private waitForTarball;
+}

package/build/stage-storage.js

@@ -0,0 +1,207 @@
+const require_runtime = require("./_virtual/_rolldown/runtime.js");
+const require_storage_utils = require("./lib/storage-utils.js");
+let debug = require("debug");
+debug = require_runtime.__toESM(debug);
+let node_stream = require("node:stream");
+let node_stream_promises = require("node:stream/promises");
+let _verdaccio_core = require("@verdaccio/core");
+let node_crypto = require("node:crypto");
+//#region src/stage-storage.ts
+var debug$1 = (0, debug.default)("verdaccio:storage:stage");
+/**
+* Storage namespace holding every staged item.
+*
+* It is deliberately NOT registered through `storagePlugin.add()`: doing so
+* would list it in the plugin database and leak it into search results and the
+* web UI package list. The staged items are enumerated through {@link STAGE_INDEX}
+* instead.
+*/
+var STAGE_NAMESPACE = ".stage";
+/**
+* Logical name used when reading/writing the index document. Storage handlers
+* are scoped to a folder and ignore this argument when resolving the path, but
+* it is what shows up in plugin logs, so keep it descriptive.
+*/
+var STAGE_INDEX = "stage-index";
+/** Strip the internal fields before the record leaves the registry. */
+function toStagePackageVersion(record) {
+	const { tarballFilename: _tarballFilename, ...rest } = record;
+	return rest;
+}
+function isNotFound(err) {
+	return err?.code === "ENOENT" || err?.code === 404 || err?.status === 404;
+}
+/**
+* Persistence for the staged publish workflow (`npm stage`).
+*
+* Everything goes through {@link pluginUtils.StorageHandler}, so it works with
+* any storage plugin (local-storage, memory, S3, GCS) without the plugin having
+* to know that staging exists. On disk it looks like:
+*
+* ```
+* <storage>/.stage/package.json            index of every staged item
+* <storage>/.stage/<uuid>/package.json     the staged item (record + packument)
+* <storage>/.stage/<uuid>/<name>-<v>.tgz   the staged tarball
+* ```
+*/
+var StageStorage = class {
+	plugin;
+	logger;
+	/**
+	* Serializes index mutations within this process.
+	*
+	* `StorageHandler.updatePackage()` takes a lock in local-storage but releases
+	* it before we get to save, and other plugins do not lock at all, so a
+	* read-modify-write on the index would race. This keeps a single Verdaccio
+	* process consistent; several processes sharing one storage backend are NOT
+	* supported.
+	*/
+	indexQueue = Promise.resolve();
+	constructor(plugin, logger) {
+		this.plugin = plugin;
+		this.logger = logger;
+	}
+	/** Stage a new version. Returns the persisted record, including its generated id. */
+	async add(input, tarball, { signal }) {
+		if (_verdaccio_core.validationUtils.validateName(input.tarballFilename) === false) throw _verdaccio_core.errorUtils.getBadRequest(`invalid tarball name ${input.tarballFilename}`);
+		const record = {
+			id: (0, node_crypto.randomUUID)(),
+			packageName: input.packageName,
+			version: input.version,
+			tag: input.tag,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			actor: input.actor,
+			actorType: "user",
+			access: input.access,
+			shasum: input.shasum,
+			tarballFilename: input.tarballFilename
+		};
+		debug$1("staging %o@%o as %o", record.packageName, record.version, record.id);
+		return this.enqueueIndexMutation(async () => {
+			const items = await this.readIndex();
+			if (items.find((item) => item.packageName === record.packageName && item.version === record.version)) throw _verdaccio_core.errorUtils.getConflict(`${record.packageName}@${record.version} is already staged`);
+			const handler = this.itemStorage(record.id);
+			await this.writeTarball(handler, record.tarballFilename, tarball, { signal });
+			const document = {
+				record,
+				packument: input.packument
+			};
+			await handler.savePackage(record.id, document);
+			await this.writeIndex([record, ...items]);
+			this.logger.info({
+				packageName: record.packageName,
+				version: record.version,
+				stageId: record.id
+			}, "staged @{packageName}@@{version} as @{stageId}");
+			return record;
+		});
+	}
+	/** Every staged item, newest first, optionally narrowed to one package. */
+	async list(filter = {}) {
+		const items = await this.readIndex();
+		if (typeof filter.packageName === "string") return items.filter((item) => item.packageName === filter.packageName);
+		return items;
+	}
+	/** A single staged item, or `undefined` when the id is unknown. */
+	async get(id) {
+		return (await this.readIndex()).find((item) => item.id === id);
+	}
+	/** Whether a version of a package is already staged (used to answer 409). */
+	async findByVersion(packageName, version) {
+		return (await this.readIndex()).find((item) => item.packageName === packageName && item.version === version);
+	}
+	/** The publish payload kept for a staged item, needed to approve it. */
+	async getPackument(id) {
+		return (await this.readDocument(id))?.packument;
+	}
+	/** Read the staged tarball as a stream. */
+	async readTarball(id, { signal }) {
+		const record = await this.get(id);
+		if (!record) throw _verdaccio_core.errorUtils.getNotFound("no such staged package version");
+		return this.itemStorage(id).readTarball(record.tarballFilename, { signal });
+	}
+	/**
+	* Drop a staged item and its tarball.
+	*
+	* @returns `false` when the id was unknown, `true` when something was removed.
+	*/
+	async remove(id) {
+		const record = await this.get(id);
+		if (!record) return false;
+		const handler = this.itemStorage(id);
+		await this.updateIndex((items) => items.filter((item) => item.id !== id));
+		for (const file of [record.tarballFilename, require_storage_utils.STORAGE.PACKAGE_FILE_NAME]) try {
+			await handler.deletePackage(file);
+		} catch (err) {
+			debug$1("could not delete staged file %o: %s", file, err?.message);
+		}
+		try {
+			await handler.removePackage(id);
+		} catch (err) {
+			debug$1("could not delete staged folder %o: %s", id, err?.message);
+		}
+		debug$1("removed staged item %o", id);
+		return true;
+	}
+	itemStorage(id) {
+		return this.plugin.getPackageStorage(`${STAGE_NAMESPACE}/${id}`);
+	}
+	indexStorage() {
+		return this.plugin.getPackageStorage(STAGE_NAMESPACE);
+	}
+	async readDocument(id) {
+		try {
+			return await this.itemStorage(id).readPackage(id);
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+	}
+	async readIndex() {
+		try {
+			const index = await this.indexStorage().readPackage(STAGE_INDEX);
+			return Array.isArray(index?.items) ? index.items : [];
+		} catch (err) {
+			if (isNotFound(err)) {
+				debug$1("no stage index yet");
+				return [];
+			}
+			throw err;
+		}
+	}
+	/** Read-modify-write the index, serialized against other callers (see {@link indexQueue}). */
+	async updateIndex(mutate) {
+		return this.enqueueIndexMutation(async () => {
+			const items = mutate(await this.readIndex());
+			await this.writeIndex(items);
+			return items;
+		});
+	}
+	async enqueueIndexMutation(run) {
+		const queued = this.indexQueue.then(run, run);
+		this.indexQueue = queued.catch(() => void 0);
+		return queued;
+	}
+	async writeIndex(items) {
+		const index = { items };
+		await this.indexStorage().savePackage(STAGE_INDEX, index);
+	}
+	async writeTarball(handler, filename, tarball, { signal }) {
+		const writeStream = await handler.writeTarball(filename, { signal });
+		await (0, node_stream_promises.pipeline)(node_stream.Readable.from(tarball), writeStream);
+		await this.waitForTarball(handler, filename);
+	}
+	async waitForTarball(handler, filename, attempts = 20) {
+		for (let attempt = 0; attempt < attempts; attempt++) {
+			if (await handler.hasTarball(filename)) return;
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		}
+		throw _verdaccio_core.errorUtils.getInternalError(`staged tarball ${filename} was never persisted`);
+	}
+};
+//#endregion
+exports.STAGE_NAMESPACE = STAGE_NAMESPACE;
+exports.StageStorage = StageStorage;
+exports.toStagePackageVersion = toStagePackageVersion;
+
+//# sourceMappingURL=stage-storage.js.map

package/build/stage-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-storage.js","names":[],"sources":["../src/stage-storage.ts"],"sourcesContent":["import buildDebug from 'debug';\nimport { randomUUID } from 'node:crypto';\nimport { Readable } from 'node:stream';\nimport { pipeline } from 'node:stream/promises';\n\nimport type { pluginUtils } from '@verdaccio/core';\nimport { errorUtils, validationUtils } from '@verdaccio/core';\nimport type { Logger, Manifest } from '@verdaccio/types';\n\nimport { STORAGE } from './lib/storage-utils';\n\nconst debug = buildDebug('verdaccio:storage:stage');\n\n/**\n * Storage namespace holding every staged item.\n *\n * It is deliberately NOT registered through `storagePlugin.add()`: doing so\n * would list it in the plugin database and leak it into search results and the\n * web UI package list. The staged items are enumerated through {@link STAGE_INDEX}\n * instead.\n */\nexport const STAGE_NAMESPACE = '.stage';\n\n/**\n * Logical name used when reading/writing the index document. Storage handlers\n * are scoped to a folder and ignore this argument when resolving the path, but\n * it is what shows up in plugin logs, so keep it descriptive.\n */\nconst STAGE_INDEX = 'stage-index';\n\n/**\n * Metadata of a package version awaiting review.\n *\n * Mirrors the `StagePackageVersion` schema documented by npmjs, plus\n * {@link StageRecord.tarballFilename}, which is internal and must be stripped\n * before serving the record over the API (see {@link toStagePackageVersion}).\n */\nexport interface StageRecord {\n  /** Unique identifier. Must be a UUID: the npm CLI validates the format client side. */\n  id: string;\n  packageName: string;\n  version: string;\n  /** dist-tag the version will be published under once approved. */\n  tag: string;\n  /** ISO timestamp of when the version was staged. */\n  createdAt: string;\n  /** Username of whoever staged the version. */\n  actor: string;\n  actorType: 'user';\n  access: 'public' | 'private';\n  /** sha1 of the tarball, as reported by `npm stage list`. */\n  shasum: string;\n  /** Internal: name of the tarball inside the staged item folder. */\n  tarballFilename: string;\n}\n\n/** Shape served to clients: {@link StageRecord} without the internal fields. */\nexport type StagePackageVersion = Omit<StageRecord, 'tarballFilename'>;\n\n/**\n * The publish payload kept for a staged item, minus `_attachments` (the tarball\n * is stored separately as a real tarball, not as base64 inside this document).\n */\nexport type StagedPackument = Omit<Manifest, '_attachments'>;\n\n/** Persisted document of a single staged item. */\ninterface StageDocument {\n  record: StageRecord;\n  packument: StagedPackument;\n}\n\n/** Persisted index of every staged item, newest first. */\ninterface StageIndex {\n  items: StageRecord[];\n}\n\nexport interface AddStageInput {\n  packageName: string;\n  version: string;\n  tag: string;\n  actor: string;\n  access: 'public' | 'private';\n  shasum: string;\n  tarballFilename: string;\n  packument: StagedPackument;\n}\n\nexport interface ListStageFilter {\n  /** Restrict the result to a single package name. */\n  packageName?: string;\n}\n\n/** Strip the internal fields before the record leaves the registry. */\nexport function toStagePackageVersion(record: StageRecord): StagePackageVersion {\n  const { tarballFilename: _tarballFilename, ...rest } = record;\n  return rest;\n}\n\nfunction isNotFound(err: any): boolean {\n  return err?.code === 'ENOENT' || err?.code === 404 || err?.status === 404;\n}\n\n/**\n * Persistence for the staged publish workflow (`npm stage`).\n *\n * Everything goes through {@link pluginUtils.StorageHandler}, so it works with\n * any storage plugin (local-storage, memory, S3, GCS) without the plugin having\n * to know that staging exists. On disk it looks like:\n *\n * ```\n * <storage>/.stage/package.json            index of every staged item\n * <storage>/.stage/<uuid>/package.json     the staged item (record + packument)\n * <storage>/.stage/<uuid>/<name>-<v>.tgz   the staged tarball\n * ```\n */\nexport class StageStorage {\n  private readonly plugin: pluginUtils.Storage<any>;\n  private readonly logger: Logger;\n  /**\n   * Serializes index mutations within this process.\n   *\n   * `StorageHandler.updatePackage()` takes a lock in local-storage but releases\n   * it before we get to save, and other plugins do not lock at all, so a\n   * read-modify-write on the index would race. This keeps a single Verdaccio\n   * process consistent; several processes sharing one storage backend are NOT\n   * supported.\n   */\n  private indexQueue: Promise<unknown> = Promise.resolve();\n\n  public constructor(plugin: pluginUtils.Storage<any>, logger: Logger) {\n    this.plugin = plugin;\n    this.logger = logger;\n  }\n\n  /** Stage a new version. Returns the persisted record, including its generated id. */\n  public async add(\n    input: AddStageInput,\n    tarball: Buffer,\n    { signal }: { signal: AbortSignal }\n  ): Promise<StageRecord> {\n    // the filename reaches us from the `_attachments` key of the request, so it\n    // is attacker controlled. The regular publish path asserts the same thing\n    // before writing; without it a name like `..` escapes the item folder and\n    // the write fails inside an unawaited stream handler, taking the process\n    // down rather than the request.\n    if (validationUtils.validateName(input.tarballFilename) === false) {\n      throw errorUtils.getBadRequest(`invalid tarball name ${input.tarballFilename}`);\n    }\n\n    const record: StageRecord = {\n      id: randomUUID(),\n      packageName: input.packageName,\n      version: input.version,\n      tag: input.tag,\n      createdAt: new Date().toISOString(),\n      actor: input.actor,\n      actorType: 'user',\n      access: input.access,\n      shasum: input.shasum,\n      tarballFilename: input.tarballFilename,\n    };\n    debug('staging %o@%o as %o', record.packageName, record.version, record.id);\n\n    return this.enqueueIndexMutation(async () => {\n      const items = await this.readIndex();\n      const alreadyStaged = items.find(\n        (item) => item.packageName === record.packageName && item.version === record.version\n      );\n      if (alreadyStaged) {\n        throw errorUtils.getConflict(`${record.packageName}@${record.version} is already staged`);\n      }\n\n      const handler = this.itemStorage(record.id);\n      // the tarball goes first: if it fails there is no record pointing at a\n      // tarball that never landed.\n      await this.writeTarball(handler, record.tarballFilename, tarball, { signal });\n      const document: StageDocument = { record, packument: input.packument };\n      await handler.savePackage(record.id, document as unknown as Manifest);\n      await this.writeIndex([record, ...items]);\n\n      this.logger.info(\n        { packageName: record.packageName, version: record.version, stageId: record.id },\n        'staged @{packageName}@@{version} as @{stageId}'\n      );\n      return record;\n    });\n  }\n\n  /** Every staged item, newest first, optionally narrowed to one package. */\n  public async list(filter: ListStageFilter = {}): Promise<StageRecord[]> {\n    const items = await this.readIndex();\n    if (typeof filter.packageName === 'string') {\n      return items.filter((item) => item.packageName === filter.packageName);\n    }\n    return items;\n  }\n\n  /** A single staged item, or `undefined` when the id is unknown. */\n  public async get(id: string): Promise<StageRecord | undefined> {\n    const items = await this.readIndex();\n    return items.find((item) => item.id === id);\n  }\n\n  /** Whether a version of a package is already staged (used to answer 409). */\n  public async findByVersion(\n    packageName: string,\n    version: string\n  ): Promise<StageRecord | undefined> {\n    const items = await this.readIndex();\n    return items.find((item) => item.packageName === packageName && item.version === version);\n  }\n\n  /** The publish payload kept for a staged item, needed to approve it. */\n  public async getPackument(id: string): Promise<StagedPackument | undefined> {\n    const document = await this.readDocument(id);\n    return document?.packument;\n  }\n\n  /** Read the staged tarball as a stream. */\n  public async readTarball(id: string, { signal }: { signal: AbortSignal }): Promise<Readable> {\n    const record = await this.get(id);\n    if (!record) {\n      throw errorUtils.getNotFound('no such staged package version');\n    }\n    return this.itemStorage(id).readTarball(record.tarballFilename, { signal });\n  }\n\n  /**\n   * Drop a staged item and its tarball.\n   *\n   * @returns `false` when the id was unknown, `true` when something was removed.\n   */\n  public async remove(id: string): Promise<boolean> {\n    const record = await this.get(id);\n    if (!record) {\n      return false;\n    }\n    const handler = this.itemStorage(id);\n    // the index entry goes first: a leftover folder is invisible, whereas a\n    // leftover index entry would surface a staged item that cannot be read.\n    await this.updateIndex((items) => items.filter((item) => item.id !== id));\n    // the folder can only be dropped once it is empty, so both files go first\n    for (const file of [record.tarballFilename, STORAGE.PACKAGE_FILE_NAME]) {\n      try {\n        await handler.deletePackage(file);\n      } catch (err: any) {\n        debug('could not delete staged file %o: %s', file, err?.message);\n      }\n    }\n    try {\n      await handler.removePackage(id);\n    } catch (err: any) {\n      debug('could not delete staged folder %o: %s', id, err?.message);\n    }\n    debug('removed staged item %o', id);\n    return true;\n  }\n\n  private itemStorage(id: string): pluginUtils.StorageHandler {\n    return this.plugin.getPackageStorage(`${STAGE_NAMESPACE}/${id}`);\n  }\n\n  private indexStorage(): pluginUtils.StorageHandler {\n    return this.plugin.getPackageStorage(STAGE_NAMESPACE);\n  }\n\n  private async readDocument(id: string): Promise<StageDocument | undefined> {\n    try {\n      const document = (await this.itemStorage(id).readPackage(id)) as unknown as StageDocument;\n      return document;\n    } catch (err: any) {\n      if (isNotFound(err)) {\n        return undefined;\n      }\n      throw err;\n    }\n  }\n\n  private async readIndex(): Promise<StageRecord[]> {\n    try {\n      const index = (await this.indexStorage().readPackage(STAGE_INDEX)) as unknown as StageIndex;\n      return Array.isArray(index?.items) ? index.items : [];\n    } catch (err: any) {\n      if (isNotFound(err)) {\n        debug('no stage index yet');\n        return [];\n      }\n      throw err;\n    }\n  }\n\n  /** Read-modify-write the index, serialized against other callers (see {@link indexQueue}). */\n  private async updateIndex(\n    mutate: (items: StageRecord[]) => StageRecord[]\n  ): Promise<StageRecord[]> {\n    return this.enqueueIndexMutation(async (): Promise<StageRecord[]> => {\n      const items = mutate(await this.readIndex());\n      await this.writeIndex(items);\n      return items;\n    });\n  }\n\n  private async enqueueIndexMutation<T>(run: () => Promise<T>): Promise<T> {\n    const queued = this.indexQueue.then(run, run);\n    // keep the chain alive even when a caller rejects\n    this.indexQueue = queued.catch(() => undefined);\n    return queued;\n  }\n\n  private async writeIndex(items: StageRecord[]): Promise<void> {\n    const index: StageIndex = { items };\n    await this.indexStorage().savePackage(STAGE_INDEX, index as unknown as Manifest);\n  }\n\n  private async writeTarball(\n    handler: pluginUtils.StorageHandler,\n    filename: string,\n    tarball: Buffer,\n    { signal }: { signal: AbortSignal }\n  ): Promise<void> {\n    const writeStream = await handler.writeTarball(filename, { signal });\n\n    // `StorageHandler.writeTarball` only promises a Writable. The two bundled\n    // plugins happen to emit 'open' before accepting writes, but nothing in the\n    // interface says a plugin must, and waiting for it would hang staging\n    // forever on one that does not. Piping straight away is correct either way:\n    // a stream that is not ready yet buffers the writes.\n    await pipeline(Readable.from(tarball), writeStream);\n\n    // Both plugins rename the temporary file inside an async 'close' handler\n    // that nobody awaits, so 'close' does not guarantee the tarball is in its\n    // final place yet. Give the rename a bounded chance to land.\n    await this.waitForTarball(handler, filename);\n  }\n\n  private async waitForTarball(\n    handler: pluginUtils.StorageHandler,\n    filename: string,\n    attempts = 20\n  ): Promise<void> {\n    for (let attempt = 0; attempt < attempts; attempt++) {\n      if (await handler.hasTarball(filename)) {\n        return;\n      }\n      await new Promise((resolve) => setTimeout(resolve, 10));\n    }\n    throw errorUtils.getInternalError(`staged tarball ${filename} was never persisted`);\n  }\n}\n"],"mappings":"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"}

package/build/stage-storage.mjs

@@ -0,0 +1,203 @@
+import { STORAGE } from "./lib/storage-utils.mjs";
+import buildDebug from "debug";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { errorUtils, validationUtils } from "@verdaccio/core";
+import { randomUUID } from "node:crypto";
+//#region src/stage-storage.ts
+var debug = buildDebug("verdaccio:storage:stage");
+/**
+* Storage namespace holding every staged item.
+*
+* It is deliberately NOT registered through `storagePlugin.add()`: doing so
+* would list it in the plugin database and leak it into search results and the
+* web UI package list. The staged items are enumerated through {@link STAGE_INDEX}
+* instead.
+*/
+var STAGE_NAMESPACE = ".stage";
+/**
+* Logical name used when reading/writing the index document. Storage handlers
+* are scoped to a folder and ignore this argument when resolving the path, but
+* it is what shows up in plugin logs, so keep it descriptive.
+*/
+var STAGE_INDEX = "stage-index";
+/** Strip the internal fields before the record leaves the registry. */
+function toStagePackageVersion(record) {
+	const { tarballFilename: _tarballFilename, ...rest } = record;
+	return rest;
+}
+function isNotFound(err) {
+	return err?.code === "ENOENT" || err?.code === 404 || err?.status === 404;
+}
+/**
+* Persistence for the staged publish workflow (`npm stage`).
+*
+* Everything goes through {@link pluginUtils.StorageHandler}, so it works with
+* any storage plugin (local-storage, memory, S3, GCS) without the plugin having
+* to know that staging exists. On disk it looks like:
+*
+* ```
+* <storage>/.stage/package.json            index of every staged item
+* <storage>/.stage/<uuid>/package.json     the staged item (record + packument)
+* <storage>/.stage/<uuid>/<name>-<v>.tgz   the staged tarball
+* ```
+*/
+var StageStorage = class {
+	plugin;
+	logger;
+	/**
+	* Serializes index mutations within this process.
+	*
+	* `StorageHandler.updatePackage()` takes a lock in local-storage but releases
+	* it before we get to save, and other plugins do not lock at all, so a
+	* read-modify-write on the index would race. This keeps a single Verdaccio
+	* process consistent; several processes sharing one storage backend are NOT
+	* supported.
+	*/
+	indexQueue = Promise.resolve();
+	constructor(plugin, logger) {
+		this.plugin = plugin;
+		this.logger = logger;
+	}
+	/** Stage a new version. Returns the persisted record, including its generated id. */
+	async add(input, tarball, { signal }) {
+		if (validationUtils.validateName(input.tarballFilename) === false) throw errorUtils.getBadRequest(`invalid tarball name ${input.tarballFilename}`);
+		const record = {
+			id: randomUUID(),
+			packageName: input.packageName,
+			version: input.version,
+			tag: input.tag,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			actor: input.actor,
+			actorType: "user",
+			access: input.access,
+			shasum: input.shasum,
+			tarballFilename: input.tarballFilename
+		};
+		debug("staging %o@%o as %o", record.packageName, record.version, record.id);
+		return this.enqueueIndexMutation(async () => {
+			const items = await this.readIndex();
+			if (items.find((item) => item.packageName === record.packageName && item.version === record.version)) throw errorUtils.getConflict(`${record.packageName}@${record.version} is already staged`);
+			const handler = this.itemStorage(record.id);
+			await this.writeTarball(handler, record.tarballFilename, tarball, { signal });
+			const document = {
+				record,
+				packument: input.packument
+			};
+			await handler.savePackage(record.id, document);
+			await this.writeIndex([record, ...items]);
+			this.logger.info({
+				packageName: record.packageName,
+				version: record.version,
+				stageId: record.id
+			}, "staged @{packageName}@@{version} as @{stageId}");
+			return record;
+		});
+	}
+	/** Every staged item, newest first, optionally narrowed to one package. */
+	async list(filter = {}) {
+		const items = await this.readIndex();
+		if (typeof filter.packageName === "string") return items.filter((item) => item.packageName === filter.packageName);
+		return items;
+	}
+	/** A single staged item, or `undefined` when the id is unknown. */
+	async get(id) {
+		return (await this.readIndex()).find((item) => item.id === id);
+	}
+	/** Whether a version of a package is already staged (used to answer 409). */
+	async findByVersion(packageName, version) {
+		return (await this.readIndex()).find((item) => item.packageName === packageName && item.version === version);
+	}
+	/** The publish payload kept for a staged item, needed to approve it. */
+	async getPackument(id) {
+		return (await this.readDocument(id))?.packument;
+	}
+	/** Read the staged tarball as a stream. */
+	async readTarball(id, { signal }) {
+		const record = await this.get(id);
+		if (!record) throw errorUtils.getNotFound("no such staged package version");
+		return this.itemStorage(id).readTarball(record.tarballFilename, { signal });
+	}
+	/**
+	* Drop a staged item and its tarball.
+	*
+	* @returns `false` when the id was unknown, `true` when something was removed.
+	*/
+	async remove(id) {
+		const record = await this.get(id);
+		if (!record) return false;
+		const handler = this.itemStorage(id);
+		await this.updateIndex((items) => items.filter((item) => item.id !== id));
+		for (const file of [record.tarballFilename, STORAGE.PACKAGE_FILE_NAME]) try {
+			await handler.deletePackage(file);
+		} catch (err) {
+			debug("could not delete staged file %o: %s", file, err?.message);
+		}
+		try {
+			await handler.removePackage(id);
+		} catch (err) {
+			debug("could not delete staged folder %o: %s", id, err?.message);
+		}
+		debug("removed staged item %o", id);
+		return true;
+	}
+	itemStorage(id) {
+		return this.plugin.getPackageStorage(`${STAGE_NAMESPACE}/${id}`);
+	}
+	indexStorage() {
+		return this.plugin.getPackageStorage(STAGE_NAMESPACE);
+	}
+	async readDocument(id) {
+		try {
+			return await this.itemStorage(id).readPackage(id);
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+	}
+	async readIndex() {
+		try {
+			const index = await this.indexStorage().readPackage(STAGE_INDEX);
+			return Array.isArray(index?.items) ? index.items : [];
+		} catch (err) {
+			if (isNotFound(err)) {
+				debug("no stage index yet");
+				return [];
+			}
+			throw err;
+		}
+	}
+	/** Read-modify-write the index, serialized against other callers (see {@link indexQueue}). */
+	async updateIndex(mutate) {
+		return this.enqueueIndexMutation(async () => {
+			const items = mutate(await this.readIndex());
+			await this.writeIndex(items);
+			return items;
+		});
+	}
+	async enqueueIndexMutation(run) {
+		const queued = this.indexQueue.then(run, run);
+		this.indexQueue = queued.catch(() => void 0);
+		return queued;
+	}
+	async writeIndex(items) {
+		const index = { items };
+		await this.indexStorage().savePackage(STAGE_INDEX, index);
+	}
+	async writeTarball(handler, filename, tarball, { signal }) {
+		const writeStream = await handler.writeTarball(filename, { signal });
+		await pipeline(Readable.from(tarball), writeStream);
+		await this.waitForTarball(handler, filename);
+	}
+	async waitForTarball(handler, filename, attempts = 20) {
+		for (let attempt = 0; attempt < attempts; attempt++) {
+			if (await handler.hasTarball(filename)) return;
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		}
+		throw errorUtils.getInternalError(`staged tarball ${filename} was never persisted`);
+	}
+};
+//#endregion
+export { STAGE_NAMESPACE, StageStorage, toStagePackageVersion };
+
+//# sourceMappingURL=stage-storage.mjs.map

package/build/stage-storage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-storage.mjs","names":[],"sources":["../src/stage-storage.ts"],"sourcesContent":["import buildDebug from 'debug';\nimport { randomUUID } from 'node:crypto';\nimport { Readable } from 'node:stream';\nimport { pipeline } from 'node:stream/promises';\n\nimport type { pluginUtils } from '@verdaccio/core';\nimport { errorUtils, validationUtils } from '@verdaccio/core';\nimport type { Logger, Manifest } from '@verdaccio/types';\n\nimport { STORAGE } from './lib/storage-utils';\n\nconst debug = buildDebug('verdaccio:storage:stage');\n\n/**\n * Storage namespace holding every staged item.\n *\n * It is deliberately NOT registered through `storagePlugin.add()`: doing so\n * would list it in the plugin database and leak it into search results and the\n * web UI package list. The staged items are enumerated through {@link STAGE_INDEX}\n * instead.\n */\nexport const STAGE_NAMESPACE = '.stage';\n\n/**\n * Logical name used when reading/writing the index document. Storage handlers\n * are scoped to a folder and ignore this argument when resolving the path, but\n * it is what shows up in plugin logs, so keep it descriptive.\n */\nconst STAGE_INDEX = 'stage-index';\n\n/**\n * Metadata of a package version awaiting review.\n *\n * Mirrors the `StagePackageVersion` schema documented by npmjs, plus\n * {@link StageRecord.tarballFilename}, which is internal and must be stripped\n * before serving the record over the API (see {@link toStagePackageVersion}).\n */\nexport interface StageRecord {\n  /** Unique identifier. Must be a UUID: the npm CLI validates the format client side. */\n  id: string;\n  packageName: string;\n  version: string;\n  /** dist-tag the version will be published under once approved. */\n  tag: string;\n  /** ISO timestamp of when the version was staged. */\n  createdAt: string;\n  /** Username of whoever staged the version. */\n  actor: string;\n  actorType: 'user';\n  access: 'public' | 'private';\n  /** sha1 of the tarball, as reported by `npm stage list`. */\n  shasum: string;\n  /** Internal: name of the tarball inside the staged item folder. */\n  tarballFilename: string;\n}\n\n/** Shape served to clients: {@link StageRecord} without the internal fields. */\nexport type StagePackageVersion = Omit<StageRecord, 'tarballFilename'>;\n\n/**\n * The publish payload kept for a staged item, minus `_attachments` (the tarball\n * is stored separately as a real tarball, not as base64 inside this document).\n */\nexport type StagedPackument = Omit<Manifest, '_attachments'>;\n\n/** Persisted document of a single staged item. */\ninterface StageDocument {\n  record: StageRecord;\n  packument: StagedPackument;\n}\n\n/** Persisted index of every staged item, newest first. */\ninterface StageIndex {\n  items: StageRecord[];\n}\n\nexport interface AddStageInput {\n  packageName: string;\n  version: string;\n  tag: string;\n  actor: string;\n  access: 'public' | 'private';\n  shasum: string;\n  tarballFilename: string;\n  packument: StagedPackument;\n}\n\nexport interface ListStageFilter {\n  /** Restrict the result to a single package name. */\n  packageName?: string;\n}\n\n/** Strip the internal fields before the record leaves the registry. */\nexport function toStagePackageVersion(record: StageRecord): StagePackageVersion {\n  const { tarballFilename: _tarballFilename, ...rest } = record;\n  return rest;\n}\n\nfunction isNotFound(err: any): boolean {\n  return err?.code === 'ENOENT' || err?.code === 404 || err?.status === 404;\n}\n\n/**\n * Persistence for the staged publish workflow (`npm stage`).\n *\n * Everything goes through {@link pluginUtils.StorageHandler}, so it works with\n * any storage plugin (local-storage, memory, S3, GCS) without the plugin having\n * to know that staging exists. On disk it looks like:\n *\n * ```\n * <storage>/.stage/package.json            index of every staged item\n * <storage>/.stage/<uuid>/package.json     the staged item (record + packument)\n * <storage>/.stage/<uuid>/<name>-<v>.tgz   the staged tarball\n * ```\n */\nexport class StageStorage {\n  private readonly plugin: pluginUtils.Storage<any>;\n  private readonly logger: Logger;\n  /**\n   * Serializes index mutations within this process.\n   *\n   * `StorageHandler.updatePackage()` takes a lock in local-storage but releases\n   * it before we get to save, and other plugins do not lock at all, so a\n   * read-modify-write on the index would race. This keeps a single Verdaccio\n   * process consistent; several processes sharing one storage backend are NOT\n   * supported.\n   */\n  private indexQueue: Promise<unknown> = Promise.resolve();\n\n  public constructor(plugin: pluginUtils.Storage<any>, logger: Logger) {\n    this.plugin = plugin;\n    this.logger = logger;\n  }\n\n  /** Stage a new version. Returns the persisted record, including its generated id. */\n  public async add(\n    input: AddStageInput,\n    tarball: Buffer,\n    { signal }: { signal: AbortSignal }\n  ): Promise<StageRecord> {\n    // the filename reaches us from the `_attachments` key of the request, so it\n    // is attacker controlled. The regular publish path asserts the same thing\n    // before writing; without it a name like `..` escapes the item folder and\n    // the write fails inside an unawaited stream handler, taking the process\n    // down rather than the request.\n    if (validationUtils.validateName(input.tarballFilename) === false) {\n      throw errorUtils.getBadRequest(`invalid tarball name ${input.tarballFilename}`);\n    }\n\n    const record: StageRecord = {\n      id: randomUUID(),\n      packageName: input.packageName,\n      version: input.version,\n      tag: input.tag,\n      createdAt: new Date().toISOString(),\n      actor: input.actor,\n      actorType: 'user',\n      access: input.access,\n      shasum: input.shasum,\n      tarballFilename: input.tarballFilename,\n    };\n    debug('staging %o@%o as %o', record.packageName, record.version, record.id);\n\n    return this.enqueueIndexMutation(async () => {\n      const items = await this.readIndex();\n      const alreadyStaged = items.find(\n        (item) => item.packageName === record.packageName && item.version === record.version\n      );\n      if (alreadyStaged) {\n        throw errorUtils.getConflict(`${record.packageName}@${record.version} is already staged`);\n      }\n\n      const handler = this.itemStorage(record.id);\n      // the tarball goes first: if it fails there is no record pointing at a\n      // tarball that never landed.\n      await this.writeTarball(handler, record.tarballFilename, tarball, { signal });\n      const document: StageDocument = { record, packument: input.packument };\n      await handler.savePackage(record.id, document as unknown as Manifest);\n      await this.writeIndex([record, ...items]);\n\n      this.logger.info(\n        { packageName: record.packageName, version: record.version, stageId: record.id },\n        'staged @{packageName}@@{version} as @{stageId}'\n      );\n      return record;\n    });\n  }\n\n  /** Every staged item, newest first, optionally narrowed to one package. */\n  public async list(filter: ListStageFilter = {}): Promise<StageRecord[]> {\n    const items = await this.readIndex();\n    if (typeof filter.packageName === 'string') {\n      return items.filter((item) => item.packageName === filter.packageName);\n    }\n    return items;\n  }\n\n  /** A single staged item, or `undefined` when the id is unknown. */\n  public async get(id: string): Promise<StageRecord | undefined> {\n    const items = await this.readIndex();\n    return items.find((item) => item.id === id);\n  }\n\n  /** Whether a version of a package is already staged (used to answer 409). */\n  public async findByVersion(\n    packageName: string,\n    version: string\n  ): Promise<StageRecord | undefined> {\n    const items = await this.readIndex();\n    return items.find((item) => item.packageName === packageName && item.version === version);\n  }\n\n  /** The publish payload kept for a staged item, needed to approve it. */\n  public async getPackument(id: string): Promise<StagedPackument | undefined> {\n    const document = await this.readDocument(id);\n    return document?.packument;\n  }\n\n  /** Read the staged tarball as a stream. */\n  public async readTarball(id: string, { signal }: { signal: AbortSignal }): Promise<Readable> {\n    const record = await this.get(id);\n    if (!record) {\n      throw errorUtils.getNotFound('no such staged package version');\n    }\n    return this.itemStorage(id).readTarball(record.tarballFilename, { signal });\n  }\n\n  /**\n   * Drop a staged item and its tarball.\n   *\n   * @returns `false` when the id was unknown, `true` when something was removed.\n   */\n  public async remove(id: string): Promise<boolean> {\n    const record = await this.get(id);\n    if (!record) {\n      return false;\n    }\n    const handler = this.itemStorage(id);\n    // the index entry goes first: a leftover folder is invisible, whereas a\n    // leftover index entry would surface a staged item that cannot be read.\n    await this.updateIndex((items) => items.filter((item) => item.id !== id));\n    // the folder can only be dropped once it is empty, so both files go first\n    for (const file of [record.tarballFilename, STORAGE.PACKAGE_FILE_NAME]) {\n      try {\n        await handler.deletePackage(file);\n      } catch (err: any) {\n        debug('could not delete staged file %o: %s', file, err?.message);\n      }\n    }\n    try {\n      await handler.removePackage(id);\n    } catch (err: any) {\n      debug('could not delete staged folder %o: %s', id, err?.message);\n    }\n    debug('removed staged item %o', id);\n    return true;\n  }\n\n  private itemStorage(id: string): pluginUtils.StorageHandler {\n    return this.plugin.getPackageStorage(`${STAGE_NAMESPACE}/${id}`);\n  }\n\n  private indexStorage(): pluginUtils.StorageHandler {\n    return this.plugin.getPackageStorage(STAGE_NAMESPACE);\n  }\n\n  private async readDocument(id: string): Promise<StageDocument | undefined> {\n    try {\n      const document = (await this.itemStorage(id).readPackage(id)) as unknown as StageDocument;\n      return document;\n    } catch (err: any) {\n      if (isNotFound(err)) {\n        return undefined;\n      }\n      throw err;\n    }\n  }\n\n  private async readIndex(): Promise<StageRecord[]> {\n    try {\n      const index = (await this.indexStorage().readPackage(STAGE_INDEX)) as unknown as StageIndex;\n      return Array.isArray(index?.items) ? index.items : [];\n    } catch (err: any) {\n      if (isNotFound(err)) {\n        debug('no stage index yet');\n        return [];\n      }\n      throw err;\n    }\n  }\n\n  /** Read-modify-write the index, serialized against other callers (see {@link indexQueue}). */\n  private async updateIndex(\n    mutate: (items: StageRecord[]) => StageRecord[]\n  ): Promise<StageRecord[]> {\n    return this.enqueueIndexMutation(async (): Promise<StageRecord[]> => {\n      const items = mutate(await this.readIndex());\n      await this.writeIndex(items);\n      return items;\n    });\n  }\n\n  private async enqueueIndexMutation<T>(run: () => Promise<T>): Promise<T> {\n    const queued = this.indexQueue.then(run, run);\n    // keep the chain alive even when a caller rejects\n    this.indexQueue = queued.catch(() => undefined);\n    return queued;\n  }\n\n  private async writeIndex(items: StageRecord[]): Promise<void> {\n    const index: StageIndex = { items };\n    await this.indexStorage().savePackage(STAGE_INDEX, index as unknown as Manifest);\n  }\n\n  private async writeTarball(\n    handler: pluginUtils.StorageHandler,\n    filename: string,\n    tarball: Buffer,\n    { signal }: { signal: AbortSignal }\n  ): Promise<void> {\n    const writeStream = await handler.writeTarball(filename, { signal });\n\n    // `StorageHandler.writeTarball` only promises a Writable. The two bundled\n    // plugins happen to emit 'open' before accepting writes, but nothing in the\n    // interface says a plugin must, and waiting for it would hang staging\n    // forever on one that does not. Piping straight away is correct either way:\n    // a stream that is not ready yet buffers the writes.\n    await pipeline(Readable.from(tarball), writeStream);\n\n    // Both plugins rename the temporary file inside an async 'close' handler\n    // that nobody awaits, so 'close' does not guarantee the tarball is in its\n    // final place yet. Give the rename a bounded chance to land.\n    await this.waitForTarball(handler, filename);\n  }\n\n  private async waitForTarball(\n    handler: pluginUtils.StorageHandler,\n    filename: string,\n    attempts = 20\n  ): Promise<void> {\n    for (let attempt = 0; attempt < attempts; attempt++) {\n      if (await handler.hasTarball(filename)) {\n        return;\n      }\n      await new Promise((resolve) => setTimeout(resolve, 10));\n    }\n    throw errorUtils.getInternalError(`staged tarball ${filename} was never persisted`);\n  }\n}\n"],"mappings":"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"}