Documentation ¶
Overview ¶
Package command defines common types to be used with command execution.
Index ¶
- Constants
- func NodePropertiesFromAPI(np *repb.NodeProperties) *cpb.NodeProperties
- func NodePropertiesToAPI(np *cpb.NodeProperties) *repb.NodeProperties
- func ResultToProto(res *Result) *cpb.CommandResult
- func TimeFromProto(tPb *tspb.Timestamp) time.Time
- func TimeIntervalToProto(t *TimeInterval) *cpb.TimeInterval
- func TimeToProto(t time.Time) *tspb.Timestamp
- func ToProto(cmd *Command) *cpb.Command
- type Command
- type ExecutionOptions
- type Identifiers
- type InputExclusion
- type InputSpec
- type InputType
- type Metadata
- type Result
- type ResultStatus
- type SymlinkBehaviorType
- type TimeInterval
- type VirtualInput
Constants ¶
const ( // EventServerQueued: Queued time on the remote server. EventServerQueued = "ServerQueued" // EventServerWorker: The total remote worker (bot) time. EventServerWorker = "ServerWorker" // EventServerWorkerInputFetch: Time to fetch inputs to the remote bot. EventServerWorkerInputFetch = "ServerWorkerInputFetch" // EventServerWorkerExecution: The actual execution on the remote bot. EventServerWorkerExecution = "ServerWorkerExecution" // EventServerWorkerOutputUpload: Uploading outputs to the CAS on the bot. EventServerWorkerOutputUpload = "ServerWorkerOutputUpload" // EventDownloadResults: Downloading action results from CAS. EventDownloadResults = "DownloadResults" // EventComputeMerkleTree: Computing the input Merkle tree. EventComputeMerkleTree = "ComputeMerkleTree" // EventCheckActionCache: Checking the action cache. EventCheckActionCache = "CheckActionCache" // EventUpdateCachedResult: Uploading local outputs to CAS and updating cached // action result. EventUpdateCachedResult = "UpdateCachedResult" // EventUploadInputs: Uploading action inputs to CAS for remote execution. EventUploadInputs = "UploadInputs" // EventExecuteRemotely: Total time to execute remotely. EventExecuteRemotely = "ExecuteRemotely" )
These are the events that we export time metrics on:
const InterruptedExitCode = 8
InterruptedExitCode is an exit code corresponding to an execution interruption by the user.
const LocalErrorExitCode = 35
LocalErrorExitCode is an exit code corresponding to a local error.
const RemoteErrorExitCode = 45
RemoteErrorExitCode is an exit code corresponding to a remote server error.
const TimeoutExitCode = 128 + 14
TimeoutExitCode is an exit code corresponding to the command timing out remotely.
Variables ¶
This section is empty.
Functions ¶
func NodePropertiesFromAPI ¶
func NodePropertiesFromAPI(np *repb.NodeProperties) *cpb.NodeProperties
func NodePropertiesToAPI ¶
func NodePropertiesToAPI(np *cpb.NodeProperties) *repb.NodeProperties
func ResultToProto ¶
func ResultToProto(res *Result) *cpb.CommandResult
ResultToProto serializes a command.Result struct into a proto message.
func TimeFromProto ¶
TimeFromProto converts a valid Timestamp proto into a time.Time.
func TimeIntervalToProto ¶
func TimeIntervalToProto(t *TimeInterval) *cpb.TimeInterval
TimeIntervalToProto serializes the SDK TimeInterval into a proto.
func TimeToProto ¶
TimeToProto converts a valid time.Time into a proto Timestamp.
Types ¶
type Command ¶
type Command struct { // Identifiers used to identify this command to be passed to RE. Identifiers *Identifiers // Args (required): command line elements to execute. Args []string // ExecRoot is an absolute path to the execution root of the command. All the other paths are // specified relatively to this path. ExecRoot string // WorkingDir is the working directory, relative to the exec root, for the command to run // in. It must be a directory which exists in the input tree. If it is left empty, then the // action is run from the exec root. WorkingDir string // RemoteWorkingDir is the working directory when executing the command on RE server. // It's relative to exec root and, if provided, needs to have the same number of levels // as WorkingDir. If not provided, the remote command is run from the WorkingDir RemoteWorkingDir string // InputSpec: the command inputs. InputSpec *InputSpec // OutputFiles are the command output files. OutputFiles []string // OutputDirs are the command output directories. // The files and directories will likely be merged into a single Outputs field in the future. OutputDirs []string // Timeout is an optional duration to wait for command execution before timing out. Timeout time.Duration // Platform is the platform to use for the execution. Platform map[string]string }
Command encompasses the complete information required to execute a command remotely. To make sure to initialize a valid Command object, call FillDefaultFieldValues on the created struct.
func FromREProto ¶
func (*Command) FillDefaultFieldValues ¶
func (c *Command) FillDefaultFieldValues()
FillDefaultFieldValues initializes valid default values to inner Command fields. This function should be called on every new Command object before use.
type ExecutionOptions ¶
type ExecutionOptions struct { // Whether to accept cached action results. Defaults to true. AcceptCached bool // When set, this execution results will not be cached. DoNotCache bool // Download command outputs after execution. Defaults to true. DownloadOutputs bool // Preserve mtimes for unchanged outputs when downloading. Defaults to false. PreserveUnchangedOutputMtime bool // Download command stdout and stderr. Defaults to true. If StreamOutErr is also set, this value // is ignored for uncached actions if the server provides log streams for both stdout and stderr. // For cached action results, or if the server does not provide log streams for stdout or stderr, // this value will determine whether stdout and stderr is downloaded. DownloadOutErr bool // Request that stdout and stderr be streamed back to the client while the action is running. // Defaults to false. If either stream is not provided by the server, the client will fall back to // downloading the corresponding streams after the action has completed, provided DownloadOutErr // is also set. The client may expect a delay in this scenario as the streams are downloaded after // the fact. StreamOutErr bool }
ExecutionOptions specify how to execute a given Command.
func DefaultExecutionOptions ¶
func DefaultExecutionOptions() *ExecutionOptions
DefaultExecutionOptions returns the recommended ExecutionOptions.
type Identifiers ¶
type Identifiers struct { // CommandID is an optional id to use to identify a command. CommandID string // InvocationID is an optional id to use to identify an invocation spanning multiple commands. InvocationID string CorrelatedInvocationID string // ToolName is an optional tool name to pass to the remote server for logging. ToolName string // ToolVersion is an optional tool version to pass to the remote server for logging. ToolVersion string // ExecutionID is a UUID generated for a particular execution of this command. ExecutionID string }
Identifiers is a group of identifiers of a command.
type InputExclusion ¶
type InputExclusion struct { // Required: the path regular expression to match for exclusion. Regex string // The input type to match for exclusion. Type InputType }
InputExclusion represents inputs to be excluded from being considered for command execution.
func (*InputExclusion) String ¶
func (s *InputExclusion) String() string
String returns the string representation of the InputExclusion.
type InputSpec ¶
type InputSpec struct { // Input paths (files or directories) that need to be present for the command execution. Inputs []string // Inputs not present on the local file system, but should be staged for command execution. VirtualInputs []*VirtualInput // Inputs matching these patterns will be excluded. InputExclusions []*InputExclusion // Environment variables the command relies on. EnvironmentVariables map[string]string // SymlinkBehavior represents the way symlinks will be handled. SymlinkBehavior SymlinkBehaviorType // Node properties of inputs. InputNodeProperties map[string]*cpb.NodeProperties }
InputSpec represents all the required inputs to a remote command.
type InputType ¶
type InputType int
InputType can be specified to narrow down the matching for a given input path.
type Metadata ¶
type Metadata struct { // CommandDigest is a digest of the command being executed. It can be used // to detect changes in the command between builds. CommandDigest digest.Digest // ActionDigest is a digest of the action being executed. It can be used // to detect changes in the action between builds. ActionDigest digest.Digest // The total number of input files. InputFiles int // The total number of input directories. InputDirectories int // The overall number of bytes from all the inputs. TotalInputBytes int64 // Event times for remote events, by event name. EventTimes map[string]*TimeInterval // The total number of output files (incl symlinks). OutputFiles int // The total number of output directories (incl symlinks, but not recursive). OutputDirectories int // The overall number of bytes from all the output files (incl. stdout/stderr, but not symlinks). TotalOutputBytes int64 // Output File digests. OutputFileDigests map[string]digest.Digest // Output Directory digests. OutputDirectoryDigests map[string]digest.Digest // Output Symlinks. OutputSymlinks map[string]string // Missing digests that are uploaded to CAS. MissingDigests []digest.Digest // LogicalBytesUploaded is the sum of sizes in bytes of the blobs that were uploaded. It should be // the same value as the sum of digest sizes in MissingDigests. LogicalBytesUploaded int64 // RealBytesUploaded is the number of bytes that were put on the wire for upload (exclusing metadata). // It may differ from LogicalBytesUploaded due to compression. RealBytesUploaded int64 // LogicalBytesDownloaded is the sum of sizes in bytes of the blobs that were downloaded. It should be // the same value as the sum of digest sizes in OutputDigests. LogicalBytesDownloaded int64 // RealBytesDownloaded is the number of bytes that were put on the wire for download (exclusing metadata). // It may differ from LogicalBytesDownloaded due to compression. RealBytesDownloaded int64 // StderrDigest is a digest of the standard error after being executed. StderrDigest digest.Digest // StdoutDigest is a digest of the standard output after being executed. StdoutDigest digest.Digest }
Metadata is general information associated with a Command execution.
type Result ¶
type Result struct { // Command exit code. ExitCode int // Status of the finished run. Status ResultStatus // Any error encountered. Err error }
Result is the result of a finished command execution.
func NewLocalErrorResult ¶
NewLocalErrorResult constructs a Result from a local error.
func NewRemoteErrorResult ¶
NewRemoteErrorResult constructs a Result from a remote error.
func NewResultFromExitCode ¶
NewResultFromExitCode constructs a Result from a given command exit code.
func NewTimeoutResult ¶
func NewTimeoutResult() *Result
NewTimeoutResult constructs a new result for a timeout-exceeded command.
func ResultFromProto ¶
func ResultFromProto(res *cpb.CommandResult) *Result
ResultFromProto parses a command.Result struct from a proto message.
type ResultStatus ¶
type ResultStatus int
ResultStatus represents the options for a finished command execution.
const ( // UnspecifiedResultStatus is an invalid value, should not be used. UnspecifiedResultStatus ResultStatus = iota // SuccessResultStatus indicates that the command executed successfully. SuccessResultStatus // CacheHitResultStatus indicates that the command was a cache hit. CacheHitResultStatus // NonZeroExitResultStatus indicates that the command executed with a non zero exit code. NonZeroExitResultStatus // TimeoutResultStatus indicates that the command exceeded its specified deadline. TimeoutResultStatus // InterruptedResultStatus indicates that the command execution was interrupted. InterruptedResultStatus // RemoteErrorResultStatus indicates that an error occurred on the remote server. RemoteErrorResultStatus // LocalErrorResultStatus indicates that an error occurred locally. LocalErrorResultStatus )
func (ResultStatus) IsOk ¶
func (s ResultStatus) IsOk() bool
IsOk returns whether the status indicates a successful action.
func (ResultStatus) String ¶
func (s ResultStatus) String() string
type SymlinkBehaviorType ¶
type SymlinkBehaviorType int
SymlinkBehaviorType represents how symlinks are handled.
const ( // UnspecifiedSymlinkBehavior means following clients.TreeSymlinkOpts // or DefaultTreeSymlinkOpts if clients.TreeSymlinkOpts is null. UnspecifiedSymlinkBehavior SymlinkBehaviorType = iota // ResolveSymlink means symlinks are resolved. ResolveSymlink // PreserveSymlink means symlinks are kept as-is. PreserveSymlink )
func (SymlinkBehaviorType) String ¶
func (s SymlinkBehaviorType) String() string
type TimeInterval ¶
TimeInterval is a time window for an event.
func TimeIntervalFromProto ¶
func TimeIntervalFromProto(t *cpb.TimeInterval) *TimeInterval
TimeIntervalFromProto parses the SDK TimeInterval from a proto.
type VirtualInput ¶
type VirtualInput struct { // The path for the input to be staged at, relative to the ExecRoot. Path string // The byte contents of the file to be staged. Contents []byte // Whether the file should be staged as executable. IsExecutable bool // Whether the file is actually an empty directory. This is used to provide // empty directory inputs. When this is set, Contents and IsExecutable are // ignored. IsEmptyDirectory bool }
VirtualInput represents an input that does not actually exist on disk, but we want to stage it on disk for the command execution.
func (*VirtualInput) String ¶
func (s *VirtualInput) String() string
String returns the string representation of the VirtualInput.