releasesource

type Artifact struct {
	// Name is the file's name within the release. A BARE FILENAME, validated as
	// one; see artifactName.
	Name string `json:"name"`

	// OS and Arch are Go's spellings, matching the archive names the install
	// script already derives from uname.
	OS   string `json:"os"`
	Arch string `json:"arch"`

	// Kind separates the forms one platform publishes: an archive, a .deb, a
	// .rpm. An updater picks by kind, and an unknown one is refused rather than
	// treated as an archive.
	Kind string `json:"kind"`

	// SHA256 is the digest of the bytes as published, lowercase hex.
	SHA256 string `json:"sha256"`

	// Size is the published length in bytes, carried so a reader can bound the
	// download rather than discovering the length by exhausting a disk. A digest
	// alone cannot do that: it is only checkable after the last byte.
	Size int64 `json:"size"`
}

type BuildRequest struct {
	// Dist is the directory GoReleaser wrote its artifacts into.
	Dist string

	Version string
	Commit  string
	BuiltAt time.Time

	Wire          Range
	LedgerSchema  int
	GuestContract string

	// RollbackTo is the release a failed update of this one restores. Empty for
	// the first release billet ever publishes.
	RollbackTo string
}

type ChannelStatement struct {
	Schema  int    `json:"schema"`
	Channel string `json:"channel"`

	// Tag is the release this channel currently names.
	Tag string `json:"tag"`

	// ManifestSHA256 is the digest of that release's manifest.
	//
	// THE THING A ROLLOUT PERSISTS. A tag names a release and a digest names its
	// CONTENTS, and only the second survives somebody moving a tag. GitHub release
	// immutability means that should be impossible, which is a reason to record
	// the digest rather than a reason not to: an assumption billet can check for
	// free is one it should check.
	ManifestSHA256 string `json:"manifest_sha256"`

	PublishedAt time.Time `json:"published_at"`
	ExpiresAt   time.Time `json:"expires_at"`

	// ReleaseImmutable is the publisher asserting it PROVED the release immutable
	// before advancing the channel.
	//
	// CARRIED AND CHECKED rather than assumed from the repository setting. GitHub's
	// release immutability applies only to releases created after it was enabled,
	// so "the repository is protected now" says nothing about a given release. The
	// workflow proves it per release and signs the assertion; a reader that
	// accepted an absent or false value would be trusting a property nobody
	// checked.
	ReleaseImmutable bool `json:"release_immutable"`
}

type Client struct {
	// HTTP is the transport. Nil means a bounded default.
	HTTP *http.Client

	// Repo is the repository releases come from.
	Repo string

	// Now is the clock the channel's expiry is judged against. Nil means
	// time.Now — a parameter because expiry is the behaviour worth testing and a
	// test that waits ten days is a test nobody runs.
	Now func() time.Time
	// contains filtered or unexported fields
}

type Current struct {
	// Version is the release the running binary reports itself as.
	Version string
	// Wire is the node-wire range the running control plane speaks.
	Wire Range
	// LedgerSchema is the highest migration the running binary knows.
	LedgerSchema int
	// GuestContract is the guest protocol the running binary speaks.
	GuestContract string
	// OS and Arch are the platform this deployment runs on.
	OS   string
	Arch string
}

type GuestContractChange struct {
	From string
	To   string
}

type Manifest struct {
	// Schema is the layout version of this document.
	Schema int `json:"schema"`

	// Version is the release, as its git tag spells it.
	Version string `json:"version"`

	// Commit is the commit the release was built from, for an operator
	// reconciling a running binary against what it claims to be.
	Commit string `json:"commit"`

	// BuiltAt is when the release was produced, in UTC.
	BuiltAt time.Time `json:"built_at"`

	// Wire is the node-wire range this release speaks.
	//
	// THE FIELD THAT DECIDES WHETHER A ROLLOUT CAN EVEN BEGIN. A candidate whose
	// range does not overlap the range the running control plane speaks cannot be
	// bridged to — there is no version both halves implement, so nodes could not
	// register against it — and that has to be knowable before the binary is
	// replaced rather than after the fleet has fallen off.
	Wire Range `json:"wire"`

	// SchemaVersion is the ledger migration this release expects.
	//
	// Migrations are append-only and a binary refuses a database carrying a
	// version it has never heard of, so a candidate BELOW the installed schema
	// cannot open the ledger it would inherit. That is a rollback the updater has
	// to refuse rather than discover after it has stopped the control plane.
	LedgerSchema int `json:"ledger_schema"`

	// GuestContract is the protocol a guest image's baked agent must speak.
	//
	// A STRING COMPARED FOR EQUALITY, never ordered, for the reason
	// imagesource.Manifest.GuestContract gives: a newer contract is not backward
	// compatible by default, and treating it as "greater than or equal" turns a
	// clean refusal into a guest that boots and never reports.
	GuestContract string `json:"guest_contract"`

	// Actions is the tag billet's bundled composite actions resolve to in this
	// release. It is the release's own version for an ordinary cut; it is carried
	// explicitly so a reader can check that rather than assume it.
	Actions string `json:"actions"`

	// RollbackTo is the release a failed update of this one restores.
	//
	// PART OF THE MANIFEST RATHER THAN DERIVED, because "the previous tag" is not
	// the same question as "a release this one can be rolled back to". A candidate
	// that migrated the ledger cannot be rolled back to a binary that refuses the
	// new schema, and only the release knows that about itself.
	//
	// EMPTY IS A VALUE. The first release billet ever publishes has nothing behind
	// it, and refusing that would mean no release could ever be the first.
	RollbackTo string `json:"rollback_to,omitempty"`

	// Artifacts is every published file, keyed by nothing — a reader selects by
	// os and arch.
	Artifacts []Artifact `json:"artifacts"`
}

type Policy = imagesource.Policy

type Range struct {
	Min int `json:"min"`
	Max int `json:"max"`
}