Documentation
¶
Overview ¶
Package pluginfetch materialises one plugin, at one published version, out of a git repository.
It is TRANSPORT, deliberately and only. The client is allowed to fetch — that is the same class of work as dialling the console or writing files to disk — but every decision about what a plugin MEANS stays on the console: which version satisfies a constraint, whether the manifest is valid, how the tree is staged into a project. See the public-split architecture doc; the line this package must not cross is doing compiler work on the way past.
The two checks it does make are not that line. Both are about whether the bytes on disk are the ones the caller asked for, which is the question a fetch is responsible for answering:
- the manifest must name the plugin the tag names, and the version the tag names. `publish-plugins.sh` refuses to cut a disagreeing tag, but a repo this client did not publish never went through that gate, and the manifest is what travels on into the project once the tag is gone.
- the caller gets the resolved commit SHA and the content digest, so the lock can pin something a moved tag cannot change.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoReleases = errors.New("no releases published")
ErrNoReleases is returned when a registry ANSWERED and publishes no release of the plugin asked for.
A sentinel rather than a message a caller greps, because the two failures a resolve can have want different advice and must not be confused: a registry nobody can reach is fixed with access or a URL, while one that simply has no such plugin is fixed with another name. A CLI that appended "here is how to list what exists" to both would be telling someone with a broken remote to go and read a list they also cannot fetch.
Functions ¶
func CompareVersions ¶
CompareVersions orders two `vX.Y.Z[-prerelease]` strings: -1, 0 or +1.
Semver's precedence rules, kept to the part this project uses:
- numeric comparison of major, minor and patch;
- a version WITH a prerelease is lower than the same version without one, so promoting `v0.1.0-rc.2` to `v0.1.0` supersedes its own candidates;
- prerelease identifiers compare dot-separated part by part, numerically when both sides are numeric. That is why the tag format is `rc.2` and not `rc2`: glued, the comparison is lexical and `rc10` sorts BELOW `rc2`, which nobody notices until the tenth candidate.
An unparseable version sorts below a parseable one rather than erroring: this orders what a repository already contains, and one hand-made tag should not make every real release unreachable.
func LatestVersion ¶
LatestVersion returns the highest version published for one plugin in a repository, PRERELEASES INCLUDED.
That last part is the whole reason this exists rather than a call into an off-the-shelf resolver. Every plugin release is an `-rc.N` today and will be until w17 ships as a service, and the standard rule — the one semver states and `go get @latest` implements — is that a prerelease is never selected while any release exists. Under that rule today's catalogue resolves correctly by accident, and the day someone cuts one clean `v0.1.0` every later candidate becomes invisible. The rule is written down here instead.
Why the client resolves this ¶
Deciding which version satisfies a constraint is the console's job, and this looks like that but is not: it is an ordering over OUR OWN tag format, not knowledge about schemas or compilation. It has to run here for a plainer reason too — the repository may be a third party's, reachable only with the developer's own credentials, so a rule that cannot run where the data is would not be a rule at all. What the console still decides is everything about the tree that comes back.
func PublishedPlugins ¶
PublishedPlugins names every plugin a registry publishes, read from its tags.
A registry's inventory IS its tag namespace: `<plugin>/v<version>`. Nothing else in the repository says which directories are plugins — a directory with no release is not something a project can pin, so it is not published.
Types ¶
type Fetched ¶
Fetched is what the lock records: where the tree landed, which release it was, and the two values that make the pin immutable.
Ref and Version are carried back rather than left for the caller to rebuild from its own inputs — a caller that resolved "latest" does not otherwise know what it got, and one that rebuilt the string could rebuild it wrong.
type Source ¶
type Source struct {
// Repo is any git URL: the internal plugins repo, or a third party's.
Repo string
// Plugin is the catalogue name, which is also the top-level directory in
// the repo and the tag prefix — one string, so the three cannot drift.
Plugin string
// Version is the tag's version part, `v`-prefixed (`v0.1.0-rc.1`).
Version string
}
Source names one published plugin version.
Source Files