@arc-e-tect/api-only-publisher 0.16.1 → 0.17.0

package/src/cli.js

@@ -17,6 +17,8 @@ const { pack, PackError } = require("./pack");
 const { changedSince, ChangedError } = require("./changed");
 const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
+const { outcomeOf } = require("./channel-error");
+const { guard, GuardError } = require("./version-guard");
 const { refuseRemote } = require("./remote");
 const { CHANNEL_TYPES } = require("./channel-types");
 const { VersionError: PolicyError, describe } = require("./version-policy");
@@ -40,6 +42,7 @@ Usage:
   api-only-publisher targets
   api-only-publisher closure [--target <name>]...
   api-only-publisher changed --since <ref>
+  api-only-publisher check [--target <name>]... [--pre-release <ids>] [--since <ref>]
   api-only-publisher pack [--pre-release <ids>] [--target <name>]... [--out <dir>]
   api-only-publisher publish [--pre-release <ids>] [--target <name>]... [--channel <name>]... [--out <dir>]
   api-only-publisher split [--out <dir>] [--by kind|target]
@@ -63,7 +66,9 @@ Options:
                     init only: the value of that question; a flag always wins.
   --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
                     config only: the value of that question; a flag always wins.
-  --since <ref>     changed only: the git ref to compare the working tree against.
+  --since <ref>     changed: the git ref to compare the working tree against.
+                    check/publish: the ref to compare a target without a release
+                    tag against, instead of the merge-base with the main branch.
   --out <dir>       pack/publish/split: where to write, instead of build.packages
                     or build.split in apionly.yaml.
   --channel <name>  publish only: repeat for several. Default: every configured channel.
@@ -76,6 +81,8 @@ Options:
 What gets built, and where each document goes, is declared in apionly.yaml.
 A published target's version is read from its version file:
 <target>.bundle.properties beside its bundle root, or the file its versionFile names.
