deploystate

type Action ¶

type Action int

Action is what a reconcile pass concluded it should DO. Separate from State, which is what it concluded is TRUE, because the same truth yields different actions under different policy — and conflating them is how a reporting tool grows a write path nobody reviewed.

const (
	// ActionNone means nothing to do: the target is converged, or it is
	// unknown and there is nothing to act on.
	ActionNone Action = iota
	// ActionReport means drift exists and forge will say so and stop.
	ActionReport
	// ActionConverge means drift exists and policy permits correcting it.
	ActionConverge
	// ActionWait means the target is matching but has not yet held its
	// shape past the stability window. Distinct from None: a caller
	// arming a rollback timer needs to know the clock is still running.
	ActionWait
)

func (a Action) String() string

type Decision ¶

type Decision struct {
	Key    Key
	State  State
	Policy Policy
	Action Action

	// Drifted lists the OWNED fields that do not match. Empty under
	// every action but report and converge.
	Drifted []Field

	// Reason is one line explaining the action, for the log line a human
	// reads when they ask why forge did or did not do something.
	Reason string
}

Decision is one pass's conclusion about one target.

func Decide(rec Record, policy Policy, now time.Time, window time.Duration) Decision

func DecideEnv(ctx context.Context, store Store, env string, now time.Time, window time.Duration) ([]Decision, error)

type Desired ¶

type Desired struct {
	// Digest is the canonical image digest declared, when the
	// declaration pins one. Empty when the target is pinned by mutable
	// tag instead, which is a legitimate and common case and must not be
	// reported as drift — see [Record.Evaluate].
	Digest string `json:"digest,omitempty"`

	// Image and Tag are the human-facing reference, carried for
	// reporting (a non-cluster provider has no cluster to ask, so the
	// deployed tag has to be remembered somewhere).
	Image string `json:"image,omitempty"`
	Tag   string `json:"tag,omitempty"`

	// Replicas is the declared scale, or nil when the tier has no
	// replica concept. Nil and a pointer to 0 mean different things:
	// "not applicable" versus "deliberately scaled to nothing".
	Replicas *int `json:"replicas,omitempty"`

	// DeclaredAt is when this declaration was recorded.
	DeclaredAt time.Time `json:"declared_at,omitzero"`
}

Desired is what the declaration asks for. Only the fields a Field can name — this is the comparison half of a Record, not a copy of the whole spec.

type Field ¶

type Field string

Field names a comparable property of a target. NOT every difference is drift, and this type is how forge says which differences are its business.

The failure this prevents is specific and common: an autoscaler moves a replica count, forge reports drift, the engineer confirms it is correct behaviour, and after the third such report nobody reads the drift badge again. A signal people have learned to ignore is worse than no signal, because it occupies the place where a real one would have gone.

So ownership is per-target and explicit. A target under an HPA lists FieldDigest and not FieldReplicas; a target forge fully owns lists both. Anything not listed is the world's, and a difference there is recorded and never reported as drift.

const (
	// FieldDigest is the content-addressed identity of what is running.
	FieldDigest Field = "digest"
	// FieldReplicas is the scale. Frequently NOT forge's to own — an
	// autoscaler owning this field is the motivating example for this
	// whole type.
	FieldReplicas Field = "replicas"
)

type Key ¶

type Key struct {
	// Env is the environment name (dev, staging, prod).
	Env string `json:"env"`
	// Provider is the deploy provider id (k8s, compose, external, ...).
	Provider string `json:"provider"`
	// Service is the service or frontend name.
	Service string `json:"service"`
}

Key identifies one target within one project. Three segments, matching the on-disk layout that already exists (.forge/state/<provider>-<env>-<service>.json), so adopting this package does not orphan any state a user already has.

func (k Key) String() string

func (k Key) Valid() bool

type Local ¶

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

Local implements Store over a directory. This is the default backend, and it is also the acceptance test for the interface: an OSS user with no server at all gets drift detection, five states, and policy out of it.

On-disk layout ¶

.forge/state/reconcile-<env>-<provider>-<service>.json   one Record
.forge/state/policy-<env>.json                           one Policy

