buildfarm.proto

syntax = "proto3";

package build.buildfarm.v1test;

import "google/api/annotations.proto";
import "build/bazel/remote/execution/v2/remote_execution.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

option go_package = "buildfarm";
option java_package = "build.buildfarm.v1test";
option java_multiple_files = true;
option java_outer_classname = "OperationQueueProto";

// The Admin API is used to perform administrative functions on Buildfarm infrastructure
service Admin {
  rpc TerminateHost(TerminateHostRequest) returns (google.rpc.Status) {
    option (google.api.http) = { get: "/v1test/admin:terminateHost" };
  }

  rpc StopContainer(StopContainerRequest) returns (google.rpc.Status) {
    option (google.api.http) = { get: "/v1test/admin:stopContainer" };
  }

  rpc GetHosts(GetHostsRequest) returns (GetHostsResult) {
    option (google.api.http) = { get: "/v1test/admin:getHosts" };
  }

  rpc GetClientStartTime(GetClientStartTimeRequest) returns (GetClientStartTimeResult) {
    option (google.api.http) = { get: "/v1test/admin:getClientStartTime" };
  }

  rpc ScaleCluster(ScaleClusterRequest) returns (google.rpc.Status) {
    option (google.api.http) = { get: "/v1test/admin:scaleCluster" };
  }
}

message TerminateHostRequest {
  string instance_name = 1;

  string host_id = 2;
}

message StopContainerRequest {
  string instance_name = 1;

  string host_id = 2;

  string container_name = 3;
}

message GetHostsRequest {
  string filter = 1;

  int32 age_in_minutes = 2;

  string status = 3;
}

message GetHostsResult {
  int64 num_hosts = 1;

  repeated Host hosts = 2;
}

message Host {
  int64 host_num = 1;

  string host_id = 2;

  string ip_address = 3;

  google.protobuf.Timestamp launch_time = 4;

  string state = 5;

  string dns_name = 6;

  int64 uptime_minutes = 7;

  int64 num_cores = 8;

  string type = 9;

  string lifecycle = 10;
}

message GetClientStartTimeRequest {
  string instance_name = 1;
  string client_key = 2;
}

message GetClientStartTimeResult {
  google.protobuf.Timestamp client_start_time = 1;
}

message ScaleClusterRequest {
  string scale_group_name = 1;

  int32 min_hosts = 2;

  int32 max_hosts = 3;

  int32 target_hosts = 4;

  int32 target_reserved_hosts_percent = 5;
}

// The OperationQueue API is used internally to communicate with Workers
service OperationQueue {
  rpc Take(TakeOperationRequest) returns (QueueEntry) {
    option (google.api.http) = { get: "/v1test/{instance_name=**}/operation:take" };
  }

  rpc Put(google.longrunning.Operation) returns (google.rpc.Status) {
    option (google.api.http) = { post: "/v1test/{instance_name=**}/operation:put" body: "*" };
  }

  rpc Poll(PollOperationRequest) returns (google.rpc.Status) {
    option (google.api.http) = { get: "/v1test/{instance_name=**}/operation:poll" };
  }

  rpc Status(OperationsStatusRequest) returns (OperationsStatus) {
    option (google.api.http) = { get: "/v1test/{instance_name=**}/operation:status" };
  }
}

message OperationsStatusRequest {
  string instance_name = 1;
}

message TakeOperationRequest {
  // The instance of the execution system to operate against. A server may
  // support multiple instances of the execution system (with their own workers,
  // storage, caches, etc.). The server MAY require use of this field to select
  // between them in an implementation-defined fashion, otherwise it can be
  // omitted.
  string instance_name = 1;

  // The platform features available for the execution environment. The server MAY
  // choose to execute the action on any worker satisfying the requirements, so
  // the client SHOULD ensure that running the action on any such worker will
  // have the same result.
  build.bazel.remote.execution.v2.Platform platform = 5;
}

message PollOperationRequest {
  // The operation name in question
  string operation_name = 2;

  // The current state of the worker
  build.bazel.remote.execution.v2.ExecutionStage.Value stage = 3;
}

message BuildFarmServerConfig {
  repeated InstanceConfig instances = 1;

  string default_instance_name = 2; // must be present in instances list or empty

  int32 port = 3;

  int32 execute_keepalive_after_seconds = 4;

  MetricsConfig metrics_config = 5;

  AdminConfig admin_config = 6;
}

