Documentation
¶
Overview ¶
Package store is the server's SQLite persistence layer: executions, their stack/edge subgraph, and per-(class,target) approval gate state. Pure-Go SQLite (modernc.org/sqlite, no cgo); schema migrated by goose at Open.
Index ¶
- func AssociateClaimExecution(db *sql.DB, env string, pr int, execID string) error
- func BumpRev(db *sql.DB, id string) error
- func ClaimStacks(db *sql.DB, env string, pr int, execID string, stacks []string, ...) error
- func ClaimedStacks(db *sql.DB, env string, now time.Time) (map[string]int, error)
- func DeleteTarget(tx *sql.Tx, pr int, environment, class, target string) error
- func EnvironmentsForPR(db *sql.DB, pr int) ([]string, error)
- func GetStackOutput(db *sql.DB, execID, stack, kind string) (pointer, excerpt string, ok bool, err error)
- func IsClassified(db *sql.DB, pr int, environment string) (bool, error)
- func IsQuiescent(db *sql.DB) (bool, error)
- func LatestExecutionID(db *sql.DB, pr int, environment string) (string, bool)
- func LatestVerifyExecutionID(db *sql.DB, pr int, environment string) (string, bool)
- func LoadGraph(db *sql.DB, id string) (events.Graph, error)
- func MarkActive(db *sql.DB, pr int, environment string) error
- func MarkClassified(db *sql.DB, pr int, environment string) error
- func Open(dsn string) (*sql.DB, error)
- func ReleaseClaimStack(db *sql.DB, env string, pr int, stack string) error
- func ReleaseClaimsByPREnv(db *sql.DB, env string, pr int) error
- func RenewClaims(db *sql.DB, env string, pr int, expiresAt time.Time) error
- func SetCheckRunID(db *sql.DB, id string, checkRunID int64) error
- func SetExecutionStatus(db *sql.DB, id, status string) error
- func SetReport(db *sql.DB, id, markdown string) error
- func SetTargetRequester(db *sql.DB, pr int, environment, requester string) error
- func SweepExpiredClaims(db *sql.DB, now time.Time) ([]string, error)
- func UpdateStack(db *sql.DB, id, stack string, status events.Status, detail string) error
- func UpsertApplyLockCheck(db *sql.DB, c ApplyLockCheck) error
- func UpsertInit(db *sql.DB, in events.Init) error
- func UpsertPhase(db *sql.DB, p events.PhaseEvent) error
- func UpsertStackOutput(db *sql.DB, execID, stack, kind, pointer, excerpt string) error
- func UpsertTarget(db *sql.DB, pr int, environment, class, target, grant, state string) error
- type ApplyLockCheck
- type Claim
- type Execution
- type Gate
- type GateTarget
- type OpenGrantPR
- type PRTarget
- type RawChangeSet
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AssociateClaimExecution ¶ added in v0.15.0
AssociateClaimExecution links a PR's claims to the apply execution that now owns them (so heartbeats/finalize can target by pr+env).
func BumpRev ¶
BumpRev increments the cache-bust revision (used by the rendered SVG URL so GitHub's image proxy re-fetches on each state change).
func ClaimStacks ¶ added in v0.15.0
func ClaimStacks(db *sql.DB, env string, pr int, execID string, stacks []string, expiresAt time.Time) error
ClaimStacks records that PR `pr` (apply exec `execID`, may be "") holds the per-stack lock claim for `stacks` in `env` until `expiresAt`. Idempotent: re-claiming the same stacks for the same PR refreshes the row.
func ClaimedStacks ¶ added in v0.15.0
ClaimedStacks returns the active (unexpired at `now`) claims for env as stack_path → owner_pr.
func DeleteTarget ¶ added in v0.9.9
DeleteTarget removes a single gate target row.
func EnvironmentsForPR ¶ added in v0.15.0
EnvironmentsForPR returns the distinct environments that have at least one execution for the given PR. Order is unspecified.
func GetStackOutput ¶ added in v0.6.0
func GetStackOutput(db *sql.DB, execID, stack, kind string) (pointer, excerpt string, ok bool, err error)
GetStackOutput returns the stored pointer + excerpt for a stack's output kind. ok is false when none is recorded.
func IsClassified ¶
IsClassified reports whether a plan ever classified (pr, environment).
func IsQuiescent ¶ added in v0.9.9
IsQuiescent reports whether no PR is in flight: no gate_targets row is in a non-terminal state (anything other than DENIED/REVOKED/EXPIRED). Used to gate the reconciler_core cut-over so the engine swaps only between PRs.
func LatestExecutionID ¶ added in v0.6.0
LatestExecutionID returns the most recent execution id for (pr, environment). ok is false when none exists.
func LatestVerifyExecutionID ¶ added in v0.6.0
LatestVerifyExecutionID returns the most recent verify-context execution id for (pr, environment) — i.e. a run whose status_context begins with "verify". ok is false when none exists.
func MarkActive ¶
MarkActive flips every stored target for (pr, environment) to ACTIVE, so the gate drops out of PendingGates and the live approval panel shows approved rather than the stale request-time waiting state.
func MarkClassified ¶
MarkClassified records that (pr, environment) was classified by a plan, even when the plan was clean (zero gate_targets). Idempotent.
func Open ¶
Open opens the SQLite database at dsn, enables WAL, and applies all migrations. dsn is a modernc.org/sqlite DSN, e.g. a file path or "file:/data/server.db".
func ReleaseClaimStack ¶ added in v0.15.0
ReleaseClaimStack deletes the claim for a single stack owned by pr in env.
func ReleaseClaimsByPREnv ¶ added in v0.15.0
ReleaseClaimsByPREnv drops all claims a PR holds in an env.
func RenewClaims ¶ added in v0.15.0
RenewClaims extends the lease for a PR's claims in an env (heartbeat).
func SetCheckRunID ¶
SetCheckRunID records the GitHub check-run id created for an execution.
func SetExecutionStatus ¶ added in v0.13.2
SetExecutionStatus persists the execution-level commit status (e.g. terminal "success"/"failure"). This is the signal isFinished reads for an apply; the apply driver writes it once the apply concludes.
func SetTargetRequester ¶ added in v0.7.0
SetTargetRequester records the leased requester SA for every gate target of a (pr, environment). Idempotent; no-op if no rows match.
func SweepExpiredClaims ¶ added in v0.15.0
SweepExpiredClaims deletes all claims expired at `now` and returns the distinct environments that lost a claim (so the caller can re-evaluate their held checks).
func UpdateStack ¶
UpdateStack ticks one stack's status (and optional failure detail).
func UpsertApplyLockCheck ¶ added in v0.15.0
func UpsertApplyLockCheck(db *sql.DB, c ApplyLockCheck) error
func UpsertInit ¶
UpsertInit records an execution and its changed subgraph from an Init event. Re-init with the same id is upsert-safe. The phase column is intentionally left untouched: the lifecycle phase is owned by UpsertPhase, which may run before Init. Stack status is set only on first insert; a repeat Init (e.g. run register followed by run plan) never regresses an already-advanced stack.
func UpsertPhase ¶
func UpsertPhase(db *sql.DB, p events.PhaseEvent) error
UpsertPhase sets the execution's lifecycle phase, creating a bare row if Init has not run yet. Identity fields are only overwritten when the event carries a non-zero value, so a bare phase bump never clobbers data set by an earlier Init (and an early phase event survives a later Init).
func UpsertStackOutput ¶ added in v0.6.0
UpsertStackOutput records (or updates) the pointer + tail excerpt for one stack's output of a given kind ("log", later "plan"/"verify").
func UpsertTarget ¶
UpsertTarget records or updates the grant for a (pr, environment, class, target). On conflict the grant_name, state, and updated_at are overwritten. NOTE: `requester` is deliberately excluded from the ON CONFLICT update set. SetTargetRequester writes the leased requester SA after the initial upsert; subsequent reconcile-loop UpsertTarget calls (state refreshes) must not clobber it — keeping it out of the update set is the invariant that lets handleGateCheck trust targets[0].Requester for the entire (pr, environment).
Types ¶
type ApplyLockCheck ¶ added in v0.15.0
type ApplyLockCheck struct {
Environment string
HeadSHA string
CheckRunID int64
PR int
Repo string
Stacks []string
State string // clear | held | unverifiable
Kind string // merge_group | pr_head
}
ApplyLockCheck is a persisted apply-lock check run (so serve can PATCH it later when an overlapping apply releases). Keyed by (environment, head_sha).
func GetApplyLockCheck ¶ added in v0.15.0
func HeldApplyLockChecks ¶ added in v0.15.0
func HeldApplyLockChecks(db *sql.DB, env string) ([]ApplyLockCheck, error)
type Execution ¶
type Execution struct {
ID string
Repo string
SHA string
PR int
Environment string
CheckRunID sql.NullInt64
Rev int
ReportMarkdown string
LogURL string
Status string // execution-level commit status (e.g. "in_progress"/"success"/"failure"); written by the serve handler, distinct from per-stack events.Status
StatusContext string
Phase string
CreatedAt time.Time
}
Execution is a row of the executions table.
func GetExecution ¶
GetExecution loads one execution row.
func ListExecutions ¶ added in v0.6.0
ListExecutions returns the most recent executions, newest first.
type Gate ¶
Gate identifies the unit an approval verdict is posted for.
func PendingGates ¶
PendingGates returns the (pr, environment) gates that still have at least one target not yet ACTIVE — i.e. gates whose verdict may still need posting. The reconcile loop walks these to self-heal the gap where an approval event is processed while the grant is still activating (some providers fire no further event for the activating→active transition) and dropped events / restarts.
type GateTarget ¶
type GateTarget struct {
Class string
Target string
GrantName string
State string
Requester string
}
GateTarget holds the per-(class,target) grant state recorded for a (pr, environment).
func TargetsFor ¶
TargetsFor returns every GateTarget recorded for (pr, environment). Returns a non-nil empty slice when none match.
type OpenGrantPR ¶ added in v0.10.0
OpenGrantPR is a PR that still holds at least one open (non-terminal) grant, paired with the repo of its latest execution (for the orphan sweep's GitHub closed-state check). Repo is "" when no execution row exists.
func OpenGrantPRs ¶ added in v0.10.0
func OpenGrantPRs(db *sql.DB) ([]OpenGrantPR, error)
OpenGrantPRs returns every PR with at least one gate target in an open state (AWAITING/ACTIVATING/ACTIVE), each paired with its latest execution's repo. Unlike PendingGates it INCLUDES fully-ACTIVE (Satisfied) gates — the merged-PR orphan whose grants were never revoked — which is exactly what the sweep must re-examine. Terminal states (DENIED/REVOKED/EXPIRED) are deliberately excluded: those grants are no longer live, so the sweep has nothing to revoke for them (an EXPIRED grant the reconciler may later re-arm becomes AWAITING again — open — and is caught on the next sweep). A PR is one row regardless of how many environments hold open grants (GROUP BY pr); revokeOrphans handles every env.
type PRTarget ¶ added in v0.9.5
PRTarget is a (environment, class, target) tuple recorded for a PR, used by the PR-closed webhook to revoke orphaned grants across all environments.
type RawChangeSet ¶ added in v0.9.9
type RawChangeSet struct {
PR int
Environment string
Classified bool
Targets []GateTarget
}
RawChangeSet is the persisted state for (pr, environment): the classified marker and gate targets. It is the store-level shape the server maps into reconcile.ChangeSet.
func LoadChangeSet ¶ added in v0.9.9
LoadChangeSet reads the classified marker and gate targets for (pr, env).
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package migrations embeds the goose SQL migrations for the server store.
|
Package migrations embeds the goose SQL migrations for the server store. |