A NEW filename prefix rather than reusing the existing `<provider>-<env>-<service>.json`, and that is deliberate. Those files are written and read by forge's non-cluster providers to remember the tag they last shipped (the next deploy's ${LAST_TAG}). Widening that file's schema in place would mean an older forge reading a newer file, and a provider that misparses it loses the only record of what it deployed.

So the two coexist, and Local READS the legacy file when it has no record of its own (see Local.Get). A project that has been deploying for months does not report "never deployed" on the day it turns reconciliation on.

func NewLocal(projectDir string) *Local

func (l *Local) Get(ctx context.Context, key Key) (Record, error)

func (l *Local) List(ctx context.Context, env string) ([]Record, error)

func (l *Local) Policy(ctx context.Context, env string) (Policy, error)

func (l *Local) PolicyPath(env string) string

func (l *Local) Put(ctx context.Context, rec Record) error

func (l *Local) SetPolicy(ctx context.Context, env string, p Policy) error

type Observation ¶

type Observation struct {
	// Digest is what is RUNNING. Empty means the observer could not
	// determine it.
	Digest string `json:"digest,omitempty"`

	// Replicas is the observed scale, nil when not applicable.
	Replicas *int `json:"replicas,omitempty"`

	// Ready is how many of those replicas are passing readiness. Nil
	// when not applicable. This is the field that separates "applied" —
	// which a deploy's own return value already told you — from
	// "working", which only a read can.
	Ready *int `json:"ready,omitempty"`

	// Serving is the observer's verdict on whether the target is doing
	// its job. FALSE IS THE ZERO VALUE, so an Observation that nobody
	// filled in cannot read as serving. Meaningful only when Measured is
	// true.
	Serving bool `json:"serving"`

	// Measured distinguishes "looked, and here is what I found" from "did
	// not look". Without it, a zero Observation is indistinguishable
	// from a target that is genuinely absent and unhealthy, and those
	// call for opposite actions: investigate versus go and look.
	Measured bool `json:"measured"`

	// Detail is one line of human-readable context. REQUIRED whenever
	// the observation is anything other than a clean serving read — an
	// unknown with no reason is indistinguishable from an observer that
	// silently failed.
	Detail string `json:"detail,omitempty"`

	// ObservedAt is when the read happened, wall-clock UTC. A caller
	// comparing declared against observed needs to know how stale the
	// answer is; without it a cached observation reads as a fresh one.
	ObservedAt time.Time `json:"observed_at,omitzero"`
}

Observation is what was actually found running. Mirrors deploytarget.Observed's facts without importing it: forge's internal package may not be imported from pkg/, and an operator implementing a Store should not have to depend on forge's provider tree to do it.

type Policy ¶

type Policy int

Policy is what forge is permitted to do about a difference between what an environment declares and what is actually running.

Three values, and the default is deliberately the timid one ¶

Policy is an int enum precisely so its ZERO VALUE is PolicyObserve. A Policy that arrives by any path — decoded from a file that predates this field, built as a struct literal in a test, returned by a backend that has not been taught about policy yet — reads as "report, change nothing" until something deliberately says otherwise. The failure mode of a forgotten field must be inaction.

That is not timidity for its own sake. Silent correction during an incident, while an engineer is deliberately holding a thing together by hand, is the single behaviour that makes people rip these systems out — and they are right to, because at that moment the reconciler is not enforcing an invariant, it is fighting the only person who understands the situation. Converge is opt-in, per environment, forever.

const (
	// PolicyObserve reports drift and changes nothing. The zero value,
	// and the default for an environment that has never said otherwise.
	PolicyObserve Policy = iota

	// PolicyConverge permits forge to correct drift it detects. Opt-in.
	PolicyConverge

	// PolicyPinned refuses ALL changes, including ones a human asked
	// for through a normal deploy.
	//
	// Distinct from observe, and the distinction is the whole reason
	// there are three values rather than a bool. Observe says "I will
	// not act on my own initiative"; pinned says "nothing may change
	// this environment right now", which is what you set during a
	// freeze, an incident, or a migration you are driving by hand.
	// Collapsing them would mean the only way to stop a deploy is to
	// also stop drift REPORTING — losing the signal at the exact moment
	// it is most wanted.
	PolicyPinned
)

