response

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: 6 Imported by: 0

Documentation

Overview

Package response is Ripen's wire surface: the Response envelope every verb answers in, and the typed payloads inside it. JSON is the output of this package — there is no --json flag. A human-readable view of the same payload lives on the CLI as --pretty, and is not a second schema.

Two rules hold everywhere in this package. Identity is always the three parts backend/stack/service, never the state store's internal key. And a value that can be absent is null, never an empty string pretending to be a value.

Index

Constants

View Source 
const SchemaVersion = 1

SchemaVersion is the Response envelope's version. It moves independently of the Event envelope's, and additive changes — a new field, a new result code — do not bump it.

Variables

View Source 
var Commands = []string{
	"status", "candidates", "audit", "explain",
	"run", "propose", "clear-proposal", "clear-breaker",
	"notify-test", "schema", "version",
}

Commands is every command with a published response schema, in the order the documentation lists them.

Functions

func Optional 

func Optional(value string) *string

Optional renders a value that may be absent: empty means null.

func Schemas 

func Schemas() map[string]any

Schemas returns one JSON Schema per command: the Response envelope with that command's payload in place of data.

func Stamp 

func Stamp(at time.Time) string

Stamp renders a time the way every timestamp on the wire is rendered.

func Write 

func Write(writer io.Writer, envelope Envelope) error

Write encodes an envelope as one line of JSON.

Types

type Acknowledged 

type Acknowledged struct {
	Changed bool    `json:"changed"`
	Reason  string  `json:"reason"`
	Breaker Breaker `json:"breaker"`
	Detail  string  `json:"detail"`
}

Acknowledged is the answer to the verbs that change one thing and report the state afterwards.

type Attempt 

type Attempt struct {
	Identity
	RunID       string  `json:"run_id"`
	Actor       string  `json:"actor"`
	Result      string  `json:"result"`
	Detail      string  `json:"detail"`
	OldDigest   *string `json:"old_digest"`
	NewDigest   *string `json:"new_digest"`
	AttemptedAt string  `json:"attempted_at"`
}

Attempt is one audit-trail row.

type AttemptSummary 

type AttemptSummary struct {
	RunID       string `json:"run_id"`
	Actor       string `json:"actor"`
	Result      string `json:"result"`
	Detail      string `json:"detail"`
	AttemptedAt string `json:"attempted_at"`
}

AttemptSummary is the last thing that happened to a Service.

type Audit 

type Audit struct {
	Attempts   []Attempt `json:"attempts"`
	NextCursor *string   `json:"next_cursor"`
}

Audit is the answer to `ripen audit`, newest first. NextCursor is null when the page is the last one.

type Breaker 

type Breaker struct {
	Open   bool    `json:"open"`
	Reason *string `json:"reason"`
}

Breaker is the Circuit breaker's state.

type Candidate 

type Candidate struct {
	Identity
	Observation
}

Candidate is one observed Candidate with its identity.

type Candidates 

type Candidates struct {
	Candidates []Candidate `json:"candidates"`
}

Candidates is the answer to `ripen candidates`.

type Code 

type Code string

Code is the closed set of failure codes. Receivers must ignore codes they do not know. 

const (
	CodeUsage               Code = "usage"
	CodeConfigInvalid       Code = "config_invalid"
	CodeNotFound            Code = "not_found"
	CodePreconditionFailed  Code = "precondition_failed"
	CodeBreakerOpen         Code = "breaker_open"
	CodeStateLocked         Code = "state_locked"
	CodeBackendUnavailable  Code = "backend_unavailable"
	CodeRegistryUnavailable Code = "registry_unavailable"
	CodeInternal            Code = "internal"
)

The v1 error codes.

type EffectivePolicy 

type EffectivePolicy struct {
	Mode                       string   `json:"mode"`
	MaxUpdatesPerRun           int      `json:"max_updates_per_run"`
	CandidateMinAgeSeconds     int      `json:"candidate_min_age_seconds"`
	VerificationTimeoutSeconds int      `json:"verification_timeout_seconds"`
	LeaseTTLSeconds            int      `json:"lease_ttl_seconds"`
	CheckIntervalSeconds       int      `json:"check_interval_seconds"`
	ObservationConcurrency     int      `json:"observation_concurrency"`
	StateFile                  string   `json:"state_file"`
	Backends                   []string `json:"backends"`
	StackCount                 int      `json:"stack_count"`
	ProposalsConfigured        bool     `json:"proposals_configured"`
	NotifierConfigured         bool     `json:"notifier_configured"`
}

