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

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.3
+:api-only-publisher-version: 0.15.0
 
 [NOTE]
 .About this documentation
@@ -641,7 +641,7 @@ Not a distribution mechanism between repositories: it makes the pipeline testabl
 Publishing a version again writes it again and keeps the others (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
 
 |`maven`
-|A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file and a bearer token.
+|A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file, and keeps its `maven-metadata.xml` (<<maven-remote,Publishing to a remote Maven repository §>>).
 Native for Gradle consumers: version resolution, caching and conflict handling come free, which is what lets the Subscriber carry no HTTP client of its own.
 
 |`npm`
@@ -651,6 +651,10 @@ Native for Gradle consumers: version resolution, caching and conflict handling c
 |The language-neutral floor: immutable per tag, works for private repositories with a token, readable by a consumer with no JVM and no Node.js.
 No dependency-resolution semantics and no update notification, which is why it is the fallback rather than the default.
 
+|`gitlab-package`
+|A GitLab project's Generic Package Registry: the archive and `manifest.json` as a generic package per target, on gitlab.com or a self-managed GitLab.
+In a GitLab CI job it needs no settings at all. See <<gitlab-package,The `gitlab-package` channel §>>.
+
 |`nuget`
 |A path writes a `.nupkg` into a local feed; an `http(s)` URL -- the feed's service index -- pushes to a remote one.
 Native for .NET consumers: a `PackageReference` at a version, restored from a feed. See <<nuget,The `nuget` channel §>>.
@@ -674,13 +678,46 @@ What happens when the destination already has the version:
 |`file`; `maven` and `nuget` to a directory; `npm` with `publish: false`
 |Written again. With the same content the bytes are the same; with different content the version is replaced, and every subscriber whose lockfile recorded the old bytes fails its build until the change is published as a new version.
 
-|`maven` and `nuget` to a URL, `npm`, `github-release`
+|`maven` and `nuget` to a URL, `npm`, `github-release`, `gitlab-package`
 |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.
+`maven` and `gitlab-package` read back every file before uploading any, so a run interrupted half-way is completed by the next one; a GitLab registry that allows duplicate packages, as it does by default, would otherwise replace a 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.
 |===
 
+[#remote-switch]
+=== Refusing remote publishing
+
+A channel's *local mode* writes files: `file`, `maven` and `nuget` to a directory, `npm` with `publish: false`.
+Its *remote mode* sends them somewhere: `maven` and `nuget` to a URL, `npm` with publishing, `github-release`, `gitlab-package`.
+
+`API_ONLY_PUBLISHER_REMOTE` decides whether `publish` may use a remote mode:
+
+[cols="1,3", options="header"]
+|===
+| Value | Effect
+
+| `allow`, or unset
+| Every channel works. The default outside the Docker image.
+
+| `never`
+| `publish` refuses a run that would use any remote channel, naming each of them, before it reads a version or packs anything; the local modes work as always.
+The Publisher then contacts nothing. The default in the Docker image (<<docker-network,Nothing phones home §>>).
+|===
+
+[source,text]
+----
+Error: API_ONLY_PUBLISHER_REMOTE=never refuses the remote channels maven, github-release, so nothing was built, packed or sent. Publish with their local modes, or set API_ONLY_PUBLISHER_REMOTE=allow where this run may contact them.
+----
+
+Any other value fails `publish`, whatever its channels: a typo in a switch that keeps the Publisher sealed is not ignored.
+`--channel` narrows what is checked: `publish --channel file` succeeds under `never`, whatever else `apionly.yaml` configures.
+The Publisher used as a library keeps the same rule.
+
+The switch is a promise the Publisher keeps, not an enforcement: whoever runs it can change the variable.
+Where contacting nothing must be guaranteed, isolate the job's network on the platform as well -- `docker run --network none`, or a network policy for the runner.
+
 [#handoff]
 === The hand-off: what a `publish` run wrote
 
@@ -706,15 +743,15 @@ The hand-off is for a later step that publishes those files itself -- the second
 [#channel-text]
 === What a package says about itself
 
-The Maven POM, the npm `package.json`, the NuGet `.nuspec` and a GitHub release all describe the contract.
+The Maven POM, the npm `package.json`, the NuGet `.nuspec`, a GitHub release and a GitLab release all describe the contract.
 By default each says `API description documents for <target>.`, and a GitHub release is titled `<target> <version>`.
-`channels.<channel>.description` replaces the description, and `channels.github-release.title` and `notes` the release's title and notes (notes default to the description); `{target}` and `{version}` are filled in, as in `tagFormat`.
+`channels.<channel>.description` replaces the description, and `title` and `notes` on `channels.github-release` and `channels.gitlab-package` the release's title and notes (notes default to the description); `{target}` and `{version}` are filled in, as in `tagFormat`.
 
 npm publishes a release under the dist-tag `latest` and a pre-release under `next`.
 `channels.npm.releaseTag` and `prereleaseTag` name others: publishing a patch to an older line under `releaseTag: v1` keeps `latest` on the newest line, which publishing it under `latest` would move back.
 
 Credentials are read from the environment, never from configuration.
-`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, and `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
+`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default, and `channels.gitlab-package.tokenEnv` the GitLab token's, `GITLAB_TOKEN` by default, with `CI_JOB_TOKEN` when that is unset; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
 
 link:../docs/reference/how-publisher-and-subscriber-work-together.adoc#channels[How the Publisher and the Subscriber work together →] lists each channel's layout and options.
 
@@ -784,6 +821,88 @@ Until a `.targets` file places and verifies the documents for a .NET build, a co
 The same packed archive always produces a byte-identical package: entries in a fixed order, a fixed timestamp.
 Since `pack` is reproducible, publishing the same commit again produces the same package too, so a republish to a local feed can be checked as unchanged.
 
+[#gitlab-package]
+=== The `gitlab-package` channel
+
+It publishes each target to a GitLab project's Generic Package Registry, on gitlab.com or a self-managed GitLab, without any GitLab tooling: a package is a few HTTP requests the Publisher sends itself.
+
+[source,yaml]
+----
+channels:
+  gitlab-package:                          # in a GitLab CI job, nothing below is needed
+    # url: https://gitlab.example.com/api/v4  # default: $CI_API_V4_URL, else https://gitlab.com/api/v4
+    # project: group/subgroup/api-library     # an ID or a path; default: $CI_PROJECT_ID
+    # tokenEnv: GITLAB_TOKEN                  # default; when unset, $CI_JOB_TOKEN is used
+    # tokenType: private                      # private (default), deploy or job
+    # packageName: "{target}"                 # default
+    # release: false                          # true: also the tag's GitLab release
+    # tagFormat: "{target}-v{version}"        # for release: true
+    # title, notes, description               # as for github-release
+----
+
+*The package* is named after the target, at the contract's version, and holds two files: `<target>-<version>.tgz` and `manifest.json`, the ones the `file` channel writes.
+A consumer downloads them from `<url>/projects/<project>/packages/generic/<target>/<version>/<file>`, or from the project's *Deploy › Package registry* page.
+
+*In a GitLab CI job* the channel needs no settings: the API URL, the project and the job's token come from GitLab's predefined variables `CI_API_V4_URL`, `CI_PROJECT_ID` and `CI_JOB_TOKEN`.
+link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, from the Docker image, in one job (<<docker-gitlab,Reference pipeline: GitLab CI §>>).
+
+*The credential* is the first of these the environment holds:
+
+[cols="2,2,3", options="header"]
+|===
+| Variable | Sent as | For
+
+| The one `tokenEnv` names, `GITLAB_TOKEN` by default
+| `PRIVATE-TOKEN`; with `tokenType: deploy`, `DEPLOY-TOKEN`; with `tokenType: job`, `JOB-TOKEN`
+| A personal or project access token with the `api` scope, or a deploy token with `write_package_registry` (and `read_package_registry`, for the read-back).
+
+| `CI_JOB_TOKEN`
+| `JOB-TOKEN`
+| A GitLab CI job publishing to its own project.
+|===
+
+Without either, `publish` fails before anything is sent, naming both.
+A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
+
+*The same version again.*
+GitLab allows duplicate packages by default: it accepts a different file under a version it already has, and serves that one from then on.
+So the channel reads every file back before uploading any: an identical file is left alone, a missing one is uploaded, and a different one fails `publish` (<<idempotent,Publishing the same version again §>>).
+Turning *Allow duplicates* off for generic packages, in the group's *Settings › Packages and registries*, makes GitLab refuse a replaced file too, from every client; the Publisher keeps a version immutable either way.
+
+*`release: true`* also creates the tag's GitLab release, tagging `$CI_COMMIT_SHA` or, outside CI, the checkout's `HEAD`, and links both files as packages.
+An existing release keeps everything it has, and only gets the links it lacks.
+A pre-release publishes the package and no release: GitLab has no pre-release flag, so the release would become the project's latest.
+A deploy token cannot create a release -- GitLab gives it the package registry only -- so `release: true` with `tokenType: deploy` is refused before anything is sent.
+
+link:../docs/guides/publishing-to-gitlab/overview.adoc[Publishing to GitLab →] covers the rest: job-token permissions, self-managed instances and their certificates, and how consumers read the packages.
+
+[#maven-remote]
+=== Publishing to a remote Maven repository
+
+An `http(s)` `repository` deploys with an HTTP `PUT` per file: the artifact, its POM, and `-manifest.json`.
+
+[source,yaml]
+----
+channels:
+  maven:
+    groupId: com.example.api
+    repository: https://gitlab.example.com/api/v4/projects/1234/packages/maven
+    tokenEnv: CI_JOB_TOKEN    # default: MAVEN_TOKEN
+    tokenHeader: Job-Token    # default: Authorization, as a bearer token
+    # metadata: false         # leave maven-metadata.xml to a repository that generates it
+----
+
+*The token* goes as a bearer token, `Authorization: Bearer <token>`, unless `tokenHeader` names another header, which then carries it as it is.
+GitLab's Maven registry takes a job token as `Job-Token`, a personal or project access token as `Private-Token`, and a deploy token as `Deploy-Token`; a GitLab Maven repository URL needs the project's numeric ID, since Gradle reads `%2F` in a path as `/`.
+
+*Every file is read back* before any is uploaded: identical is left alone, missing is uploaded, different fails `publish`, naming the file.
+
+*`maven-metadata.xml`* lists an artifact's versions, which is how Gradle resolves a version range and how Renovate and Dependabot see a new version.
+Nexus, Artifactory and GitHub Packages keep it themselves; GitLab does not for files uploaded this way.
+So after a version's files, the channel adds the version to it, as `mvn deploy` does: `latest` is the highest version, `release` the highest that is not a pre-release, and `lastUpdated` the time of the commit, so the same commit writes the same file.
+It is written only when it lacks the version, or its `latest` or `release` would change.
+A repository that refuses it fails `publish`, naming `metadata: false`; the version's files are published by then, and a re-run retries only the metadata.
+
 [#why-registries]
 === Why npm, Maven and NuGet rather than release assets alone
 
@@ -999,7 +1118,7 @@ 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.
+A channel is one way of shipping it -- `file`, `maven`, `npm`, `nuget`, `github-release` or `gitlab-package` -- 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.
@@ -1093,7 +1212,8 @@ This publishes `com.example.contracts:orders:<version>@tgz`, which a build fetch
 *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.
+* 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` or `gitlab-package` for anything else.
+* A library hosted on GitLab publishes to its own project's registries: `gitlab-package`, which needs no settings in a GitLab CI job, and `maven` to the project's Maven registry with `tokenHeader: Job-Token` (<<gitlab-package,The `gitlab-package` channel §>>).
 
 [#recipe-microservices]
 === Microservice architecture: several targets, one channel
@@ -1189,7 +1309,8 @@ One run publishes `com.example.partner:partner-api`, `@example-partner/partner-a
 * `--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 §>>).
+* Each channel takes its credential from the environment, never from `apionly.yaml`: `MAVEN_TOKEN`, `NUGET_API_KEY` and `GITLAB_TOKEN` by default, npm's own configuration for `npm`, and the GitHub CLI's for `github-release` (<<channel-text,What a package says about itself §>>).
+* A partner without a package manager gets a download: `github-release` where the library is on GitHub, `gitlab-package` where it is on GitLab.
 * 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.
 
@@ -1539,13 +1660,45 @@ The Publisher is also a Docker image, for CI pipelines that may run only what ha
 |===
 
 Vetting the npm package does not vet what it runs: it fetches Redocly CLI and AsyncAPI CLI with `npx` when it runs.
-The image is one artefact, with one digest, holding one Publisher version *and* its toolchain, and it is *sealed*: it downloads nothing, and contacts nothing, when it runs.
+The image is one artefact, with one digest, holding one Publisher version *and* its toolchain, and it is *sealed*: it downloads nothing when it runs, and contacts nothing unless a job allows it to publish.
 It can be pulled by digest, its signature verified, its SBOM and provenance read, scanned, and mirrored, and then a pipeline knows exactly what it runs.
 
 Both registries serve the same image, with the same digest: Docker Hub gets a copy of what GHCR was given, never a rebuild.
 
 link:../docs/guides/publishing-from-ci/overview.adoc[Publishing from CI with the image →] is the guide, with prompts that set up the pipeline in your own repository.
 
+Publishing from the image takes one job or two:
+
+[cols="1,2,2", options="header"]
+|===
+| | One job | Two steps
+
+| What runs
+| The image, and nothing else.
+| The image packages; a job per registry publishes with that registry's own client, on an image of its own.
+
+| Credentials and network
+| The publishing job allows the image to contact the registry (`API_ONLY_PUBLISHER_REMOTE: allow`) and hands it the token.
+| The image never holds a credential, and runs with no network.
+
+| Channels
+| `gitlab-package`, and `maven` to a URL: the remote modes the image is tested with.
+| Every channel, in its local mode.
+
+| Reference pipeline
+| <<docker-gitlab,GitLab CI §>>
+| <<docker-github-actions,GitHub Actions §>>, and the <<docker-gitlab,GitLab CI §>> variant
+|===
+
+[#docker-one-job]
+=== One job: the image publishes
+
+The job runs `build`, `lint` and `publish` in the image, with `API_ONLY_PUBLISHER_REMOTE: allow` and the registry's token in its environment.
+Nothing else runs, so the image is the only artefact to vet, mirror and pin; the publishing clients and their images that two steps need are not.
+The image stays sealed in every other job, and the job contacts only the destinations `apionly.yaml` configures.
+
+The remote modes the image is tested with are `gitlab-package` and `maven` to a URL: its smoke test publishes with both, as a non-root user on a read-only root, to a GitLab stand-in on a network with no route out (<<docker-verifying,Running the smoke test §>>).
+
 [#docker-two-steps]
 === Two steps: package in the image, publish with the platform's tools
 
@@ -1556,14 +1709,15 @@ It needs no network and no credential.
 Every `publish` run writes a hand-off, <<handoff,The hand-off §>>, listing each file it wrote with its SHA-256.
 The publishing job checks the files against it, and publishes exactly those bytes: the bytes in the registry are the bytes the vetted tool produced.
 
-Credentials never enter the image.
+In two steps, credentials never enter the image.
 
 [IMPORTANT]
-.What the image does not do yet
+.What the image does not publish itself yet
 ====
-The image does not publish to a remote registry itself.
-The channels' remote modes -- `maven` or `nuget` to a URL, `npm` with publishing, `github-release` -- may work from inside it, but they are neither tested nor supported there.
-Publish in a second step, as <<docker-pipelines>> shows.
+The image refuses every remote mode unless a job sets `API_ONLY_PUBLISHER_REMOTE: allow` (<<remote-switch,Refusing remote publishing §>>).
+Allowed, it supports `gitlab-package` and `maven` to a URL.
+`nuget` to a URL, `npm` with publishing and `github-release` may work from inside it too, but they are neither tested nor supported there yet -- `github-release` needs the GitHub CLI, which the image does not hold.
+Publish those in a second step, as <<docker-pipelines>> shows.
 ====
 
 [#docker-tags]
@@ -1803,6 +1957,10 @@ The image makes no outbound connection: it sets, in its environment, what switch
 
 This is tested, not assumed: the whole smoke test was run on a network whose every packet was captured, and the image sent none.
 
+Nor does `publish` contact anything: the image sets `API_ONLY_PUBLISHER_REMOTE=never`, so a run that would use a remote channel fails before it packs anything, naming the channels (<<remote-switch,Refusing remote publishing §>>).
+A pipeline that publishes from the image sets `API_ONLY_PUBLISHER_REMOTE: allow` on that job: a visible line, reviewed like any other.
+The variable is the Publisher's promise; a pipeline that must be sure the job contacts nothing also runs it without a network, `docker run --network none`.
+
 [#docker-ci-job]
 ==== As a CI job image
 
@@ -1850,19 +2008,24 @@ Each publishing step checks for the version first, compares the bytes, and publi
 [#docker-gitlab]
 ==== Reference pipeline: GitLab CI
 
-[WARNING]
-====
-*Not exercised.*
-This pipeline is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
-====
+One job, on a `v*` tag, as the GitHub Actions pipeline: the image builds, lints and publishes the targets to the project's Generic Package Registry with `gitlab-package`, and, where `apionly.yaml` configures it, to the project's Maven registry, both with the job's `CI_JOB_TOKEN`.
+`apionly.yaml` needs no GitLab settings for it; the pipeline's header says what to add for the Maven registry.
+Copy it to `.gitlab-ci.yml`, then set the digest and the targets.
+The tag pattern keeps out the tag a GitLab release puts on the commit, `<target>-v<version>`, which would otherwise start the pipeline a second time; a library that tags its releases otherwise changes the rule, and keeps that one out.
 
-The same two steps: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+It has run on gitlab.com: with the job token, it published to the project's generic and Maven registries, created the release, and, run again, found everything published and changed nothing.
+It is validated against GitLab's published CI schema, the image's smoke test publishes as this job does to a GitLab stand-in, and the link:../.github/workflows/api-only-publisher-image-e2e.yml[end-to-end workflow →] publishes the same way to a gitlab.com test project, with a deploy token.
 
 [source,yaml]
 ----
 include::pipelines/gitlab-ci.yml[]
 ----
 
+link:../docs/guides/publishing-to-gitlab/overview.adoc[Publishing to GitLab →] is the guide: tokens, a self-managed GitLab, and what consumers need.
+
+*The two-step variant*, link:pipelines/gitlab-ci-two-step.yml[`pipelines/gitlab-ci-two-step.yml` →], keeps the image sealed: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with that registry's own client and `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+It is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
+
 [#docker-mirror-in-pipelines]
 ==== Using a mirrored image
 
@@ -1956,12 +2119,14 @@ docker build -t api-only-publisher:local --build-arg VERSION=0.0.0-local .
 docker/smoke-test.sh api-only-publisher:local 0.0.0-local
 ----
 
-It runs every step with no network, a read-only root and your own user: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, the shell mode, and a build as an arbitrary UID.
+It runs every step with a read-only root and your own user, and all but the last with no network: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, a remote channel refused while sealed, the shell mode, and a build as an arbitrary UID.
+The last step publishes with `gitlab-package` and `maven` to a GitLab stand-in, run from the same image, on a Docker network it creates with no route out (`docker network create --internal`) and removes afterwards; it checks every request went to the project's package registries with the job token, and that a re-run uploads nothing.
 
 link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.
 link:test/docker.test.js[`test/docker.test.js` →] holds it to what the link:pipelines/[reference pipelines →] do, the same actions, commands, inputs and environment, but not to the versions they pin.
 The reference pipelines are examples, maintained on their own, and the end-to-end workflow is maintained with this repository's other workflows, so a new version of an action in one never fails the Publisher's build while the other has not moved.
 Give it an image by digest; it publishes version `0.<run>.<attempt>` of two scratch targets, `apionly-e2e-alpha` and `apionly-e2e-beta`, to npm, Maven and NuGet on GitHub Packages and to a scratch release, publishes again to prove a re-run is safe, resolves each package with its own client and with the Subscriber, and removes what it published.
+Its `gitlab` job publishes the same targets from the image, in one job, to a gitlab.com test project's Generic Package Registry and Maven registry with a deploy token (secret `GITLAB_E2E_DEPLOY_TOKEN`), publishes again, checks GitLab serves the image's bytes and lists the version in `maven-metadata.xml`, and resolves a contract with the Subscriber; a deploy token cannot delete packages, so the run's summary lists the scratch versions to delete by hand.
 The image workflow, dispatched by hand, is the release's dry run: its defaults are the scratch names `ghcr.io/arc-e-tect/api-only-publisher-scratch` and `arcetect/api-only-publisher-scratch`, and it builds from the branch's source.
 
 [#adapting]

package/package.json

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

package/src/channels.js

@@ -12,9 +12,11 @@ const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
 
-const { isPrerelease, npmDistTag } = require("./version-policy");
+const { parse, compare, isPrerelease, npmDistTag } = require("./version-policy");
 const { ChannelError } = require("./channel-error");
 const { publishNuget } = require("./nuget");
+const { publishGitlabPackage } = require("./gitlab");
+const { refuseRemote } = require("./remote");
 
 /** What every package and release says it is, unless `description` says otherwise. */
 const DEFAULT_DESCRIPTION = "API description documents for {target}.";
@@ -301,11 +303,11 @@ function publishGithubRelease(archive, manifest, options, log) {
  * configuration file gets committed, and a credential in a committed file is a
  * credential that has leaked.
  */
-async function putFile(url, body, token, contentType) {
+async function putFile(url, body, auth, contentType) {
     const response = await fetch(url, {
         method: "PUT",
         headers: {
-            "Authorization": `Bearer ${token}`,
+            ...auth,
             "Content-Type": contentType,
             "Content-Length": String(body.length),
         },
@@ -322,8 +324,8 @@ async function putFile(url, body, token, contentType) {
 }
 
 /** What a Maven repository holds at `url`, or null when it holds nothing there. */
-async function getFile(url, token) {
-    const response = await fetch(url, { headers: { "Authorization": `Bearer ${token}` } });
+async function getFile(url, auth) {
+    const response = await fetch(url, { headers: auth });
     if (response.status === 404) return null;
     if (!response.ok) {
         throw new ChannelError(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
@@ -333,6 +335,54 @@ async function getFile(url, token) {
     return Buffer.from(await response.arrayBuffer());
 }
 
+/** An HTTP header name: RFC 9110's token. */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+/** The highest of `versions` that parse as semver and pass `keep`, or null. */
+function highest(versions, keep = () => true) {
+    const valid = versions.filter((v) => { try { parse(v); return keep(v); } catch { return false; } });
+    return valid.length ? valid.reduce((a, b) => (compare(a, b) >= 0 ? a : b)) : null;
+}
+
+/** The artifact's maven-metadata.xml, as `mvn deploy` keeps it. */
+function metadataXml(groupId, artifactId, versions, lastUpdated) {
+    const latest = highest(versions);
+    const release = highest(versions, (v) => !isPrerelease(v));
+    return '<?xml version="1.0" encoding="UTF-8"?>\n<metadata>\n' +
+        `  <groupId>${groupId}</groupId>\n  <artifactId>${artifactId}</artifactId>\n  <versioning>\n` +
+        (latest ? `    <latest>${latest}</latest>\n` : "") + (release ? `    <release>${release}</release>\n` : "") +
+        `    <versions>\n${versions.map((v) => `      <version>${v}</version>\n`).join("")}    </versions>\n` +
+        `    <lastUpdated>${lastUpdated}</lastUpdated>\n  </versioning>\n</metadata>\n`;
+}
+
+/**
+ * Adds the version to the artifact's maven-metadata.xml, which a repository that does not
+ * generate it -- GitLab's -- otherwise never has, so that update bots never see a new
+ * version. Written only when it lacks the version, or its latest or release would change.
+ */
+async function updateMetadata(url, groupId, artifactId, manifest, auth, log) {
+    const held = await getFile(url, auth);
+    const xml = held ? held.toString("utf8") : "";
+    const block = /<versions>([\s\S]*?)<\/versions>/.exec(xml);
+    const versions = block ? [...block[1].matchAll(/<version>\s*([^<\s]+)\s*<\/version>/g)].map((m) => m[1]) : [];
+    const tag = (name) => ((new RegExp(`<${name}>\\s*([^<\\s]+)\\s*</${name}>`).exec(xml)) || [])[1] || null;
+    const listed = versions.includes(manifest.version) ? versions : [...versions, manifest.version];
+    if (listed === versions && tag("latest") === highest(listed)
+        && tag("release") === highest(listed, (v) => !isPrerelease(v))) {
+        return;
+    }
+    // The commit's time, as the archive's producedAt, so the same commit writes the same file.
+    const lastUpdated = String(manifest.producedAt || new Date().toISOString()).replace(/\.\d+Z$/, "Z").replace(/[-:TZ]/g, "");
+    try {
+        await putFile(url, Buffer.from(metadataXml(groupId, artifactId, listed, lastUpdated), "utf8"), auth, "application/xml");
+    } catch (error) {
+        throw new ChannelError(`the repository refused maven-metadata.xml for ${groupId}:${artifactId}: ${error.message.trim()} ` +
+            "The version's files are published; a re-run retries only the metadata. For a repository that generates " +
+            "its own maven-metadata.xml, set channels.maven.metadata: false.");
+    }
+    log(`-- Listed ${manifest.version} in ${groupId}:${artifactId}'s maven-metadata.xml`);
+}
+
 function publishMavenRemote(archive, manifest, options, log) {
     const tokenEnv = options.tokenEnv || "MAVEN_TOKEN";
     const token = process.env[tokenEnv];
@@ -342,12 +392,20 @@ function publishMavenRemote(archive, manifest, options, log) {
             `Remote publication needs one; set it in the release job's environment.`
         );
     }
+    // A bearer token unless tokenHeader names another header, which then carries the
+    // token as it is: GitLab takes a job, personal or deploy token as Job-Token,
+    // Private-Token or Deploy-Token, and Bearer only for OAuth.
+    if (options.tokenHeader !== undefined && !HEADER_NAME.test(options.tokenHeader)) {
+        throw new ChannelError(`channels.maven.tokenHeader must be an HTTP header name, such as Job-Token, ` +
+            `not ${JSON.stringify(options.tokenHeader)}`);
+    }
+    const auth = options.tokenHeader === undefined ? { "Authorization": `Bearer ${token}` } : { [options.tokenHeader]: token };
 
     const artifactId = options.artifactId || manifest.target;
     const version = manifest.version;
     const extension = options.extension || "tgz";
-    const base = `${options.repository.replace(/\/+$/, "")}/` +
-        `${options.groupId.split(".").join("/")}/${artifactId}/${version}/${artifactId}-${version}`;
+    const artifactDir = `${options.repository.replace(/\/+$/, "")}/${options.groupId.split(".").join("/")}/${artifactId}`;
+    const base = `${artifactDir}/${version}/${artifactId}-${version}`;
 
     const work = (async () => {
         // Idempotent, file by file: each file the repository already has is left alone when
@@ -363,7 +421,7 @@ function publishMavenRemote(archive, manifest, options, log) {
         ];
         const missing = [];
         for (const file of files) {
-            const existing = await getFile(file.url, token);
+            const existing = await getFile(file.url, auth);
             if (!existing) {
                 missing.push(file);
             } else if (!existing.equals(file.bytes)) {
@@ -373,7 +431,10 @@ function publishMavenRemote(archive, manifest, options, log) {
                     "A published version is never replaced; publish the change as a new version.");
             }
         }
-        for (const file of missing) await putFile(file.url, file.bytes, token, file.type);
+        for (const file of missing) await putFile(file.url, file.bytes, auth, file.type);
+        if (options.metadata !== false) {
+            await updateMetadata(`${artifactDir}/maven-metadata.xml`, options.groupId, artifactId, manifest, auth, log);
+        }
         return missing.length === 0;
     })();
 
@@ -392,6 +453,7 @@ function publishMavenRemote(archive, manifest, options, log) {
 
 const CHANNELS = {
     file: publishFile, maven: publishMaven, npm: publishNpm, "github-release": publishGithubRelease, nuget: publishNuget,
+    "gitlab-package": publishGitlabPackage,
 };
 
 function publish(archive, manifest, channel, options, log = () => {}) {
@@ -401,6 +463,8 @@ function publish(archive, manifest, channel, options, log = () => {}) {
             `unknown channel '${channel}'; available channels are ${Object.keys(CHANNELS).join(", ")}`
         );
     }
+    // Here as well as in the CLI, so the Publisher used as a library keeps it too.
+    refuseRemote([channel], { [channel]: options || {} });
     return handler(archive, manifest, options || {}, log);
 }
 

package/src/cli.js

@@ -17,6 +17,7 @@ const { pack, PackError } = require("./pack");
 const { changedSince, ChangedError } = require("./changed");
 const { split, SplitError } = require("./split");
 const { publish, ChannelError } = require("./channels");
+const { refuseRemote } = require("./remote");
 const { VersionError: PolicyError, describe } = require("./version-policy");
 const { versionOf, BundleVersionError } = require("./bundle-version");
 const { unreferenced } = require("./unreferenced");
@@ -451,6 +452,8 @@ async function main(argv, io = {}) {
             if (names.length === 0) {
                 throw new ConfigError("no channels configured; add a `channels:` block or pass --channel");
             }
+            // Every channel this run uses, before anything is read, packed or sent.
+            refuseRemote(names, configured);
             const shipped = shippedTargets(config, targets);
             const versions = versionsOf(config, shipped, options.preRelease);
             const closures = forTargets(config, undefined, shipped);

package/src/gitlab.js

@@ -0,0 +1,187 @@
+"use strict";
+
+// `gitlab-package` -- publish to a GitLab project's Generic Package Registry.
+//
+// One generic package per target, at the contract's version, holding the archive and
+// manifest.json: the same two files the `file` channel writes. In a GitLab CI job it
+// needs no settings at all: the API, the project and the job token come from GitLab's
+// own CI variables. `release: true` also creates the tag's GitLab release, linking both
+// files as packages.
+//
+// GitLab allows duplicate versions by default: a different file under a version it has
+// is accepted, and served from then on. So every file is read back before it is
+// uploaded, and the read-back, not GitLab, keeps a published version immutable.
+
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const { isPrerelease } = require("./version-policy");
+const { ChannelError } = require("./channel-error");
+
+const GITLAB_COM = "https://gitlab.com/api/v4";
+const TOKEN_HEADERS = { private: "PRIVATE-TOKEN", deploy: "DEPLOY-TOKEN", job: "JOB-TOKEN" };
+
+/** The API, the project and the credential, from configuration first and GitLab CI variables second. */
+function channelSettings(options, env = process.env) {
+    const tokenEnv = options.tokenEnv || "GITLAB_TOKEN";
+    let token = env[tokenEnv];
+    let tokenType = options.tokenType || "private";
+    if (!TOKEN_HEADERS[tokenType]) {
+        throw new ChannelError(`channels.gitlab-package.tokenType must be private, deploy or job, not ${JSON.stringify(tokenType)}`);
+    }
+    if (!token && env.CI_JOB_TOKEN) {
+        token = env.CI_JOB_TOKEN;
+        tokenType = "job";
+    }
+    if (!token) {
+        throw new ChannelError(
+            `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.");
+    }
+    const project = options.project === undefined ? env.CI_PROJECT_ID : String(options.project);
+    if (!project) {
+        throw new ChannelError("the gitlab-package channel needs a project: set channels.gitlab-package.project, " +
+            "or run in a GitLab CI job ($CI_PROJECT_ID)");
+    }
+    const url = (options.url || env.CI_API_V4_URL || GITLAB_COM).replace(/\/+$/, "");
+    return { url, project, tokenType, headers: { [TOKEN_HEADERS[tokenType]]: token } };
+}
+
+/** The commit a new release's tag points at: the CI job's, or the checkout's HEAD. */
+function releaseRef(options, env = process.env) {
+    if (env.CI_COMMIT_SHA) return env.CI_COMMIT_SHA;
+    try {
+        return execFileSync("git", ["-C", path.resolve(options.baseDir || "."), "rev-parse", "HEAD"],
+            { encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+        throw new ChannelError("release: true needs the commit to tag: $CI_COMMIT_SHA, or a git checkout to read HEAD from");
+    }
+}
+
+/** The status and GitLab's message, without the status twice: GitLab's messages often start with it. */
+async function answered(response) {
+    const text = await response.text();
+    let message = text;
+    try {
+        const body = JSON.parse(text);
+        message = body.message || body.error || text;
+    } catch {
+        // Not JSON: a proxy's error page, say. Reported as it came.
+    }
+    return message.startsWith(String(response.status)) ? message : `${response.status} ${message}`;
+}
+
+const TOKEN_HINT = " Check the token, and that it may read and write this project's package registry.";
+
+/** GitLab's copy of a package file: its bytes, or null when it has none. */
+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)}.` +
+            (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; ` +
+        "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)}`;
+    // 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}.` +
+        (response.status === 401 || response.status === 403 ? TOKEN_HINT : ""));
+}
+
+async function api(url, headers, method = "GET", body) {
+    return fetch(url, {
+        method,
+        headers: body === undefined ? headers : { ...headers, "Content-Type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+}
+
+/** Creates the tag's release, or adds the package links an existing one lacks; never changes anything else. */
+async function release(settings, manifest, options, links, ref, log) {
+    const { format, DEFAULT_DESCRIPTION } = require("./channels");
+    const tag = format(options.tagFormat || "{target}-v{version}", manifest);
+    const releases = `${settings.url}/projects/${encodeURIComponent(settings.project)}/releases`;
+    const existing = await api(`${releases}/${encodeURIComponent(tag)}`, settings.headers);
+    if (existing.status === 404) {
+        const created = await api(releases, settings.headers, "POST", {
+            tag_name: tag,
+            ref,
+            name: format(options.title || "{target} {version}", manifest),
+            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)}`);
+        log(`-- Created the GitLab release ${tag}`);
+        return;
+    }
+    if (!existing.ok) {
+        throw new ChannelError(`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)}`);
+        log(`-- Linked ${link.name} from the GitLab release ${tag}`);
+    }
+}
+
+function publishGitlabPackage(archive, manifest, options, log) {
+    const { format } = require("./channels");
+    const settings = channelSettings(options);
+    const wantsRelease = options.release === true && !isPrerelease(manifest.version);
+    if (wantsRelease && settings.tokenType === "deploy") {
+        throw new ChannelError("a deploy token cannot create a GitLab release: GitLab gives it the package registry only. " +
+            "Publish with $CI_JOB_TOKEN, or a personal or project access token with the api scope, or set release: false.");
+    }
+    const ref = wantsRelease ? releaseRef(options) : null;
+
+    const packageName = format(options.packageName || "{target}", manifest);
+    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") },
+    ].map((file) => ({ ...file, url: `${base}/${encodeURIComponent(file.name)}` }));
+
+    return (async () => {
+        let identical = 0;
+        for (const file of files) {
+            if (await upload(file.url, file.name, file.bytes, manifest, settings.headers)) identical += 1;
+        }
+        const alreadyPublished = identical === files.length;
+        log(alreadyPublished
+            ? `-- ${packageName} ${manifest.version} is already in GitLab project ${settings.project}, identical; nothing to do`
+            : `-- Published ${packageName} ${manifest.version} to GitLab project ${settings.project}`);
+
+        if (options.release === true && !wantsRelease) {
+            log(`-- no GitLab release for a pre-release: ${manifest.version} would become the latest release`);
+        }
+        if (wantsRelease) {
+            await release(settings, manifest, options,
+                files.map((file) => ({ name: file.name, url: file.url, link_type: "package" })), ref, log);
+        }
+        return { location: files[0].url, ...(alreadyPublished ? { alreadyPublished } : {}) };
+    })();
+}
+
+module.exports = { publishGitlabPackage, channelSettings };

package/src/pack.js

@@ -22,6 +22,21 @@ function sha256(file) {
     return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
 }
 
+/**
+ * A repository URL fit to publish: without the credentials a remote URL can carry --
+ * GitLab CI checks out with `https://gitlab-ci-token:<job token>@host/...`, and a
+ * clone made with a token in its URL keeps it there -- and without a query string or
+ * fragment, where some hosts carry one too. An scp-like `git@host:path` and a local
+ * path are left alone: neither holds a secret.
+ */
+function publicUrl(url) {
+    if (!url) return url;
+    const match = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)([^?#]*)/i.exec(url);
+    if (!match) return url;
+    const [, scheme, authority, rest] = match;
+    return scheme + authority.slice(authority.lastIndexOf("@") + 1) + rest;
+}
+
 function gitInfo(cwd) {
     const git = (args) => {
         try {
@@ -31,7 +46,7 @@ function gitInfo(cwd) {
         }
     };
     return {
-        repository: git(["config", "--get", "remote.origin.url"]),
+        repository: publicUrl(git(["config", "--get", "remote.origin.url"])),
         commit: git(["rev-parse", "HEAD"]),
     };
 }
@@ -145,4 +160,4 @@ function pack(config, target, { version, closureSha256, outDir, log = () => {} }
     return { archive, manifest: data, manifestPath };
 }
 
-module.exports = { pack, manifest, sha256, MANIFEST_NAME, MANIFEST_SCHEMA_VERSION, PackError };
+module.exports = { pack, manifest, sha256, MANIFEST_NAME, MANIFEST_SCHEMA_VERSION, PackError, publicUrl };

package/src/remote.js

@@ -0,0 +1,60 @@
+"use strict";
+
+// Whether `publish` may contact anything.
+//
+// A channel's local mode writes files; its remote mode sends them somewhere: a
+// repository or feed at a URL, a registry, a release. API_ONLY_PUBLISHER_REMOTE=never
+// refuses every remote mode, so the Publisher contacts nothing. The Docker image sets
+// it, and is sealed unless a pipeline sets allow; outside the image it is unset, and
+// the Publisher behaves as it always has.
+//
+// It is a promise the Publisher keeps, not an enforcement: whoever sets the variable
+// can change it. A guarantee needs the platform to isolate the job's network.
+
+const { ChannelError } = require("./channel-error");
+
+const REMOTE_ENV = "API_ONLY_PUBLISHER_REMOTE";
+
+/** `allow`, the default when unset or empty, or `never`; anything else is refused. */
+function remoteMode(env = process.env) {
+    const value = env[REMOTE_ENV];
+    if (value === undefined || value === "") return "allow";
+    if (value !== "allow" && value !== "never") {
+        throw new ChannelError(`${REMOTE_ENV} must be allow or never, not ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+
+const URL = /^https?:\/\//;
+
+/** Whether `channel`, with these settings, would contact anything. */
+function isRemote(channel, settings = {}) {
+    switch (channel) {
+        case "maven":
+        case "nuget":
+            return URL.test(settings.repository || "");
+        case "npm":
+            return settings.publish !== false;
+        case "github-release":
+        case "gitlab-package":
+            return true;
+        default:
+            return false;
+    }
+}
+
+/**
+ * Refuses, under `never`, a run that would use any remote channel, naming each of them,
+ * before anything is built, packed or sent. Also refuses an invalid value, whatever the
+ * channels: a typo in a switch that keeps the Publisher sealed is not ignored.
+ */
+function refuseRemote(names, configured = {}, env = process.env) {
+    if (remoteMode(env) === "allow") return;
+    const remote = names.filter((name) => isRemote(name, configured[name] || {}));
+    if (remote.length === 0) return;
+    throw new ChannelError(
+        `${REMOTE_ENV}=never refuses the remote channels ${remote.join(", ")}, so nothing was built, packed or sent. ` +
+        `Publish with their local modes, or set ${REMOTE_ENV}=allow where this run may contact them.`);
+}
+
+module.exports = { REMOTE_ENV, remoteMode, isRemote, refuseRemote };

package/src/version-policy.js

@@ -33,6 +33,32 @@ function parse(version) {
     };
 }
 
+/**
+ * Semver precedence: negative when `a` comes before `b`, positive after, 0 when equal.
+ * Build metadata is ignored; a release comes after its pre-releases; pre-release
+ * identifiers compare numerically when both are numbers, a number before a word.
+ */
+function compare(a, b) {
+    const x = parse(a);
+    const y = parse(b);
+    for (const part of ["major", "minor", "patch"]) {
+        if (x[part] !== y[part]) return x[part] - y[part];
+    }
+    if (x.prerelease === y.prerelease) return 0;
+    if (x.prerelease === null) return 1;
+    if (y.prerelease === null) return -1;
+    const xs = x.prerelease.split(".");
+    const ys = y.prerelease.split(".");
+    for (let i = 0; i < Math.min(xs.length, ys.length); i++) {
+        if (xs[i] === ys[i]) continue;
+        const [xn, yn] = [/^\d+$/.test(xs[i]), /^\d+$/.test(ys[i])];
+        if (xn && yn) return Number(xs[i]) - Number(ys[i]);
+        if (xn !== yn) return xn ? -1 : 1;
+        return xs[i] < ys[i] ? -1 : 1;
+    }
+    return xs.length - ys.length;
+}
+
 function isPrerelease(version) {
     // -SNAPSHOT is not semver-legal as Maven spells it, but it is what Maven
     // consumers expect, so it is recognised rather than rejected.
@@ -65,4 +91,4 @@ function describe(version) {
     return { prerelease: true, kind: "other" };
 }
 
-module.exports = { parse, isPrerelease, npmDistTag, describe, VersionError, SEMVER };
+module.exports = { parse, compare, isPrerelease, npmDistTag, describe, VersionError, SEMVER };