watch

package
v3.52.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultMaxConsecutiveErrors is the number of consecutive polling failures
	// before the watch loop aborts.
	DefaultMaxConsecutiveErrors = 10

	// DefaultRequestTimeout is the per-request timeout for each polling call.
	DefaultRequestTimeout = 30 * time.Second
)

Variables

This section is empty.

Functions

func FetchPromisedHardFailures added in v3.50.0 

func FetchPromisedHardFailures(ctx context.Context, client *buildkite.Client, org, pipeline string, buildNumber int) (map[string]bool, error)

FetchPromisedHardFailures returns the set of job UUIDs that the server classifies as failing *and* are still running — i.e. running jobs that have declared a hard-failing promised exit status (an early failure declaration).

It queries the build-scoped jobs index with state=failed. When PROMISED_EXIT_STATUS_FOR_FAILING is enabled server-side, that filter folds running script jobs with a hard-failing promised exit status into the failed results (soft-fails excluded), so the server — not the client — owns the precise "will fail" classification. We keep only the still-running jobs; finished failures are surfaced through the normal failed path.

Best-effort by design: until the server change ships (or for orgs without the flag), state=failed returns only finished jobs, so the running-job filter yields an empty set and this is a no-op. Callers should treat an error as "no promised failures this poll" rather than fatal.

func WatchBuild 

func WatchBuild(
	ctx context.Context,
	client *buildkite.Client,
	org, pipeline string,
	buildNumber int,
	interval time.Duration,
	onStatus StatusFunc,
	opts ...WatchOpt,
) (buildkite.Build, error)

WatchBuild polls a build until it reaches a terminal state (FinishedAt != nil). It calls onStatus after each successful poll so callers can render progress.

Types

type BuildStatus 

type BuildStatus struct {
	NewlyFailed          []buildkite.Job
	NewlyRetryPassed     []buildkite.Job
	NewlyPromisedFailure []buildkite.Job
	Running              []buildkite.Job
	TotalRunning         int
	Summary              JobSummary
	Build                buildkite.Build
}

BuildStatus is the output of JobTracker.Update().

type FormattedJob 

type FormattedJob struct {
	buildkite.Job
}

FormattedJob wraps a Buildkite job with watch-specific formatting and classification helpers.

func NewFormattedJob 

func NewFormattedJob(j buildkite.Job) FormattedJob

NewFormattedJob wraps a Buildkite job.

func (FormattedJob) DisplayName 

func (j FormattedJob) DisplayName() string

DisplayName returns a human-readable name for a job.

func (FormattedJob) Duration 

func (j FormattedJob) Duration() time.Duration

Duration returns the elapsed duration for a job.

func (FormattedJob) HasPromisedFailure added in v3.50.0 

func (j FormattedJob) HasPromisedFailure() bool

HasPromisedFailure reports whether the job has declared an early (promised) failure: a non-zero promised exit status recorded before the job finished.

This is intentionally retry-blind and does not consult soft-fail rules — the build-show payload doesn't carry them. It surfaces the raw declaration only. Precise hard-vs-soft classification is owned server-side (the jobs index "failed" scope); this client-side check is the fallback used by the tracker when no server classification is available for a poll.

func (FormattedJob) IsFailed 

func (j FormattedJob) IsFailed() bool

func (FormattedJob) IsRunning added in v3.50.0 

func (j FormattedJob) IsRunning() bool

IsRunning reports whether the job is still actively executing.

func (FormattedJob) IsSoftFailed 

func (j FormattedJob) IsSoftFailed() bool

func (FormattedJob) IsTerminalFailureState 

func (j FormattedJob) IsTerminalFailureState() bool

type JobSummary 

type JobSummary struct {
	Passed     int `json:"passed"`
	Failed     int `json:"failed"`
	SoftFailed int `json:"soft_failed"`
	Running    int `json:"running"`
	Scheduled  int `json:"scheduled"`
	Blocked    int `json:"blocked"`
	Skipped    int `json:"skipped"`
	Waiting    int `json:"waiting"`
}

JobSummary aggregates job counts by high-level state.

func (JobSummary) String 

func (s JobSummary) String() string

String returns a human-readable summary of non-zero job counts.

type JobTracker 

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

JobTracker tracks job state changes across polls.

func NewJobTracker 

func NewJobTracker() *JobTracker

NewJobTracker creates a new JobTracker.

func (*JobTracker) FailedJobs added in v3.33.1 

func (t *JobTracker) FailedJobs() []buildkite.Job

FailedJobs returns all hard-failed, non-superseded jobs (excludes soft failures), sorted by start time.

func (*JobTracker) PassedJobs added in v3.35.0 

func (t *JobTracker) PassedJobs() []buildkite.Job

PassedJobs returns all non-superseded jobs that passed, sorted by start time.

func (*JobTracker) SetServerClassifiedFailures added in v3.50.0 

func (t *JobTracker) SetServerClassifiedFailures(set map[string]bool)

SetServerClassifiedFailures records the server's precise set of running jobs that are hard-failing promised failures, keyed by job ID. Call this before Update on each poll. Passing a non-nil map (even empty) makes the tracker trust the server's classification for promised-failure surfacing; passing nil (the default) falls back to the client-side declaration heuristic.

The server set is soft-fail-aware, so it avoids surfacing jobs that declared a promised exit status which would actually be soft-failed — something the build-show payload alone can't determine.

func (*JobTracker) Update 

func (t *JobTracker) Update(b buildkite.Build) BuildStatus

Update processes a build and returns the current status with any state changes.

type StatusFunc 

type StatusFunc func(b buildkite.Build) error

StatusFunc is called on each successful poll with the latest build state. Returning an error aborts the watch loop and propagates that error to the caller.

type TestStatusFunc added in v3.35.0 

type TestStatusFunc func(newTestChanges []buildkite.BuildTest) error

TestStatusFunc is called with newly-seen test changes on each poll. Returning an error aborts the watch loop.

type TestTracker added in v3.35.0 

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

TestTracker tracks which test executions have already been reported, so that each test change is only surfaced once across polling iterations.

func NewTestTracker added in v3.35.0 

func NewTestTracker() *TestTracker

NewTestTracker creates a new TestTracker.

func (*TestTracker) Update added in v3.35.0 

func (t *TestTracker) Update(tests []buildkite.BuildTest) []buildkite.BuildTest

Update processes a list of build tests and returns only those with at least one execution that has not been seen before.

type WatchOpt added in v3.35.0 

type WatchOpt func(*watchConfig)

WatchOpt configures optional WatchBuild behavior.

func WithRetriedJobs added in v3.37.0 

func WithRetriedJobs() WatchOpt

WithRetriedJobs includes retried (superseded) jobs in each poll so the tracker can correlate original failures with their retry outcomes.

func WithTestTracking added in v3.35.0 

func WithTestTracking(fn TestStatusFunc) WatchOpt

WithTestTracking enables polling BuildTests.List for failed tests on each iteration, calling onTestStatus with any newly-seen test changes.

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.