func ParsePolicy(s string) (Policy, error)

func (p Policy) AllowsChange() bool

func (p Policy) AllowsConverge() bool

func (p Policy) MarshalJSON() ([]byte, error)

func (p Policy) String() string

func (p *Policy) UnmarshalJSON(data []byte) error

type Record ¶

type Record struct {
	Key Key `json:"key"`

	Desired  Desired     `json:"desired"`
	Observed Observation `json:"observed"`

	// Owned lists the fields forge is responsible for. EMPTY MEANS
	// NOTHING IS OWNED, which is deliberate: a Record that predates this
	// field, or that a backend forgot to populate, reports no drift
	// rather than reporting every difference as drift. The direction of
	// the default matters — over-reporting is what destroys trust in the
	// signal, and under-reporting is visible as a badge that never moves.
	Owned []Field `json:"owned,omitempty"`

	// StableSince is when the target most recently ENTERED its current
	// matching, serving shape. Nil whenever it is not in one.
	//
	// This field is why "converged" means something. A clean apply is
	// not a successful promotion: the apply succeeds, the pod starts,
	// the pod crashes, and a reconciler that reported success at apply
	// time has already told everyone the promotion worked. Requiring the
	// shape to HOLD for a window is what makes the report honest, and it
	// is the same clock an automatic rollback would arm itself against.
	StableSince *time.Time `json:"stable_since,omitempty"`
}

Record is one target's two halves side by side, plus the bookkeeping that turns a comparison into a trustworthy verdict.

func (r Record) DriftedFields() []Field

func (r Record) Evaluate(now time.Time, window time.Duration) State

func (r Record) Owns(f Field) bool

func (r Record) WithStability(prev *Record, now time.Time) Record

type Remote ¶

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

Remote implements Store against an HTTP+JSON endpoint. Reliant is the first implementor of the server side; the protocol is written down here so it is not.

Why this exists in forge rather than only in Reliant ¶

An interface with one implementation is not a seam, it is a type declaration with extra steps. Shipping the second implementation is what proves the boundary holds — and it did its job: writing this is what established that the interface needed no transaction, no lease and no cursor, because nothing here wanted one.

Why HTTP+JSON and not a generated client ¶

The same reason forge chose REST over a vendored SDK twice already. A generated client drags a protocol runtime into forge/pkg, which every forge APP inherits — and the shapes on the wire here are five verbs over two flat structs. `net/http` covers it with no new module.

The protocol ¶

GET    {base}/v1/state/{env}/{provider}/{service}   -> 200 Record | 404
PUT    {base}/v1/state/{env}/{provider}/{service}   <- Record, 204
GET    {base}/v1/state/{env}                        -> 200 {"records":[...]}
GET    {base}/v1/policy/{env}                       -> 200 {"policy":"..."} | 404
PUT    {base}/v1/policy/{env}                       <- {"policy":"..."}, 204

Every path segment is URL-escaped, so a service name with a slash cannot reach a sibling route.

func NewRemote(baseURL string, opts ...RemoteOption) *Remote

func (r *Remote) Get(ctx context.Context, key Key) (Record, error)

func (r *Remote) List(ctx context.Context, env string) ([]Record, error)

func (r *Remote) Policy(ctx context.Context, env string) (Policy, error)

func (r *Remote) Put(ctx context.Context, rec Record) error

func (r *Remote) SetPolicy(ctx context.Context, env string, p Policy) error

type RemoteOption ¶

type RemoteOption func(*Remote)

RemoteOption configures a Remote.

func WithBearerToken(token string) RemoteOption

func WithHTTPClient(c *http.Client) RemoteOption

type State ¶

type State int

State is the verdict for one target: five values, not two.

A boolean "in sync" collapses three genuinely different situations — still settling, actively wrong, and not measured — into one "no", and every consumer then re-derives the distinction from fields the boolean was supposed to save it from reading.