message MetricsConfig {
  string metrics_destination = 1;

  string cluster_id = 2;

  oneof type {
    AwsMetricsConfig aws_metrics_config = 3;
    GcpMetricsConfig gcp_metrics_config = 4;
    LogMetricsConfig log_metrics_config = 5;
  }
}

message AwsMetricsConfig {
  string operations_metrics_topic = 1;

  int32 sns_client_max_connections = 2;

  string secret_name = 3;

  string region = 4;
}

message GcpMetricsConfig {
  string operations_metrics_topic = 1;
}

message LogMetricsConfig {
  string log_level = 1;
}

message AdminConfig {
  string deployment_environment = 1;

  oneof type {
    AwsAdminConfig aws_admin_config = 2;
    GcpAdminConfig gcp_admin_config = 3;
  }
}

message AwsAdminConfig {
  string region = 1;
}

message GcpAdminConfig {
}

message MemoryCASConfig {
  // limit for CAS total content size
  int64 max_size_bytes = 1;
}

message GrpcCASConfig {
  // CAS resources must contain instance names
  string instance_name = 1;

  // grpc endpoint supporting CAS/BS
  string target = 2;
}

message FilesystemCASConfig {
  // path to cached files from CAS
  // if relative, is made relative to root
  string path = 1;

  // limit for contents of files retained
  // from CAS in the cache
  int64 max_size_bytes = 2;

  // limit for contents of a single file retained
  // from CAS in the cache
  int64 max_entry_size_bytes = 3;
}

message FilesystemACConfig {
  // path to action cache files from AC
  string path = 1;
}

message FuseCASConfig {
  // used to identify the backing store
  string name = 1;
}

message ContentAddressableStorageConfig {
  oneof type {
    MemoryCASConfig memory = 1;
    GrpcCASConfig grpc = 2;
    FilesystemCASConfig filesystem = 3;
    FuseCASConfig fuse = 4;
  }
}

message DelegateCASConfig {
}

message GrpcACConfig {
  // AC requests can contain instance names
  string instance_name = 1;

  // grpc endpoint supporting AC
  string target = 2;
}

message ActionCacheConfig {
  oneof type {
    DelegateCASConfig delegate_cas = 1;
    FilesystemACConfig filesystem = 3;
    GrpcACConfig grpc = 2;
  }
}

message MemoryInstanceConfig {
  // the limits of the listOperations request
  int32 list_operations_default_page_size = 1;
  int32 list_operations_max_page_size = 2;

  // the limits of the getTree request
  int32 tree_default_page_size = 3;
  int32 tree_max_page_size = 4;

  // timeout after dispatch before which executing,
  // complete or an operation poll must be received, or
  // the operation is considered lost on a worker and is
  // requeued
  google.protobuf.Duration operation_poll_timeout = 5;

  // delay after timeout when executing before which
  // completed must be received, or the operation is
  // considered lost on a worker and is requeued
  google.protobuf.Duration operation_completed_delay = 6;

  // default timeout for actions
  // if a timeout is unspecified for an action, this value
  // is imposed on it, after which the operation will be
  // cancelled
  google.protobuf.Duration default_action_timeout = 7;

  // maximum selectable timeout
  // a maximum threshold for an action's specified timeout,
  // beyond which an action will be rejected for execution
  google.protobuf.Duration maximum_action_timeout = 8;

  ContentAddressableStorageConfig cas_config = 9;

  ActionCacheConfig action_cache_config = 10;
}

message ProvisionedQueue {
  string name = 1;
  
  build.bazel.remote.execution.v2.Platform platform = 2;
}

message ProvisionedQueuesConfig {
  repeated ProvisionedQueue queues = 1;
}

message RedisShardBackplaneConfig {
  string redis_uri = 1;
  int32 jedis_pool_max_total = 15;
  string workers_hash_name = 2;
  string worker_channel = 25;
  string action_cache_prefix = 3;
  int32 action_cache_expire = 4;
  string action_blacklist_prefix = 28;
  int32 action_blacklist_expire = 29;
  string invocation_blacklist_prefix = 30;
  string operation_prefix = 5;
  int32 operation_expire = 6;
  string pre_queued_operations_list_name = 18;
  string processing_list_name = 19;
  string processing_prefix = 20;
  int32 processing_timeout_millis = 21;
  string queued_operations_list_name = 7;
  string dispatching_list_name = 22;
  string dispatching_prefix = 23;
  int32 dispatching_timeout_millis = 24;
  string dispatched_operations_hash_name = 8;
  string operation_channel_prefix = 9;
  string cas_prefix = 10;
  int32 cas_expire = 11;
  bool subscribe_to_backplane = 26;
  bool run_failsafe_operation = 27;
  int32 max_queue_depth = 16;
  int32 max_pre_queue_depth = 17;
  ProvisionedQueuesConfig provisioned_queues = 31;
  int32 timeout = 32;
  int32 max_attempts = 33;
}

