@arc-e-tect/api-only-publisher 0.14.1 → 0.14.3

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.14.1
+:api-only-publisher-version: 0.14.3
 
 [NOTE]
 .About this documentation
@@ -58,6 +58,7 @@ It need not be a deployable, which is why this is not called `services`.
 
 This document is the reference for the Publisher alone.
 To set it up for your situation, start at link:../docs/README.adoc[the documentation →].
+For the configuration that fits a typical situation -- one API or several, one kind of consumer or many -- see <<recipes,Recipes §>>.
 
 [#requirements]
 == Requirements
@@ -676,6 +677,7 @@ What happens when the destination already has the version:
 |`maven` and `nuget` to a URL, `npm`, `github-release`
 |The same bytes: nothing is sent, and the log says `already published, identical`. Different bytes: `publish` fails, naming the version -- a published version is never replaced, so publish the change as a new version.
 `github-release` compares the asset it would upload with the one the release has, and never overwrites one.
+`npm` compares the integrity hash the registry records, or the tarball's SHA-1 where it records only that, as GitLab's does; its files are packed with fixed modes, so the package is the same bytes whatever the umask of the machine that publishes it.
 A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
 |===
 
@@ -755,10 +757,14 @@ A .NET build uses it with `dotnet nuget add source <repository>`, or a `nuget.co
 
 *A remote feed* is configured by its service index, the URL a feed's settings show and that ends in `index.json`, such as `https://api.nuget.org/v3/index.json`.
 The Publisher reads the service index for its `PackagePublish/2.0.0` endpoint, then pushes the package there with one `PUT`, as `multipart/form-data`, with the key from the environment variable `tokenEnv` names in the `X-NuGet-ApiKey` header.
-A feed that already has the version answers 409; the Publisher then reads the feed's copy back (its `PackageBaseAddress/3.0.0` resource) and succeeds when it is the same package, and fails when it is not, or cannot be read (<<idempotent,Publishing the same version again §>>).
+The `PUT` goes to that endpoint with a trailing `/`, as `dotnet nuget push` sends it; a GitLab feed recognises the upload only there.
+Before the push, the Publisher reads the feed's copy of the version back (its `PackageBaseAddress/3.0.0` resource): the same package succeeds without a push, a different one fails, and a copy that cannot be read, other than one the feed does not have, fails rather than being pushed over (<<idempotent,Publishing the same version again §>>).
+The check comes first because a feed may accept a different package under a version it already has: GitLab does, by default, and serves the new one from then on.
+A feed that answers the push with 409 -- the version appeared in the meantime -- is read back and compared the same way.
 Without the variable set, the push fails before anything is sent, naming it.
-That is how nuget.org, GitHub Packages and self-hosted feeds such as BaGet take a push.
-A feed that authenticates some other way -- Azure Artifacts, which expects a credential provider or a token in an `Authorization` header -- is not supported yet; only the local-HTTP-stub tests exercise the push, not a real feed.
+That is how nuget.org, GitHub Packages, GitLab and self-hosted feeds such as BaGet take a push.
+A feed that authenticates some other way -- Azure Artifacts, which expects a credential provider or a token in an `Authorization` header -- is not supported yet.
+The local-HTTP-stub tests exercise the push; a real feed, GitLab's, was checked by hand.
 
 *The package holds* the `.nuspec`, the two Open Packaging Conventions parts (`[Content_Types].xml` and `_rels/.rels`), and exactly what `pack` produced -- the documents and `manifest.json` -- extracted, never rebuilt, under `contracts/`:
 
@@ -981,6 +987,354 @@ When that version changes, the review is redone rather than rewritten, and the c
 Everything in the Publisher's own link:package.json[`package.json` →] is an ordinary dependency, left to a dependency updater: `yaml`, and semantic-release and its plugins, with which the Publisher is released.
 link:../README.adoc#dependency-updates[The repository's dependency updates →] list every project, and which of the two changes it.
 
+[#recipes]
+== Recipes
+
+Configuring the Publisher is the easy part.
+The unfamiliar part is the idea behind it: an API description is a product.
+It has a version, it is released, and the teams and companies that build against it obtain it the way they obtain any other dependency, in the package format their own build already understands.
+
+Two questions decide how a library is configured:
+
+* *How many targets?*
+A target is one contract with a version of its own and consumers of its own: what gets shipped.
+* *How many channels?*
+A channel is one way of shipping it -- `file`, `maven`, `npm`, `nuget` or `github-release` -- chosen to suit the technology of whoever consumes it: how it reaches them.
+
+Each recipe below answers both, for a situation in which the answer is typical.
+They are starting points, not boundaries: the situations describe where each shape usually turns up, and nothing stops a shape being used elsewhere.
+
+[cols="2,1,1,2,4",options="header"]
+|===
+|Recipe |Targets |Channels |Every target on every channel? |Typical situation
+
+|<<recipe-vanilla,Vanilla §>>
+|One
+|One
+|Yes
+|One API, consumed by builds that all use the same technology.
+
+|<<recipe-microservices,Microservice architecture §>>
+|Several
+|One
+|Yes
+|Several services, each with its own contract, built by teams that share a technology.
+
+|<<recipe-business-partners,Business partners §>>
+|One
+|Several
+|Yes
+|One API offered to third parties, each building its client with a different technology.
+
+|<<recipe-platform,Platform §>>
+|Several
+|Several
+|Yes
+|A set of backend services that first and third parties build applications on, each with the technology of its choice.
+
+|<<recipe-ecosystem,Eco-system §>>
+|Several
+|Several
+|No
+|Parties that each use some of the backend services, with technologies of their own.
+|===
+
+[#recipes-two-facts]
+=== Two facts every recipe rests on
+
+*A channel is named after its type.*
+`channels.maven` is the Maven channel, `channels.npm` the npm channel, and so on, so one `apionly.yaml` has at most one channel of each type, with one destination each.
+Two consumers who both read Maven get the same Maven repository; <<recipe-business-partners,Business partners §>> shows what to do when they each need their own.
+
+*`apionly.yaml` says which channels exist, not which target goes where.*
+Without `--channel`, `publish` ships every published target to every configured channel, packing each target once and sending the same bytes everywhere.
+`--target` and `--channel` narrow a run, and both may be repeated:
+
+[source,console]
+----
+npm run apionly -- publish --target payments --channel nuget
+----
+
+So when different targets go to different channels, the routing lives in the commands that run `publish`, as <<recipe-ecosystem,Eco-system §>> shows, and not in `apionly.yaml`.
+
+The excerpts below show only `channels` and `targets`; the rest of `apionly.yaml` is as <<configuration,Configuration §>> describes, and as `init` writes it.
+Every published target also needs its version file, as <<versions,Versions §>> describes, and a `build` before its `publish`.
+
+[#recipe-vanilla]
+=== Vanilla: one target, one channel
+
+*When.*
+One API, described in one library, and consumed by builds that all use the same technology.
+A single service whose clients are all Gradle or Maven builds; a library that lives in the same repository as its only implementation.
+
+.apionly.yaml (excerpt)
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.contracts
+    repository: https://maven.example.com/releases  # a directory works too
+    # tokenEnv: MAVEN_TOKEN                         # the variable holding the token
+
+targets:
+  orders:
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+----
+
+[source,console]
+----
+npm run apionly -- build
+npm run apionly -- publish
+----
+
+This publishes `com.example.contracts:orders:<version>@tgz`, which a build fetches with the link:../api-only-subscriber/README.adoc[API-Only Subscriber →].
+
+*Variations.*
+
+* A library that lives in the same repository as its implementation needs no repository at all: the `file` channel, with `directory: build/publish`, is what `init` writes, and the Subscriber reads it from there.
+* A consumer that is not a JVM build takes a different channel in place of `maven`: `npm` for a Node.js or TypeScript build, `nuget` for .NET, `github-release` for anything else.
+
+[#recipe-microservices]
+=== Microservice architecture: several targets, one channel
+
+*When.*
+Several services, each owning its own contract, and one library describing them all, so that a schema the services share is one fragment rather than several copies.
+The teams use the same technology, so one channel reaches all of them.
+
+.apionly.yaml (excerpt)
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.contracts
+    repository: https://maven.example.com/releases
+
+targets:
+  orders:
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+    asyncapi:
+      bundle: bundles/orders_asyncapi_structure.yaml
+  payments:
+    openapi:
+      bundle: bundles/payments_openapi_structure.yaml
+  shipping:
+    openapi:
+      bundle: bundles/shipping_openapi_structure.yaml
+  landscape:
+    openapi:
+      aggregate: [orders, payments, shipping]  # a view of all of them; never published
+----
+
+[source,console]
+----
+npm run apionly -- build
+npm run apionly -- changed --since origin/main  # the targets this branch changes
+npm run apionly -- publish
+----
+
+Each target is published as an artifact of its own, at the version in its own version file: `com.example.contracts:orders`, `com.example.contracts:payments` and `com.example.contracts:shipping`.
+A service subscribes to its own contract to implement it, and to the contracts of the services it calls, as a client.
+
+*Worth knowing.*
+
+* Versions are per target, so a change to one service's fragments releases only that service's contract.
+A change to a fragment several targets share changes all of them, and `changed` names which, as <<closure,Independent versioning, and the dependency closure §>> describes.
+* Publishing every target on every run is safe: a version that is already published, with the same bytes, is left alone (<<idempotent,Publishing the same version again §>>).
+What fails is a changed contract whose version was not changed, which is the mistake `changed` exists to catch first.
+* `landscape` is optional: a whole-landscape view for reading, generated on every build and never published, as <<aggregates,Aggregates §>> describes.
+
+[#recipe-business-partners]
+=== Business partners: one target, several channels
+
+*When.*
+One API, offered to third parties who each build their own client: one in Java, one in TypeScript, one in C#, one in whatever it chose.
+Each of them should get the contract in the package format its own build understands, and all of them should get the same contract.
+
+.apionly.yaml (excerpt)
+[source,yaml]
+----
+channels:
+  maven:                       # the partners that build on the JVM
+    groupId: com.example.partner
+    repository: https://maven.example.com/partner
+  npm:                         # the partners that build with Node.js or TypeScript
+    scope: "@example-partner"
+    access: restricted
+  nuget:                       # the partners that build with .NET
+    idPrefix: Example.Partner
+    repository: https://nuget.example.com/v3/index.json
+  github-release:              # everyone else: a download, no package manager needed
+    repository: example/partner-api
+
+targets:
+  partner-api:
+    openapi:
+      bundle: bundles/partner-api_openapi_structure.yaml
+    asyncapi:
+      bundle: bundles/partner-api_asyncapi_structure.yaml
+----
+
+[source,console]
+----
+npm run apionly -- build
+npm run apionly -- publish
+----
+
+One run publishes `com.example.partner:partner-api`, `@example-partner/partner-api`, `Example.Partner.PartnerApi` and the release `partner-api-v<version>`, all four from the same packed archive, so a Java partner and a .NET partner always read byte-identical documents.
+
+*Worth knowing.*
+
+* `--channel` publishes to one of them on its own, for instance when one partner's feed was unreachable during the release: `npm run apionly -- publish --channel nuget`.
+The other channels already have the version, and would leave it alone anyway.
+* A pre-release, `publish --pre-release rc.1`, is how a partner gets an unfinished contract to start building against, without any partner's production build picking it up by accident (<<pre-releases,Pre-releases §>>).
+* Each channel takes its credential from the environment, never from `apionly.yaml`: `MAVEN_TOKEN` and `NUGET_API_KEY` by default, npm's own configuration for `npm`, and the GitHub CLI's for `github-release` (<<channel-text,What a package says about itself §>>).
+* Partners that each need a repository of *the same type* -- two Maven repositories, one per partner -- cannot be two `maven` channels.
+Publish to a local destination instead, `repository` or `directory` set to a directory, and let the pipeline copy the files it lists in `packages.sha256` to each partner's repository, as <<handoff,The hand-off §>> describes.
+
+[#recipe-platform]
+=== Platform: several targets, several channels, every target on every channel
+
+*When.*
+A set of backend services that others build applications on: the organisation's own teams, and third parties.
+Which services an application uses, and with which technology it is built, is up to whoever builds it, so every contract is offered in every format.
+
+.apionly.yaml (excerpt)
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.platform
+    repository: https://maven.example.com/platform
+  npm:
+    scope: "@example-platform"
+    access: public
+  nuget:
+    idPrefix: Example.Platform
+    repository: https://api.nuget.org/v3/index.json
+
+targets:
+  catalog:
+    openapi:
+      bundle: bundles/catalog_openapi_structure.yaml
+  customers:
+    openapi:
+      bundle: bundles/customers_openapi_structure.yaml
+  orders:
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+    asyncapi:
+      bundle: bundles/orders_asyncapi_structure.yaml
+  payments:
+    openapi:
+      bundle: bundles/payments_openapi_structure.yaml
+  platform:
+    openapi:
+      aggregate: [catalog, customers, orders, payments]
+----
+
+[source,console]
+----
+npm run apionly -- build
+npm run apionly -- publish
+----
+
+The configuration is the <<recipe-microservices,microservice architecture §>>'s targets with the <<recipe-business-partners,business partners §>>' channels, and the plain `publish` ships every target to every channel.
+
+*Worth knowing.*
+
+* Adding a target to `targets` publishes it on every channel, and adding a channel publishes every target on it.
+For a platform that is the point; when it is not, the library is an <<recipe-ecosystem,eco-system §>>.
+* The `platform` aggregate is the one document that shows the whole platform, for a developer portal or a review; it is never published, so nobody can build against it by accident (<<aggregates-never-published,An aggregate is never published §>>).
+* A target that is not for others at all -- a service's internal administration API, say -- stays in the library with `publish: false`: it is built and linted with the rest, and shipped nowhere.
+
+[#recipe-ecosystem]
+=== Eco-system: several targets, several channels, not every target on every channel
+
+*When.*
+Several parties, first and third, each use some of the backend services, and each builds with a technology of its own.
+The internal Java teams use all of them; the web front end, in TypeScript, uses the catalogue and the orders; a .NET payment provider uses the payments contract and nothing else.
+Offering every contract in every format would publish contracts to places nobody reads them, and offer a third party contracts it has no business with.
+
+This is also the answer to a question that comes up as soon as a library holds more than one target: _how do I publish one of the targets to a different channel?_
+
+Start from a routing table: which target goes to which channel.
+
+[cols="1,1,1,1",options="header"]
+|===
+|Target |`maven` |`npm` |`nuget`
+|`catalog`  |Yes |Yes |
+|`customers`|Yes |    |
+|`orders`   |Yes |Yes |
+|`payments` |Yes |    |Yes
+|===
+
+`apionly.yaml` declares the channels and the targets, as for a <<recipe-platform,platform §>>:
+
+.apionly.yaml (excerpt)
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.services
+    repository: https://maven.example.com/services
+  npm:
+    scope: "@example-web"
+    access: restricted
+  nuget:
+    idPrefix: Example.Services
+    repository: https://nuget.example.com/v3/index.json
+
+targets:
+  catalog:
+    openapi:
+      bundle: bundles/catalog_openapi_structure.yaml
+  customers:
+    openapi:
+      bundle: bundles/customers_openapi_structure.yaml
+  orders:
+    openapi:
+      bundle: bundles/orders_openapi_structure.yaml
+  payments:
+    openapi:
+      bundle: bundles/payments_openapi_structure.yaml
+----
+
+The routing table becomes one `publish` per channel, each naming its targets.
+Keeping those commands as scripts in the library's `package.json` keeps the routing in one place, reviewed with the library, rather than spread across pipeline files:
+
+.package.json (excerpt)
+[source,json]
+----
+{
+  "scripts": {
+    "apionly": "api-only-publisher",
+    "publish:maven": "api-only-publisher publish --channel maven",
+    "publish:npm": "api-only-publisher publish --channel npm --target catalog --target orders",
+    "publish:nuget": "api-only-publisher publish --channel nuget --target payments",
+    "publish:all": "npm run publish:maven && npm run publish:npm && npm run publish:nuget"
+  }
+}
+----
+
+[source,console]
+----
+npm run apionly -- build
+npm run publish:all
+----
+
+`publish:maven` names no target, because every target goes there; a channel that takes only some names each of them.
+
+*Worth knowing.*
+
+* A new target goes only where a script sends it.
+`publish:maven` picks it up because it names no target; the npm and NuGet consumers do not see it until it is added to their script, which is the deliberate step an eco-system wants.
+* Each script passes its arguments on: `npm run publish:npm -- --pre-release rc.1` publishes a pre-release of the npm targets alone.
+* Each run packs again, and the archives are the same bytes every time (<<idempotent,Publishing the same version again §>>), so a target on two channels is identical on both.
+* Each run replaces the hand-off files in the packages directory (<<handoff,The hand-off §>>).
+A pipeline that publishes the files itself gives each run its own `--out`, such as `--out build/packages/npm`, and keeps every channel's list.
+
 [#behaviour]
 == Behaviour worth knowing about
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/channels.js

@@ -156,6 +156,9 @@ function publishNpm(archive, manifest, options, log) {
                 ? { type: "git", url: manifest.source.repository }
                 : undefined,
         }, null, 2) + "\n");
+        // npm packs each file with its mode, and extracting and writing them applied this
+        // process's umask: fixed modes keep the package the same bytes on every machine.
+        for (const file of fs.readdirSync(workDir)) fs.chmodSync(path.join(workDir, file), 0o644);
 
         const outDir = path.resolve(options.baseDir || ".", options.directory || "build/packages/npm");
         fs.mkdirSync(outDir, { recursive: true });
@@ -173,16 +176,25 @@ function publishNpm(archive, manifest, options, log) {
         // Idempotent: a version the registry already has is left alone when it is the
         // same package, and refused when it is not -- npm never replaces a version.
         const registry = options.registry ? ["--registry", options.registry] : [];
-        const local = JSON.parse(execFileSync("npm", ["pack", "--dry-run", "--json"],
-            { cwd: workDir, encoding: "utf8", stdio: "pipe" }))[0].integrity;
-        const published = npmPublishedIntegrity(name, version, registry);
-        if (published === local) {
-            log(`-- npm ${name}@${version} is already published, identical; nothing to do`);
-            return { location: name + "@" + version, distTag, name, alreadyPublished: true };
-        }
+        const [local] = JSON.parse(execFileSync("npm", ["pack", "--dry-run", "--json"],
+            { cwd: workDir, encoding: "utf8", stdio: "pipe" }));
+        const published = npmPublishedDist(name, version, registry);
         if (published) {
+            // The SHA-512 integrity when the registry records one; the tarball's SHA-1
+            // otherwise, as GitLab's npm registry records only that.
+            const [held, mine] = published.integrity ? [published.integrity, local.integrity]
+                : published.shasum ? [published.shasum, local.shasum] : [null, null];
+            if (!held) {
+                throw new ChannelError(
+                    `npm already has ${name}@${version}, and it cannot be compared: the registry records neither ` +
+                    "an integrity nor a shasum for it. A published version is never replaced; publish the change as a new version.");
+            }
+            if (held === mine) {
+                log(`-- npm ${name}@${version} is already published, identical; nothing to do`);
+                return { location: name + "@" + version, distTag, name, alreadyPublished: true };
+            }
             throw new ChannelError(
-                `npm already has ${name}@${version}, and it is not this package (${published}, not ${local}). ` +
+                `npm already has ${name}@${version}, and it is not this package (${held}, not ${mine}). ` +
                 "A published version is never replaced; publish the change as a new version.");
         }
 
@@ -201,12 +213,12 @@ function publishNpm(archive, manifest, options, log) {
     }
 }
 
-/** The integrity npm records for `name@version`, or null when it has no such version. */
-function npmPublishedIntegrity(name, version, registry) {
+/** The `dist` npm records for `name@version` -- integrity, shasum, tarball -- or null when it has no such version. */
+function npmPublishedDist(name, version, registry) {
     try {
-        const out = execFileSync("npm", ["view", `${name}@${version}`, "dist.integrity", ...registry],
+        const out = execFileSync("npm", ["view", `${name}@${version}`, "dist", "--json", ...registry],
             { encoding: "utf8", stdio: "pipe" }).trim();
-        return out || null;
+        return out ? JSON.parse(out) : null;
     } catch (error) {
         const output = `${error.stdout || ""}${error.stderr || ""}`;
         if (/E404/.test(output)) return null;
@@ -338,24 +350,31 @@ function publishMavenRemote(archive, manifest, options, log) {
         `${options.groupId.split(".").join("/")}/${artifactId}/${version}/${artifactId}-${version}`;
 
     const work = (async () => {
-        // Idempotent: an artifact the repository already has is left alone when it is
-        // the same bytes, and refused when it is not.
-        const bytes = fs.readFileSync(archive);
-        const existing = await getFile(`${base}.${extension}`, token);
-        if (existing) {
-            if (existing.equals(bytes)) return true;
-            throw new ChannelError(
-                `${options.repository} already has ${options.groupId}:${artifactId}:${version}, and it is not this archive. ` +
-                "A published version is never replaced; publish the change as a new version.");
+        // Idempotent, file by file: each file the repository already has is left alone when
+        // it is the same bytes, and refuses the whole version when it is not. Every file is
+        // read back before any is uploaded, so a run interrupted after the artifact is
+        // completed by the next one, and a version that differs anywhere is not touched.
+        const files = [
+            { url: `${base}.${extension}`, bytes: fs.readFileSync(archive), type: "application/octet-stream" },
+            { url: `${base}.pom`, type: "application/xml",
+              bytes: Buffer.from(pom(options.groupId, artifactId, version, extension, pomDescription(options, manifest)), "utf8") },
+            { url: `${base}-manifest.json`, type: "application/json",
+              bytes: Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8") },
+        ];
+        const missing = [];
+        for (const file of files) {
+            const existing = await getFile(file.url, token);
+            if (!existing) {
+                missing.push(file);
+            } else if (!existing.equals(file.bytes)) {
+                throw new ChannelError(
+                    `${options.repository} already has ${options.groupId}:${artifactId}:${version}, ` +
+                    `and its ${file.url.split("/").pop()} is not this one. ` +
+                    "A published version is never replaced; publish the change as a new version.");
+            }
         }
-        await putFile(`${base}.${extension}`, bytes, token, "application/octet-stream");
-        await putFile(`${base}.pom`,
-            Buffer.from(pom(options.groupId, artifactId, version, extension, pomDescription(options, manifest)), "utf8"),
-            token, "application/xml");
-        await putFile(`${base}-manifest.json`,
-            Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8"),
-            token, "application/json");
-        return false;
+        for (const file of missing) await putFile(file.url, file.bytes, token, file.type);
+        return missing.length === 0;
     })();
 
     // The CLI is synchronous throughout; surfacing the promise here would make

package/src/nuget.js

@@ -184,20 +184,41 @@ async function feedResources(index) {
     return { publish, content: find(CONTENT_RESOURCE) };
 }
 
+/** Where the feed's `PackageBaseAddress/3.0.0` resource serves this version's package. */
+function contentUrl(content, id, version) {
+    const lowerId = id.toLowerCase();
+    const lowerVersion = String(version).toLowerCase();
+    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) {
     if (!content) return null;
-    const lowerId = id.toLowerCase();
-    const lowerVersion = String(version).toLowerCase();
-    const url = `${content.replace(/\/?$/, "/")}${lowerId}/${lowerVersion}/${lowerId}.${lowerVersion}.nupkg`;
-    const response = await fetch(url, { headers: { "X-NuGet-ApiKey": key } });
+    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);
 }
 
+/**
+ * The feed's copy of this version, read before the push: its bytes, or null when the feed
+ * does not have it. Anything else is reported rather than pushed over, since a push could
+ * then replace a version the feed does have.
+ */
+async function publishedCopy(content, id, version, key) {
+    const url = contentUrl(content, id, version);
+    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() +
+            (response.status === 401 || response.status === 403
+                ? ". Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+
 /**
  * Push the package to a remote feed: one PUT to the endpoint the service index names,
  * the package as the first part of a multipart body, the key in X-NuGet-ApiKey.
@@ -216,7 +237,28 @@ function publishRemote(archive, manifest, options, id, log) {
     const { bytes } = nupkg(archive, id, manifest, options);
 
     return (async () => {
-        const { publish: endpoint, content } = await feedResources(options.repository);
+        const { publish: resource, content } = await feedResources(options.repository);
+        // With a trailing slash, as `dotnet nuget push` sends it: a GitLab feed recognises
+        // the upload only at that form of the URL, and refuses the other as invalid.
+        const endpoint = resource.replace(/\/?$/, "/");
+
+        // 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.
+        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");
+            }
+        }
         const boundary = `api-only-${crypto.createHash("sha256").update(bytes).digest("hex").slice(0, 32)}`;
         const body = Buffer.concat([
             Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="package"; filename="package.nupkg"\r\n` +