README
¶
Build analysis
Observations
The controller reloads the queue-scoped Build, invokes the queue's issue detector, and persists each returned observation individually. Observations already stored for the same build, task, and unit within a queue are not persisted again, so repeated polls and retries after partial writes are safe. Detector results accompanying an error are discarded.
This controller only accumulates historical observations. An empty detection result neither deletes earlier observations nor establishes recovery. Open-issue projection, lifecycle history, and resolution are outside its scope.
Polling and completion
Every delivery reloads the Build and its Request before detection. After a successful pass, a nonterminal Build holds the delivery for two minutes; a terminal Build completes the delivery after persistence. The status read before detection determines whether the pass holds: if the Build finishes during detection, another delivery is needed to analyze it after observing terminal status. More than one delivery may analyze the same terminal Build; observation persistence remains idempotent.
If the Request is terminal but the loaded Build is nonterminal, analysis reloads the Build before deciding to stop. The Build may have finished between the initial Build read and the Request read; reloading avoids skipping its final analysis. If it is still nonterminal, analysis stops without detection or a hold. This can occur when the status-polling DLQ handler fails the Request without learning the actual build result, leaving the Build at its last observed status.
Status polling and updates remain the responsibility of buildsignal. Analysis never changes Request state or releases build slots.
Errors
Detection, persistence, configuration, state-loading, and message-validation errors are returned to the consumer for its normal retry or DLQ policy, whether the Build is running or terminal. Analysis errors do not use the two-minute polling hold. The consumer classifies errors and applies its configured retry limits and backoff; a final analysis can still fail and dead-letter.
DLQ recovery
The recovery controller records a build_analysis_abandoned event in the Request's history, with the build ID, to indicate that analysis could not complete and issue observations may be incomplete. It does not rerun detection, delete earlier observations, change Request or Build state, or release a build slot. Original failure details are logged rather than included in the immutable history event.
History identity is stable per build, so repeated recovery deliveries and separate analysis notices for the same build retain one event. Different builds retain different events, even for the same Request. A later successful analysis does not erase the historical occurrence.
State-read and history-write errors are returned for retry. Hosts must run recovery with the DLQ consumer's always-retryable processor and unlimited-retry subscription; only recovery work is retried, not analysis. Unusable payloads, invalid or unresolvable queues, missing Build or Request records, and queue mismatches are logged and acknowledged rather than retried indefinitely.
Host integration
The reference service supplies a no-op detector and publishes analysis notices at build start and completion. It registers the normal analysis controller with bounded retries and the recovery controller with the existing DLQ consumer. See build issue observation for the publication rules and retry configuration.
Documentation
¶
Overview ¶
Package buildanalysis accumulates issue observations during and after builds. Build status is read from storage; status polling remains separate.
Index ¶
Constants ¶
const PollDelayMs int64 = 120000
PollDelayMs is the delay in milliseconds after a successful nonterminal pass. Two minutes limits provider traffic during long-running builds.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller accumulates observations while builds run and after completion. Terminal analysis must finish persistence before its delivery completes.
func NewController ¶
func NewController( logger *zap.SugaredLogger, scope tally.Scope, stores storage.Factory, detectorFactory buildissue.DetectorFactory, topicKey consumer.TopicKey, consumerGroup string, ) *Controller
func (*Controller) ConsumerGroup ¶
func (c *Controller) ConsumerGroup() string
func (*Controller) Name ¶
func (c *Controller) Name() string
func (*Controller) Process ¶
Process holds after a successful nonterminal pass. Errors are returned for normal queue retry or DLQ handling; partial writes are safe to retry.
func (*Controller) TopicKey ¶
func (c *Controller) TopicKey() consumer.TopicKey
type DLQController ¶
type DLQController struct {
// contains filtered or unexported fields
}
DLQController records incomplete analysis without rerunning detection or changing the validation outcome.
func NewDLQController ¶
func NewDLQController( logger *zap.SugaredLogger, scope tally.Scope, stores storage.Factory, materializer requestlog.Materializer, topicKey consumer.TopicKey, consumerGroup string, ) *DLQController
NewDLQController creates a controller for incomplete build analysis.
func (*DLQController) ConsumerGroup ¶
func (c *DLQController) ConsumerGroup() string
func (*DLQController) Name ¶
func (c *DLQController) Name() string
func (*DLQController) Process ¶
Process retains incomplete-analysis history and acknowledges unusable messages. State-read and history-write failures are returned for DLQ recovery retry.
func (*DLQController) TopicKey ¶
func (c *DLQController) TopicKey() consumer.TopicKey
Source Files