message ShardInstanceConfig {
  bool run_dispatched_monitor = 1;

  int32 dispatched_monitor_interval_seconds = 2;

  bool run_operation_queuer = 3;

  oneof backplane {
    RedisShardBackplaneConfig redis_shard_backplane_config = 4;
  }

  int64 max_blob_size = 5;

  // maximum selectable timeout
  // a maximum threshold for an action's specified timeout,
  // beyond which an action will be rejected for execution
  google.protobuf.Duration maximum_action_timeout = 7;
  
  // default timeouts on grpc requests made by instances
  google.protobuf.Duration grpc_timeout = 8;
}

message ShardWorkerInstanceConfig {
  // whether to stream stdout from processes
  bool stream_stdout = 6;

  // control for process stdout
  CASInsertionPolicy stdout_cas_policy = 7;

  // whether to stream stderr from processes
  bool stream_stderr = 8;

  // control for process stdout
  CASInsertionPolicy stderr_cas_policy = 9;

  // control for process output files
  CASInsertionPolicy file_cas_policy = 10;

  // page size for getTree request
  uint32 tree_page_size = 12;
  
  // default timeouts on grpc requests made by instances
  google.protobuf.Duration grpc_timeout = 13;
}

message ShardWorkerConfig {
  ShardWorkerInstanceConfig shard_worker_instance_config = 1;

  int32 port = 2;

  string public_name = 3;

  // base directory for all work being performed
  string root = 4;

  // the sequence of cas into which expirations cascade
  repeated ContentAddressableStorageConfig cas = 27;

  // period of poll requests during execution
  google.protobuf.Duration operation_poll_period = 13;

  // initial platform used to match operations
  build.bazel.remote.execution.v2.Platform platform = 14;

  // default platform to populate matched commands
  build.bazel.remote.execution.v2.Platform default_platform = 28;

  // total size of the inline content for
  // action results
  int32 inline_content_limit = 15;

  // input fetch width
  int32 input_fetch_stage_width = 26;

  // execute width
  int32 execute_stage_width = 16;

  // symlink cas input-only directories
  bool link_input_directories = 17;

  // selected hash function
  build.bazel.remote.execution.v2.DigestFunction.Value digest_function = 18;

  // default timeout for actions
  // if a timeout is unspecified for an action, this value
  // is imposed on it, after which the operation will
  // be killed
  google.protobuf.Duration default_action_timeout = 19;

  // maximum selectable timeout
  // a maximum threshold for an action's specified timeout,
  // beyond which an action will be rejected for execution
  google.protobuf.Duration maximum_action_timeout = 20;

  oneof backplane {
    RedisShardBackplaneConfig redis_shard_backplane_config = 21;
  }

  // available execution policies, will be used to match
  // with an action's platform for selection
  repeated ExecutionPolicy execution_policies = 25;

  // support any execution limiting, whether global or specified
  bool limit_execution = 31;

  // limit the available cores to execute_stage_width for unmetered execution if set
  bool limit_global_execution = 29;

  // only allow test executions to be multicore (min-cores > 1), limiting both to 1 if not a test
  bool only_multicore_tests = 30;

  // user principal name for executions
  string exec_owner = 32;
  
  // This determines whether the shard instance will participate in the backplane
  // and cache it's operation outputs in its own cache file CAS.
  // When omitted from CAS, the worker will send its output to another worker's CAS.
  bool omit_from_cas = 33;
}

message ShardWorker {
  string endpoint = 1;

  int64 expire_at = 2;
}

message WorkerChange {
  message Add {
  }

  message Remove {
    string source = 1;

    string reason = 2;
  }

  string name = 1;

  google.protobuf.Timestamp effectiveAt = 2;

  oneof type {
    Add add = 3;

    Remove remove = 4;
  }
}

message OperationChange {
  message Reset {
    google.protobuf.Timestamp expiresAt = 1;

    google.longrunning.Operation operation = 2;
  }

  message Expire {
    bool force = 1;
  }

  google.protobuf.Timestamp effectiveAt = 1;

  string source = 2;

  oneof type {
    Reset reset = 3;

    Expire expire = 4;
  }
}

