host

Documentation

Overview

Package host implements the 'Host Application' portion of the luciexe protocol.

It manages a local Logdog Butler service, and also runs all LUCI Auth related daemons. It intercepts and interprets build.proto streams within the Butler context, merging them as necessary.

Index

• Variables
• func ResolveExeCmd(opts *Options, defaultPayloadPath string) ([]string, error)
• func Run(ctx context.Context, options *Options, ...) (<-chan *bbpb.Build, error)
• type Options

Variables

var DefaultExeAuth = func(id string, knownGerritHosts []string) *authctx.Context {
	return &authctx.Context{
		ID: id,
		Options: chromeinfra.SetDefaultAuthOptions(auth.Options{
			Scopes: []string{
				"https://www.googleapis.com/auth/cloud-platform",
				"https://www.googleapis.com/auth/userinfo.email",
				"https://www.googleapis.com/auth/gerritcodereview",
				"https://www.googleapis.com/auth/firebase",
			},
		}),
		EnableGitAuth:      true,
		EnableGCEEmulation: true,
		EnableDockerAuth:   true,
		EnableFirebaseAuth: true,
		KnownGerritHosts:   knownGerritHosts,
	}
}

DefaultExeAuth returns a copy of the default value for Options.ExeAuth.

Functions

func ResolveExeCmd

func ResolveExeCmd(opts *Options, defaultPayloadPath string) ([]string, error)

ResolveExeCmd resolves the given host options and returns the command for luciexe host to invoke as a luciexe.

This includes resolving paths relative to the current working directory, or the directory contains agent inputs if DownloadAgentInputs enabled.

func Run

func Run(ctx context.Context, options *Options, cb func(context.Context, Options, <-chan lucictx.DeadlineEvent, func())) (<-chan *bbpb.Build, error)

Run executes `cb` in a "luciexe" host environment.

The merged Build objects collected from the host environment (i.e. generated within `cb`) will be pushed to the returned "<-chan *bbpb.Build" as `cb` executes.

Error during starting up the host environment will be directly returned. But `cb` does not return anything to avoid messy semantics because it's run in a goroutine; If `cb` could error out, it's recommended to make your own `chan error` and have `cb` push to that.

The context should be used for cancellation of the callback function; It's up to the `cb` implementation to respect the cancelled context.

When the callback function completes, Run closes the returned channel.

Blocking the returned channel may block the execution of `cb`.

NOTE: This modifies the environment (i.e. with os.Setenv) while `cb` is running. Be careful when using Run concurrently with other code. You MUST completely drain the returned channel in order to be guaranteed that all side-effects of Run have been unwound.

Types

type Options

type Options struct {
	// Where the butler will sink its data to.
	//
	// This is typically one of the implementations in
	// go.chromium.org/luci/logdog/client/butler/output.
	//
	// If nil, will use the 'null' logdog Output.
	LogdogOutput ldOutput.Output

	// Butler is VERY noisy at debug level, potentially amplifying client writes
	// by up to two orders of magnitude.
	//
	// If this is higher than the log level in the context, this will be applied
	// to the butler agent.
	ButlerLogLevel logging.Level

	// If set, enables logging at context level for the butler streamserver.
	// If unset (the default), logging in the butler streamserver is set to
	//   Warning.
	//
	// Streamsever logging is generally redundant with the butler logs at level
	// Info or Debug.
	StreamServerDisableLogAdjustment bool

	// ExeAuth describes the LUCI Auth environment to run the user code within.
	//
	// `Run` will manage the lifecycle of ExeAuth entirely.
	//
	// If nil, defaults to `DefaultExeAuth("luciexe", nil)`.
	//
	// It's recommended to use DefaultExeAuth() explicitly with reasonable values
	// for `id` and `knownGerritHosts`.
	ExeAuth *authctx.Context

	// The BaseDir becomes the root of this hosted luciexe session; All
	// directories (workdirs, tempdirs, etc.) are derived relative to this.
	//
	// If not provided, Run will pick a random directory under os.TempDir as the
	// value for BaseDir.
	//
	// The BaseDir (provided or picked) will be managed by Run; Prior to
	// execution, Run will ensure that the directory is empty by removing its
	// contents.
	BaseDir string

	// The CacheDir is the absolute path to the cache base directory.
	//
	// If not provided, Run will pick a directory under the BaseDir; Build may
	// override some of the cache directories by setting e.g.
	// Build.Infra.Buildbucket.Agent.CipdClientCache.
	CacheDir string

	// The base Build message to use as the template for all merged Build
	// messages.
	//
	// This will add logdog tags based on Build.Builder to all log streams.
	// e.g., "buildbucket.bucket"
	BaseBuild *bbpb.Build

	// If LeakBaseDir is true, Run will not try to remove BaseDir at the end if
	// it's execution.
	//
	// If BaseDir is not provided, this must be false.
	LeakBaseDir bool

	// The viewer URL for this hosted execution (if any). This will be used to
	// apply viewer.LogdogViewerURLTag to all logdog streams (the tag which is
	// used to implement the "Back to build" link in Milo).
	ViewerURL string

	// If DownloadAgentInputs is true, Run will check inputs for agent and ensure
	// them available in the working directory from cipd, cas or other sources.
	DownloadAgentInputs bool
	// contains filtered or unexported fields
}

Options is an optional struct which allows you to control how Run operates.