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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.