Documentation
¶
Overview ¶
Package furrowbin carries furrow inside codeaf and puts it on disk the first time anything wants it.
THE RULING THIS PACKAGE EXISTS FOR IS "NO VARIANCE": every codeaf is a codeaf with furrow. Before this, furrow was a program the person went and installed, so the four workspace verbs — byte-exact forks that carry the dirty tree, the sealed timeline, the restore that puts a .env back — were a capability some machines had. Half a product is worse than either half: the model cannot plan around a verb that exists on the author's laptop and not on the reader's, and the pages that described it had to hedge every sentence. So the binary rides along, and the only thing that still varies is whether a particular folder has been attached with `furrow watch`.
The bytes get here in three moves, and each one is somewhere else:
- pin.json, committed, names the release and the sha256 of every platform's artifact. It is the auditable half and the one source of the version.
- `make build` runs cmd/fetch, which downloads that platform's artifact, checks it against the pin, and stages it gzipped into cache/. The artifact is gitignored — six megabytes of binary in git is six megabytes in every clone forever — and a fetch that cannot happen fails the build out loud, naming the command to run, rather than quietly producing an codeaf without furrow.
- This package embeds cache/ and, on first need, writes the binary out under the state root.
Ensure is the whole runtime surface, and internal/furrow is its only caller. NOTHING ELSE IN THE TREE KNOWS THE BINARY WAS EMBEDDED: the seam stays where it was, a caller still asks internal/furrow whether furrow can act on a folder, and the answer's new reason for being yes is not the caller's business.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotEmbedded = errors.New("this codeaf was not built with furrow inside it")
ErrNotEmbedded is what Ensure answers on a build that carries no furrow for this platform — a plain `go build ./...` in a fresh clone, which is a real and useful thing to be able to do. It is not the shipped state: `make build` fetches first and fails rather than produce one.
Functions ¶
func Compress ¶
Compress is what the fetcher stages with, and it lives here rather than in the fetcher so that the two halves of the format — who writes it and who reads it — are the same twenty lines apart.
func Embedded ¶
func Embedded() bool
Embedded reports whether this build carries furrow for the machine it is running on. It reads the embedded directory and decompresses nothing, so asking is free.
func Ensure ¶
Ensure puts the embedded furrow on disk if it is not already there and returns the path to it.
It is memoised for the life of the process because it sits in front of belt construction, where it is asked once per session and would otherwise cost a stat each time; the first call in a fresh state root costs one decompression and one six-megabyte write, and every call after that on every later boot costs one stat.
func Platform ¶
Platform is the key an artifact is filed under, and the only place the spelling of that key is decided. It is a function rather than a fmt.Sprintf at four call sites because the build stages a file whose NAME is this string and the running binary looks that name up: the two have to agree exactly or the binary quietly carries a furrow it will never find.
func StagedFileName ¶
StagedFileName is the name the fetcher writes inside cache/ for one platform. The build needs it for a platform it is cross-compiling to, which is why it takes the platform rather than reading runtime's.
Types ¶
type Artifact ¶
type Artifact struct {
// Asset is the file's name on the release page, which is also the last
// element of its download URL.
Asset string `json:"asset"`
// SHA256 is the hex digest published in the release's own SHA256SUMS. IT
// IS THE ONLY THING THAT MAKES THE FETCH TRUSTWORTHY: a build that takes
// whatever the network hands it and embeds it in the product has moved the
// supply chain from "a release somebody signed for" to "whatever answered".
SHA256 string `json:"sha256"`
}
Artifact is one platform's release asset and the hash it must have.
type Pin ¶
type Pin struct {
// Repository is the GitHub owner/name the release hangs off, and Tag is
// the release's tag. They are carried rather than hardcoded so that a
// furrow that moves house is a one-line diff in pin.json.
Repository string `json:"repository"`
Tag string `json:"tag"`
// Version is furrow's own version without the tag's leading v, and it is
// what stamps the extracted file's name. It is separate from Tag because
// a tag is a git label and a version is what `furrow --version` prints;
// they agree today and there is no reason to make one imply the other.
Version string `json:"version"`
// Artifacts maps "<goos>-<goarch>" to the release asset for it. A platform
// with no entry is a platform this codeaf cannot embed furrow for — which
// the build says out loud rather than quietly skipping.
Artifacts map[string]Artifact `json:"artifacts"`
}
Pin is the whole of the pin file: which furrow, from where, and what each platform's artifact must hash to.
func ReadPin ¶
func ReadPin() Pin
ReadPin returns the compiled-in pin.
A malformed pin panics rather than becoming an error every caller carries. The file is embedded at compile time and a test in this package parses every byte of it, so a pin that does not decode is a pin that could not have got past `make test` — it is not a runtime mode, and the same reasoning internal/packed states for its archives holds here.
func (Pin) ArtifactFor ¶
ArtifactFor returns the pinned asset for one platform.
func (Pin) DownloadURL ¶
DownloadURL is where one platform's artifact lives. GitHub's release download path is stable and public, so no token and no gh CLI is needed — which matters because this runs inside `make build` on machines that have neither.
Source Files
Directories