| // Copyright 2020 The Bazel Authors. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| syntax = "proto3"; |
| |
| package build.bazel.remote.asset.v1; |
| |
| import "build/bazel/remote/execution/v2/remote_execution.proto"; |
| import "google/api/annotations.proto"; |
| import "google/protobuf/duration.proto"; |
| import "google/protobuf/timestamp.proto"; |
| import "google/rpc/status.proto"; |
| |
| option csharp_namespace = "Build.Bazel.Remote.Asset.v1"; |
| option go_package = "github.com/bazelbuild/remote-apis/build/bazel/remote/asset/v1;remoteasset"; |
| option java_multiple_files = true; |
| option java_outer_classname = "RemoteAssetProto"; |
| option java_package = "build.bazel.remote.asset.v1"; |
| option objc_class_prefix = "RA"; |
| |
| // The Remote Asset API provides a mapping from a URI and Qualifiers to |
| // Digests. |
| // |
| // Multiple URIs may be used to refer to the same content. For example, the |
| // same tarball may exist at multiple mirrors and thus be retrievable from |
| // multiple URLs. When URLs are used, these should refer to actual content as |
| // Fetch service implementations may choose to fetch the content directly |
| // from the origin. For example, the HEAD of a git repository's active branch |
| // can be referred to as: |
| // |
| // uri: https://github.com/bazelbuild/remote-apis.git |
| // |
| // URNs may be used to strongly identify content, for instance by using the |
| // uuid namespace identifier: urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6. |
| // This is most applicable to named content that is Push'd, where the URN |
| // serves as an agreed-upon key, but carries no other inherent meaning. |
| // |
| // Service implementations may choose to support only URLs, only URNs for |
| // Push'd content, only other URIs for which the server and client agree upon |
| // semantics of, or any mixture of the above. |
| |
| // Qualifiers are used to disambiguate or sub-select content that shares a URI. |
| // This may include specifying a particular commit or branch, in the case of |
| // URIs referencing a repository; they could also be used to specify a |
| // particular subdirectory of a repository or tarball. Qualifiers may also be |
| // used to ensure content matches what the client expects, even when there is |
| // no ambiguity to be had - for example, a qualifier specifying a checksum |
| // value. |
| // |
| // In cases where the semantics of the request are not immediately clear from |
| // the URL and/or qualifiers - e.g. dictated by URL scheme - it is recommended |
| // to use an additional qualifier to remove the ambiguity. The `resource_type` |
| // qualifier is recommended for this purpose. |
| // |
| // Qualifiers may be supplied in any order. |
| message Qualifier { |
| // The "name" of the qualifier, for example "resource_type". |
| // No separation is made between 'standard' and 'nonstandard' |
| // qualifiers, in accordance with https://tools.ietf.org/html/rfc6648, |
| // however implementers *SHOULD* take care to avoid ambiguity. |
| string name = 1; |
| |
| // The "value" of the qualifier. Semantics will be dictated by the name. |
| string value = 2; |
| } |
| |
| // The Fetch service resolves or fetches assets referenced by URI and |
| // Qualifiers, returning a Digest for the content in |
| // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. |
| // |
| // As with other services in the Remote Execution API, any call may return an |
| // error with a [RetryInfo][google.rpc.RetryInfo] error detail providing |
| // information about when the client should retry the request; clients SHOULD |
| // respect the information provided. |
| service Fetch { |
| // Resolve or fetch referenced assets, making them available to the caller and |
| // other consumers in the [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. |
| // |
| // Servers *MAY* fetch content that they do not already have cached, for any |
| // URLs they support. |
| // |
| // Servers *SHOULD* ensure that referenced files are present in the CAS at the |
| // time of the response, and (if supported) that they will remain available |
| // for a reasonable period of time. The lifetimes of the referenced blobs *SHOULD* |
| // be increased if necessary and applicable. |
| // In the event that a client receives a reference to content that is no |
| // longer present, it *MAY* re-issue the request with |
| // `oldest_content_accepted` set to a more recent timestamp than the original |
| // attempt, to induce a re-fetch from origin. |
| // |
| // Servers *MAY* cache fetched content and reuse it for subsequent requests, |
| // subject to `oldest_content_accepted`. |
| // |
| // Servers *MAY* support the complementary [Push][build.bazel.remote.asset.v1.Push] |
| // API and allow content to be directly inserted for use in future fetch |
| // responses. |
| // |
| // Servers *MUST* ensure Fetch'd content matches all the specified |
| // qualifiers except in the case of previously Push'd resources, for which |
| // the server *MAY* trust the pushing client to have set the qualifiers |
| // correctly, without validation. |
| // |
| // Servers not implementing the complementary [Push][build.bazel.remote.asset.v1.Push] |
| // API *MUST* reject requests containing qualifiers it does not support. |
| // |
| // Servers *MAY* transform assets as part of the fetch. For example a |
| // tarball fetched by [FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory] |
| // might be unpacked, or a Git repository |
| // fetched by [FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob] |
| // might be passed through `git-archive`. |
| // |
| // Errors handling the requested assets will be returned as gRPC Status errors |
| // here; errors outside the server's control will be returned inline in the |
| // `status` field of the response (see comment there for details). |
| // The possible RPC errors include: |
| // * `INVALID_ARGUMENT`: One or more arguments were invalid, such as a |
| // qualifier that is not supported by the server. |
| // * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to |
| // perform the requested operation. The client may retry after a delay. |
| // * `UNAVAILABLE`: Due to a transient condition the operation could not be |
| // completed. The client should retry. |
| // * `INTERNAL`: An internal error occurred while performing the operation. |
| // The client should retry. |
| // * `DEADLINE_EXCEEDED`: The fetch could not be completed within the given |
| // RPC deadline. The client should retry for at least as long as the value |
| // provided in `timeout` field of the request. |
| // |
| // In the case of unsupported qualifiers, the server *SHOULD* additionally |
| // send a [BadRequest][google.rpc.BadRequest] error detail where, for each |
| // unsupported qualifier, there is a `FieldViolation` with a `field` of |
| // `qualifiers.name` and a `description` of `"{qualifier}" not supported` |
| // indicating the name of the unsupported qualifier. |
| rpc FetchBlob(FetchBlobRequest) returns (FetchBlobResponse) { |
| option (google.api.http) = { post: "/v1/{instance_name=**}/assets:fetchBlob" body: "*" }; |
| } |
| rpc FetchDirectory(FetchDirectoryRequest) returns (FetchDirectoryResponse) { |
| option (google.api.http) = { post: "/v1/{instance_name=**}/assets:fetchDirectory" body: "*" }; |
| } |
| } |
| |
| // A request message for |
| // [Fetch.FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob]. |
| message FetchBlobRequest { |
| // 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 timeout for the underlying fetch, if content needs to be retrieved from |
| // origin. |
| // |
| // If unset, the server *MAY* apply an implementation-defined timeout. |
| // |
| // If set, and the user-provided timeout exceeds the RPC deadline, the server |
| // *SHOULD* keep the fetch going after the RPC completes, to be made |
| // available for future Fetch calls. The server may also enforce (via clamping |
| // and/or an INVALID_ARGUMENT error) implementation-defined minimum and |
| // maximum timeout values. |
| // |
| // If this timeout is exceeded on an attempt to retrieve content from origin |
| // the client will receive DEADLINE_EXCEEDED in [FetchBlobResponse.status]. |
| google.protobuf.Duration timeout = 2; |
| |
| // The oldest content the client is willing to accept, as measured from the |
| // time it was Push'd or when the underlying retrieval from origin was |
| // started. |
| // Upon retries of Fetch requests that cannot be completed within a single |
| // RPC, clients *SHOULD* provide the same value for subsequent requests as the |
| // original, to simplify combining the request with the previous attempt. |
| // |
| // If unset, the client *SHOULD* accept content of any age. |
| google.protobuf.Timestamp oldest_content_accepted = 3; |
| |
| // The URI(s) of the content to fetch. These may be resources that the server |
| // can directly fetch from origin, in which case multiple URIs *SHOULD* |
| // represent the same content available at different locations (such as an |
| // origin and secondary mirrors). These may also be URIs for content known to |
| // the server through other mechanisms, e.g. pushed via the [Push][build.bazel.remote.asset.v1.Push] |
| // service. |
| // |
| // Clients *MUST* supply at least one URI. Servers *MAY* match any one of the |
| // supplied URIs. |
| repeated string uris = 4; |
| |
| // Qualifiers sub-specifying the content to fetch - see comments on |
| // [Qualifier][build.bazel.remote.asset.v1.Qualifier]. |
| // The same qualifiers apply to all URIs. |
| // |
| // Specified qualifier names *MUST* be unique. |
| repeated Qualifier qualifiers = 5; |
| } |
| |
| // A response message for |
| // [Fetch.FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob]. |
| message FetchBlobResponse { |
| // If the status has a code other than `OK`, it indicates that the operation |
| // was unable to be completed for reasons outside the servers' control. |
| // The possible fetch errors include: |
| // * `DEADLINE_EXCEEDED`: The operation could not be completed within the |
| // specified timeout. |
| // * `NOT_FOUND`: The requested asset was not found at the specified location. |
| // * `PERMISSION_DENIED`: The request was rejected by a remote server, or |
| // requested an asset from a disallowed origin. |
| // * `ABORTED`: The operation could not be completed, typically due to a |
| // failed consistency check. |
| google.rpc.Status status = 1; |
| |
| // The uri from the request that resulted in a successful retrieval, or from |
| // which the error indicated in `status` was obtained. |
| string uri = 2; |
| |
| // Any qualifiers known to the server and of interest to clients. |
| repeated Qualifier qualifiers = 3; |
| |
| // A minimum timestamp the content is expected to be available through. |
| // Servers *MAY* omit this field, if not known with confidence. |
| google.protobuf.Timestamp expires_at = 4; |
| |
| // The result of the fetch, if the status had code `OK`. |
| // The digest of the file's contents, available for download through the CAS. |
| build.bazel.remote.execution.v2.Digest blob_digest = 5; |
| } |
| |
| // A request message for |
| // [Fetch.FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory]. |
| message FetchDirectoryRequest { |
| // 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 timeout for the underlying fetch, if content needs to be retrieved from |
| // origin. This value is allowed to exceed the RPC deadline, in which case the |
| // server *SHOULD* keep the fetch going after the RPC completes, to be made |
| // available for future Fetch calls. |
| // |
| // If this timeout is exceeded on an attempt to retrieve content from origin |
| // the client will receive DEADLINE_EXCEEDED in [FetchDirectoryResponse.status]. |
| google.protobuf.Duration timeout = 2; |
| |
| // The oldest content the client is willing to accept, as measured from the |
| // time it was Push'd or when the underlying retrieval from origin was |
| // started. |
| // Upon retries of Fetch requests that cannot be completed within a single |
| // RPC, clients *SHOULD* provide the same value for subsequent requests as the |
| // original, to simplify combining the request with the previous attempt. |
| // |
| // If unset, the client *SHOULD* accept content of any age. |
| google.protobuf.Timestamp oldest_content_accepted = 3; |
| |
| // The URI(s) of the content to fetch. These may be resources that the server |
| // can directly fetch from origin, in which case multiple URIs *SHOULD* |
| // represent the same content available at different locations (such as an |
| // origin and secondary mirrors). These may also be URIs for content known to |
| // the server through other mechanisms, e.g. pushed via the [Push][build.bazel.remote.asset.v1.Push] |
| // service. |
| // |
| // Clients *MUST* supply at least one URI. Servers *MAY* match any one of the |
| // supplied URIs. |
| repeated string uris = 4; |
| |
| // Qualifiers sub-specifying the content to fetch - see comments on |
| // [Qualifier][build.bazel.remote.asset.v1.Qualifier]. |
| // The same qualifiers apply to all URIs. |
| // |
| // Specified qualifier names *MUST* be unique. |
| repeated Qualifier qualifiers = 5; |
| } |
| |
| // A response message for |
| // [Fetch.FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory]. |
| message FetchDirectoryResponse { |
| // If the status has a code other than `OK`, it indicates that the operation |
| // was unable to be completed for reasons outside the servers' control. |
| // The possible fetch errors include: |
| // * `DEADLINE_EXCEEDED`: The operation could not be completed within the |
| // specified timeout. |
| // * `NOT_FOUND`: The requested asset was not found at the specified location. |
| // * `PERMISSION_DENIED`: The request was rejected by a remote server, or |
| // requested an asset from a disallowed origin. |
| // * `ABORTED`: The operation could not be completed, typically due to a |
| // failed consistency check. |
| google.rpc.Status status = 1; |
| |
| // The uri from the request that resulted in a successful retrieval, or from |
| // which the error indicated in `status` was obtained. |
| string uri = 2; |
| |
| // Any qualifiers known to the server and of interest to clients. |
| repeated Qualifier qualifiers = 3; |
| |
| // A minimum timestamp the content is expected to be available through. |
| // Servers *MAY* omit this field, if not known with confidence. |
| google.protobuf.Timestamp expires_at = 4; |
| |
| // The result of the fetch, if the status had code `OK`. |
| // the root digest of a directory tree, suitable for fetching via |
| // [ContentAddressableStorage.GetTree]. |
| build.bazel.remote.execution.v2.Digest root_directory_digest = 5; |
| } |
| |
| // The Push service is complementary to the Fetch, and allows for |
| // associating contents of URLs to be returned in future Fetch API calls. |
| // |
| // As with other services in the Remote Execution API, any call may return an |
| // error with a [RetryInfo][google.rpc.RetryInfo] error detail providing |
| // information about when the client should retry the request; clients SHOULD |
| // respect the information provided. |
| service Push { |
| // These APIs associate the identifying information of a resource, as |
| // indicated by URI and optionally Qualifiers, with content available in the |
| // CAS. For example, associating a repository url and a commit id with a |
| // Directory Digest. |
| // |
| // Servers *SHOULD* only allow trusted clients to associate content, and *MAY* |
| // only allow certain URIs to be pushed. |
| // |
| // Clients *MUST* ensure associated content is available in CAS prior to |
| // pushing. |
| // |
| // Clients *MUST* ensure the Qualifiers listed correctly match the contents, |
| // and Servers *MAY* trust these values without validation. |
| // Fetch servers *MAY* require exact match of all qualifiers when returning |
| // content previously pushed, or allow fetching content with only a subset of |
| // the qualifiers specified on Push. |
| // |
| // Clients can specify expiration information that the server *SHOULD* |
| // respect. Subsequent requests can be used to alter the expiration time. |
| // |
| // A minimal compliant Fetch implementation may support only Push'd content |
| // and return `NOT_FOUND` for any resource that was not pushed first. |
| // Alternatively, a compliant implementation may choose to not support Push |
| // and only return resources that can be Fetch'd from origin. |
| // |
| // Errors will be returned as gRPC Status errors. |
| // The possible RPC errors include: |
| // * `INVALID_ARGUMENT`: One or more arguments to the RPC were invalid. |
| // * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to |
| // perform the requested operation. The client may retry after a delay. |
| // * `UNAVAILABLE`: Due to a transient condition the operation could not be |
| // completed. The client should retry. |
| // * `INTERNAL`: An internal error occurred while performing the operation. |
| // The client should retry. |
| rpc PushBlob(PushBlobRequest) returns (PushBlobResponse) { |
| option (google.api.http) = { post: "/v1/{instance_name=**}/assets:pushBlob" body: "*" }; |
| } |
| |
| rpc PushDirectory(PushDirectoryRequest) returns (PushDirectoryResponse) { |
| option (google.api.http) = { post: "/v1/{instance_name=**}/assets:pushDirectory" body: "*" }; |
| } |
| } |
| |
| // A request message for |
| // [Push.PushBlob][build.bazel.remote.asset.v1.Push.PushBlob]. |
| message PushBlobRequest { |
| // 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 URI(s) of the content to associate. If multiple URIs are specified, the |
| // pushed content will be available to fetch by specifying any of them. |
| repeated string uris = 2; |
| |
| // Qualifiers sub-specifying the content that is being pushed - see comments |
| // on [Qualifier][build.bazel.remote.asset.v1.Qualifier]. |
| // The same qualifiers apply to all URIs. |
| repeated Qualifier qualifiers = 3; |
| |
| // A time after which this content should stop being returned via [FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob]. |
| // Servers *MAY* expire content early, e.g. due to storage pressure. |
| google.protobuf.Timestamp expire_at = 4; |
| |
| // The blob to associate. |
| build.bazel.remote.execution.v2.Digest blob_digest = 5; |
| |
| // Referenced blobs or directories that need to not expire before expiration |
| // of this association, in addition to `blob_digest` itself. |
| // These fields are hints - clients *MAY* omit them, and servers *SHOULD* |
| // respect them, at the risk of increased incidents of Fetch responses |
| // indirectly referencing unavailable blobs. |
| repeated build.bazel.remote.execution.v2.Digest references_blobs = 6; |
| repeated build.bazel.remote.execution.v2.Digest references_directories = 7; |
| } |
| |
| // A response message for |
| // [Push.PushBlob][build.bazel.remote.asset.v1.Push.PushBlob]. |
| message PushBlobResponse { /* empty */ } |
| |
| // A request message for |
| // [Push.PushDirectory][build.bazel.remote.asset.v1.Push.PushDirectory]. |
| message PushDirectoryRequest { |
| // 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 URI(s) of the content to associate. If multiple URIs are specified, the |
| // pushed content will be available to fetch by specifying any of them. |
| repeated string uris = 2; |
| |
| // Qualifiers sub-specifying the content that is being pushed - see comments |
| // on [Qualifier][build.bazel.remote.asset.v1.Qualifier]. |
| // The same qualifiers apply to all URIs. |
| repeated Qualifier qualifiers = 3; |
| |
| // A time after which this content should stop being returned via |
| // [FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory]. |
| // Servers *MAY* expire content early, e.g. due to storage pressure. |
| google.protobuf.Timestamp expire_at = 4; |
| |
| // Directory to associate |
| build.bazel.remote.execution.v2.Digest root_directory_digest = 5; |
| |
| // Referenced blobs or directories that need to not expire before expiration |
| // of this association, in addition to `root_directory_digest` itself. |
| // These fields are hints - clients *MAY* omit them, and servers *SHOULD* |
| // respect them, at the risk of increased incidents of Fetch responses |
| // indirectly referencing unavailable blobs. |
| repeated build.bazel.remote.execution.v2.Digest references_blobs = 6; |
| repeated build.bazel.remote.execution.v2.Digest references_directories = 7; |
| } |
| |
| // A response message for |
| // [Push.PushDirectory][build.bazel.remote.asset.v1.Push.PushDirectory]. |
| message PushDirectoryResponse { /* empty */ } |