bbfacade

Documentation

Overview

Package bbfacade provides a facade for CV Tryjob support, hiding Buildbucket-specifc implementation details.

Index

• Variables
• type Facade
  • func (f *Facade) CancelTryjob(ctx context.Context, tj *tryjob.Tryjob, reason string) error
  • func (f *Facade) Fetch(ctx context.Context, luciProject string, eid tryjob.ExternalID) (tryjob.Status, *tryjob.Result, error)
  • func (f *Facade) Kind() string
  • func (f *Facade) Launch(ctx context.Context, tryjobs []*tryjob.Tryjob, r *run.Run, cls []*run.RunCL) []*tryjob.LaunchResult
  • func (f *Facade) Parse(ctx context.Context, data any) (tryjob.Status, *tryjob.Result, error)
  • func (f *Facade) Search(ctx context.Context, cls []*run.RunCL, definitions []*tryjob.Definition, ...) error

Variables

var AcceptedAdditionalPropKeys = stringset.NewFromSlice(
	"$recipe_engine/cq",
	"$recipe_engine/cv",
	"requester",
)

AcceptedAdditionalPropKeys are additional properties keys that, if present in the requested properties of the build, indicate that LUCI CV should still consider the build as reusable.

LUCI CV checks requested properties rather than input properties because LUCI CV only cares about whether the properties used by a build are different from the pre-defined properties in Project Config (assuming change in properties may result in change in build result). Requested properties are properties provided in ScheduleBuild, which currently is the only way to add/modify build properties. LUCI CV permits certain keys which are either added by LUCI CV itself, or known to not change build behavior.

Types

type Facade

type Facade struct {
	ClientFactory buildbucket.ClientFactory
}

Facade provides APIs that LUCI CV can use to interact with buildbucket tryjobs.

func (*Facade) CancelTryjob

func (f *Facade) CancelTryjob(ctx context.Context, tj *tryjob.Tryjob, reason string) error

CancelTryjob asks buildbucket to cancel a running tryjob.

It returns nil error if the buildbucket build is ended.

func (*Facade) Fetch

func (f *Facade) Fetch(ctx context.Context, luciProject string, eid tryjob.ExternalID) (tryjob.Status, *tryjob.Result, error)

Fetch retrieves the Buildbucket build for the given external ID and returns its current status and result.

func (*Facade) Kind

func (f *Facade) Kind() string

func (*Facade) Launch

func (f *Facade) Launch(ctx context.Context, tryjobs []*tryjob.Tryjob, r *run.Run, cls []*run.RunCL) []*tryjob.LaunchResult

Launch schedules requested Tryjobs in Buildbucket.

The Tryjobs will include relevant info from the Run (e.g. Run mode) and involves all provided CLs.

Return LaunchResults that has the same length as the provided Tryjobs. LaunchResult.Err is populated if the Buildbucket returns non-successful response or any error occurred even before sending the schedule request to buildbucket (e.g. invalid input).

Uses Tryjob ID as the request key for deduplication. This ensures only one Buildbucket build will be scheduled for one Tryjob within the deduplication window (currently 1 min. in Buildbucket).

func (*Facade) Parse

func (f *Facade) Parse(ctx context.Context, data any) (tryjob.Status, *tryjob.Result, error)

Parse parses tryjob status and result from the buildbucket build.

Returns error if the given data is not a buildbucket build.

func (*Facade) Search

func (f *Facade) Search(ctx context.Context, cls []*run.RunCL, definitions []*tryjob.Definition, luciProject string, cb func(*tryjob.Tryjob) bool) error

Search searches Buildbucket for builds that match all provided CLs and any of the provided definitions.

Also filters out builds that specify extra properties. See: `AcceptedAdditionalPropKeys`.

`cb` is invoked for each matching Tryjob converted from Buildbucket build until `cb` returns false or all matching Tryjobs are exhausted or error occurs. The Tryjob `cb` receives only populates following fields:

• ExternalID
• Definition
• Status
• Result

Also, the Tryjobs are guaranteed to have decreasing build ID (in other word, from newest to oldest) ONLY within the same host. For example, for following matching builds:

• host: A, build: 100, create time: now
• host: A, build: 101, create time: now - 2min
• host: B, build: 1000, create time: now - 1min
• host: B, build: 1001, create time: now - 3min

It is possible that `cb` is called in following orders:

• host: B, build: 1000, create time: now - 1min
• host: A, build: 100, create time: now
• host: B, build: 1001, create time: now - 3min
• host: A, build: 101, create time: now - 2min

TODO(crbug/1369200): Fix the edge case that may cause Search failing to return newer builds before older builds across different patchsets. TODO(yiwzhang): ensure `cb` get called from newest to oldest builds across all hosts.

Uses the provided `luciProject` for authentication. If any of the given definitions defines builder from other LUCI Project, this other LUCI Project should grant bucket READ permission to the provided `luciProject`. Otherwise, the builds won't show up in the search result.