state

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package state persists Baselines, Candidates, and coordination state in SQLite. Go schema versions migrate in place; Python databases are unsupported.

Index

Constants

This section is empty.

Variables

View Source 
var ErrLeaseLost = errors.New("the run lease is no longer owned")

ErrLeaseLost indicates missing, expired, or superseded ownership.

Functions

func IsBusy added in v1.3.0 

func IsBusy(err error) bool

IsBusy reports contention with another SQLite connection, including extended busy codes.

Types

type AcceptedDigest 

type AcceptedDigest struct {
	Key    Key
	Digest string
}

AcceptedDigest pairs a Key with its accepted Baseline digest.

type Attempt 

type Attempt struct {
	// ID is the audit trail's own order. It is the cursor `ripen audit`
	// pages by, and it never appears in the JSON surface.
	ID          int64
	Key         Key
	RunID       string
	Actor       domain.Actor
	OldDigest   string
	NewDigest   string
	Result      domain.ResultCode
	Detail      string
	AttemptedAt time.Time
}

Attempt is one recorded Transaction attempt.

type AuditFilter 

type AuditFilter struct {
	Limit   int
	Cursor  int64
	RunID   string
	Backend domain.Backend
	Stack   string
	Service string
	Result  domain.ResultCode
}

AuditFilter narrows and pages the audit trail. Every field is optional; an empty filter reads the newest attempts.

type CandidateObservation 

type CandidateObservation struct {
	Digest    string
	FirstSeen time.Time
	LastSeen  time.Time
	Count     int
}

CandidateObservation is one observed Candidate digest and its history.

type CandidateRecord 

type CandidateRecord struct {
	Key       Key
	Digest    string
	FirstSeen time.Time
	LastSeen  time.Time
	Count     int
}

CandidateRecord is one observed Candidate, with its Key.

type Evaluation added in v1.2.0 

type Evaluation struct {
	Key         Key
	RunID       string
	Result      domain.ResultCode
	Detail      string
	EvaluatedAt time.Time
}

Evaluation records an outcome independently of Candidate history.

type Key 

type Key struct {
	Backend domain.Backend
	Stack   string
	Service string
}

Key identifies one Service's state: backend, stack, and service, with service empty for a stack-level policy. The Python schema's state_key column pretended this was one string; schema v1 stores the three parts.

type NotifierHealth 

type NotifierHealth struct {
	LastSuccessAt       *time.Time
	ConsecutiveFailures int
}

NotifierHealth is the persisted Notifier delivery health.

type PendingProposal 

type PendingProposal struct {
	Digest     string
	URL        string
	ProposedAt time.Time
}

PendingProposal is an open Proposal (PR) awaiting review.

type ProposalRecord 

type ProposalRecord struct {
	Key    Key
	Digest string
	URL    string
}

ProposalRecord pairs a Key with its pending Proposal for Status.

type SchedulerProgress added in v1.2.0 

type SchedulerProgress struct {
	LastCompletedAt *time.Time
	NextTickAt      *time.Time
}

SchedulerProgress records scheduled and completed observation times.

type StackCheck added in v1.2.0 

type StackCheck struct {
	OwnerToken  string
	Key         Key
	RunID       string
	StartedAt   time.Time
	CompletedAt *time.Time
	Outcome     string
}

StackCheck records the most recent observation attempt for a stack.

type Status 

type Status struct {
	BreakerOpen      bool
	BreakerReason    string
	AcceptedDigests  []AcceptedDigest
	LeaseActive      bool
	PendingProposals []ProposalRecord
}

Status is the durable state snapshot behind `ripen status`.

type Store 

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

Store is the SQLite-backed state store.

func Open 

func Open(path string) (*Store, error)

Open opens (creating if needed) the state database at path, creating the parent directory when missing.

func (*Store) AcceptPendingProposal added in v1.2.0 

func (s *Store) AcceptPendingProposal(token string, key Key, expected PendingProposal, now time.Time) (bool, error)

AcceptPendingProposal accepts only the exact Proposal that was evaluated.

func (*Store) AcceptedDigest 

func (s *Store) AcceptedDigest(key Key) (string, bool, error)

AcceptedDigest returns the accepted Baseline digest for a Key.