EffectivePolicy is what Ripen is actually running with, after defaults — not what the file said.

type Envelope 

type Envelope struct {
	SchemaVersion int    `json:"schema_version"`
	Command       string `json:"command"`
	OccurredAt    string `json:"occurred_at"`
	OK            bool   `json:"ok"`
	Data          any    `json:"data,omitempty"`
	Error         *Error `json:"error,omitempty"`
}

Envelope wraps every answer, success or failure.

func Fail 

func Fail(command string, at time.Time, code Code, message string) Envelope

Fail builds an error envelope.

func Succeed 

func Succeed(command string, at time.Time, data any) Envelope

Succeed builds a success envelope around one payload.

type Error 

type Error struct {
	Code      Code   `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable"`
}

Error is a failure in the same envelope as a success.

type Evaluation added in v1.2.0 

type Evaluation struct {
	Identity
	RunID       string `json:"run_id"`
	Result      string `json:"result"`
	Detail      string `json:"detail"`
	EvaluatedAt string `json:"evaluated_at"`
}

Evaluation is the most recent service evaluation, including refusals.

type Explain 

type Explain struct {
	Backend          string           `json:"backend"`
	Stack            string           `json:"stack"`
	Enabled          bool             `json:"enabled"`
	Excluded         bool             `json:"excluded"`
	GitPath          *string          `json:"git_path"`
	ExpectedServices []string         `json:"expected_services"`
	Breaker          Breaker          `json:"breaker"`
	Mode             string           `json:"mode"`
	Services         []ExplainService `json:"services"`
}

Explain is the answer to `ripen explain <stack>`: why the next run would, or would not, act on this stack.

type ExplainService 

type ExplainService struct {
	Identity
	Enabled         bool         `json:"enabled"`
	AutoApply       bool         `json:"auto_apply"`
	Health          Health       `json:"health"`
	Baseline        *string      `json:"baseline"`
	Candidate       *Observation `json:"candidate"`
	PendingProposal *Proposal    `json:"pending_proposal"`
	// Blockers is what stands between this Service and an apply right
	// now, in the order Ripen would hit them. Empty means it would act.
	Blockers []string `json:"blockers"`
}

ExplainService is one Service's reasoning.

type Health 

type Health struct {
	Type           string `json:"type"`
	Target         string `json:"target"`
	AcceptedStatus []int  `json:"accepted_status"`
}

Health is one configured functional health check.

type Identity 

type Identity struct {
	Backend string  `json:"backend"`
	Stack   string  `json:"stack"`
	Service *string `json:"service"`
}

Identity names one Service. Service is null for a stack-level policy.

type Lease 

type Lease struct {
	Active bool `json:"active"`
}

Lease says whether a run is in flight.

type NotifierHealth 

type NotifierHealth struct {
	LastSuccessAt       *string `json:"last_success_at"`
	ConsecutiveFailures int     `json:"consecutive_failures"`
	DroppedSinceStart   int     `json:"dropped_since_start"`
}

NotifierHealth is how the outbound Notifier is doing. Delivery is at-most-once and fail-open, so this is the only way to know.

type NotifyTest 

type NotifyTest struct {
	Delivered bool           `json:"delivered"`
	Detail    string         `json:"detail"`
	Health    NotifierHealth `json:"health"`
}

NotifyTest is the answer to `ripen notify test`.

type Observation 

type Observation struct {
	Digest       string `json:"digest"`
	FirstSeen    string `json:"first_seen"`
	LastSeen     string `json:"last_seen"`
	Observations int    `json:"observations"`
	Mature       bool   `json:"mature"`
	MatureAt     string `json:"mature_at"`
}

Observation is a Candidate as the state store holds it.

type Proposal 