+A target changed since its release, or since the main branch, needs a new version:
+check says which do not have one, and publish refuses them.
 `;
 
 function parseArgs(argv) {
@@ -289,6 +296,20 @@ async function runConfig(options, positional, io, log) {
     return 0;
 }
 
+/** Fails with every target the guard refused -- and, with `undecided`, every one it could not decide -- each with its reason. */
+function refuseViolations(results, { undecided = false } = {}) {
+    const listed = (verdict) => results.filter((r) => r.verdict === verdict).map((r) => `  ${r.target} ${r.version}: ${r.reason}`);
+    const violations = listed("violation");
+    const unknown = undecided ? listed("undecided") : [];
+    const parts = [];
+    if (violations.length > 0) {
+        parts.push(`${violations.length} target(s) changed without a new version:\n${violations.join("\n")}\n` +
+            "A published version is never replaced: a changed specification needs a changed version.");
+    }
+    if (unknown.length > 0) parts.push(`${unknown.length} target(s) could not be checked:\n${unknown.join("\n")}`);
+    if (parts.length > 0) throw new GuardError(parts.join("\n\n"));
+}
+
 async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
@@ -425,6 +446,17 @@ async function main(argv, io = {}) {
             log(`\n${changed.length} of ${results.length} target(s) changed since ${options.since}.`);
             return 0;
         }
+        case "check": {
+            for (const target of targets || []) {
+                if (!config.isPublished(target)) throw new ConfigError(`${target} is not published, so it has no version to check`);
+            }
+            const results = guard(config, shippedTargets(config, targets), { preRelease: options.preRelease, since: options.since });
+            for (const r of results) log(`${r.target.padEnd(18)} ${r.version.padEnd(14)} ${r.verdict === "ok" ? "ok" : r.verdict.toUpperCase()}  ${r.reason}`);
+            // check is the gate: a target it cannot decide fails it too.
+            refuseViolations(results, { undecided: true });
+            log(`\n${results.length} target(s) checked.`);
+            return 0;
+        }
         case "pack": {
             const outDir = options.out ? path.resolve(options.dir, options.out) : config.packagesDir();
             const shipped = shippedTargets(config, targets);
@@ -483,9 +515,21 @@ async function main(argv, io = {}) {
             // Every channel this run uses, before anything is read, packed or sent.
             refuseRemote([...new Set(shipped.flatMap((target) => routes.get(target)))], configured);
             const versions = versionsOf(config, shipped, options.preRelease);
+            // A changed target needs a new version: decided before anything is packed or sent.
+            try {
+                const checked = guard(config, shipped, { preRelease: options.preRelease, since: options.since });
+                refuseViolations(checked);
+                for (const r of checked.filter((c) => c.verdict === "undecided")) {
+                    log(`warning: ${r.target} ${r.version}: version not checked: ${r.reason}`);
+                }
+            } catch (error) {
+                if (!(error instanceof GuardError && error.notARepository)) throw error;
+                log(`warning: versions not checked: ${error.message}`);
+            }
             const closures = forTargets(config, undefined, shipped);
             let published = 0;
             const handoff = [];
+            const outcomes = [];
             for (const target of Object.keys(config.targets)) {
                 if (!shipped.includes(target)) continue;
                 const closure = closures.get(target);
@@ -496,18 +540,36 @@ async function main(argv, io = {}) {
                     outDir, log,
                 });
                 for (const name of routes.get(target)) {
-                    // A remote channel returns a promise; a local one does not.
-                    const result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
-                    for (const file of result.files || []) {
-                        handoff.push({ file, target, version: manifest.version, channel: name, type: config.channelType(name) });
+                    const entry = { target, version: manifest.version, channel: name, type: config.channelType(name) };
+                    let result;
+                    try {
+                        // A remote channel returns a promise; a local one does not.
+                        result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
+                    } catch (error) {
+                        // A channel is an external party: what it cannot take is reported, never fatal.
+                        const outcome = outcomeOf(error);
+                        if (!outcome) throw error;
+                        outcomes.push({ ...entry, outcome, reason: error.message });
+                        log(`warning: ${target} ${manifest.version} was not published to ${name}: ${error.message}`);
+                        if (process.env.GITHUB_ACTIONS === "true") {
+                            console.log(`::warning title=${target} ${manifest.version} not published to ${name}::${error.message.replace(/\r?\n/g, " ")}`);
+                        }
+                        continue;
                     }
+                    outcomes.push({ ...entry, outcome: result.alreadyPublished ? "already-published" : "published" });
+                    for (const file of result.files || []) handoff.push({ file, ...entry });
                     published += 1;
                 }
             }
-            // What a later step publishes byte for byte; README.adoc#handoff.
-            const { sha256: listing } = writeHandoff(config.root, outDir, handoff);
+            // What a later step publishes byte for byte, and what each channel made of it; README.adoc#handoff.
+            const { sha256: listing } = writeHandoff(config.root, outDir, handoff, outcomes);
             log(`\nPublished ${published} artifact(s).`);
             log(`Listed ${handoff.length} file(s) in ${path.relative(config.root, listing)}.`);
+            const problems = outcomes.length - published;
+            if (problems > 0) {
+                log(`Channel problems: ${problems} of ${outcomes.length} publication(s) did not complete.` +
+                    (published === 0 ? " Nothing was published." : ""));
+            }
             return 0;
         }
         case "split": {
@@ -533,7 +595,7 @@ function report(error) {
         error instanceof ClosureError || error instanceof PackError ||
         error instanceof ChangedError || error instanceof SplitError ||
         error instanceof ChannelError || error instanceof PolicyError ||
-        error instanceof BundleVersionError) {
+        error instanceof BundleVersionError || error instanceof GuardError) {
         console.error(`Error: ${error.message}`);
         process.exitCode = 1;
     } else {

package/src/config.js

@@ -21,7 +21,7 @@ const SUPPORTED_SCHEMA_VERSION = 1;
 // often a typo or a bad indent than a value nobody has used yet -- see checkKeys.
 const ROOT_KEYS = [
     "schemaVersion", "sources", "defaults", "build", "reports", "lint",
-    "distribution", "channels", "targets", "toolchain", "portfolio",
+    "distribution", "channels", "targets", "toolchain", "portfolio", "versioning",
 ];
 const SOURCES_KEYS = ["root", "openapi", "asyncapi"];
 const DEFAULTS_KEYS = ["openapi", "asyncapi", "placeholders"];
@@ -36,6 +36,7 @@ const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile", "channels"
 const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
 const PORTFOLIO_KEYS = ["openapi", "security", "location"];
 const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
+const VERSIONING_KEYS = ["tagFormat", "mainBranch"];
 
 // What every portfolio setting is when apionly.yaml says nothing: safe for the
 // ordinary case (a gateway routing /<target>/** to each service), and named rather
@@ -204,6 +205,16 @@ function load(configPath) {
         );
     }
 
+    const versioning = parsed.versioning || {};
+    checkKeys(versioning, VERSIONING_KEYS, "versioning");
+    if (versioning.tagFormat !== undefined) {
+        const format = requireString(versioning.tagFormat, "versioning.tagFormat");
+        if (!format.includes("{target}") || !format.includes("{version}")) {
+            throw new ConfigError(`versioning.tagFormat must contain {target} and {version}, not ${JSON.stringify(format)}`);
+        }
+    }
+    if (versioning.mainBranch !== undefined) requireString(versioning.mainBranch, "versioning.mainBranch");
+
     const channels = parsed.channels || {};
     const types = channelTypes(channels);
 
@@ -314,6 +325,7 @@ function load(configPath) {
         distribution: parsed.distribution || null,
         channels,
         portfolio,
+        versioning,
         targets,
 
         // --- derived accessors, so callers never re-derive a path themselves ---
@@ -329,6 +341,15 @@ function load(configPath) {
         stagingDir(kind) {
             return path.join(this.stagingRoot(kind), requireString(this.sources[kind], `sources.${kind}`));
         },
+        // How a target's releases are tagged in git -- by the pipeline that publishes them,
+        // never by the Publisher, which only reads the tags -- and the branch a change is
+        // compared with when a target has no release tag yet.
+        tagFormat() {
+            return this.versioning.tagFormat || "{target}-v{version}";
+        },
+        mainBranch() {
+            return this.versioning.mainBranch || "main";
+        },
         // Where pack and publish write archives, and split its parts, unless --out says
         // otherwise; relative to this configuration, as every other path here is.
         packagesDir() {

package/src/gitlab.js

@@ -16,7 +16,8 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { isPrerelease } = require("./version-policy");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
+const { judgeHeld } = require("./held-documents");
 
 const GITLAB_COM = "https://gitlab.com/api/v4";
 const TOKEN_HEADERS = { private: "PRIVATE-TOKEN", deploy: "DEPLOY-TOKEN", job: "JOB-TOKEN" };
@@ -34,7 +35,7 @@ function channelSettings(options, env = process.env) {
         tokenType = "job";
     }
     if (!token) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no token in $${tokenEnv}, which channels.gitlab-package.tokenEnv names, and no $CI_JOB_TOKEN. ` +
             "Set one in the release job's environment, or run in a GitLab CI job.");
     }