func (*Store) AcquireLease 

func (s *Store) AcquireLease(now time.Time, ttlSeconds int) (string, bool, error)

AcquireLease takes the run lease when no unexpired lease exists, returning an owner token. BEGIN IMMEDIATE serializes contenders.

func (*Store) ActiveTransaction added in v1.2.0 

func (s *Store) ActiveTransaction() (*TransactionProgress, error)

ActiveTransaction returns the unfinished Transaction, even after lease expiry.

func (*Store) Attempts 

func (s *Store) Attempts(limit int) ([]Attempt, error)

Attempts returns the newest attempts, most recent first.

func (*Store) AuditPage 

func (s *Store) AuditPage(filter AuditFilter) ([]Attempt, error)

AuditPage reads the audit trail newest first, narrowed by the filter and paged by attempt id. The audit trail is the attempts table — never the Event stream, which is a notification channel and not a record.

func (*Store) BeginTransaction added in v1.2.0 

func (s *Store) BeginTransaction(token string, key Key, runID string, now time.Time) error

BeginTransaction reserves deployment ownership while the breaker is closed.

func (*Store) Candidate 

func (s *Store) Candidate(key Key) (*CandidateRecord, error)

Candidate returns one Key's observed Candidate, or nil.

func (*Store) Candidates 

func (s *Store) Candidates() ([]CandidateRecord, error)

Candidates returns every observed Candidate, oldest Key first.

func (*Store) CheckLease added in v1.2.0 

func (s *Store) CheckLease(token string, now time.Time) error

CheckLease verifies that the token still owns an unexpired lease.

func (*Store) ClearBreaker 

func (s *Store) ClearBreaker(reason string, now time.Time) error

ClearBreaker closes the Circuit breaker; the operator's reason is mandatory and recorded.

func (*Store) ClearPendingProposal 

func (s *Store) ClearPendingProposal(key Key) (bool, error)

ClearPendingProposal removes a Key's Proposal record, reporting whether one existed.

func (*Store) ClearSuppression 

func (s *Store) ClearSuppression(event, stack, service string) error

ClearSuppression drops one suppression key, re-arming it. Recovery uses this: a stack that failed, recovered, and fails again must page the second time.

func (*Store) Close 

func (s *Store) Close() error

Close releases the underlying database handle.

func (*Store) CompleteTransaction added in v1.2.0 

func (s *Store) CompleteTransaction(token string, attempt Attempt, acceptedDigest, breakerReason string, clearMarker bool, now time.Time) error

CompleteTransaction atomically records the owner's outcome and any terminal state changes.

func (*Store) Evaluations added in v1.2.0 

func (s *Store) Evaluations() ([]Evaluation, error)

Evaluations returns latest service evaluations.

func (*Store) FinishStackCheck added in v1.2.0 

func (s *Store) FinishStackCheck(token string, key Key, runID, outcome string, now time.Time) error

FinishStackCheck persists an observation's terminal outcome.

func (*Store) FinishTransaction added in v1.2.0 

func (s *Store) FinishTransaction(token string) error

FinishTransaction removes only the matching owner's completed Transaction.

func (*Store) LastAttempt 

func (s *Store) LastAttempt(key Key) (*Attempt, error)

LastAttempt returns the newest audit entry for one Key, or nil. The Key is matched exactly, empty service included, which is why this does not go through the audit filter.

func (*Store) NotifierDestination 

func (s *Store) NotifierDestination() (string, error)

NotifierDestination reads the fingerprint of the destination the suppression table was built against.

func (*Store) NotifierHealth 

func (s *Store) NotifierHealth() (NotifierHealth, error)

NotifierHealth reads the persisted Notifier delivery health.

func (*Store) ObserveCandidate 

func (s *Store) ObserveCandidate(key Key, digest string, now time.Time) (CandidateObservation, error)

ObserveCandidate records one observation of a Candidate digest. A new digest replaces any previous Candidate for the Key; re-observing the same digest increments its count, preserving first_seen.

func (*Store) OpenBreaker 

func (s *Store) OpenBreaker(reason string, now time.Time) error

OpenBreaker opens the Circuit breaker with a reason.

func (*Store) PendingProposal 

