torb yank

A yanked version stays in the registry - nothing is ever deleted, and a lock that pins it still installs it - but new resolutions pass it over, and a build with a lock that pins it prints the reason. yank is for a release with a security hole or a broken build; the next version is the fix.

Synopsis#

torb yank <owner/name> <version>    Withdraw a version from new resolutions
  --reason <text>                   Why: a lock that pins the version prints it (required)
  --undo                            Take the yank back instead, without a reason
  --registry <url>                  The registry, instead of the one the owner is bound to
  --project <directory>             The project whose registry lines bind the owner (default: the working directory's)

What it does#

1. The registry is found as torb owner finds it: --registry, else the owner's registry binding in the project, else the public registry.
2. At a registry on the network yank sends POST <registry>/api/1/packages/<owner>/<name>/<version>/yank with the reason, and --undo sends DELETE of the same path, with the token a request to the registry sends: TORB_TOKEN, else the one torb login stored. A member with the yank action may; the registry appends a signed yank or unyank line to the package's index file.
3. At a file: registry yank appends the line itself, as torb publish appends a release: yank "<version>", reason: "<reason>", or unyank "<version>". A registry whose index/config.trb lists signing keys is refused, since only its write service can sign a record.

$ torb yank acme/http 1.2.4 --reason "sends the proxy password in clear text"
yanked acme/http 1.2.4
$ torb yank acme/http 1.2.4 --undo
acme/http 1.2.4 is no longer yanked

The index file only ever grows: the last yank or unyank line of a version is the one that holds.

Pitfalls#

A yank is not a deletion. A project whose lock pins the version keeps installing it, and is told why on every build; only a new resolution - torb update, a new project - passes it over. Publish the fix as a new version.

The reason is public. It is in the index file anyone reads; write what a user of the version needs to know, not more.

A refusal of the registry - yanked already, no such release, a token without the yank action - ends with the exit code 1, a command written wrong - no --reason, or --reason with --undo - with 2.

Examples#

Yank a release in a registry directory a team shares:

$ torb yank acme/http 1.2.4 --reason "breaks on Windows" --registry file:../registry
yanked acme/http 1.2.4 in file:../registry: breaks on Windows

Related#

• torb publish - the release a yank withdraws.
• torb deprecate - flags a whole package, and withdraws nothing.
• torb audit - reports the locked versions that are yanked.
• torb owner - who may yank.
• torb login - stores the token a yank sends.