@@ -78,32 +79,39 @@ async function readBack(fileUrl, name, headers) {
     const response = await fetch(fileUrl, { headers });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`could not read ${name} back from ${fileUrl}: ${await answered(response)}.` +
+        throw new ChannelUnavailable(`could not read ${name} back from ${fileUrl}: ${await answered(response)}.` +
             (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
     }
     return Buffer.from(await response.arrayBuffer());
 }
 
-function notThisOne(name, manifest) {
-    return new ChannelError(`GitLab already has ${name} in ${manifest.target} ${manifest.version}, and it is not this one; ` +
+function refused(name, manifest, why) {
+    return new ChannelConflict(`GitLab already has ${name} in ${manifest.target} ${manifest.version}, and it ${why}; ` +
         "a published version is never replaced, so publish the change as a new version");
 }
 
-/** Uploads one file unless GitLab has it: true when it was already there, identical. */
-async function upload(fileUrl, name, bytes, manifest, headers) {
-    const held = await readBack(fileUrl, name, headers);
-    if (held) {
-        if (held.equals(bytes)) return true;
-        throw notThisOne(name, manifest);
-    }
-    const response = await fetch(fileUrl, { method: "PUT", headers, body: bytes });
-    if (response.ok) return false;
-    const refused = `${await answered(response)}`;
+/** The manifest in GitLab's copy of a file, which must describe the same documents as `manifest`. */
+function sameAs(held, file, manifest) {
+    const judged = judgeHeld(held, file.kind, manifest);
+    if (judged.verdict === "unreadable") throw refused(file.name, manifest, `cannot be compared: ${judged.reason}`);
+    if (judged.verdict === "different") throw refused(file.name, manifest, "is not this one");
+    return judged.held;
+}
+
+/**
+ * Uploads one file unless GitLab has it: GitLab's copy when it was already there with the
+ * same documents, or null when it was uploaded now.
+ */
+async function upload(file, manifest, headers) {
+    const held = await readBack(file.url, file.name, headers);
+    if (held) return { held, found: sameAs(held, file, manifest) };
+    const response = await fetch(file.url, { method: "PUT", headers, body: file.bytes });
+    if (response.ok) return null;
+    const answer = `${await answered(response)}`;
     // Refused, perhaps as a duplicate another run published meanwhile: compare that one.
-    const now = await readBack(fileUrl, name, headers).catch(() => null);
-    if (now && now.equals(bytes)) return true;
-    if (now) throw notThisOne(name, manifest);
-    throw new ChannelError(`GitLab refused ${name}: ${refused}.` +
+    const now = await readBack(file.url, file.name, headers).catch(() => null);
+    if (now) return { held: now, found: sameAs(now, file, manifest) };
+    throw new ChannelUnavailable(`GitLab refused ${file.name}: ${answer}.` +
         (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
 }
 
@@ -129,18 +137,18 @@ async function release(settings, manifest, options, links, ref, log) {
             description: format(options.notes || options.description || DEFAULT_DESCRIPTION, manifest),
             assets: { links },
         });
-        if (!created.ok) throw new ChannelError(`GitLab refused the release ${tag}: ${await answered(created)}`);
+        if (!created.ok) throw new ChannelUnavailable(`GitLab refused the release ${tag}: ${await answered(created)}`);
         log(`-- Created the GitLab release ${tag}`);
         return;
     }
     if (!existing.ok) {
-        throw new ChannelError(`could not read the GitLab release ${tag}: ${await answered(existing)}`);
+        throw new ChannelUnavailable(`could not read the GitLab release ${tag}: ${await answered(existing)}`);
     }
     // A release's link names are unique: one already named, or already pointing here, is left as it is.
     const held = ((await existing.json()).assets || {}).links || [];
     for (const link of links.filter((l) => !held.some((h) => h.url === l.url || h.name === l.name))) {
         const added = await api(`${releases}/${encodeURIComponent(tag)}/assets/links`, settings.headers, "POST", link);
-        if (!added.ok) throw new ChannelError(`GitLab refused a link on the release ${tag}: ${await answered(added)}`);
+        if (!added.ok) throw new ChannelUnavailable(`GitLab refused a link on the release ${tag}: ${await answered(added)}`);
         log(`-- Linked ${link.name} from the GitLab release ${tag}`);
     }
 }
@@ -159,18 +167,28 @@ function publishGitlabPackage(archive, manifest, options, log) {
     const base = `${settings.url}/projects/${encodeURIComponent(settings.project)}/packages/generic/` +
         `${encodeURIComponent(packageName)}/${encodeURIComponent(manifest.version)}`;
     const files = [
-        { name: path.basename(archive), bytes: require("fs").readFileSync(archive) },
-        { name: "manifest.json", bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n") },
+        { name: path.basename(archive), bytes: require("fs").readFileSync(archive), kind: "tgz" },
+        { name: "manifest.json", bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n"), kind: "json" },
     ].map((file) => ({ ...file, url: `${base}/${encodeURIComponent(file.name)}` }));
 
     return (async () => {
-        let identical = 0;
+        // Idempotent, by documents: a file GitLab has is left alone when it holds the same
+        // documents, and refused when it does not.
+        let held = 0;
+        let identical = true;
         for (const file of files) {
-            if (await upload(file.url, file.name, file.bytes, manifest, settings.headers)) identical += 1;
+            const copy = await upload(file, manifest, settings.headers);
+            if (!copy) continue;
+            held += 1;
+            identical = identical && copy.held.equals(file.bytes);
+            // A version completed beside an archive from another commit gets that archive's
+            // manifest, so the two agree on where the version came from.
+            if (file.kind === "tgz") files[1].bytes = copy.found.bytes;
         }
-        const alreadyPublished = identical === files.length;
+        const alreadyPublished = held === files.length;
         log(alreadyPublished
-            ? `-- ${packageName} ${manifest.version} is already in GitLab project ${settings.project}, identical; nothing to do`
+            ? `-- ${packageName} ${manifest.version} is already in GitLab project ${settings.project}, ` +
+              `${identical ? "identical" : "with the same documents"}; nothing to do`
             : `-- Published ${packageName} ${manifest.version} to GitLab project ${settings.project}`);
 
         if (options.release === true && !wantsRelease) {

package/src/handoff.js

@@ -21,9 +21,11 @@ const HANDOFF_SCHEMA_VERSION = 1;
 /**
  * Writes packages.json and packages.sha256 into `outDir`, replacing any from an
  * earlier run, listing `entries` -- `{ file, target, version, channel }`, `file`
- * absolute -- sorted by path.
+ * absolute -- sorted by path. packages.json also lists `outcomes`, what each channel
+ * made of each target: `published`, `already-published`, or a channel problem --
+ * `conflict` or `unavailable`, with its reason -- that did not fail the run.
  */
-function writeHandoff(root, outDir, entries) {
+function writeHandoff(root, outDir, entries, outcomes = []) {
     const files = entries
         .map(({ file, target, version, channel, type = channel }) => ({
             path: path.relative(root, file).split(path.sep).join("/"),
@@ -35,7 +37,7 @@ function writeHandoff(root, outDir, entries) {
     fs.mkdirSync(outDir, { recursive: true });
     const json = path.join(outDir, HANDOFF_JSON);
     const sha256 = path.join(outDir, HANDOFF_SHA256);
-    fs.writeFileSync(json, JSON.stringify({ schemaVersion: HANDOFF_SCHEMA_VERSION, files }, null, 2) + "\n");
+    fs.writeFileSync(json, JSON.stringify({ schemaVersion: HANDOFF_SCHEMA_VERSION, files, outcomes }, null, 2) + "\n");
     fs.writeFileSync(sha256, files.map((f) => `${f.sha256}  ${f.path}\n`).join(""));
     return { json, sha256 };
 }

package/src/held-documents.js

@@ -0,0 +1,91 @@
+"use strict";
+
+// What a destination already holds under a version, told apart by its documents.
+//
+// A published version is its documents: the manifest's `files`, each document's name and
+// SHA-256, which is exactly what a subscriber records in its lockfile. Comparing bytes
+// instead says too much: the manifest also records the commit it was packed from and that
+// commit's time, so the same documents packed from a later commit are another archive,
+// and a channel comparing bytes would refuse a version that has not changed.
+
+const { untgz } = require("./tar");
+const { unzip } = require("./zip");
+
+class HeldError extends Error {}
+
+// Where each kind of package keeps the manifest: the packed archive at its root, an npm
+// package below package/, a NuGet package in its content folder.
+const MANIFEST_ENTRIES = ["manifest.json", "package/manifest.json", "contracts/manifest.json"];
+
+function kindOf(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) return "tgz";
+    if (bytes.length >= 4 && bytes.readUInt32LE(0) === 0x04034b50) return "zip";
+    if (/^\s*\{/.test(bytes.toString("utf8", 0, 64))) return "json";
+    throw new HeldError("it is neither a manifest nor a package");
+}
+
+/**
+ * The manifest a destination holds, from the manifest itself or from the package that
+ * carries it: its parsed contents and its bytes, as written.
+ *
+ * @param {Buffer} bytes a manifest.json, a packed archive, an npm package or a .nupkg
+ * @param {"tgz"|"zip"|"json"} [kind] what `bytes` should be; recognised when omitted
+ * @returns {{manifest: object, bytes: Buffer}}
+ */
+function heldManifest(bytes, kind = kindOf(bytes)) {
+    let raw = bytes;
+    if (kind !== "json") {
+        let entries;
+        try {
+            entries = kind === "zip" ? unzip(bytes) : untgz(bytes);
+        } catch (error) {
+            // A truncated package can also end a read out of bounds; it is unreadable either way.
+            throw new HeldError(error.message);
+        }
+        const entry = entries.find((e) => MANIFEST_ENTRIES.includes(e.name));
+        if (!entry) throw new HeldError("it holds no manifest.json");
+        raw = entry.data;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw.toString("utf8"));
+    } catch (error) {
+        throw new HeldError(`its manifest.json is not JSON: ${error.message}`);
+    }
+    if (!manifest || !Array.isArray(manifest.files)) throw new HeldError("its manifest.json lists no files");
+    return { manifest, bytes: raw };
+}
+
+/** The manifest in `bytes`; see heldManifest. */
+function manifestIn(bytes, kind) {
+    return heldManifest(bytes, kind).manifest;
+}
+
+/**
+ * Whether `held` describes the same documents as `mine`: the same target and version, and
+ * the same document names with the same hashes, in any order. Provenance is not compared.
+ */
+function sameDocuments(held, mine) {
+    if (held.target !== mine.target || String(held.version) !== String(mine.version)) return false;
+    const listing = (manifest) => manifest.files.map((f) => `${f.path}\0${f.sha256}`).sort().join("\n");
+    return listing(held) === listing(mine);
+}
+
+/**
+ * What a destination's copy of a version is, against the manifest being published:
+ * `same` with the manifest it carries, `different`, or `unreadable` with the reason --
+ * something that cannot be compared is never taken for the same version.
+ *
+ * @returns {{verdict: "same", held: {manifest: object, bytes: Buffer}} | {verdict: "different"} | {verdict: "unreadable", reason: string}}
+ */
+function judgeHeld(bytes, kind, manifest) {
+    let held;
+    try {
+        held = heldManifest(bytes, kind);
+    } catch (error) {
+        return { verdict: "unreadable", reason: error.message };
+    }
+    return sameDocuments(held.manifest, manifest) ? { verdict: "same", held } : { verdict: "different" };
+}
+
+module.exports = { heldManifest, manifestIn, sameDocuments, judgeHeld, HeldError };

package/src/nuget.js

@@ -24,7 +24,8 @@ const { execFileSync } = require("child_process");
 
 const { parse, isPrerelease } = require("./version-policy");
 const { zip } = require("./zip");
-const { ChannelError } = require("./channel-error");
+const { ChannelError, ChannelConflict, ChannelUnavailable } = require("./channel-error");
+const { judgeHeld } = require("./held-documents");
 
 /** Where the documents and manifest.json sit inside the package. */
 const CONTENT_FOLDER = "contracts";
@@ -173,13 +174,13 @@ function publishLocal(archive, manifest, options, id, log) {
 async function feedResources(index) {
     const response = await fetch(index);
     if (!response.ok) {
-        throw new ChannelError(`could not read the NuGet service index at ${index}: ${response.status} ${response.statusText}`);
+        throw new ChannelUnavailable(`could not read the NuGet service index at ${index}: ${response.status} ${response.statusText}`);
     }
     const resources = (await response.json()).resources || [];
     const find = (type) => (resources.find((r) => r["@type"] === type) || {})["@id"] || null;
     const publish = find(PUBLISH_RESOURCE);
     if (!publish) {
-        throw new ChannelError(`the NuGet feed at ${index} has no ${PUBLISH_RESOURCE} resource, so it cannot be pushed to`);
+        throw new ChannelUnavailable(`the NuGet feed at ${index} has no ${PUBLISH_RESOURCE} resource, so it cannot be pushed to`);
     }
     return { publish, content: find(CONTENT_RESOURCE) };
 }
@@ -191,15 +192,27 @@ function contentUrl(content, id, version) {
     return `${content.replace(/\/?$/, "/")}${lowerId}/${lowerVersion}/${lowerId}.${lowerVersion}.nupkg`;
 }
 
-/**
- * Whether the feed's copy of this version is these bytes: true or false, or null when the
- * feed offers no way to read it back.
- */
-async function sameAsPublished(content, id, version, bytes, key) {
+/** The feed's copy of this version, or null when the feed offers no way to read it back. */
+async function readableCopy(content, id, version, key) {
     if (!content) return null;
     const response = await fetch(contentUrl(content, id, version), { headers: { "X-NuGet-ApiKey": key } });
     if (!response.ok) return null;
-    return Buffer.from(await response.arrayBuffer()).equals(bytes);
+    return Buffer.from(await response.arrayBuffer());
+}
+
+/**
+ * Whether the feed's copy `held` is this version, by its documents: "identical" for the
+ * same bytes, "same" for the same documents in another package, as from another commit;
+ * anything else is refused, as a published version is never replaced.
+ */
+function judge(held, bytes, id, manifest) {
+    if (held.equals(bytes)) return "identical";
+    const refused = (why) => new ChannelConflict(`the NuGet feed already has ${id} ${manifest.version}, and it ${why}; ` +
+        "a published version is never replaced, so publish the change as a new version");
+    const judged = judgeHeld(held, "zip", manifest);
+    if (judged.verdict === "unreadable") throw refused(`cannot be compared: ${judged.reason}`);
+    if (judged.verdict === "different") throw refused("is not this package");
+    return "same";
 }
 
 /**
@@ -212,7 +225,7 @@ async function publishedCopy(content, id, version, key) {
     const response = await fetch(url, { headers: { "X-NuGet-ApiKey": key } });
     if (response.status === 404) return null;
     if (!response.ok) {
-        throw new ChannelError(`could not read ${id} ${version} back from ${url}: ${response.status} ${response.statusText}`.trim() +
+        throw new ChannelUnavailable(`could not read ${id} ${version} back from ${url}: ${response.status} ${response.statusText}`.trim() +
             (response.status === 401 || response.status === 403
                 ? ". Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
     }
@@ -230,7 +243,7 @@ function publishRemote(archive, manifest, options, id, log) {
     const tokenEnv = options.tokenEnv || "NUGET_API_KEY";
     const key = process.env[tokenEnv];
     if (!key) {
-        throw new ChannelError(
+        throw new ChannelUnavailable(
             `no API key in $${tokenEnv}, which channels.nuget.tokenEnv names. ` +
             "Remote publication needs one; set it in the release job's environment.");
     }
@@ -245,19 +258,17 @@ function publishRemote(archive, manifest, options, id, log) {
         // Idempotent before the push, not only after a 409: a feed that allows duplicate
         // versions -- GitLab's default -- accepts a different package under a version it
         // has, and serves that one from then on.
+        const already = (verdict) => {
+            log(`-- NuGet ${id} ${manifest.version} is already published, ` +
+                `${verdict === "identical" ? "identical" : "with the same documents"}; nothing to do`);
+            return {
+                location: endpoint, id, version: manifest.version, prerelease: isPrerelease(manifest.version),
+                alreadyPublished: true,
+            };
+        };
         if (content) {
             const held = await publishedCopy(content, id, manifest.version, key);
-            if (held && held.equals(bytes)) {
-                log(`-- NuGet ${id} ${manifest.version} is already published, identical; nothing to do`);
-                return {
-                    location: endpoint, id, version: manifest.version, prerelease: isPrerelease(manifest.version),
-                    alreadyPublished: true,
-                };
-            }
-            if (held) {
-                throw new ChannelError(`the NuGet feed already has ${id} ${manifest.version}, and it is not this package; ` +
-                    "a published version is never replaced, so publish the change as a new version");
-            }
+            if (held) return already(judge(held, bytes, id, manifest));
         }
         const boundary = `api-only-${crypto.createHash("sha256").update(bytes).digest("hex").slice(0, 32)}`;
         const body = Buffer.concat([
@@ -276,21 +287,14 @@ function publishRemote(archive, manifest, options, id, log) {
             body,
         });
         if (response.status === 409) {
-            // Idempotent: the same package again is success, a different one is not.
-            const same = await sameAsPublished(content, id, manifest.version, bytes, key);
-            if (same) {
-                log(`-- NuGet ${id} ${manifest.version} is already published, identical; nothing to do`);
-                return {
-                    location: endpoint, id, version: manifest.version, prerelease: isPrerelease(manifest.version),
-                    alreadyPublished: true,
-                };
-            }
-            throw new ChannelError(`the NuGet feed already has ${id} ${manifest.version}` +
-                (same === false ? ", and it is not this package" : ", and it cannot be read back to compare") +
-                "; a published version is never replaced, so publish the change as a new version");
+            // Idempotent: the same documents again are success, others are not.
+            const held = await readableCopy(content, id, manifest.version, key);
+            if (held) return already(judge(held, bytes, id, manifest));
+            throw new ChannelConflict(`the NuGet feed already has ${id} ${manifest.version}, and it cannot be read back to compare; ` +
+                "a published version is never replaced, so publish the change as a new version");
         }
         if (!response.ok) {
-            throw new ChannelError(`the NuGet feed refused the package: ${response.status} ${response.statusText}. ` +
+            throw new ChannelUnavailable(`the NuGet feed refused the package: ${response.status} ${response.statusText}. ` +
                 (response.status === 401 || response.status === 403
                     ? "Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
         }

package/src/tar.js

@@ -63,4 +63,40 @@ function tgz(entries, mtime) {
     return gzipped;
 }
 
-module.exports = { tgz, TarError };
+function text(block, start, length) {
+    const end = block.indexOf(0, start);
+    return block.toString("utf8", start, end < 0 || end > start + length ? start + length : end);
+}
+
+/**
+ * The regular files in a gzipped tar archive, in order: what `tgz` writes, and what npm
+ * packs, with a ustar prefix joined to the name. Directories, links and pax headers are
+ * skipped.
+ *
+ * @param {Buffer} bytes
+ * @returns {Array<{name: string, data: Buffer}>}
+ */
+function untgz(bytes) {
+    let tar;
+    try {
+        tar = zlib.gunzipSync(bytes);
+    } catch (error) {
+        throw new TarError(`not a gzipped tar archive: ${error.message}`);
+    }
+    const entries = [];
+    for (let offset = 0; offset + BLOCK <= tar.length;) {
+        const block = tar.subarray(offset, offset + BLOCK);
+        if (block.every((byte) => byte === 0)) break;
+        const prefix = block.toString("ascii", 257, 262) === "ustar" ? text(block, 345, 155) : "";
+        const name = prefix ? `${prefix}/${text(block, 0, 100)}` : text(block, 0, 100);
+        const size = parseInt(text(block, 124, 12).trim() || "0", 8);
+        const start = offset + BLOCK;
+        if (start + size > tar.length) throw new TarError(`the archive ends inside ${name}`);
+        const type = String.fromCharCode(block[156]);
+        if (type === "0" || type === "\0") entries.push({ name, data: Buffer.from(tar.subarray(start, start + size)) });
+        offset = start + Math.ceil(size / BLOCK) * BLOCK;
+    }
+    return entries;
+}
+
+module.exports = { tgz, untgz, TarError };