func (s *Store) PendingProposal(key Key) (*PendingProposal, error)

PendingProposal returns the Key's open Proposal, or nil.

func (*Store) ReconcileTransaction added in v1.2.0 

func (s *Store) ReconcileTransaction(token string, attempt Attempt, reason string, now time.Time) error

ReconcileTransaction records an explicitly verified interrupted Transaction and clears its breaker atomically.

func (*Store) RecordAttempt 

func (s *Store) RecordAttempt(attempt Attempt, now time.Time) error

RecordAttempt appends one Transaction attempt to the audit trail.

func (*Store) RecordEvaluation added in v1.2.0 

func (s *Store) RecordEvaluation(token string, key Key, runID string, result domain.ResultCode, detail string, now time.Time) error

RecordEvaluation persists the latest service check, including refusals.

func (*Store) RecordNotifierFailure 

func (s *Store) RecordNotifierFailure() error

RecordNotifierFailure increments the persisted failure streak.

func (*Store) RecordNotifierSuccess 

func (s *Store) RecordNotifierSuccess(now time.Time) error

RecordNotifierSuccess records a successful delivery, resetting the failure streak.

func (*Store) ReleaseLease 

func (s *Store) ReleaseLease(token string) error

ReleaseLease releases the lease if the token still owns it; releasing a superseded token is a no-op.

func (*Store) RenewLease added in v1.2.0 

func (s *Store) RenewLease(token string, now time.Time, ttlSeconds int) error

RenewLease extends an unexpired lease only for its current owner.

func (*Store) ResetSuppression 

func (s *Store) ResetSuppression() error

ResetSuppression clears every suppression record — used when the webhook destination changes, so the new destination pages current state once (which is correct).

func (*Store) Scheduler added in v1.2.0 

func (s *Store) Scheduler() (SchedulerProgress, error)

Scheduler returns durable scheduling timestamps.

func (*Store) SetAcceptedDigest 

func (s *Store) SetAcceptedDigest(key Key, digest string, now time.Time) error

SetAcceptedDigest records a digest as the accepted Baseline and clears the Key's Candidates and pending Proposal: accepting is the terminal state of both.

func (*Store) SetNotifierDestination 

func (s *Store) SetNotifierDestination(fingerprint string) error

SetNotifierDestination records which destination the suppression table belongs to.

func (*Store) SetPendingProposal 

func (s *Store) SetPendingProposal(key Key, digest, proposalURL string, now time.Time) error

SetPendingProposal records an open Proposal for a Key.

func (*Store) SetSchedulerProgress added in v1.2.0 

func (s *Store) SetSchedulerProgress(token string, p SchedulerProgress, now time.Time) error

SetSchedulerProgress persists the next tick and last completed observation.

func (*Store) SetSuppressionState 

func (s *Store) SetSuppressionState(event, stack, service, state string, now time.Time) error

SetSuppressionState records the state a notification was last sent for.

func (*Store) SetTransactionPhase added in v1.2.0 

func (s *Store) SetTransactionPhase(token, phase string, now time.Time) error

SetTransactionPhase persists the owner's current Transaction phase.

func (*Store) StackChecks added in v1.2.0 

func (s *Store) StackChecks() ([]StackCheck, error)

StackChecks returns latest stack observation progress.

func (*Store) StartStackCheck added in v1.2.0 

func (s *Store) StartStackCheck(token string, key Key, runID string, now time.Time) error

StartStackCheck persists an observation start before work is dispatched.

func (*Store) Status 

func (s *Store) Status(now time.Time) (Status, error)

Status reads the durable state snapshot.

func (*Store) SuppressionState 

func (s *Store) SuppressionState(event, stack, service string) (string, bool, error)

SuppressionState reads the last notified state for a suppression key.

func (*Store) WithLease added in v1.2.0 

func (s *Store) WithLease(token string, clock func() time.Time) *Store

WithLease returns a store whose reconciliation writes require current lease ownership.

type TransactionProgress added in v1.2.0 

type TransactionProgress struct {
	OwnerToken     string
	Key            Key
	RunID          string
	Phase          string
	StartedAt      time.Time
	PhaseStartedAt time.Time
}

TransactionProgress is durable ownership of an unfinished Transaction.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.