buildbucket

README

Buildbucket

Buildbucket is a generic build queue. Read more at https://chromium.googlesource.com/infra/infra/+/master/appengine/cr-buildbucket/README.md

Documentation

Overview

Package buildbucket defines Go types that are more convenient than the API types in "github.com/TriggerMail/luci-go/common/api/buildbucket/buildbucket/v1"

Index

• Constants
• Variables
• func BucketNameToV2(v1Bucket string) (project string, bucket string)
• func BuildToV2(msg *v1.ApiCommonBuildMessage) (b *buildbucketpb.Build, err error)
• func ConvertBuildSteps(c context.Context, annSteps []*annotpb.Step_Substep, annURL string) ([]*buildbucketpb.Step, error)
• func StatusToV2(build *v1.ApiCommonBuildMessage) (buildbucketpb.Status, error)
• type Build
  • func GetByAddress(c context.Context, client *v1.Service, address string) (*Build, error)
  • func (b *Build) Address() string
  • func (b *Build) ParseMessage(msg *v1.ApiCommonBuildMessage) error
  • func (b *Build) PutRequest() (*v1.ApiPutRequestMessage, error)
  • func (b *Build) RunDuration() (duration time.Duration, ok bool)
  • func (b *Build) SchedulingDuration() (duration time.Duration, ok bool)
• type Input
• type Output
• type Properties

Constants

const StepSep = "|"

Variables

var MalformedBuild = errors.BoolTag{Key: errors.NewTagKey("malformed buildbucket v1 build")}

MalformedBuild tag is present in an error if the build was malformed.

Functions

func BucketNameToV2

func BucketNameToV2(v1Bucket string) (project string, bucket string)

BucketNameToV2 converts a v1 Bucket name to the v2 constituent parts. An error is returned if the bucketname does not match the expected format. The difference between the bucket name is that v2 uses short names, for example: v1: luci.chromium.try v2: try "luci" is dropped, "chromium" is recorded as the project, "try" is the name. If the bucket does not conform to this convention, or if it is not a luci bucket, then this return and empty string for both project and bucket.

func BuildToV2

func BuildToV2(msg *v1.ApiCommonBuildMessage) (b *buildbucketpb.Build, err error)

BuildToV2 converts a v1 build message to v2.

The returned build may be incomplete if msg is incomplete. For example, if msg is a partial response and does not have builder name, the returned build won't have it either.

The returned build does not include steps. Returns an error if msg is malformed.

func ConvertBuildSteps

func ConvertBuildSteps(c context.Context, annSteps []*annotpb.Step_Substep, annURL string) ([]*buildbucketpb.Step, error)

ConvertBuildSteps converts a build given the root step's substeps, which must be the actual steps of the build, and the Logdog URL for links conversion. The provided context is used only for logging.

Does not verify that the returned build satisfies all the constraints described in the proto files.

Unsupported fields:

• Substep.annotation_stream,
• Step.link,
• Link.isolate_object,
• Link.dm_link.

func StatusToV2

func StatusToV2(build *v1.ApiCommonBuildMessage) (buildbucketpb.Status, error)

StatusToV2 converts v1 build's Status, Result, FailureReason and CancelationReason to v2 Status enum.

If build.Status is "", returns (Status_STATUS_UNSPECIFIED, nil). Useful with partial buildbucket responses.

Types

type Build

type Build struct {
	ID           int64
	CreationTime time.Time
	CreatedBy    identity.Identity
	Project      string
	Bucket       string
	Builder      string
	// Number identifies the build within the builder.
	// Build numbers are monotonically increasing, mostly contiguous.
	//
	// The type is *int to prevent accidental confusion
	// of valid build number 0 with absence of the number (zero value).
	Number *int
	// BuildSets is parsed "buildset" tag values.
	//
	// If a buildset is present in tags, but not recognized
	// it won't be included here.
	BuildSets []buildbucketpb.BuildSet
	Tags      strpair.Map
	Input     Input

	Status           buildbucketpb.Status
	StatusChangeTime time.Time
	URL              string
	StartTime        time.Time
	UpdateTime       time.Time
	Canary           bool
	Experimental     bool

	CompletionTime time.Time
	Output         Output
}

Build is a buildbucket build. It is a more type-safe version of buildbucket.ApiCommonBuildMessage.

DEPRECATED: use BuildToV2.

func GetByAddress

func GetByAddress(c context.Context, client *v1.Service, address string) (*Build, error)

GetByAddress fetches a build by its address. Returns (nil, nil) if build is not found.

func (*Build) Address

func (b *Build) Address() string

Address returns an alternative identifier of the build. If b has a number, the address is "<bucket>/<builder>/<number>". Otherwise it is "<id>".

See also "github.com/TriggerMail/luci-go/common/api/buildbucket/v1".FormatBuildAddress.

func (*Build) ParseMessage

func (b *Build) ParseMessage(msg *v1.ApiCommonBuildMessage) error

ParseMessage parses a build message to Build.

Numeric values in JSON-formatted fields, e.g. property values, are parsed as json.Number.

If an error is returned, the state of b is undefined.

DEPRECATED: use BuildToV2.

func (*Build) PutRequest

func (b *Build) PutRequest() (*v1.ApiPutRequestMessage, error)

PutRequest converts b to a build creation request.

If a buildset is present in both b.BuildSets and b.Map, it is deduped. Returned value has zero ClientOperationId. Returns an error if properties could not be marshaled to JSON.

func (*Build) RunDuration

func (b *Build) RunDuration() (duration time.Duration, ok bool)

RunDuration returns duration between build start and completion.

func (*Build) SchedulingDuration

func (b *Build) SchedulingDuration() (duration time.Duration, ok bool)

SchedulingDuration returns duration between build creation and start.

type Input

type Input struct {
	// Properties is opaque data passed to the build.
	// For recipe-based builds, this is build properties.
	Properties Properties
}

Input is the input to the builder.

type Output

type Output struct {
	Properties Properties

	// TODO(nodir, iannucci): replace type "error" with a new type that
	// represents a stack of errors emitted by different layers of the system,
	// where each error has
	// - domain string, e.g. "kitchen"
	// - reason string, e.g. kitchen-specific error code
	// - message string: human readable error
	// - meta: a proto.Struct with random data provided by the layer
	// The new type must implement error so that the change is
	// backward compatible.
	Err error // populated in builds with status StatusError
}

Output is build output.

type Properties

type Properties interface{}

Properties is data provided by users, opaque to LUCI services. The value must be JSON marshalable/unmarshalable into/out from a JSON object.

When using an unmarshaling function, such as (*Build).ParseMessage, if the user knows the properties they need, they may set the value to a json-compatible struct. The unmarshaling function will try to unmarshal the properties into the struct. Otherwise, the unmarshaling function will use a generic type, e.g. map[string]interface{}.

Example:

var props struct {
  A string
}
var build buildbucket.Build
build.Input.Properties = &props
if err := build.ParseMessage(msg); err != nil {
  return err
}
println(props.A)