message DispatchedOperation {
  QueueEntry queue_entry = 1;

  int64 requeue_at = 2;
}

message ProfiledQueuedOperationMetadata {
  QueuedOperation queued_operation = 1;

  QueuedOperationMetadata queued_operation_metadata = 2;

  google.protobuf.Duration transformed_in = 3;

  google.protobuf.Duration validated_in = 4;

  google.protobuf.Duration uploaded_in = 5;
}

message ExecuteEntry {
  string operation_name = 1;

  build.bazel.remote.execution.v2.Digest action_digest = 2;

  bool skip_cache_lookup = 3;

  build.bazel.remote.execution.v2.RequestMetadata request_metadata = 4;

  build.bazel.remote.execution.v2.ExecutionPolicy execution_policy = 5;

  build.bazel.remote.execution.v2.ResultsCachePolicy results_cache_policy = 6;

  string stdout_stream_name = 7;

  string stderr_stream_name = 8;

  google.protobuf.Timestamp queued_timestamp = 9;
}

message QueueEntry {
  ExecuteEntry execute_entry = 1;

  build.bazel.remote.execution.v2.Digest queued_operation_digest = 2;

  build.bazel.remote.execution.v2.Platform platform = 3;
}

message QueueStatus {
  int64 size = 1;

  repeated int64 internal_sizes = 2;
  
  string name = 3;
}

message OperationQueueStatus {
  repeated QueueStatus provisions = 1;
  
  int64 size = 2;
}

message OperationsStatus {
  QueueStatus prequeue = 1;

  OperationQueueStatus operation_queue = 2;

  int64 dispatched_size = 3;

  repeated string active_workers = 4;
}

message QueuedOperationMetadata {
  build.bazel.remote.execution.v2.ExecuteOperationMetadata execute_operation_metadata = 1;

  build.bazel.remote.execution.v2.Digest queued_operation_digest = 2;

  build.bazel.remote.execution.v2.RequestMetadata request_metadata = 3;
}

// A `Tree` contains all the
// [Directory][build.bazel.remote.execution.v2.Directory] protos in a
// single directory Merkle tree, compressed into one message, with a map
// to index the directories.
message Tree {
  // The digest of the root directory in the tree.
  build.bazel.remote.execution.v2.Digest rootDigest = 1;

  map<string, build.bazel.remote.execution.v2.Directory> directories = 2;
}

message QueuedOperation {
  build.bazel.remote.execution.v2.Action action = 1;

  build.bazel.remote.execution.v2.Command command = 2;

  build.bazel.remote.execution.v2.Tree legacy_tree = 4;

  Tree tree = 5;
}

message ExecutingOperationMetadata {
  build.bazel.remote.execution.v2.ExecuteOperationMetadata execute_operation_metadata = 1;

  build.bazel.remote.execution.v2.RequestMetadata request_metadata = 2;

  int64 started_at = 3;

  string executing_on = 4;
}

message CompletedOperationMetadata {
  build.bazel.remote.execution.v2.ExecuteOperationMetadata execute_operation_metadata = 1;

  build.bazel.remote.execution.v2.RequestMetadata request_metadata = 2;

  reserved 3 to 8; // fields now in ExecutedActionMetadata
}

message OperationRequestMetadata {
  string operation_name = 1;

  bool done = 2;

  build.bazel.remote.execution.v2.RequestMetadata request_metadata = 3;

  build.bazel.remote.execution.v2.ExecuteOperationMetadata execute_operation_metadata = 4;

  build.bazel.remote.execution.v2.ExecuteResponse execute_response = 5;

  string cluster_id = 6;
}

message InstanceConfig {
  string name = 1;

  build.bazel.remote.execution.v2.DigestFunction.Value digest_function = 2;

  oneof type {
    MemoryInstanceConfig memory_instance_config = 3;
    ShardInstanceConfig shard_instance_config = 4;
  }
}

enum CASInsertionPolicy {
  UNKNOWN = 0;

  ALWAYS_INSERT = 1;

  INSERT_ABOVE_LIMIT = 2;
};

message InstanceEndpoint {
  // target suitable for grpc channel creation: host:port is common
  string target = 1;

  // instance to be used
  string instance_name = 2;

  // deadline for requests in seconds
  int32 deadline_after_seconds = 3;
}

message ExecutionWrapper {
  string path = 1;

  repeated string arguments = 2;
}

