recipe_proto/go/api/command/command.proto

// Copied from
// https://raw.githubusercontent.com/bazelbuild/remote-apis-sdks/master/go/api/command/command.proto

syntax = "proto3";

package cmd;

import "google/protobuf/timestamp.proto";

// A command to execute locally or remotely.
message Command {
  // Identifiers used to identify this command to be passed to RE.
  Identifiers identifiers = 1;

  // An absolute path to the execution root of the command. All the other paths
  // are specified relatively to this path.
  string exec_root = 2;

  // The command inputs.
  InputSpec input = 3;

  // The command outputs.
  OutputSpec output = 4;

  // Command line elements to execute.
  repeated string args = 5;

  // If > 0, the maximum number of seconds to wait for command execution
  // before timing out.
  int32 execution_timeout = 6;

  // 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 in the exec root.
  string working_directory = 7;

  // The platform to use for the remote execution.
  map<string, string> platform = 8;

  // 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
  string remote_working_directory = 9;
}

// Identifiers identifying a command that are passed to the remote server for
// logging.
message Identifiers {
  // An optional id to use to identify a command.
  string command_id = 1;

  // An optional id to use to identify an invocation.
  string invocation_id = 2;

  // An optional id to use to identify a build.
  string correlated_invocations_id = 3;

  // An optional tool name to pass to the remote server for logging.
  string tool_name = 4;

  // An optional tool version to pass to the remote server for logging.
  string tool_version = 5;

  // An optional ID identifying a particular execution of this command.
  string execution_id = 6;
}

message InputType {
  enum Value {
    // Any type will match.
    UNSPECIFIED = 0;
    // Only directories match.
    DIRECTORY = 1;
    // Only files match.
    FILE = 2;
  }
}

message ExcludeInput {
  // If an input matches this regular expression, ignore it.
  string regex = 1;
  // If an input path has this type, ignore it.
  InputType.Value type = 2;
}

// VirtualInput represents an input that does not actually exist on disk, but we
// want to stage it on disk for the command execution.
message VirtualInput {
  // The path for the input file to be staged at, relative to the ExecRoot.
  string path = 1;
  // The byte contents of the file to be staged.
  bytes contents = 2;
  // Whether the file should be staged as executable.
  bool is_executable = 3;
  // Whether the input is an empty directory.
  bool is_empty_directory = 4;
}

message SymlinkBehaviorType {
  enum Value {
    // Use Client.TreeSymlinkOpts or default if it is not set.
    UNSPECIFIED = 0;
    // Resolves symlinks.
    RESOLVE = 1;
    // Preserve symlinks as-is.
    PRESERVE = 2;
  }
}

message InputSpec {
  // Input paths (files or directories) that need to be uploaded to the remote
  // server for the command execution.
  // Note: a known limitation of the first version of the proxy is that for any
  // *directory* inputs, the contents of the directory will only be read once,
  // and then cached throughout the proxy lifetime. Any subsequent changes to
  // the directory will therefore not be captured.
  repeated string inputs = 2;

  // Virtual inputs that need to be staged as if they were present on disk.
  repeated VirtualInput virtual_inputs = 5;

  // Inputs matching these patterns will be excluded (not uploaded remotely).
  repeated ExcludeInput exclude_inputs = 3;

  // Environment variables the command relies on.
  map<string, string> environment_variables = 4;

  // Determines how symlinks should be treated when constructing the input tree.
  SymlinkBehaviorType.Value symlink_behavior = 6;
}

message OutputSpec {
  // Output files relative to working directory generated by the command.
  repeated string output_files = 1;

  // Output directories relative to working directory generated by the command.
  repeated string output_directories = 2;
}

message CommandResultStatus {
  enum Value {
    // Default case. Should not be used.
    UNKNOWN = 0;
    // Command executed successfully.
    SUCCESS = 1;
    // The command did not execute and a previously cached result was
    // retrieved.
    CACHE_HIT = 2;
    // The command executed with a non zero exit code.
    NON_ZERO_EXIT = 3;
    // The command timed out.
    TIMEOUT = 4;
    // The command was interrupted.
    INTERRUPTED = 5;
    // Execution of the command failed due to a remote execution error.
    REMOTE_ERROR = 6;
    // Execution of the command failed due to a local execution error.
    LOCAL_ERROR = 7;
  }
}

// Result of a command execution returned by the proxy.
message CommandResult {
  // Status of the finished run.
  CommandResultStatus.Value status = 1;

  // Command exit code.
  int32 exit_code = 2;

  // Optional exception trace or other message that should be displayed.
  string msg = 3;
}

// TimeInterval is used to serialize the SDK TimeInterval struct.
message TimeInterval {
  google.protobuf.Timestamp from = 1;
  google.protobuf.Timestamp to = 2;
}