Documentation
¶
Overview ¶
Package registry is `install`'s two reads: the Manifest a ref names, and the `checksums.txt` published beside it (§11, ADR-0087, issue #187).
**What a ref is, and why `hyper` names no registry, is ADR-0087's** — an absolute `https://` URL naming the Manifest, the digest published in the ref's own directory, and the ref recorded being the one the caller typed. It is stated there rather than restated here: the load-bearing half of distribution belongs where a reader of `docs/adr/` finds it, and a package comment that argued it again would be a second copy to drift.
**It is `hyper`'s own fetch and not an Operation**, which is internal/release's sentence one command over and true here for the same reasons: no Capability is declared, no Target is bound, no credential resolves, no Journal entry is written and no Store is opened. `install` is not a Run. What it shares with a Capability's call is the dialer alone — capability.Dial, threaded from cli.Process — which is what lets a case exercise a real handshake against a server standing in the test process (§9, ADR-0009).
**It is internal/release's sibling and shares its reader.** The `sha256sum` line grammar and the client both come from there, one format having one parse and one set of transport terms having one place they are written down — threaded dialer as DialTLSContext, keep-alives off, redirects followed, plaintext refused, and no timeout, no artefact having declared one and the interrupt belonging to the human in front of the command (ADR-0014, ADR-0082).
**What it answers is bytes and the digest they were verified against, or one error.** There is one sort in the whole package and it is not the status line: §11 puts *a ref the registry does not hold* and *a fetch that did not complete* on one exit code deliberately, so building a sort between them would be inventing a distinction the specification spent a paragraph collapsing. The one answer that is told apart is bytes that arrived and are not the bytes the publisher published (§11, ADR-0060).
Index ¶
Constants ¶
const MaxManifest = 1 << 22
MaxManifest is how much of a Manifest is read. A Manifest is a reviewed artefact a human reads in a diff, so the cap is generous enough that no honest one reaches it — and it is here for internal/release's own reason: nothing about a URL guarantees what is behind it, and a body that is not the file it should be must fail as a fetch that did not complete rather than as a laptop reading a gigabyte into memory (ADR-0087).
It is this package's own number and the checksums file's is not: that file is a few hundred bytes by construction and takes internal/release's cap unchanged, the two reads being two different kinds of file rather than one read performed twice.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Fetched ¶
Fetched is what a verified read answers: the published bytes exactly as they arrived, and the digest they were verified against.
The bytes are the **published** ones — the file without the origin: block naming them, a digest being unable to cover itself — so what a caller writes is these bytes verbatim and then the block (§11, ADR-0087).
func Fetch ¶
Fetch performs the two reads and answers the verified bytes.
**The Manifest is read first and the order is not arbitrary.** It is the read that establishes the registry answers at all, and a ref that names nothing is the common case — reading the checksums file first would spend a request proving a file exists beside a file that does not (ADR-0087).
It answers a *Mismatch where the bytes arrived and did not verify, and an ordinary error everywhere else: a status line that is not `200`, a checksums file naming every published file but this one, a host that never answered, a body that stopped part way through and a body over the cap. Its caller exits on those two differently and on nothing else (§11).
**Nothing is judged beyond the digest.** The bytes are not parsed, the Manifest's own name is not read, and no static pass runs here or in the caller: it is *digest only, never intent*, and what a Manifest declares is `check`'s to report the moment the file lands (§11, ADR-0004).
type Mismatch ¶
Mismatch is bytes that arrived and are not the bytes the publisher published: artefact.CodeOriginDigestMismatch, and the one answer this package tells apart from every other.
The code is spelled at the check that recomputes it offline rather than again here, the two being one fact at the two ends of one mechanism: this package verifies published bytes once, and `check` makes that verification repeatable by anyone reading the repository long afterwards (§11, internal/artefact/manifest_origin.go).
It is a check declining rather than the world resisting, which is what puts it at a different exit code from everything else here: the read completed, the digest was published, and a verbatim retry declines identically — the remedy is the publisher's rather than another attempt (§11, §12, ADR-0060).
**Both digests are carried whole.** A digest is verified with `sha256sum` rather than recognised by eye, and an abbreviation is a value a reader has to go somewhere else to complete (ADR-0047).
type Ref ¶
type Ref struct {
// contains filtered or unexported fields
}
Ref is a ref the grammar admitted: the coordinate the caller typed, and the two things everything downstream derives from it.
**The typed string is what is kept**, and it is what String answers. A ref records a location a later `install` is typed from, so a value normalised on the way in — a lowered host, a resolved dot segment, an escape rewritten — would put a coordinate the publisher never published into a tracked file (ADR-0087).
It is a type rather than a string because the grammar is a parse and the two derivations are only sound behind it: ChecksumsURL cuts at the last `/`, which names the ref's own directory precisely because the last segment was established to hold no separator of its own.
func ParseRef ¶
ParseRef reads a ref against ADR-0087's grammar and answers what it is, or the clause it fell outside.
**Every clause is a parse and nothing here reaches the network**, which is the property the rule exists to keep: its caller exits `2`, and ADR-0060 keeps that code decidable without a round trip. Where the grammar ends is where the network begins, and everything the network answers is its caller's other code.
The error is the whole message its caller renders, less the command name: the ref as typed, and the one clause it broke. One clause rather than every clause it breaks — a caller who typed `http://` is told the scheme is `https` and does not need to be told about the query string they also wrote.
func (Ref) Basename ¶
Basename is the ref's last path segment: the checksums line to read, and the name of the file `install` writes into providers/.
**The path comes from the ref and never from the Manifest.** It is *digest only, never intent*, one aisle over: a command reading a `provider:` key to choose a filename would be deciding on a parse it has no business making, and `name-mismatch` already reports a Manifest published under a filename that disagrees with its own name (§4, §11).
func (Ref) ChecksumsURL ¶
ChecksumsURL is `checksums.txt` in the ref's own directory — the ref with its last path segment replaced, which is the whole of the registry convention ADR-0087 states.
It is derived from the **typed** ref rather than from wherever a redirect landed, for the reason the recorded ref is: the checksums file a publisher published sits beside the bytes they published, and the coordinate for it is the one that was typed.
Source Files