Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareRequestID ¶
CompareRequestID compares ingest order of two request IDs in the same queue. Returns -1 if a is older than b, 0 if equal, 1 if a is newer than b. IDs must follow the format request/<queue>/<counter>.
Types ¶
type Build ¶
type Build struct {
// ID is the build's own key: the runner-assigned id returned by
// Trigger (e.g. a Buildkite build number). Opaque; never parsed or
// derived by stovepipe.
ID string `json:"id"`
// RequestID is the Request this build validates (Build->Request
// navigation; no reverse index from Request to its builds is needed).
RequestID string `json:"request_id"`
// Status is the build's lifecycle state.
Status BuildStatus `json:"status"`
// Version is used for optimistic locking. Versioning starts at 1 and
// is incremented for each change to the object.
Version int32 `json:"version"`
}
Build represents a single build triggered for a Request's commit. All fields except Status and Version are immutable after creation — build is the sole creator (via BuildStore.Create), and buildsignal is the sole writer of Status/Version afterward.
type BuildID ¶
type BuildID struct {
// ID is the runner-assigned identifier for the build.
ID string `json:"id"`
}
BuildID wraps the runner-assigned build identifier for BuildRunner Status/Cancel/Trigger parameters.
type BuildMetadata ¶
BuildMetadata carries caller-supplied, provider-echoed free-form metadata about a build. The runner must not depend on its contents. Empty today; expected to carry real data eventually (e.g. conflict-graph info, or other upstream decisions relevant to the build) once a concrete need lands in either domain — the shape is deferred until then, not decided here.
type BuildStatus ¶
type BuildStatus string
BuildStatus defines the possible states of a build. Shaped the same as SubmitQueue's own BuildStatus (submitqueue/entity/build.go), but defined locally rather than shared — see build.md's "Alternatives considered for sharing the contract".
const ( // BuildStatusUnknown is the unreachable zero value, set by default when // the structure is initialized. It should never be seen in the system. BuildStatusUnknown BuildStatus = "" // BuildStatusAccepted indicates the build has been accepted for // execution by the runner via Trigger, but has not yet started. BuildStatusAccepted BuildStatus = "accepted" // BuildStatusRunning indicates the build is currently executing. BuildStatusRunning BuildStatus = "running" // BuildStatusSucceeded indicates the build completed successfully. // This is a terminal state. BuildStatusSucceeded BuildStatus = "succeeded" // BuildStatusFailed indicates the build did not complete successfully. // This is a terminal state. BuildStatusFailed BuildStatus = "failed" // BuildStatusCancelled indicates the build was cancelled. // This is a terminal state. BuildStatusCancelled BuildStatus = "cancelled" )
func (BuildStatus) IsTerminal ¶
func (s BuildStatus) IsTerminal() bool
IsTerminal returns true if the status represents a final state (Succeeded, Failed, or Cancelled). A terminal status is write-once: once buildsignal persists one, a later poll reporting a different terminal value must never overwrite it (see buildsignal.md's Algorithm, step 6).
type BuildStrategy ¶
type BuildStrategy string
BuildStrategy defines how build validates the request's commit.
const ( // BuildStrategyUnknown is the zero value before process chooses a strategy. BuildStrategyUnknown BuildStrategy = "" // BuildStrategyIncrementalSinceGreen validates only the delta since the pinned baseline URI. BuildStrategyIncrementalSinceGreen BuildStrategy = "incremental_since_green" // BuildStrategyFull validates the whole repo from scratch. BuildStrategyFull BuildStrategy = "full" )
type IngestRequest ¶
type IngestRequest struct {
// Queue is the name of the queue whose head commit should be ingested.
Queue string
}
IngestRequest represents the validated inputs of an ingest RPC call. The controller resolves the queue's head commit and mints a request ID internally.
type IngestResult ¶
type IngestResult struct {
// ID is the globally unique request identifier assigned to the ingested commit.
// Format: "request/<queue>/<counter_value>".
ID string
}
IngestResult is the outcome of a successful ingest operation.
type Queue ¶
type Queue struct {
// Name is the stable logical id for the queue. It should be unique within the system.
Name string `json:"name"`
// LastGreenURI is the queue's last-known-good commit: the most recent head at which
// whole-repo validation recorded green (health degree 0). Empty until the first such outcome.
LastGreenURI string `json:"last_green_uri"`
// LastGreenRequestID is the request that established LastGreenURI. The bookmark only
// moves forward: a green outcome adopts the pair only when this id is empty or older
// than the candidate's, compared by ingest order via CompareRequestID.
LastGreenRequestID string `json:"last_green_request_id"`
// InFlightCount is the number of trunk validations admitted by process but not yet terminal.
InFlightCount int32 `json:"in_flight_count"`
// LatestRequestID is the request id of the newest head ingest accepted for this queue.
// Empty until the first request is created. Coalescing compares IDs via CompareRequestID.
LatestRequestID string `json:"latest_request_id"`
// Version is the version of the object. It is used for optimistic locking.
// Versioning starts at 1 and is incremented for each change to the object.
Version int32 `json:"version"`
}
Queue holds per-queue pipeline coordination state for a named repo+ref (e.g. "monorepo/main").
type QueueConfig ¶
type QueueConfig struct {
// Name uniquely identifies this queue within the system.
// Referenced by Request.Queue.
Name string `json:"name" yaml:"name"`
// MaxConcurrent is the cap on concurrent in-flight validations for the queue.
MaxConcurrent int32 `json:"max_concurrent" yaml:"max_concurrent"`
// GateWaitDelayMs is the redelivery delay while the latest head waits for a slot.
GateWaitDelayMs int64 `json:"gate_wait_delay_ms" yaml:"gate_wait_delay_ms"`
}
QueueConfig holds deployment configuration for a Stovepipe validation queue. Mutable runtime state (latest head, in-flight count) lives on the Queue row; knobs such as max_concurrent are resolved here at gate-check time. Immutable after load.
type Request ¶
type Request struct {
// ID is the globally unique identifier for the request. Format: "request/<queue>/<counter>"
// (e.g. "request/monorepo/main/42").
ID string `json:"id"`
// Queue is the name of the queue (a named repo+ref) being validated. It namespaces the ID
// and is the stable handle the ingest caller supplies.
Queue string `json:"queue"`
// URI is the opaque, VCS-agnostic locator of the commit under validation, as produced by the
// SourceControl extension.
URI string `json:"uri"`
// BuildStrategy is the validation scope process chose when admitting this request.
BuildStrategy BuildStrategy `json:"build_strategy"`
// BaseURI is the base URI to be used for this request when the strategy is incremental.
// Empty for full builds and cold start.
BaseURI string `json:"base_uri"`
// State is the current state of the request in the pipeline.
State RequestState `json:"state"`
// Version is the version of the object. It is used for optimistic locking.
// Versioning starts at 1 and is incremented for each change to the object.
Version int32 `json:"version"`
}
Request represents a single validation of a queue at a particular commit. The queue reports a newly observed commit, Stovepipe mints a Request (identity namespaced by the queue), and the request flows through the pipeline accumulating state.
type RequestState ¶
type RequestState string
RequestState defines the internal state of a Stovepipe validation request as it moves through the pipeline. States are internal and used to implement a state machine; a customer-facing status type may be layered on top later, as in SubmitQueue.
const ( // RequestStateUnknown is the unreachable zero value. It is set by default when the // structure is initialized and should never be seen in the system. RequestStateUnknown RequestState = "" // RequestStateAccepted is the initial state of a request: a new commit has been observed // for the queue and the request has been admitted into the pipeline, but no validation // strategy has been chosen yet. RequestStateAccepted RequestState = "accepted" // RequestStateProcessing means process admitted the request, recorded build strategy and // baseline, and published to build. RequestStateProcessing RequestState = "processing" // RequestStateSuperseded means process skipped the request because a newer head exists. RequestStateSuperseded RequestState = "superseded" // RequestStateSucceeded means the build validating this request's commit reached a // successful terminal status. RequestStateSucceeded RequestState = "succeeded" // RequestStateFailed means the build validating this request's commit reached an // unsuccessful terminal status, or the request could never complete and was forced to a // conservative unsuccessful outcome (see workflow.md's fail-closed posture). RequestStateFailed RequestState = "failed" // RequestStateCancelled means the build validating this request's commit was cancelled // before reaching a verdict. Distinct from failed: what a cancellation implies for // greenness is decided where greenness is recorded, not here. RequestStateCancelled RequestState = "cancelled" )
func (RequestState) HasBuildOutcome ¶
func (s RequestState) HasBuildOutcome() bool
HasBuildOutcome returns true if the state records the terminal status of this request's build: succeeded, failed, or cancelled. Superseded requests never ran a build, so they are terminal without an outcome.
func (RequestState) IsTerminal ¶
func (s RequestState) IsTerminal() bool
IsTerminal returns true if the state is one the pipeline never advances past: superseded (a newer head preempted this request before it was validated) or one of the three build outcomes. Greenness derived from an outcome is a separate fact recorded against the URI, so it is not part of this lifecycle.
Source Files