rollout

type AdvanceRequest struct {
	RolloutID string
	// Node is the host, or empty for the controller itself.
	Node string
	To   Phase
	// Blocker explains a phase that needs explaining. Required for blocked,
	// because a cordoned host with no reason recorded is one nobody can clear.
	Blocker string
	// RollbackResult records what a rollback proved, or could not.
	RollbackResult string
	// ExemptReason is the operator's decision, required for exempt and
	// decommissioned.
	ExemptReason string
	// PriorRelease is what the component was running before this rollout touched
	// it, recorded once so a rollback has somewhere to go.
	PriorRelease string
	// Backoff, when positive, is how long before this component may be tried
	// again. It also increments the attempt count.
	Backoff time.Duration
	// DispatchEpoch, when positive, records the host's registration epoch at the
	// moment it was told to upgrade. See Node.DispatchEpoch.
	DispatchEpoch int64
	// ConvergedDigest, when non-empty, records the release manifest that proved a
	// host converged. See Node.ConvergedDigest.
	ConvergedDigest string
}

type Coordinator struct {
	// contains filtered or unexported fields
}

type CoordinatorOption func(*Coordinator)

type Dispatcher interface {
	Upgrade(ctx context.Context, node, version, manifestSHA256, rolloutID string,
		generation int64) error
}

type Fleet interface {
	Hosts(ctx context.Context) ([]Host, error)
}

type Host struct {
	Name string
	// Release is what the host said it was running at its last registration.
	//
	// EMPTY IS NOT "OLD". A build below VersionNodeRelease has no release to give,
	// which is the entire installed fleet on the day this ships. A host that says
	// nothing is one the coordinator cannot prove converged, so it stays pending
	// and blocks completion rather than being guessed about in either direction.
	Release string
	// Digest is the signed release manifest that produced this host's binary, or
	// empty when nothing on that machine could say.
	//
	// THE ONLY THING THAT DISTINGUISHES BYTES FROM A NAME. Release is the version
	// the host's binary was BUILT as, which two builds can share and which a moved
	// tag makes identical — so a rollout comparing versions alone converges on
	// evidence weaker than the decision it is converging. Empty is the ordinary
	// case and is read as "cannot tell"; a value that DISAGREES is a fact that
	// could not previously exist.
	Digest string
	// Wire is the protocol version its registration settled on.
	Wire int
	// Live is whether this deployment is currently in contact with it.
	Live bool
	// Epoch is the fencing token this host's CURRENT registration holds.
	//
	// THE ONLY THING THAT PROVABLY POSTDATES AN INSTRUCTION. Release and Live are
	// both true of a host that never left and of one that went away and came back
	// on the same binary, so without this the coordinator cannot tell a host still
	// draining from one that rolled itself back — and would leave the second in
	// the cohort forever.
	Epoch int64
}

type Node struct {
	Node           string
	Phase          Phase
	Attempts       int
	NextAttemptAt  string
	Blocker        string
	PriorRelease   string
	RollbackResult string
	ExemptReason   string
	UpdatedAt      string
	// ConvergedDigest is the release manifest that proved this host converged, or
	// empty for one that converged on its version alone.
	//
	// EMPTY IS A CONVERGED HOST NOTHING PROVED, not a host that failed. Read
	// beside the phase: `committed` with no digest is a host that reached the
	// target version and could not say which bytes it installed, which is every
	// host in the field before one billet-driven upgrade has run.
	ConvergedDigest string
	// DispatchEpoch is the host's registration epoch when it was told to upgrade.
	//
	// A CAUSAL FENCE, and the only one available. After the instruction, a host
	// that has not started yet and one that upgraded, failed and rolled itself
	// back are identical in every other field — both live, both reporting the
	// previous release. A registration bumps the epoch and nothing else does, so
	// a HIGHER one provably postdates the instruction. Zero means nothing was
	// recorded, and nothing is concluded from it.
	DispatchEpoch int64
}

type Option func(*Store)

type Phase string

type Policy struct {
	// Cohort is how many nodes may be past `pending` at once. One is the default
	// and the safe answer: a fleet updated one host at a time never loses more
	// capacity than one host's worth.
	Cohort int `json:"cohort"`

	// FailureBudget is how many nodes may end blocked or rolled back before the
	// rollout stops starting new ones.
	//
	// EXPLICIT, because "keep going" and "stop on the first failure" are both
	// wrong as a default. A fleet of fifty should not stop for one bad host; a
	// fleet of two should not lose both.
	FailureBudget int `json:"failure_budget"`

	// AllowDowngrade records that an operator asked for a target older than the
	// release the fleet is running, by name.
	//
	// IN THE POLICY BECAUSE IT TRAVELS WITH THE DECISION. The controller host's
	// updater reads it out of the ledger to lower the release watermark before
	// the older candidate is probed; without it a downgrade is refused at that
	// probe and rolls back, which is the safe answer for a decision nobody made.
	// The automatic starter never sets it.
	AllowDowngrade bool `json:"allow_downgrade,omitempty"`
}

type Resolver interface {
	Resolve(ctx context.Context) (Target, error)
}

type Rollout struct {
	ID string
	// Generation fences instructions. A node that has acted on a newer one
	// refuses an older delivery rather than installing a release the rollout has
	// moved past.
	Generation int64
	// Channel is the channel this resolved from, or empty for an exact pin. Kept
	// so a report can say how the target was chosen; nothing re-resolves it.
	Channel string
	// TargetVersion is what an operator reads. TargetDigest is the identity.
	TargetVersion string
	TargetDigest  string
	// PriorVersion is what the controller was running when this began, so a
	// rollback has somewhere to go without re-deriving it.
	PriorVersion    string
	Policy          Policy
	ControllerPhase Phase
	State           string
	CreatedBy       string
	CreatedAt       string
	FinishedAt      string
	TerminalReason  string
}

type StartPolicy struct {
	// Enabled is release.automatic, read through its accessor.
	Enabled bool

	// OpenAt says whether a rollout may begin at a moment, or is nil for a
	// deployment with no maintenance window.
	OpenAt func(time.Time) bool

	// Channel is the channel followed, or empty for a deployment pinned to Pin.
	Channel string
	Pin     string

	// Rollout is the policy every automatic rollout is recorded with. Its
	// AllowDowngrade is ignored: an automatic start never downgrades.
	Rollout Policy
}

type StartRequest struct {
	Channel       string
	TargetVersion string
	TargetDigest  string
	PriorVersion  string
	Policy        Policy
	CreatedBy     string
	// Nodes is every host this rollout must converge, as the fleet stands now.
	//
	// SNAPSHOT AT START, and that is deliberate. A host that registers later is
	// running whatever it was installed with and is not part of a decision taken
	// before it existed; a host that has disappeared still holds the rollout open,
	// because its compute may be running. Both are wrong if the set is recomputed
	// on every pass.
	Nodes []string
	// RefuseAbortedTarget refuses to start when the newest rollout to this digest
	// was aborted, INSIDE THE SAME TRANSACTION THAT WOULD INSERT, so a start and
	// an abort that land between an automatic starter's read and its write cannot
	// be overruled by it. An operator's start leaves it false: `billet rollout
	// start` after an abort is the decision to try again.
	RefuseAbortedTarget bool
}

type Starter struct {
	// contains filtered or unexported fields
}

type StarterOption func(*Starter)

type Store struct {
	// contains filtered or unexported fields
}

type Target struct {
	Version string
	Digest  string
	Notes   []string
}