invoke

type Options struct {
	// This should be in Build.Step.Name format, i.e. "parent|parent|leaf".
	//
	// Namespace is used as:
	//   * The Step name of the enclosing Build Step.
	//   * Generating the new LOGDOG_NAMESPACE in the environment for the
	//     subprocess. Non-StreamName characters are replaced with '_',
	//     and if the first character of a segment is not a character, "s_" is
	//     prpended. i.e. if the current LOGDOG_NAMESPACE is "u", and this
	//     namespace is "x|!!cool!!|z", then LOGDOG_NAMESPACE for the
	//     subprocess will be "u/x/s___cool__/z".
	//     * The LUCI Executable host process will assert that all logdog stream
	//       names mentioned in the subprocess's Build are relative to this.
	//   * The basis for the stdout/stderr Logdog streams for the subprocess.
	//   * The LUCI Executable host process will adjust the subprocess's step
	//     names to be relative to this. i.e. if the subprocess emits a step "a|b"
	//     and the Namespace is "x|y|z", then the step will show up as "x|y|z|a|b"
	//     on the overall Build.
	//
	// TODO(iannucci): Logdog stream names are restricted because they show up in
	// URLs on the logdog service. If the logdog service instead uses URL encoding
	// of the stream name, then StreamName could be expanded to allow all
	// characters except for "/". At some later point we could potentially change
	// the separator from "/" to "|" to match Buildbucket semantics.
	//
	// TODO(iannucci): Find a way to have logdog stream name namespacing be more
	// transparent (i.e. without needing explicit cooperation from the logdog
	// client library via LOGDOG_NAMESPACE envvar).
	//
	// Default: The Namespace is empty. This is ONLY useful when writing
	// a transparent wrapper for a luciexe which doesn't, itself, implement the
	// luciexe protocol. If Namespace is empty, then Subprocess.Step will be
	// `nil`.
	Namespace string

	// The base dir where all sub-directories (i.e. workdir, tempdir, etc.)
	// will be created under (i.e. the `cwd` for invoked luciexe will be
	// `$BaseDir/w`). If specified, this must exist and be a directory.
	//
	// If empty, a random directory under os.TempDir will be used.
	BaseDir string

	// Absolute path to the cache base directory. This must exist and be
	// a directory.
	//
	// Default: If LUCI_CONFIG['lucictx']['cache_dir'] is set, it will be passed
	// through unchanged. Otherwise a new empty directory is allocated which will
	// be destroyed on the subprocess's completion.
	CacheDir string

	// If set, the subprocess's final Build message will be collected and returned
	// from Wait.
	//
	// If CollectOutput is specified, but CollectOutputPath is not, a temporary
	// path will be seleceted and destroyed on the subprocess's completion.
	CollectOutput bool

	// If set, will be used as the path to output the subprocess's final Build
	// state. Must end with one of {'.pb', '.json', '.textpb'}. This must be
	// a path to a non-existent file (i.e. parent must be a directory).
	//
	// If CollectOutputPath is specified, but CollectOutput is not, the subprocess
	// will be instructed to dump the result to this path, but we won't attempt to
	// parse or validate it in any way, and Wait will return a nil `output`.
	CollectOutputPath string

	// A replacement environment for the Options.
	//
	// If this is not specified, the current process's environment is inherited.
	//
	// The following environment variables will be ignored from this `Env`:
	//   * LOGDOG_NAMESPACE
	//   * LUCI_CONTEXT
	Env environ.Env
}

type Subprocess struct {
	Step *bbpb.Step
	// contains filtered or unexported fields
}