buildmerge

Documentation

Overview

Package buildmerge implements the build.proto tracking and merging logic for luciexe host applications.

You probably want to use `go.chromium.org/luci/luciexe/host` instead.

This package is separate from luciexe/host to avoid unnecessary entaglement with butler/logdog; All the logic here is implemented to avoid:

• interacting with the environment
• interacting with butler/logdog (except by implementing callbacks for those, but only acting on simple datastructures/proto messages)
• handling errors in any 'brutal' ways (all errors in this package are handled by reporting them directly in the data structures that this package manipulates).

This is done to simplify testing (as much as it can be) by concentrating all the environment stuff into luciexe/host, and all the 'pure' functional stuff here (search "imperative shell, functional core").

Index

• type Agent
  • func New(ctx context.Context, userNamespace types.StreamName, base *bbpb.Build, ...) *Agent
  • func (a *Agent) Attach(b *butler.Butler)
  • func (a *Agent) Close()
• type CalcURLFn

Types

type Agent

type Agent struct {
	// MergedBuildC is the channel of all the merged builds generated by this
	// Agent.
	//
	// The rate at which Agent merges Builds is governed by the consumption of
	// this channel; Consuming it slowly will have Agent merge less frequently,
	// and consuming it rapidly will have Agent merge more frequently.
	//
	// The last build before the channel closes will always be the final state of
	// all builds at the time this Agent was Close()'d.
	MergedBuildC <-chan *bbpb.Build

	// Wait on this channel for the Agent to drain. Will only drain after calling
	// Close() at least once.
	DrainC <-chan struct{}
	// contains filtered or unexported fields
}

Agent holds all the logic around merging build.proto streams.

func New

func New(ctx context.Context, userNamespace types.StreamName, base *bbpb.Build, calculateURLs CalcURLFn) *Agent

New returns a new Agent.

Args:

• ctx - used for logging, clock and cancelation. When canceled, the Agent will cease sending updates on MergedBuildC, but you must still invoke Agent.Close() in order to clean up all resources associated with the Agent.
• userNamespace - The logdog namespace (with a trailing slash) under which we should monitor streams.
• base - The "model" Build message that all generated builds should start with. All build proto streams will be merged onto a copy of this message. Any Output.Log's which have non-absolute URLs will have their Url and ViewUrl absolutized relative to userNamespace using calculateURLs.
• calculateURLs - A function to calculate Log.Url and Log.ViewUrl values. Should be a pure function.

The following fields will be merged into `base` from the user controlled build.proto stream(s):

Steps
SummaryMarkdown
Status
StatusDetails
UpdateTime
Tags
EndTime
Output

The frequency of updates from this Agent is governed by how quickly the caller consumes from Agent.MergedBuildC.

func (*Agent) Attach

func (a *Agent) Attach(b *butler.Butler)

Attach should be called once to attach this to a Butler.

This must be done before the butler receives any build.proto streams.

func (*Agent) Close

func (a *Agent) Close()

Close causes the Agent to stop collecting data, emit a final merged build, and then shut down all internal routines.

type CalcURLFn

type CalcURLFn func(namespaceSlash, streamName types.StreamName) (url, viewUrl string)

CalcURLFn is a stateless function which can calculate the absolute url and viewUrl from a given logdog namespace (with trailing slash) and streamName.