1// Copyright 2018 The Bazel Authors. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package build.bazel.remote.execution.v2; 18 19import "build/bazel/semver/semver.proto"; 20import "google/api/annotations.proto"; 21import "google/longrunning/operations.proto"; 22import "google/protobuf/duration.proto"; 23import "google/protobuf/timestamp.proto"; 24import "google/rpc/status.proto"; 25 26option csharp_namespace = "Build.Bazel.Remote.Execution.V2"; 27option go_package = "remoteexecution"; 28option java_multiple_files = true; 29option java_outer_classname = "RemoteExecutionProto"; 30option java_package = "build.bazel.remote.execution.v2"; 31option objc_class_prefix = "REX"; 32 33 34// The Remote Execution API is used to execute an 35// [Action][build.bazel.remote.execution.v2.Action] on the remote 36// workers. 37// 38// As with other services in the Remote Execution API, any call may return an 39// error with a [RetryInfo][google.rpc.RetryInfo] error detail providing 40// information about when the client should retry the request; clients SHOULD 41// respect the information provided. 42service Execution { 43 // Execute an action remotely. 44 // 45 // In order to execute an action, the client must first upload all of the 46 // inputs, the 47 // [Command][build.bazel.remote.execution.v2.Command] to run, and the 48 // [Action][build.bazel.remote.execution.v2.Action] into the 49 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 50 // It then calls `Execute` with an `action_digest` referring to them. The 51 // server will run the action and eventually return the result. 52 // 53 // The input `Action`'s fields MUST meet the various canonicalization 54 // requirements specified in the documentation for their types so that it has 55 // the same digest as other logically equivalent `Action`s. The server MAY 56 // enforce the requirements and return errors if a non-canonical input is 57 // received. It MAY also proceed without verifying some or all of the 58 // requirements, such as for performance reasons. If the server does not 59 // verify the requirement, then it will treat the `Action` as distinct from 60 // another logically equivalent action if they hash differently. 61 // 62 // Returns a stream of 63 // [google.longrunning.Operation][google.longrunning.Operation] messages 64 // describing the resulting execution, with eventual `response` 65 // [ExecuteResponse][build.bazel.remote.execution.v2.ExecuteResponse]. The 66 // `metadata` on the operation is of type 67 // [ExecuteOperationMetadata][build.bazel.remote.execution.v2.ExecuteOperationMetadata]. 68 // 69 // If the client remains connected after the first response is returned after 70 // the server, then updates are streamed as if the client had called 71 // [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution] 72 // until the execution completes or the request reaches an error. The 73 // operation can also be queried using [Operations 74 // API][google.longrunning.Operations.GetOperation]. 75 // 76 // The server NEED NOT implement other methods or functionality of the 77 // Operations API. 78 // 79 // Errors discovered during creation of the `Operation` will be reported 80 // as gRPC Status errors, while errors that occurred while running the 81 // action will be reported in the `status` field of the `ExecuteResponse`. The 82 // server MUST NOT set the `error` field of the `Operation` proto. 83 // The possible errors include: 84 // * `INVALID_ARGUMENT`: One or more arguments are invalid. 85 // * `FAILED_PRECONDITION`: One or more errors occurred in setting up the 86 // action requested, such as a missing input or command or no worker being 87 // available. The client may be able to fix the errors and retry. 88 // * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run 89 // the action. 90 // * `UNAVAILABLE`: Due to a transient condition, such as all workers being 91 // occupied (and the server does not support a queue), the action could not 92 // be started. The client should retry. 93 // * `INTERNAL`: An internal error occurred in the execution engine or the 94 // worker. 95 // * `DEADLINE_EXCEEDED`: The execution timed out. 96 // 97 // In the case of a missing input or command, the server SHOULD additionally 98 // send a [PreconditionFailure][google.rpc.PreconditionFailure] error detail 99 // where, for each requested blob not present in the CAS, there is a 100 // `Violation` with a `type` of `MISSING` and a `subject` of 101 // `"blobs/{hash}/{size}"` indicating the digest of the missing blob. 102 rpc Execute(ExecuteRequest) returns (stream google.longrunning.Operation) { 103 option (google.api.http) = { post: "/v2/{instance_name=**}/actions:execute" body: "*" }; 104 } 105 106 // Wait for an execution operation to complete. When the client initially 107 // makes the request, the server immediately responds with the current status 108 // of the execution. The server will leave the request stream open until the 109 // operation completes, and then respond with the completed operation. The 110 // server MAY choose to stream additional updates as execution progresses, 111 // such as to provide an update as to the state of the execution. 112 rpc WaitExecution(WaitExecutionRequest) returns (stream google.longrunning.Operation) { 113 option (google.api.http) = { post: "/v2/{name=operations/**}:waitExecution" body: "*" }; 114 } 115} 116 117// The action cache API is used to query whether a given action has already been 118// performed and, if so, retrieve its result. Unlike the 119// [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage], 120// which addresses blobs by their own content, the action cache addresses the 121// [ActionResult][build.bazel.remote.execution.v2.ActionResult] by a 122// digest of the encoded [Action][build.bazel.remote.execution.v2.Action] 123// which produced them. 124// 125// The lifetime of entries in the action cache is implementation-specific, but 126// the server SHOULD assume that more recently used entries are more likely to 127// be used again. Additionally, action cache implementations SHOULD ensure that 128// any blobs referenced in the 129// [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] 130// are still valid when returning a result. 131// 132// As with other services in the Remote Execution API, any call may return an 133// error with a [RetryInfo][google.rpc.RetryInfo] error detail providing 134// information about when the client should retry the request; clients SHOULD 135// respect the information provided. 136service ActionCache { 137 // Retrieve a cached execution result. 138 // 139 // Errors: 140 // * `NOT_FOUND`: The requested `ActionResult` is not in the cache. 141 rpc GetActionResult(GetActionResultRequest) returns (ActionResult) { 142 option (google.api.http) = { get: "/v2/{instance_name=**}/actionResults/{action_digest.hash}/{action_digest.size_bytes}" }; 143 } 144 145 // Upload a new execution result. 146 // 147 // This method is intended for servers which implement the distributed cache 148 // independently of the 149 // [Execution][build.bazel.remote.execution.v2.Execution] API. As a 150 // result, it is OPTIONAL for servers to implement. 151 // 152 // In order to allow the server to perform access control based on the type of 153 // action, and to assist with client debugging, the client MUST first upload 154 // the [Action][build.bazel.remote.execution.v2.Execution] that produced the 155 // result, along with its 156 // [Command][build.bazel.remote.execution.v2.Command], into the 157 // `ContentAddressableStorage`. 158 // 159 // Errors: 160 // * `NOT_IMPLEMENTED`: This method is not supported by the server. 161 // * `RESOURCE_EXHAUSTED`: There is insufficient storage space to add the 162 // entry to the cache. 163 rpc UpdateActionResult(UpdateActionResultRequest) returns (ActionResult) { 164 option (google.api.http) = { put: "/v2/{instance_name=**}/actionResults/{action_digest.hash}/{action_digest.size_bytes}" body: "action_result" }; 165 } 166} 167 168// The CAS (content-addressable storage) is used to store the inputs to and 169// outputs from the execution service. Each piece of content is addressed by the 170// digest of its binary data. 171// 172// Most of the binary data stored in the CAS is opaque to the execution engine, 173// and is only used as a communication medium. In order to build an 174// [Action][build.bazel.remote.execution.v2.Action], 175// however, the client will need to also upload the 176// [Command][build.bazel.remote.execution.v2.Command] and input root 177// [Directory][build.bazel.remote.execution.v2.Directory] for the Action. 178// The Command and Directory messages must be marshalled to wire format and then 179// uploaded under the hash as with any other piece of content. In practice, the 180// input root directory is likely to refer to other Directories in its 181// hierarchy, which must also each be uploaded on their own. 182// 183// For small file uploads the client should group them together and call 184// [BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs] 185// on chunks of no more than 10 MiB. For large uploads, the client must use the 186// [Write method][google.bytestream.ByteStream.Write] of the ByteStream API. The 187// `resource_name` is `{instance_name}/uploads/{uuid}/blobs/{hash}/{size}`, 188// where `instance_name` is as described in the next paragraph, `uuid` is a 189// version 4 UUID generated by the client, and `hash` and `size` are the 190// [Digest][build.bazel.remote.execution.v2.Digest] of the blob. The 191// `uuid` is used only to avoid collisions when multiple clients try to upload 192// the same file (or the same client tries to upload the file multiple times at 193// once on different threads), so the client MAY reuse the `uuid` for uploading 194// different blobs. The `resource_name` may optionally have a trailing filename 195// (or other metadata) for a client to use if it is storing URLs, as in 196// `{instance}/uploads/{uuid}/blobs/{hash}/{size}/foo/bar/baz.cc`. Anything 197// after the `size` is ignored. 198// 199// A single server MAY support multiple instances of the execution system, each 200// with their own workers, storage, cache, etc. The exact relationship between 201// instances is up to the server. If the server does, then the `instance_name` 202// is an identifier, possibly containing multiple path segments, used to 203// distinguish between the various instances on the server, in a manner defined 204// by the server. For servers which do not support multiple instances, then the 205// `instance_name` is the empty path and the leading slash is omitted, so that 206// the `resource_name` becomes `uploads/{uuid}/blobs/{hash}/{size}`. 207// 208// When attempting an upload, if another client has already completed the upload 209// (which may occur in the middle of a single upload if another client uploads 210// the same blob concurrently), the request will terminate immediately with 211// a response whose `committed_size` is the full size of the uploaded file 212// (regardless of how much data was transmitted by the client). If the client 213// completes the upload but the 214// [Digest][build.bazel.remote.execution.v2.Digest] does not match, an 215// `INVALID_ARGUMENT` error will be returned. In either case, the client should 216// not attempt to retry the upload. 217// 218// For downloading blobs, the client must use the 219// [Read method][google.bytestream.ByteStream.Read] of the ByteStream API, with 220// a `resource_name` of `"{instance_name}/blobs/{hash}/{size}"`, where 221// `instance_name` is the instance name (see above), and `hash` and `size` are 222// the [Digest][build.bazel.remote.execution.v2.Digest] of the blob. 223// 224// The lifetime of entries in the CAS is implementation specific, but it SHOULD 225// be long enough to allow for newly-added and recently looked-up entries to be 226// used in subsequent calls (e.g. to 227// [Execute][build.bazel.remote.execution.v2.Execution.Execute]). 228// 229// As with other services in the Remote Execution API, any call may return an 230// error with a [RetryInfo][google.rpc.RetryInfo] error detail providing 231// information about when the client should retry the request; clients SHOULD 232// respect the information provided. 233service ContentAddressableStorage { 234 // Determine if blobs are present in the CAS. 235 // 236 // Clients can use this API before uploading blobs to determine which ones are 237 // already present in the CAS and do not need to be uploaded again. 238 // 239 // There are no method-specific errors. 240 rpc FindMissingBlobs(FindMissingBlobsRequest) returns (FindMissingBlobsResponse) { 241 option (google.api.http) = { post: "/v2/{instance_name=**}/blobs:findMissing" body: "*" }; 242 } 243 244 // Upload many blobs at once. 245 // 246 // The server may enforce a limit of the combined total size of blobs 247 // to be uploaded using this API. This limit may be obtained using the 248 // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. 249 // Requests exceeding the limit should either be split into smaller 250 // chunks or uploaded using the 251 // [ByteStream API][google.bytestream.ByteStream], as appropriate. 252 // 253 // This request is equivalent to calling a Bytestream `Write` request 254 // on each individual blob, in parallel. The requests may succeed or fail 255 // independently. 256 // 257 // Errors: 258 // * `INVALID_ARGUMENT`: The client attempted to upload more than the 259 // server supported limit. 260 // 261 // Individual requests may return the following errors, additionally: 262 // * `RESOURCE_EXHAUSTED`: There is insufficient disk quota to store the blob. 263 // * `INVALID_ARGUMENT`: The 264 // [Digest][build.bazel.remote.execution.v2.Digest] does not match the 265 // provided data. 266 rpc BatchUpdateBlobs(BatchUpdateBlobsRequest) returns (BatchUpdateBlobsResponse) { 267 option (google.api.http) = { post: "/v2/{instance_name=**}/blobs:batchUpdate" body: "*" }; 268 } 269 270 // Download many blobs at once. 271 // 272 // The server may enforce a limit of the combined total size of blobs 273 // to be downloaded using this API. This limit may be obtained using the 274 // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. 275 // Requests exceeding the limit should either be split into smaller 276 // chunks or downloaded using the 277 // [ByteStream API][google.bytestream.ByteStream], as appropriate. 278 // 279 // This request is equivalent to calling a Bytestream `Read` request 280 // on each individual blob, in parallel. The requests may succeed or fail 281 // independently. 282 // 283 // Errors: 284 // * `INVALID_ARGUMENT`: The client attempted to read more than the 285 // server supported limit. 286 // 287 // Every error on individual read will be returned in the corresponding digest 288 // status. 289 rpc BatchReadBlobs(BatchReadBlobsRequest) returns (BatchReadBlobsResponse) { 290 option (google.api.http) = { post: "/v2/{instance_name=**}/blobs:batchRead" body: "*" }; 291 } 292 293 // Fetch the entire directory tree rooted at a node. 294 // 295 // This request must be targeted at a 296 // [Directory][build.bazel.remote.execution.v2.Directory] stored in the 297 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] 298 // (CAS). The server will enumerate the `Directory` tree recursively and 299 // return every node descended from the root. 300 // 301 // The GetTreeRequest.page_token parameter can be used to skip ahead in 302 // the stream (e.g. when retrying a partially completed and aborted request), 303 // by setting it to a value taken from GetTreeResponse.next_page_token of the 304 // last successfully processed GetTreeResponse). 305 // 306 // The exact traversal order is unspecified and, unless retrieving subsequent 307 // pages from an earlier request, is not guaranteed to be stable across 308 // multiple invocations of `GetTree`. 309 // 310 // If part of the tree is missing from the CAS, the server will return the 311 // portion present and omit the rest. 312 // 313 // * `NOT_FOUND`: The requested tree root is not present in the CAS. 314 rpc GetTree(GetTreeRequest) returns (stream GetTreeResponse) { 315 option (google.api.http) = { get: "/v2/{instance_name=**}/blobs/{root_digest.hash}/{root_digest.size_bytes}:getTree" }; 316 } 317} 318 319// The Capabilities service may be used by remote execution clients to query 320// various server properties, in order to self-configure or return meaningful 321// error messages. 322// 323// The query may include a particular `instance_name`, in which case the values 324// returned will pertain to that instance. 325service Capabilities { 326 // GetCapabilities returns the server capabilities configuration. 327 rpc GetCapabilities(GetCapabilitiesRequest) returns (ServerCapabilities) { 328 option (google.api.http) = { 329 get: "/v2/{instance_name=**}/capabilities" 330 }; 331 } 332} 333 334// An `Action` captures all the information about an execution which is required 335// to reproduce it. 336// 337// `Action`s are the core component of the [Execution] service. A single 338// `Action` represents a repeatable action that can be performed by the 339// execution service. `Action`s can be succinctly identified by the digest of 340// their wire format encoding and, once an `Action` has been executed, will be 341// cached in the action cache. Future requests can then use the cached result 342// rather than needing to run afresh. 343// 344// When a server completes execution of an 345// [Action][build.bazel.remote.execution.v2.Action], it MAY choose to 346// cache the [result][build.bazel.remote.execution.v2.ActionResult] in 347// the [ActionCache][build.bazel.remote.execution.v2.ActionCache] unless 348// `do_not_cache` is `true`. Clients SHOULD expect the server to do so. By 349// default, future calls to 350// [Execute][build.bazel.remote.execution.v2.Execution.Execute] the same 351// `Action` will also serve their results from the cache. Clients must take care 352// to understand the caching behaviour. Ideally, all `Action`s will be 353// reproducible so that serving a result from cache is always desirable and 354// correct. 355message Action { 356 // The digest of the [Command][build.bazel.remote.execution.v2.Command] 357 // to run, which MUST be present in the 358 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 359 Digest command_digest = 1; 360 361 // The digest of the root 362 // [Directory][build.bazel.remote.execution.v2.Directory] for the input 363 // files. The files in the directory tree are available in the correct 364 // location on the build machine before the command is executed. The root 365 // directory, as well as every subdirectory and content blob referred to, MUST 366 // be in the 367 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 368 Digest input_root_digest = 2; 369 370 reserved 3 to 5; // Used for fields moved to [Command][build.bazel.remote.execution.v2.Command]. 371 372 // A timeout after which the execution should be killed. If the timeout is 373 // absent, then the client is specifying that the execution should continue 374 // as long as the server will let it. The server SHOULD impose a timeout if 375 // the client does not specify one, however, if the client does specify a 376 // timeout that is longer than the server's maximum timeout, the server MUST 377 // reject the request. 378 // 379 // The timeout is a part of the 380 // [Action][build.bazel.remote.execution.v2.Action] message, and 381 // therefore two `Actions` with different timeouts are different, even if they 382 // are otherwise identical. This is because, if they were not, running an 383 // `Action` with a lower timeout than is required might result in a cache hit 384 // from an execution run with a longer timeout, hiding the fact that the 385 // timeout is too short. By encoding it directly in the `Action`, a lower 386 // timeout will result in a cache miss and the execution timeout will fail 387 // immediately, rather than whenever the cache entry gets evicted. 388 google.protobuf.Duration timeout = 6; 389 390 // If true, then the `Action`'s result cannot be cached. 391 bool do_not_cache = 7; 392} 393 394// A `Command` is the actual command executed by a worker running an 395// [Action][build.bazel.remote.execution.v2.Action] and specifications of its 396// environment. 397// 398// Except as otherwise required, the environment (such as which system 399// libraries or binaries are available, and what filesystems are mounted where) 400// is defined by and specific to the implementation of the remote execution API. 401message Command { 402 // An `EnvironmentVariable` is one variable to set in the running program's 403 // environment. 404 message EnvironmentVariable { 405 // The variable name. 406 string name = 1; 407 408 // The variable value. 409 string value = 2; 410 } 411 412 // The arguments to the command. The first argument must be the path to the 413 // executable, which must be either a relative path, in which case it is 414 // evaluated with respect to the input root, or an absolute path. 415 repeated string arguments = 1; 416 417 // The environment variables to set when running the program. The worker may 418 // provide its own default environment variables; these defaults can be 419 // overridden using this field. Additional variables can also be specified. 420 // 421 // In order to ensure that equivalent `Command`s always hash to the same 422 // value, the environment variables MUST be lexicographically sorted by name. 423 // Sorting of strings is done by code point, equivalently, by the UTF-8 bytes. 424 repeated EnvironmentVariable environment_variables = 2; 425 426 // A list of the output files that the client expects to retrieve from the 427 // action. Only the listed files, as well as directories listed in 428 // `output_directories`, will be returned to the client as output. 429 // Other files that may be created during command execution are discarded. 430 // 431 // The paths are relative to the working directory of the action execution. 432 // The paths are specified using a single forward slash (`/`) as a path 433 // separator, even if the execution platform natively uses a different 434 // separator. The path MUST NOT include a trailing slash, nor a leading slash, 435 // being a relative path. 436 // 437 // In order to ensure consistent hashing of the same Action, the output paths 438 // MUST be sorted lexicographically by code point (or, equivalently, by UTF-8 439 // bytes). 440 // 441 // An output file cannot be duplicated, be a parent of another output file, be 442 // a child of a listed output directory, or have the same path as any of the 443 // listed output directories. 444 repeated string output_files = 3; 445 446 // A list of the output directories that the client expects to retrieve from 447 // the action. Only the contents of the indicated directories (recursively 448 // including the contents of their subdirectories) will be 449 // returned, as well as files listed in `output_files`. Other files that may 450 // be created during command execution are discarded. 451 // 452 // The paths are relative to the working directory of the action execution. 453 // The paths are specified using a single forward slash (`/`) as a path 454 // separator, even if the execution platform natively uses a different 455 // separator. The path MUST NOT include a trailing slash, nor a leading slash, 456 // being a relative path. The special value of empty string is allowed, 457 // although not recommended, and can be used to capture the entire working 458 // directory tree, including inputs. 459 // 460 // In order to ensure consistent hashing of the same Action, the output paths 461 // MUST be sorted lexicographically by code point (or, equivalently, by UTF-8 462 // bytes). 463 // 464 // An output directory cannot be duplicated, be a parent of another output 465 // directory, be a parent of a listed output file, or have the same path as 466 // any of the listed output files. 467 repeated string output_directories = 4; 468 469 // The platform requirements for the execution environment. The server MAY 470 // choose to execute the action on any worker satisfying the requirements, so 471 // the client SHOULD ensure that running the action on any such worker will 472 // have the same result. 473 Platform platform = 5; 474 475 // The working directory, relative to the input root, for the command to run 476 // in. It must be a directory which exists in the input tree. If it is left 477 // empty, then the action is run in the input root. 478 string working_directory = 6; 479} 480 481// A `Platform` is a set of requirements, such as hardware, operating system, or 482// compiler toolchain, for an 483// [Action][build.bazel.remote.execution.v2.Action]'s execution 484// environment. A `Platform` is represented as a series of key-value pairs 485// representing the properties that are required of the platform. 486message Platform { 487 // A single property for the environment. The server is responsible for 488 // specifying the property `name`s that it accepts. If an unknown `name` is 489 // provided in the requirements for an 490 // [Action][build.bazel.remote.execution.v2.Action], the server SHOULD 491 // reject the execution request. If permitted by the server, the same `name` 492 // may occur multiple times. 493 // 494 // The server is also responsible for specifying the interpretation of 495 // property `value`s. For instance, a property describing how much RAM must be 496 // available may be interpreted as allowing a worker with 16GB to fulfill a 497 // request for 8GB, while a property describing the OS environment on which 498 // the action must be performed may require an exact match with the worker's 499 // OS. 500 // 501 // The server MAY use the `value` of one or more properties to determine how 502 // it sets up the execution environment, such as by making specific system 503 // files available to the worker. 504 message Property { 505 // The property name. 506 string name = 1; 507 508 // The property value. 509 string value = 2; 510 } 511 512 // The properties that make up this platform. In order to ensure that 513 // equivalent `Platform`s always hash to the same value, the properties MUST 514 // be lexicographically sorted by name, and then by value. Sorting of strings 515 // is done by code point, equivalently, by the UTF-8 bytes. 516 repeated Property properties = 1; 517} 518 519// A `Directory` represents a directory node in a file tree, containing zero or 520// more children [FileNodes][build.bazel.remote.execution.v2.FileNode], 521// [DirectoryNodes][build.bazel.remote.execution.v2.DirectoryNode] and 522// [SymlinkNodes][build.bazel.remote.execution.v2.SymlinkNode]. 523// Each `Node` contains its name in the directory, either the digest of its 524// content (either a file blob or a `Directory` proto) or a symlink target, as 525// well as possibly some metadata about the file or directory. 526// 527// In order to ensure that two equivalent directory trees hash to the same 528// value, the following restrictions MUST be obeyed when constructing a 529// a `Directory`: 530// - Every child in the directory must have a path of exactly one segment. 531// Multiple levels of directory hierarchy may not be collapsed. 532// - Each child in the directory must have a unique path segment (file name). 533// - The files, directories and symlinks in the directory must each be sorted 534// in lexicographical order by path. The path strings must be sorted by code 535// point, equivalently, by UTF-8 bytes. 536// 537// A `Directory` that obeys the restrictions is said to be in canonical form. 538// 539// As an example, the following could be used for a file named `bar` and a 540// directory named `foo` with an executable file named `baz` (hashes shortened 541// for readability): 542// 543// ```json 544// // (Directory proto) 545// { 546// files: [ 547// { 548// name: "bar", 549// digest: { 550// hash: "4a73bc9d03...", 551// size: 65534 552// } 553// } 554// ], 555// directories: [ 556// { 557// name: "foo", 558// digest: { 559// hash: "4cf2eda940...", 560// size: 43 561// } 562// } 563// ] 564// } 565// 566// // (Directory proto with hash "4cf2eda940..." and size 43) 567// { 568// files: [ 569// { 570// name: "baz", 571// digest: { 572// hash: "b2c941073e...", 573// size: 1294, 574// }, 575// is_executable: true 576// } 577// ] 578// } 579// ``` 580message Directory { 581 // The files in the directory. 582 repeated FileNode files = 1; 583 584 // The subdirectories in the directory. 585 repeated DirectoryNode directories = 2; 586 587 // The symlinks in the directory. 588 repeated SymlinkNode symlinks = 3; 589} 590 591// A `FileNode` represents a single file and associated metadata. 592message FileNode { 593 // The name of the file. 594 string name = 1; 595 596 // The digest of the file's content. 597 Digest digest = 2; 598 599 reserved 3; // Reserved to ensure wire-compatibility with `OutputFile`. 600 601 // True if file is executable, false otherwise. 602 bool is_executable = 4; 603} 604 605// A `DirectoryNode` represents a child of a 606// [Directory][build.bazel.remote.execution.v2.Directory] which is itself 607// a `Directory` and its associated metadata. 608message DirectoryNode { 609 // The name of the directory. 610 string name = 1; 611 612 // The digest of the 613 // [Directory][build.bazel.remote.execution.v2.Directory] object 614 // represented. See [Digest][build.bazel.remote.execution.v2.Digest] 615 // for information about how to take the digest of a proto message. 616 Digest digest = 2; 617} 618 619// A `SymlinkNode` represents a symbolic link. 620message SymlinkNode { 621 // The name of the symlink. 622 string name = 1; 623 624 // The target path of the symlink. The path separator is a forward slash `/`. 625 // The target path can be relative to the parent directory of the symlink or 626 // it can be an absolute path starting with `/`. Support for absolute paths 627 // can be checked using the [Capabilities][build.bazel.remote.execution.v2.Capabilities] 628 // API. The canonical form forbids the substrings `/./` and `//` in the target 629 // path. `..` components are allowed anywhere in the target path. 630 string target = 2; 631} 632 633// A content digest. A digest for a given blob consists of the size of the blob 634// and its hash. The hash algorithm to use is defined by the server, but servers 635// SHOULD use SHA-256. 636// 637// The size is considered to be an integral part of the digest and cannot be 638// separated. That is, even if the `hash` field is correctly specified but 639// `size_bytes` is not, the server MUST reject the request. 640// 641// The reason for including the size in the digest is as follows: in a great 642// many cases, the server needs to know the size of the blob it is about to work 643// with prior to starting an operation with it, such as flattening Merkle tree 644// structures or streaming it to a worker. Technically, the server could 645// implement a separate metadata store, but this results in a significantly more 646// complicated implementation as opposed to having the client specify the size 647// up-front (or storing the size along with the digest in every message where 648// digests are embedded). This does mean that the API leaks some implementation 649// details of (what we consider to be) a reasonable server implementation, but 650// we consider this to be a worthwhile tradeoff. 651// 652// When a `Digest` is used to refer to a proto message, it always refers to the 653// message in binary encoded form. To ensure consistent hashing, clients and 654// servers MUST ensure that they serialize messages according to the following 655// rules, even if there are alternate valid encodings for the same message. 656// - Fields are serialized in tag order. 657// - There are no unknown fields. 658// - There are no duplicate fields. 659// - Fields are serialized according to the default semantics for their type. 660// 661// Most protocol buffer implementations will always follow these rules when 662// serializing, but care should be taken to avoid shortcuts. For instance, 663// concatenating two messages to merge them may produce duplicate fields. 664message Digest { 665 // The hash. In the case of SHA-256, it will always be a lowercase hex string 666 // exactly 64 characters long. 667 string hash = 1; 668 669 // The size of the blob, in bytes. 670 int64 size_bytes = 2; 671} 672 673// ExecutedActionMetadata contains details about a completed execution. 674message ExecutedActionMetadata { 675 // The name of the worker which ran the execution. 676 string worker = 1; 677 678 // When was the action added to the queue. 679 google.protobuf.Timestamp queued_timestamp = 2; 680 681 // When the worker received the action. 682 google.protobuf.Timestamp worker_start_timestamp = 3; 683 684 // When the worker completed the action, including all stages. 685 google.protobuf.Timestamp worker_completed_timestamp = 4; 686 687 // When the worker started fetching action inputs. 688 google.protobuf.Timestamp input_fetch_start_timestamp = 5; 689 690 // When the worker finished fetching action inputs. 691 google.protobuf.Timestamp input_fetch_completed_timestamp = 6; 692 693 // When the worker started executing the action command. 694 google.protobuf.Timestamp execution_start_timestamp = 7; 695 696 // When the worker completed executing the action command. 697 google.protobuf.Timestamp execution_completed_timestamp = 8; 698 699 // When the worker started uploading action outputs. 700 google.protobuf.Timestamp output_upload_start_timestamp = 9; 701 702 // When the worker finished uploading action outputs. 703 google.protobuf.Timestamp output_upload_completed_timestamp = 10; 704} 705 706// An ActionResult represents the result of an 707// [Action][build.bazel.remote.execution.v2.Action] being run. 708message ActionResult { 709 reserved 1; // Reserved for use as the resource name. 710 711 // The output files of the action. For each output file requested in the 712 // `output_files` field of the Action, if the corresponding file existed after 713 // the action completed, a single entry will be present in the output list. 714 // 715 // If the action does not produce the requested output, or produces a 716 // directory where a regular file is expected or vice versa, then that output 717 // will be omitted from the list. The server is free to arrange the output 718 // list as desired; clients MUST NOT assume that the output list is sorted. 719 repeated OutputFile output_files = 2; 720 721 // The output directories of the action. For each output directory requested 722 // in the `output_directories` field of the Action, if the corresponding 723 // directory existed after the action completed, a single entry will be 724 // present in the output list, which will contain the digest of a 725 // [Tree][build.bazel.remote.execution.v2.Tree] message containing the 726 // directory tree, and the path equal exactly to the corresponding Action 727 // output_directories member. 728 // 729 // As an example, suppose the Action had an output directory `a/b/dir` and the 730 // execution produced the following contents in `a/b/dir`: a file named `bar` 731 // and a directory named `foo` with an executable file named `baz`. Then, 732 // output_directory will contain (hashes shortened for readability): 733 // 734 // ```json 735 // // OutputDirectory proto: 736 // { 737 // path: "a/b/dir" 738 // tree_digest: { 739 // hash: "4a73bc9d03...", 740 // size: 55 741 // } 742 // } 743 // // Tree proto with hash "4a73bc9d03..." and size 55: 744 // { 745 // root: { 746 // files: [ 747 // { 748 // name: "bar", 749 // digest: { 750 // hash: "4a73bc9d03...", 751 // size: 65534 752 // } 753 // } 754 // ], 755 // directories: [ 756 // { 757 // name: "foo", 758 // digest: { 759 // hash: "4cf2eda940...", 760 // size: 43 761 // } 762 // } 763 // ] 764 // } 765 // children : { 766 // // (Directory proto with hash "4cf2eda940..." and size 43) 767 // files: [ 768 // { 769 // name: "baz", 770 // digest: { 771 // hash: "b2c941073e...", 772 // size: 1294, 773 // }, 774 // is_executable: true 775 // } 776 // ] 777 // } 778 // } 779 // ``` 780 repeated OutputDirectory output_directories = 3; 781 782 // The exit code of the command. 783 int32 exit_code = 4; 784 785 // The standard output buffer of the action. The server will determine, based 786 // on the size of the buffer, whether to return it in raw form or to return 787 // a digest in `stdout_digest` that points to the buffer. If neither is set, 788 // then the buffer is empty. The client SHOULD NOT assume it will get one of 789 // the raw buffer or a digest on any given request and should be prepared to 790 // handle either. 791 bytes stdout_raw = 5; 792 793 // The digest for a blob containing the standard output of the action, which 794 // can be retrieved from the 795 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 796 // See `stdout_raw` for when this will be set. 797 Digest stdout_digest = 6; 798 799 // The standard error buffer of the action. The server will determine, based 800 // on the size of the buffer, whether to return it in raw form or to return 801 // a digest in `stderr_digest` that points to the buffer. If neither is set, 802 // then the buffer is empty. The client SHOULD NOT assume it will get one of 803 // the raw buffer or a digest on any given request and should be prepared to 804 // handle either. 805 bytes stderr_raw = 7; 806 807 // The digest for a blob containing the standard error of the action, which 808 // can be retrieved from the 809 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 810 // See `stderr_raw` for when this will be set. 811 Digest stderr_digest = 8; 812 813 // The details of the execution that originally produced this result. 814 ExecutedActionMetadata execution_metadata = 9; 815} 816 817// An `OutputFile` is similar to a 818// [FileNode][build.bazel.remote.execution.v2.FileNode], but it is used as an 819// output in an `ActionResult`. It allows a full file path rather than 820// only a name. 821// 822// `OutputFile` is binary-compatible with `FileNode`. 823message OutputFile { 824 // The full path of the file relative to the input root, including the 825 // filename. The path separator is a forward slash `/`. Since this is a 826 // relative path, it MUST NOT begin with a leading forward slash. 827 string path = 1; 828 829 // The digest of the file's content. 830 Digest digest = 2; 831 832 reserved 3; // Used for a removed field in an earlier version of the API. 833 834 // True if file is executable, false otherwise. 835 bool is_executable = 4; 836} 837 838// A `Tree` contains all the 839// [Directory][build.bazel.remote.execution.v2.Directory] protos in a 840// single directory Merkle tree, compressed into one message. 841message Tree { 842 // The root directory in the tree. 843 Directory root = 1; 844 845 // All the child directories: the directories referred to by the root and, 846 // recursively, all its children. In order to reconstruct the directory tree, 847 // the client must take the digests of each of the child directories and then 848 // build up a tree starting from the `root`. 849 repeated Directory children = 2; 850} 851 852// An `OutputDirectory` is the output in an `ActionResult` corresponding to a 853// directory's full contents rather than a single file. 854message OutputDirectory { 855 // The full path of the directory relative to the working directory. The path 856 // separator is a forward slash `/`. Since this is a relative path, it MUST 857 // NOT begin with a leading forward slash. The empty string value is allowed, 858 // and it denotes the entire working directory. 859 string path = 1; 860 861 reserved 2; // Used for a removed field in an earlier version of the API. 862 863 // The digest of the encoded 864 // [Tree][build.bazel.remote.execution.v2.Tree] proto containing the 865 // directory's contents. 866 Digest tree_digest = 3; 867} 868 869// An `ExecutionPolicy` can be used to control the scheduling of the action. 870message ExecutionPolicy { 871 // The priority (relative importance) of this action. Generally, a lower value 872 // means that the action should be run sooner than actions having a greater 873 // priority value, but the interpretation of a given value is server- 874 // dependent. A priority of 0 means the *default* priority. Priorities may be 875 // positive or negative, and such actions should run later or sooner than 876 // actions having the default priority, respectively. The particular semantics 877 // of this field is up to the server. In particular, every server will have 878 // their own supported range of priorities, and will decide how these map into 879 // scheduling policy. 880 int32 priority = 1; 881} 882 883// A `ResultsCachePolicy` is used for fine-grained control over how action 884// outputs are stored in the CAS and Action Cache. 885message ResultsCachePolicy { 886 // The priority (relative importance) of this content in the overall cache. 887 // Generally, a lower value means a longer retention time or other advantage, 888 // but the interpretation of a given value is server-dependent. A priority of 889 // 0 means a *default* value, decided by the server. 890 // 891 // The particular semantics of this field is up to the server. In particular, 892 // every server will have their own supported range of priorities, and will 893 // decide how these map into retention/eviction policy. 894 int32 priority = 1; 895} 896 897// A request message for 898// [Execution.Execute][build.bazel.remote.execution.v2.Execution.Execute]. 899message ExecuteRequest { 900 // The instance of the execution system to operate against. A server may 901 // support multiple instances of the execution system (with their own workers, 902 // storage, caches, etc.). The server MAY require use of this field to select 903 // between them in an implementation-defined fashion, otherwise it can be 904 // omitted. 905 string instance_name = 1; 906 907 // If true, the action will be executed anew even if its result was already 908 // present in the cache. If false, the result may be served from the 909 // [ActionCache][build.bazel.remote.execution.v2.ActionCache]. 910 bool skip_cache_lookup = 3; 911 912 reserved 2, 4, 5; // Used for removed fields in an earlier version of the API. 913 914 // The digest of the [Action][build.bazel.remote.execution.v2.Action] to 915 // execute. 916 Digest action_digest = 6; 917 918 // An optional policy for execution of the action. 919 // The server will have a default policy if this is not provided. 920 ExecutionPolicy execution_policy = 7; 921 922 // An optional policy for the results of this execution in the remote cache. 923 // The server will have a default policy if this is not provided. 924 // This may be applied to both the ActionResult and the associated blobs. 925 ResultsCachePolicy results_cache_policy = 8; 926} 927 928// A `LogFile` is a log stored in the CAS. 929message LogFile { 930 // The digest of the log contents. 931 Digest digest = 1; 932 933 // This is a hint as to the purpose of the log, and is set to true if the log 934 // is human-readable text that can be usefully displayed to a user, and false 935 // otherwise. For instance, if a command-line client wishes to print the 936 // server logs to the terminal for a failed action, this allows it to avoid 937 // displaying a binary file. 938 bool human_readable = 2; 939} 940 941// The response message for 942// [Execution.Execute][build.bazel.remote.execution.v2.Execution.Execute], 943// which will be contained in the [response 944// field][google.longrunning.Operation.response] of the 945// [Operation][google.longrunning.Operation]. 946message ExecuteResponse { 947 // The result of the action. 948 ActionResult result = 1; 949 950 // True if the result was served from cache, false if it was executed. 951 bool cached_result = 2; 952 953 // If the status has a code other than `OK`, it indicates that the action did 954 // not finish execution. For example, if the operation times out during 955 // execution, the status will have a `DEADLINE_EXCEEDED` code. Servers MUST 956 // use this field for errors in execution, rather than the error field on the 957 // `Operation` object. 958 // 959 // If the status code is other than `OK`, then the result MUST NOT be cached. 960 // For an error status, the `result` field is optional; the server may 961 // populate the output-, stdout-, and stderr-related fields if it has any 962 // information available, such as the stdout and stderr of a timed-out action. 963 google.rpc.Status status = 3; 964 965 // An optional list of additional log outputs the server wishes to provide. A 966 // server can use this to return execution-specific logs however it wishes. 967 // This is intended primarily to make it easier for users to debug issues that 968 // may be outside of the actual job execution, such as by identifying the 969 // worker executing the action or by providing logs from the worker's setup 970 // phase. The keys SHOULD be human readable so that a client can display them 971 // to a user. 972 map<string, LogFile> server_logs = 4; 973} 974 975// Metadata about an ongoing 976// [execution][build.bazel.remote.execution.v2.Execution.Execute], which 977// will be contained in the [metadata 978// field][google.longrunning.Operation.response] of the 979// [Operation][google.longrunning.Operation]. 980message ExecuteOperationMetadata { 981 // The current stage of execution. 982 enum Stage { 983 UNKNOWN = 0; 984 985 // Checking the result against the cache. 986 CACHE_CHECK = 1; 987 988 // Currently idle, awaiting a free machine to execute. 989 QUEUED = 2; 990 991 // Currently being executed by a worker. 992 EXECUTING = 3; 993 994 // Finished execution. 995 COMPLETED = 4; 996 } 997 998 Stage stage = 1; 999 1000 // The digest of the [Action][build.bazel.remote.execution.v2.Action] 1001 // being executed. 1002 Digest action_digest = 2; 1003 1004 // If set, the client can use this name with 1005 // [ByteStream.Read][google.bytestream.ByteStream.Read] to stream the 1006 // standard output. 1007 string stdout_stream_name = 3; 1008 1009 // If set, the client can use this name with 1010 // [ByteStream.Read][google.bytestream.ByteStream.Read] to stream the 1011 // standard error. 1012 string stderr_stream_name = 4; 1013} 1014 1015// A request message for 1016// [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution]. 1017message WaitExecutionRequest { 1018 // The name of the [Operation][google.longrunning.operations.v1.Operation] 1019 // returned by [Execute][build.bazel.remote.execution.v2.Execution.Execute]. 1020 string name = 1; 1021} 1022 1023// A request message for 1024// [ActionCache.GetActionResult][build.bazel.remote.execution.v2.ActionCache.GetActionResult]. 1025message GetActionResultRequest { 1026 // The instance of the execution system to operate against. A server may 1027 // support multiple instances of the execution system (with their own workers, 1028 // storage, caches, etc.). The server MAY require use of this field to select 1029 // between them in an implementation-defined fashion, otherwise it can be 1030 // omitted. 1031 string instance_name = 1; 1032 1033 // The digest of the [Action][build.bazel.remote.execution.v2.Action] 1034 // whose result is requested. 1035 Digest action_digest = 2; 1036} 1037 1038// A request message for 1039// [ActionCache.UpdateActionResult][build.bazel.remote.execution.v2.ActionCache.UpdateActionResult]. 1040message UpdateActionResultRequest { 1041 // The instance of the execution system to operate against. A server may 1042 // support multiple instances of the execution system (with their own workers, 1043 // storage, caches, etc.). The server MAY require use of this field to select 1044 // between them in an implementation-defined fashion, otherwise it can be 1045 // omitted. 1046 string instance_name = 1; 1047 1048 // The digest of the [Action][build.bazel.remote.execution.v2.Action] 1049 // whose result is being uploaded. 1050 Digest action_digest = 2; 1051 1052 // The [ActionResult][build.bazel.remote.execution.v2.ActionResult] 1053 // to store in the cache. 1054 ActionResult action_result = 3; 1055 1056 // An optional policy for the results of this execution in the remote cache. 1057 // The server will have a default policy if this is not provided. 1058 // This may be applied to both the ActionResult and the associated blobs. 1059 ResultsCachePolicy results_cache_policy = 4; 1060} 1061 1062// A request message for 1063// [ContentAddressableStorage.FindMissingBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.FindMissingBlobs]. 1064message FindMissingBlobsRequest { 1065 // The instance of the execution system to operate against. A server may 1066 // support multiple instances of the execution system (with their own workers, 1067 // storage, caches, etc.). The server MAY require use of this field to select 1068 // between them in an implementation-defined fashion, otherwise it can be 1069 // omitted. 1070 string instance_name = 1; 1071 1072 // A list of the blobs to check. 1073 repeated Digest blob_digests = 2; 1074} 1075 1076// A response message for 1077// [ContentAddressableStorage.FindMissingBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.FindMissingBlobs]. 1078message FindMissingBlobsResponse { 1079 // A list of the blobs requested *not* present in the storage. 1080 repeated Digest missing_blob_digests = 2; 1081} 1082 1083// A request message for 1084// [ContentAddressableStorage.BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs]. 1085message BatchUpdateBlobsRequest { 1086 // A request corresponding to a single blob that the client wants to upload. 1087 message Request { 1088 // The digest of the blob. This MUST be the digest of `data`. 1089 Digest digest = 1; 1090 1091 // The raw binary data. 1092 bytes data = 2; 1093 } 1094 1095 // The instance of the execution system to operate against. A server may 1096 // support multiple instances of the execution system (with their own workers, 1097 // storage, caches, etc.). The server MAY require use of this field to select 1098 // between them in an implementation-defined fashion, otherwise it can be 1099 // omitted. 1100 string instance_name = 1; 1101 1102 // The individual upload requests. 1103 repeated Request requests = 2; 1104} 1105 1106// A response message for 1107// [ContentAddressableStorage.BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs]. 1108message BatchUpdateBlobsResponse { 1109 // A response corresponding to a single blob that the client tried to upload. 1110 message Response { 1111 // The blob digest to which this response corresponds. 1112 Digest digest = 1; 1113 1114 // The result of attempting to upload that blob. 1115 google.rpc.Status status = 2; 1116 } 1117 1118 // The responses to the requests. 1119 repeated Response responses = 1; 1120} 1121 1122// A request message for 1123// [ContentAddressableStorage.BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs]. 1124message BatchReadBlobsRequest { 1125 // The instance of the execution system to operate against. A server may 1126 // support multiple instances of the execution system (with their own workers, 1127 // storage, caches, etc.). The server MAY require use of this field to select 1128 // between them in an implementation-defined fashion, otherwise it can be 1129 // omitted. 1130 string instance_name = 1; 1131 1132 // The individual blob digests. 1133 repeated Digest digests = 2; 1134} 1135 1136// A response message for 1137// [ContentAddressableStorage.BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs]. 1138message BatchReadBlobsResponse { 1139 // A response corresponding to a single blob that the client tried to upload. 1140 message Response { 1141 // The digest to which this response corresponds. 1142 Digest digest = 1; 1143 1144 // The raw binary data. 1145 bytes data = 2; 1146 1147 // The result of attempting to download that blob. 1148 google.rpc.Status status = 3; 1149 } 1150 1151 // The responses to the requests. 1152 repeated Response responses = 1; 1153} 1154 1155// A request message for 1156// [ContentAddressableStorage.GetTree][build.bazel.remote.execution.v2.ContentAddressableStorage.GetTree]. 1157message GetTreeRequest { 1158 // The instance of the execution system to operate against. A server may 1159 // support multiple instances of the execution system (with their own workers, 1160 // storage, caches, etc.). The server MAY require use of this field to select 1161 // between them in an implementation-defined fashion, otherwise it can be 1162 // omitted. 1163 string instance_name = 1; 1164 1165 // The digest of the root, which must be an encoded 1166 // [Directory][build.bazel.remote.execution.v2.Directory] message 1167 // stored in the 1168 // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. 1169 Digest root_digest = 2; 1170 1171 // A maximum page size to request. If present, the server will request no more 1172 // than this many items. Regardless of whether a page size is specified, the 1173 // server may place its own limit on the number of items to be returned and 1174 // require the client to retrieve more items using a subsequent request. 1175 int32 page_size = 3; 1176 1177 // A page token, which must be a value received in a previous 1178 // [GetTreeResponse][build.bazel.remote.execution.v2.GetTreeResponse]. 1179 // If present, the server will use it to return the following page of results. 1180 string page_token = 4; 1181} 1182 1183// A response message for 1184// [ContentAddressableStorage.GetTree][build.bazel.remote.execution.v2.ContentAddressableStorage.GetTree]. 1185message GetTreeResponse { 1186 // The directories descended from the requested root. 1187 repeated Directory directories = 1; 1188 1189 // If present, signifies that there are more results which the client can 1190 // retrieve by passing this as the page_token in a subsequent 1191 // [request][build.bazel.remote.execution.v2.GetTreeRequest]. 1192 // If empty, signifies that this is the last page of results. 1193 string next_page_token = 2; 1194} 1195 1196// A request message for 1197// [Capabilities.GetCapabilities][google.devtools.remoteexecution.v2.Capabilities.GetCapabilities]. 1198message GetCapabilitiesRequest { 1199 // The instance of the execution system to operate against. A server may 1200 // support multiple instances of the execution system (with their own workers, 1201 // storage, caches, etc.). The server MAY require use of this field to select 1202 // between them in an implementation-defined fashion, otherwise it can be 1203 // omitted. 1204 string instance_name = 1; 1205} 1206 1207// A response message for 1208// [Capabilities.GetCapabilities][google.devtools.remoteexecution.v2.Capabilities.GetCapabilities]. 1209message ServerCapabilities { 1210 // Capabilities of the remote cache system. 1211 CacheCapabilities cache_capabilities = 1; 1212 1213 // Capabilities of the remote execution system. 1214 ExecutionCapabilities execution_capabilities = 2; 1215 1216 // Earliest RE API version supported, including deprecated versions. 1217 build.bazel.semver.SemVer deprecated_api_version = 3; 1218 1219 // Earliest non-deprecated RE API version supported. 1220 build.bazel.semver.SemVer low_api_version = 4; 1221 1222 // Latest RE API version supported. 1223 build.bazel.semver.SemVer high_api_version = 5; 1224} 1225 1226// The digest function used for converting values into keys for CAS and Action 1227// Cache. 1228enum DigestFunction { 1229 UNKNOWN = 0; 1230 SHA256 = 1; 1231 SHA1 = 2; 1232 MD5 = 3; 1233} 1234 1235// Describes the server/instance capabilities for updating the action cache. 1236message ActionCacheUpdateCapabilities { 1237 bool update_enabled = 1; 1238} 1239 1240// Allowed values for priority in 1241// [ResultsCachePolicy][google.devtools.remoteexecution.v2.ResultsCachePolicy] 1242// Used for querying both cache and execution valid priority ranges. 1243message PriorityCapabilities { 1244 // Supported range of priorities, including boundaries. 1245 message PriorityRange { 1246 int32 min_priority = 1; 1247 int32 max_priority = 2; 1248 } 1249 repeated PriorityRange priorities = 1; 1250} 1251 1252// Capabilities of the remote cache system. 1253message CacheCapabilities { 1254 // Describes how the server treats absolute symlink targets. 1255 enum SymlinkAbsolutePathStrategy { 1256 UNKNOWN = 0; 1257 1258 // Server will return an INVALID_ARGUMENT on input symlinks with absolute targets. 1259 // If an action tries to create an output symlink with an absolute target, a 1260 // FAILED_PRECONDITION will be returned. 1261 DISALLOWED = 1; 1262 1263 // Server will allow symlink targets to escape the input root tree, possibly 1264 // resulting in non-hermetic builds. 1265 ALLOWED = 2; 1266 } 1267 1268 // All the digest functions supported by the remote cache. 1269 // Remote cache may support multiple digest functions simultaneously. 1270 repeated DigestFunction digest_function = 1; 1271 1272 // Capabilities for updating the action cache. 1273 ActionCacheUpdateCapabilities action_cache_update_capabilities = 2; 1274 1275 // Supported cache priority range for both CAS and ActionCache. 1276 PriorityCapabilities cache_priority_capabilities = 3; 1277 1278 // Maximum total size of blobs to be uploaded/downloaded using 1279 // batch methods. A value of 0 means no limit is set, although 1280 // in practice there will always be a message size limitation 1281 // of the protocol in use, e.g. GRPC. 1282 int64 max_batch_total_size_bytes = 4; 1283 1284 // Whether absolute symlink targets are supported. 1285 SymlinkAbsolutePathStrategy symlink_absolute_path_strategy = 5; 1286} 1287 1288// Capabilities of the remote execution system. 1289message ExecutionCapabilities { 1290 // Remote execution may only support a single digest function. 1291 DigestFunction digest_function = 1; 1292 1293 // Whether remote execution is enabled for the particular server/instance. 1294 bool exec_enabled = 2; 1295 1296 // Supported execution priority range. 1297 PriorityCapabilities execution_priority_capabilities = 3; 1298} 1299 1300// Details for the tool used to call the API. 1301message ToolDetails { 1302 // Name of the tool, e.g. bazel. 1303 string tool_name = 1; 1304 1305 // Version of the tool used for the request, e.g. 5.0.3. 1306 string tool_version = 2; 1307} 1308 1309// An optional Metadata to attach to any RPC request to tell the server about an 1310// external context of the request. The server may use this for logging or other 1311// purposes. To use it, the client attaches the header to the call using the 1312// canonical proto serialization: 1313// name: build.bazel.remote.execution.v2.requestmetadata-bin 1314// contents: the base64 encoded binary RequestMetadata message. 1315message RequestMetadata { 1316 // The details for the tool invoking the requests. 1317 ToolDetails tool_details = 1; 1318 1319 // An identifier that ties multiple requests to the same action. 1320 // For example, multiple requests to the CAS, Action Cache, and Execution 1321 // API are used in order to compile foo.cc. 1322 string action_id = 2; 1323 1324 // An identifier that ties multiple actions together to a final result. 1325 // For example, multiple actions are required to build and run foo_test. 1326 string tool_invocation_id = 3; 1327 1328 // An identifier to tie multiple tool invocations together. For example, 1329 // runs of foo_test, bar_test and baz_test on a post-submit of a given patch. 1330 string correlated_invocations_id = 4; 1331} 1332