// selectable controls for executions
// a universal policy can be specified with an empty name
message ExecutionPolicy {
  string name = 1;

  oneof policy {
    ExecutionWrapper wrapper = 2;
  }
}

message WorkerConfig {
  build.bazel.remote.execution.v2.DigestFunction.Value digest_function = 1;

  // endpoint for all cas requests
  InstanceEndpoint content_addressable_storage = 2;

  // endpoint for all action cache requests
  InstanceEndpoint action_cache = 3;

  // endpoint for all operation execution requests
  InstanceEndpoint operation_queue = 4;

  // base directory for all work being performed
  string root = 5;

  // path to cached files from CAS
  // if relative, is made relative to root
  string cas_cache_directory = 6;

  // limit for contents of files retained
  // from CAS in the cache
  int64 cas_cache_max_size_bytes = 7;

  // limit for contents of a single file retained
  // from CAS in the cache
  int64 cas_cache_max_entry_size_bytes = 24;

  // total size of the inline content for
  // action results
  int32 inline_content_limit = 8;

  // whether to stream stdout from processes
  bool stream_stdout = 9;

  // policy for process stdout
  CASInsertionPolicy stdout_cas_policy = 10;

  // whether to stream stderr from processes
  bool stream_stderr = 11;

  // policy for process stdout
  CASInsertionPolicy stderr_cas_policy = 12;

  // policy for process output files
  CASInsertionPolicy file_cas_policy = 13;

  reserved 14;

  // page size for getTree request
  uint32 tree_page_size = 15;

  // period of poll requests during execution
  google.protobuf.Duration operation_poll_period = 16;

  // initial platform used to match operations
  build.bazel.remote.execution.v2.Platform platform = 17;

  // default platform to populate matched commands
  build.bazel.remote.execution.v2.Platform default_platform = 25;

  // input fetch width
  int32 input_fetch_stage_width = 23;

  // execute width
  int32 execute_stage_width = 18;

  // symlink cas input-only directories
  bool link_input_directories = 19;

  // default timeout for actions
  // if a timeout is unspecified for an action, this value
  // is imposed on it, after which the operation will
  // be killed
  google.protobuf.Duration default_action_timeout = 20;

  // maximum selectable timeout
  // a maximum threshold for an action's specified timeout,
  // beyond which an action will be rejected for execution
  google.protobuf.Duration maximum_action_timeout = 21;

  // available execution policies, will be used to match
  // with an action's platform for selection
  repeated ExecutionPolicy execution_policies = 22;
}

message TreeIteratorToken {
  repeated build.bazel.remote.execution.v2.Digest directories = 1;
}

message OperationIteratorToken {
  string operation_name = 1;
}

message BlobWriteKey {
  build.bazel.remote.execution.v2.Digest digest = 1;

  string identifier = 2;
}

message OperationTimesBetweenStages {
  google.protobuf.Duration queued_to_match = 1;

  google.protobuf.Duration match_to_input_fetch_start = 2;

  google.protobuf.Duration input_fetch_start_to_complete = 3;

  google.protobuf.Duration input_fetch_complete_to_execution_start = 4;

  google.protobuf.Duration execution_start_to_complete = 5;

  google.protobuf.Duration execution_complete_to_output_upload_start = 6;

  google.protobuf.Duration output_upload_start_to_complete = 7;

  google.protobuf.Duration period = 8;

  int32 operation_count = 9;
}

message StageInformation {
  // name of the stage this message represent, i.e. InputFetchStage
  string name = 1;

  // number of slots configured for this stage
  int32 slots_configured = 2;

  // number of slots used for this stage
  int32 slots_used = 3;
}

message WorkerProfileMessage {
  // number of Entry in CAS
  int64 cas_entry_count = 1;

  // number of unreferenced Entry in CAS
  int64 cas_unreferenced_entry_count = 11;

  // number of DirectoryEntry in CAS
  int64 cas_directory_entry_count = 2;

  // number of evicted Entries since last profile request
  int32 cas_evicted_entry_count = 5;

  // the total size of evicted Entries since last profile request
  int64 cas_evicted_entry_size = 6;

  // used for removed fields representing composed used/configured slots
  reserved 7 to 8;

  repeated StageInformation stages = 9;

  repeated OperationTimesBetweenStages times = 10;
}

message WorkerProfileRequest {
}

service WorkerProfile {
  rpc GetWorkerProfile(WorkerProfileRequest) returns (WorkerProfileMessage) {}
}