StateUnknown is the ZERO VALUE, and that is load-bearing. An opaque `External` target runs a command forge cannot read back; there is genuinely nothing to observe, and the honest answer is "I do not know". Making it the zero value means a Record built by any path — a backend that failed halfway, a test literal, a file written by an older forge — reads as unknown rather than as green. A dashboard that shows green for something nobody measured is worse than one that shows nothing, because it is confidently wrong and people stop reading it.

const (
	// StateUnknown means nothing measured this target. The zero value.
	StateUnknown State = iota

	// StateConverging means the target matches what was declared but has
	// not yet been stable long enough to trust. See [Record.StableSince].
	StateConverging

	// StateConverged means the target matches AND has held that shape
	// past the stability window.
	StateConverged

	// StateDiverged means an owned field does not match the declaration.
	// This is drift.
	StateDiverged

	// StateDegraded means the target is not serving — regardless of
	// whether it matches. A perfect apply onto a crash-looping pod is
	// degraded, not converged.
	StateDegraded
)

func (s State) MarshalJSON() ([]byte, error)

func (s State) String() string

func (s *State) UnmarshalJSON(data []byte) error

type Store ¶

type Store interface {
	// Get returns the record for one target, or ErrNotFound.
	Get(ctx context.Context, key Key) (Record, error)

	// Put writes a record. Last-writer-wins; see the type comment.
	Put(ctx context.Context, rec Record) error

	// List returns every record for one environment, in a stable order
	// (provider then service) so that CLI output and diffs do not
	// reshuffle between runs for no reason.
	//
	// Scoped to ONE environment on purpose. An unscoped "list
	// everything" would be the first method a fleet backend implements
	// with a paginated cursor and an owner filter, and at that point the
	// local implementation is a toy stapled to a real one.
	List(ctx context.Context, env string) ([]Record, error)

	// Policy returns the reconcile policy for one environment. A missing
	// policy is NOT an error: it returns PolicyObserve, because the
	// absence of an opinion must mean "change nothing", never "converge".
	Policy(ctx context.Context, env string) (Policy, error)

	// SetPolicy records the reconcile policy for one environment.
	SetPolicy(ctx context.Context, env string, p Policy) error
}

Store is the pluggable backend. Five methods, and the count is a constraint rather than a coincidence.

Every method must be honestly implementable by a directory of files ¶

That is the acceptance test this interface was designed against, and Local is the proof. It is not about supporting an offline mode as a courtesy; it is the thing that keeps forge's half of reconciliation from quietly becoming a client for a mandatory server.

The pressure is real and it is specific. Each of these would be natural to add, and each is refused:

• ListDue(shard, count) — "which environments need a pass". A directory cannot shard, and more importantly SHOULD NOT: forge's loop reconciles ONE project, so it knows its environments from the config it already loaded. Sharding exists only for a fleet, and a fleet driver already has it (control-plane's reconcilestore does exactly this, over Postgres, with a lease and a fence).
• Transaction / WithTx — multi-key atomicity. Files cannot, and the only caller who would need it is one coordinating writers it does not control.
• AcquireLease / Fence — mutual exclusion between writers. A single project's loop has one writer. A fleet has many, and fences them one layer up where the lease actually lives.

The one honest gap: Put is last-writer-wins ¶

There is no compare-and-swap, and files are the reason. A CAS token on this interface would be unimplementable over a directory without lockfiles whose staleness semantics are a worse problem than the one they solve — a crashed writer's lock is indistinguishable from a live one's, and a local tool that hangs waiting for a lock nobody holds is a bug report.

This is stated rather than papered over because the alternative is a method the local backend satisfies by ignoring its own argument, which is how an interface starts lying. Concurrent writes to one project's state are outside forge's model (one loop, one project); a backend that genuinely has concurrent writers fences them where it holds the lease, which is the layer that can.

Policy is a read, every pass ¶

Store.Policy is separate from Store.Get and is meant to be called on each pass rather than cached. Opting out of convergence must be INSTANT and must not require a deploy: an engineer who sets an environment to pinned mid-incident needs the next pass to honour it, not the next release. A policy baked into an artifact, or read once at start-up, fails exactly when it is needed.