type Proposal struct {
	Digest     string `json:"digest"`
	URL        string `json:"url"`
	ProposedAt string `json:"proposed_at"`
}

Proposal is an open digest-pin Proposal.

type Proposed 

type Proposed struct {
	Identity
	Digest  string `json:"digest"`
	URL     string `json:"url"`
	Created bool   `json:"created"`
	RunID   string `json:"run_id"`
	Detail  string `json:"detail"`
}

Proposed is the answer to `ripen propose <stack>`.

type Run 

type Run struct {
	RunID          string      `json:"run_id"`
	Mode           string      `json:"mode"`
	Actor          string      `json:"actor"`
	StartedAt      string      `json:"started_at"`
	FinishedAt     string      `json:"finished_at"`
	UpdatesApplied int         `json:"updates_applied"`
	BreakerOpen    bool        `json:"breaker_open"`
	Results        []RunResult `json:"results"`
}

Run is the answer to `ripen run`.

type RunResult 

type RunResult struct {
	Backend *string `json:"backend"`
	Stack   string  `json:"stack"`
	Service *string `json:"service"`
	Result  string  `json:"result"`
	Detail  string  `json:"detail"`
	Digest  *string `json:"digest"`
}

RunResult is one Service's outcome in a run. Backend is null for a run-level result, where Stack is "*".

type Scheduler added in v1.2.0 

type Scheduler struct {
	LastCompletedAt *string `json:"last_completed_at"`
	NextTickAt      *string `json:"next_tick_at"`
	Stale           bool    `json:"stale"`
}

Scheduler exposes persisted scheduling timestamps without asserting liveness.

type SchemaSet 

type SchemaSet struct {
	SchemaVersion int            `json:"schema_version"`
	Schemas       map[string]any `json:"schemas"`
}

SchemaSet is the answer to `ripen schema`.

type Service 

type Service struct {
	Identity
	Enabled         bool            `json:"enabled"`
	AutoApply       bool            `json:"auto_apply"`
	Baseline        *string         `json:"baseline"`
	Candidate       *Observation    `json:"candidate"`
	PendingProposal *Proposal       `json:"pending_proposal"`
	LastResult      *AttemptSummary `json:"last_result"`
}

Service is one configured Service and everything durable about it. A configured Service that has never been observed still appears, with a null baseline: status is driven by the policy, not by the state.

type StackCheck added in v1.2.0 

type StackCheck struct {
	Identity
	RunID       string  `json:"run_id"`
	StartedAt   string  `json:"started_at"`
	CompletedAt *string `json:"completed_at"`
	Outcome     string  `json:"outcome"`
}

StackCheck exposes observation progress independently of Candidate age.

type Status 

type Status struct {
	Checks            []StackCheck         `json:"checks"`
	Evaluations       []Evaluation         `json:"evaluations"`
	Scheduler         Scheduler            `json:"scheduler"`
	ActiveTransaction *TransactionProgress `json:"active_transaction"`
	Breaker           Breaker              `json:"breaker"`
	Lease             Lease                `json:"lease"`
	Notifier          NotifierHealth       `json:"notifier"`
	Services          []Service            `json:"services"`
	Versions          Versions             `json:"versions"`
	EffectivePolicy   EffectivePolicy      `json:"effective_policy"`
}

Status is the answer to `ripen status`.

type TransactionProgress added in v1.2.0 

type TransactionProgress struct {
	Identity
	RunID          string `json:"run_id"`
	Phase          string `json:"phase"`
	StartedAt      string `json:"started_at"`
	PhaseStartedAt string `json:"phase_started_at"`
	Interrupted    bool   `json:"interrupted"`
}

TransactionProgress identifies unfinished work without exposing ownership tokens.

type Version 

type Version struct {
	Versions
}

Version is the answer to `ripen version`.

type Versions 

type Versions struct {
	Ripen          string `json:"ripen"`
	Commit         string `json:"commit"`
	BuiltAt        string `json:"built_at"`
	ResponseSchema int    `json:"response_schema"`
	EventSchema    int    `json:"event_schema"`
	StateSchema    int    `json:"state_schema"`
}

Versions carries every version a caller might need to reason about.

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.