From 5a7b1a472165a0ea47b9060089855385fe351193 Mon Sep 17 00:00:00 2001 From: Takuto Ikuta Date: Wed, 12 Aug 2020 20:13:43 +0900 Subject: [PATCH] Include comments in generated *.pb.go for godoc (#161) --- .bazelrc | 2 + .../bazel/remote/asset/v1/remote_asset.pb.go | 465 ++++- .../execution/v2/remote_execution.pb.go | 1510 +++++++++++++++-- .../logstream/v1/remote_logstream.pb.go | 44 +- build/bazel/semver/semver.pb.go | 13 +- 5 files changed, 1831 insertions(+), 203 deletions(-) create mode 100644 .bazelrc diff --git a/.bazelrc b/.bazelrc new file mode 100644 index 00000000..936a7e88 --- /dev/null +++ b/.bazelrc @@ -0,0 +1,2 @@ +# Include comments in generated code for godoc. +build --experimental_proto_descriptor_sets_include_source_info diff --git a/build/bazel/remote/asset/v1/remote_asset.pb.go b/build/bazel/remote/asset/v1/remote_asset.pb.go index 51c1fba7..d1eee335 100644 --- a/build/bazel/remote/asset/v1/remote_asset.pb.go +++ b/build/bazel/remote/asset/v1/remote_asset.pb.go @@ -29,8 +29,27 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package +// 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. type Qualifier struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // 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. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The "value" of the qualifier. Semantics will be dictated by the name. Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -76,15 +95,57 @@ func (m *Qualifier) GetValue() string { return "" } +// A request message for +// [Fetch.FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob]. type FetchBlobRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - Timeout *duration.Duration `protobuf:"bytes,2,opt,name=timeout,proto3" json:"timeout,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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]. + Timeout *duration.Duration `protobuf:"bytes,2,opt,name=timeout,proto3" json:"timeout,omitempty"` + // 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. OldestContentAccepted *timestamp.Timestamp `protobuf:"bytes,3,opt,name=oldest_content_accepted,json=oldestContentAccepted,proto3" json:"oldest_content_accepted,omitempty"` - Uris []string `protobuf:"bytes,4,rep,name=uris,proto3" json:"uris,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,5,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + Uris []string `protobuf:"bytes,4,rep,name=uris,proto3" json:"uris,omitempty"` + // 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. + Qualifiers []*Qualifier `protobuf:"bytes,5,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *FetchBlobRequest) Reset() { *m = FetchBlobRequest{} } @@ -147,15 +208,34 @@ func (m *FetchBlobRequest) GetQualifiers() []*Qualifier { return nil } +// A response message for +// [Fetch.FetchBlob][build.bazel.remote.asset.v1.Fetch.FetchBlob]. type FetchBlobResponse struct { - Status *status.Status `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` - Uri string `protobuf:"bytes,2,opt,name=uri,proto3" json:"uri,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - ExpiresAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expires_at,json=expiresAt,proto3" json:"expires_at,omitempty"` - BlobDigest *v2.Digest `protobuf:"bytes,5,opt,name=blob_digest,json=blobDigest,proto3" json:"blob_digest,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + Status *status.Status `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` + // The uri from the request that resulted in a successful retrieval, or from + // which the error indicated in `status` was obtained. + Uri string `protobuf:"bytes,2,opt,name=uri,proto3" json:"uri,omitempty"` + // Any qualifiers known to the server and of interest to clients. + Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + // A minimum timestamp the content is expected to be available through. + // Servers *MAY* omit this field, if not known with confidence. + ExpiresAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expires_at,json=expiresAt,proto3" json:"expires_at,omitempty"` + // The result of the fetch, if the status had code `OK`. + // The digest of the file's contents, available for download through the CAS. + BlobDigest *v2.Digest `protobuf:"bytes,5,opt,name=blob_digest,json=blobDigest,proto3" json:"blob_digest,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *FetchBlobResponse) Reset() { *m = FetchBlobResponse{} } @@ -218,15 +298,51 @@ func (m *FetchBlobResponse) GetBlobDigest() *v2.Digest { return nil } +// A request message for +// [Fetch.FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory]. type FetchDirectoryRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - Timeout *duration.Duration `protobuf:"bytes,2,opt,name=timeout,proto3" json:"timeout,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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]. + Timeout *duration.Duration `protobuf:"bytes,2,opt,name=timeout,proto3" json:"timeout,omitempty"` + // 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. OldestContentAccepted *timestamp.Timestamp `protobuf:"bytes,3,opt,name=oldest_content_accepted,json=oldestContentAccepted,proto3" json:"oldest_content_accepted,omitempty"` - Uris []string `protobuf:"bytes,4,rep,name=uris,proto3" json:"uris,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,5,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + Uris []string `protobuf:"bytes,4,rep,name=uris,proto3" json:"uris,omitempty"` + // 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. + Qualifiers []*Qualifier `protobuf:"bytes,5,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *FetchDirectoryRequest) Reset() { *m = FetchDirectoryRequest{} } @@ -289,15 +405,35 @@ func (m *FetchDirectoryRequest) GetQualifiers() []*Qualifier { return nil } +// A response message for +// [Fetch.FetchDirectory][build.bazel.remote.asset.v1.Fetch.FetchDirectory]. type FetchDirectoryResponse struct { - Status *status.Status `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` - Uri string `protobuf:"bytes,2,opt,name=uri,proto3" json:"uri,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - ExpiresAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expires_at,json=expiresAt,proto3" json:"expires_at,omitempty"` - RootDirectoryDigest *v2.Digest `protobuf:"bytes,5,opt,name=root_directory_digest,json=rootDirectoryDigest,proto3" json:"root_directory_digest,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + Status *status.Status `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"` + // The uri from the request that resulted in a successful retrieval, or from + // which the error indicated in `status` was obtained. + Uri string `protobuf:"bytes,2,opt,name=uri,proto3" json:"uri,omitempty"` + // Any qualifiers known to the server and of interest to clients. + Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + // A minimum timestamp the content is expected to be available through. + // Servers *MAY* omit this field, if not known with confidence. + ExpiresAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expires_at,json=expiresAt,proto3" json:"expires_at,omitempty"` + // The result of the fetch, if the status had code `OK`. + // the root digest of a directory tree, suitable for fetching via + // [ContentAddressableStorage.GetTree]. + RootDirectoryDigest *v2.Digest `protobuf:"bytes,5,opt,name=root_directory_digest,json=rootDirectoryDigest,proto3" json:"root_directory_digest,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *FetchDirectoryResponse) Reset() { *m = FetchDirectoryResponse{} } @@ -360,17 +496,37 @@ func (m *FetchDirectoryResponse) GetRootDirectoryDigest() *v2.Digest { return nil } +// A request message for +// [Push.PushBlob][build.bazel.remote.asset.v1.Push.PushBlob]. type PushBlobRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - Uris []string `protobuf:"bytes,2,rep,name=uris,proto3" json:"uris,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - ExpireAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expire_at,json=expireAt,proto3" json:"expire_at,omitempty"` - BlobDigest *v2.Digest `protobuf:"bytes,5,opt,name=blob_digest,json=blobDigest,proto3" json:"blob_digest,omitempty"` - ReferencesBlobs []*v2.Digest `protobuf:"bytes,6,rep,name=references_blobs,json=referencesBlobs,proto3" json:"references_blobs,omitempty"` - ReferencesDirectories []*v2.Digest `protobuf:"bytes,7,rep,name=references_directories,json=referencesDirectories,proto3" json:"references_directories,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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. + Uris []string `protobuf:"bytes,2,rep,name=uris,proto3" json:"uris,omitempty"` + // 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. + Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + // 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. + ExpireAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expire_at,json=expireAt,proto3" json:"expire_at,omitempty"` + // The blob to associate. + BlobDigest *v2.Digest `protobuf:"bytes,5,opt,name=blob_digest,json=blobDigest,proto3" json:"blob_digest,omitempty"` + // 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. + ReferencesBlobs []*v2.Digest `protobuf:"bytes,6,rep,name=references_blobs,json=referencesBlobs,proto3" json:"references_blobs,omitempty"` + ReferencesDirectories []*v2.Digest `protobuf:"bytes,7,rep,name=references_directories,json=referencesDirectories,proto3" json:"references_directories,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *PushBlobRequest) Reset() { *m = PushBlobRequest{} } @@ -447,6 +603,8 @@ func (m *PushBlobRequest) GetReferencesDirectories() []*v2.Digest { return nil } +// A response message for +// [Push.PushBlob][build.bazel.remote.asset.v1.Push.PushBlob]. type PushBlobResponse struct { XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -478,17 +636,38 @@ func (m *PushBlobResponse) XXX_DiscardUnknown() { var xxx_messageInfo_PushBlobResponse proto.InternalMessageInfo +// A request message for +// [Push.PushDirectory][build.bazel.remote.asset.v1.Push.PushDirectory]. type PushDirectoryRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - Uris []string `protobuf:"bytes,2,rep,name=uris,proto3" json:"uris,omitempty"` - Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` - ExpireAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expire_at,json=expireAt,proto3" json:"expire_at,omitempty"` - RootDirectoryDigest *v2.Digest `protobuf:"bytes,5,opt,name=root_directory_digest,json=rootDirectoryDigest,proto3" json:"root_directory_digest,omitempty"` - ReferencesBlobs []*v2.Digest `protobuf:"bytes,6,rep,name=references_blobs,json=referencesBlobs,proto3" json:"references_blobs,omitempty"` - ReferencesDirectories []*v2.Digest `protobuf:"bytes,7,rep,name=references_directories,json=referencesDirectories,proto3" json:"references_directories,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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. + Uris []string `protobuf:"bytes,2,rep,name=uris,proto3" json:"uris,omitempty"` + // 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. + Qualifiers []*Qualifier `protobuf:"bytes,3,rep,name=qualifiers,proto3" json:"qualifiers,omitempty"` + // 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. + ExpireAt *timestamp.Timestamp `protobuf:"bytes,4,opt,name=expire_at,json=expireAt,proto3" json:"expire_at,omitempty"` + // Directory to associate + RootDirectoryDigest *v2.Digest `protobuf:"bytes,5,opt,name=root_directory_digest,json=rootDirectoryDigest,proto3" json:"root_directory_digest,omitempty"` + // 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. + ReferencesBlobs []*v2.Digest `protobuf:"bytes,6,rep,name=references_blobs,json=referencesBlobs,proto3" json:"references_blobs,omitempty"` + ReferencesDirectories []*v2.Digest `protobuf:"bytes,7,rep,name=references_directories,json=referencesDirectories,proto3" json:"references_directories,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *PushDirectoryRequest) Reset() { *m = PushDirectoryRequest{} } @@ -565,6 +744,8 @@ func (m *PushDirectoryRequest) GetReferencesDirectories() []*v2.Digest { return nil } +// A response message for +// [Push.PushDirectory][build.bazel.remote.asset.v1.Push.PushDirectory]. type PushDirectoryResponse struct { XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -680,6 +861,63 @@ const _ = grpc.SupportPackageIsVersion4 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type FetchClient interface { + // 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. FetchBlob(ctx context.Context, in *FetchBlobRequest, opts ...grpc.CallOption) (*FetchBlobResponse, error) FetchDirectory(ctx context.Context, in *FetchDirectoryRequest, opts ...grpc.CallOption) (*FetchDirectoryResponse, error) } @@ -712,6 +950,63 @@ func (c *fetchClient) FetchDirectory(ctx context.Context, in *FetchDirectoryRequ // FetchServer is the server API for Fetch service. type FetchServer interface { + // 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. FetchBlob(context.Context, *FetchBlobRequest) (*FetchBlobResponse, error) FetchDirectory(context.Context, *FetchDirectoryRequest) (*FetchDirectoryResponse, error) } @@ -788,6 +1083,40 @@ var _Fetch_serviceDesc = grpc.ServiceDesc{ // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type PushClient interface { + // 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. PushBlob(ctx context.Context, in *PushBlobRequest, opts ...grpc.CallOption) (*PushBlobResponse, error) PushDirectory(ctx context.Context, in *PushDirectoryRequest, opts ...grpc.CallOption) (*PushDirectoryResponse, error) } @@ -820,6 +1149,40 @@ func (c *pushClient) PushDirectory(ctx context.Context, in *PushDirectoryRequest // PushServer is the server API for Push service. type PushServer interface { + // 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. PushBlob(context.Context, *PushBlobRequest) (*PushBlobResponse, error) PushDirectory(context.Context, *PushDirectoryRequest) (*PushDirectoryResponse, error) } diff --git a/build/bazel/remote/execution/v2/remote_execution.pb.go b/build/bazel/remote/execution/v2/remote_execution.pb.go index 7e4e53a8..4389e422 100755 --- a/build/bazel/remote/execution/v2/remote_execution.pb.go +++ b/build/bazel/remote/execution/v2/remote_execution.pb.go @@ -34,11 +34,16 @@ const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package type ExecutionStage_Value int32 const ( - ExecutionStage_UNKNOWN ExecutionStage_Value = 0 + // Invalid value. + ExecutionStage_UNKNOWN ExecutionStage_Value = 0 + // Checking the result against the cache. ExecutionStage_CACHE_CHECK ExecutionStage_Value = 1 - ExecutionStage_QUEUED ExecutionStage_Value = 2 - ExecutionStage_EXECUTING ExecutionStage_Value = 3 - ExecutionStage_COMPLETED ExecutionStage_Value = 4 + // Currently idle, awaiting a free machine to execute. + ExecutionStage_QUEUED ExecutionStage_Value = 2 + // Currently being executed by a worker. + ExecutionStage_EXECUTING ExecutionStage_Value = 3 + // Finished execution. + ExecutionStage_COMPLETED ExecutionStage_Value = 4 ) var ExecutionStage_Value_name = map[int32]string{ @@ -68,13 +73,24 @@ func (ExecutionStage_Value) EnumDescriptor() ([]byte, []int) { type DigestFunction_Value int32 const ( + // It is an error for the server to return this value. DigestFunction_UNKNOWN DigestFunction_Value = 0 - DigestFunction_SHA256 DigestFunction_Value = 1 - DigestFunction_SHA1 DigestFunction_Value = 2 - DigestFunction_MD5 DigestFunction_Value = 3 - DigestFunction_VSO DigestFunction_Value = 4 - DigestFunction_SHA384 DigestFunction_Value = 5 - DigestFunction_SHA512 DigestFunction_Value = 6 + // The SHA-256 digest function. + DigestFunction_SHA256 DigestFunction_Value = 1 + // The SHA-1 digest function. + DigestFunction_SHA1 DigestFunction_Value = 2 + // The MD5 digest function. + DigestFunction_MD5 DigestFunction_Value = 3 + // The Microsoft "VSO-Hash" paged SHA256 digest function. + // See https://github.com/microsoft/BuildXL/blob/master/Documentation/Specs/PagedHash.md . + DigestFunction_VSO DigestFunction_Value = 4 + // The SHA-384 digest function. + DigestFunction_SHA384 DigestFunction_Value = 5 + // The SHA-512 digest function. + DigestFunction_SHA512 DigestFunction_Value = 6 + // Murmur3 128-bit digest function, x64 variant. Note that this is not a + // cryptographic hash function and its collision properties are not strongly guaranteed. + // See https://github.com/aappleby/smhasher/wiki/MurmurHash3 . DigestFunction_MURMUR3 DigestFunction_Value = 7 ) @@ -111,9 +127,16 @@ func (DigestFunction_Value) EnumDescriptor() ([]byte, []int) { type SymlinkAbsolutePathStrategy_Value int32 const ( - SymlinkAbsolutePathStrategy_UNKNOWN SymlinkAbsolutePathStrategy_Value = 0 + // Invalid value. + SymlinkAbsolutePathStrategy_UNKNOWN SymlinkAbsolutePathStrategy_Value = 0 + // Server will return an `INVALID_ARGUMENT` on input symlinks with absolute + // targets. + // If an action tries to create an output symlink with an absolute target, a + // `FAILED_PRECONDITION` will be returned. SymlinkAbsolutePathStrategy_DISALLOWED SymlinkAbsolutePathStrategy_Value = 1 - SymlinkAbsolutePathStrategy_ALLOWED SymlinkAbsolutePathStrategy_Value = 2 + // Server will allow symlink targets to escape the input root tree, possibly + // resulting in non-hermetic builds. + SymlinkAbsolutePathStrategy_ALLOWED SymlinkAbsolutePathStrategy_Value = 2 ) var SymlinkAbsolutePathStrategy_Value_name = map[int32]string{ @@ -136,15 +159,70 @@ func (SymlinkAbsolutePathStrategy_Value) EnumDescriptor() ([]byte, []int) { return fileDescriptor_c43847ba40caac95, []int{39, 0} } +// An `Action` captures all the information about an execution which is required +// to reproduce it. +// +// `Action`s are the core component of the [Execution] service. A single +// `Action` represents a repeatable action that can be performed by the +// execution service. `Action`s can be succinctly identified by the digest of +// their wire format encoding and, once an `Action` has been executed, will be +// cached in the action cache. Future requests can then use the cached result +// rather than needing to run afresh. +// +// When a server completes execution of an +// [Action][build.bazel.remote.execution.v2.Action], it MAY choose to +// cache the [result][build.bazel.remote.execution.v2.ActionResult] in +// the [ActionCache][build.bazel.remote.execution.v2.ActionCache] unless +// `do_not_cache` is `true`. Clients SHOULD expect the server to do so. By +// default, future calls to +// [Execute][build.bazel.remote.execution.v2.Execution.Execute] the same +// `Action` will also serve their results from the cache. Clients must take care +// to understand the caching behaviour. Ideally, all `Action`s will be +// reproducible so that serving a result from cache is always desirable and +// correct. type Action struct { - CommandDigest *Digest `protobuf:"bytes,1,opt,name=command_digest,json=commandDigest,proto3" json:"command_digest,omitempty"` - InputRootDigest *Digest `protobuf:"bytes,2,opt,name=input_root_digest,json=inputRootDigest,proto3" json:"input_root_digest,omitempty"` - Timeout *duration.Duration `protobuf:"bytes,6,opt,name=timeout,proto3" json:"timeout,omitempty"` - DoNotCache bool `protobuf:"varint,7,opt,name=do_not_cache,json=doNotCache,proto3" json:"do_not_cache,omitempty"` - Salt []byte `protobuf:"bytes,9,opt,name=salt,proto3" json:"salt,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The digest of the [Command][build.bazel.remote.execution.v2.Command] + // to run, which MUST be present in the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + CommandDigest *Digest `protobuf:"bytes,1,opt,name=command_digest,json=commandDigest,proto3" json:"command_digest,omitempty"` + // The digest of the root + // [Directory][build.bazel.remote.execution.v2.Directory] for the input + // files. The files in the directory tree are available in the correct + // location on the build machine before the command is executed. The root + // directory, as well as every subdirectory and content blob referred to, MUST + // be in the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + InputRootDigest *Digest `protobuf:"bytes,2,opt,name=input_root_digest,json=inputRootDigest,proto3" json:"input_root_digest,omitempty"` + // A timeout after which the execution should be killed. If the timeout is + // absent, then the client is specifying that the execution should continue + // as long as the server will let it. The server SHOULD impose a timeout if + // the client does not specify one, however, if the client does specify a + // timeout that is longer than the server's maximum timeout, the server MUST + // reject the request. + // + // The timeout is a part of the + // [Action][build.bazel.remote.execution.v2.Action] message, and + // therefore two `Actions` with different timeouts are different, even if they + // are otherwise identical. This is because, if they were not, running an + // `Action` with a lower timeout than is required might result in a cache hit + // from an execution run with a longer timeout, hiding the fact that the + // timeout is too short. By encoding it directly in the `Action`, a lower + // timeout will result in a cache miss and the execution timeout will fail + // immediately, rather than whenever the cache entry gets evicted. + Timeout *duration.Duration `protobuf:"bytes,6,opt,name=timeout,proto3" json:"timeout,omitempty"` + // If true, then the `Action`'s result cannot be cached, and in-flight + // requests for the same `Action` may not be merged. + DoNotCache bool `protobuf:"varint,7,opt,name=do_not_cache,json=doNotCache,proto3" json:"do_not_cache,omitempty"` + // An optional additional salt value used to place this `Action` into a + // separate cache namespace from other instances having the same field + // contents. This salt typically comes from operational configuration + // specific to sources such as repo and service configuration, + // and allows disowning an entire set of ActionResults that might have been + // poisoned by buggy software or tool failures. + Salt []byte `protobuf:"bytes,9,opt,name=salt,proto3" json:"salt,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Action) Reset() { *m = Action{} } @@ -207,18 +285,135 @@ func (m *Action) GetSalt() []byte { return nil } +// A `Command` is the actual command executed by a worker running an +// [Action][build.bazel.remote.execution.v2.Action] and specifications of its +// environment. +// +// Except as otherwise required, the environment (such as which system +// libraries or binaries are available, and what filesystems are mounted where) +// is defined by and specific to the implementation of the remote execution API. type Command struct { - Arguments []string `protobuf:"bytes,1,rep,name=arguments,proto3" json:"arguments,omitempty"` + // The arguments to the command. The first argument must be the path to the + // executable, which must be either a relative path, in which case it is + // evaluated with respect to the input root, or an absolute path. + Arguments []string `protobuf:"bytes,1,rep,name=arguments,proto3" json:"arguments,omitempty"` + // The environment variables to set when running the program. The worker may + // provide its own default environment variables; these defaults can be + // overridden using this field. Additional variables can also be specified. + // + // In order to ensure that equivalent + // [Command][build.bazel.remote.execution.v2.Command]s always hash to the same + // value, the environment variables MUST be lexicographically sorted by name. + // Sorting of strings is done by code point, equivalently, by the UTF-8 bytes. EnvironmentVariables []*Command_EnvironmentVariable `protobuf:"bytes,2,rep,name=environment_variables,json=environmentVariables,proto3" json:"environment_variables,omitempty"` - OutputFiles []string `protobuf:"bytes,3,rep,name=output_files,json=outputFiles,proto3" json:"output_files,omitempty"` - OutputDirectories []string `protobuf:"bytes,4,rep,name=output_directories,json=outputDirectories,proto3" json:"output_directories,omitempty"` - OutputPaths []string `protobuf:"bytes,7,rep,name=output_paths,json=outputPaths,proto3" json:"output_paths,omitempty"` - Platform *Platform `protobuf:"bytes,5,opt,name=platform,proto3" json:"platform,omitempty"` - WorkingDirectory string `protobuf:"bytes,6,opt,name=working_directory,json=workingDirectory,proto3" json:"working_directory,omitempty"` - OutputNodeProperties []string `protobuf:"bytes,8,rep,name=output_node_properties,json=outputNodeProperties,proto3" json:"output_node_properties,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // A list of the output files that the client expects to retrieve from the + // action. Only the listed files, as well as directories listed in + // `output_directories`, will be returned to the client as output. + // Other files or directories that may be created during command execution + // are discarded. + // + // The paths are relative to the working directory of the action execution. + // The paths are specified using a single forward slash (`/`) as a path + // separator, even if the execution platform natively uses a different + // separator. The path MUST NOT include a trailing slash, nor a leading slash, + // being a relative path. + // + // In order to ensure consistent hashing of the same Action, the output paths + // MUST be sorted lexicographically by code point (or, equivalently, by UTF-8 + // bytes). + // + // An output file cannot be duplicated, be a parent of another output file, or + // have the same path as any of the listed output directories. + // + // Directories leading up to the output files are created by the worker prior + // to execution, even if they are not explicitly part of the input root. + // + // DEPRECATED since v2.1: Use `output_paths` instead. + OutputFiles []string `protobuf:"bytes,3,rep,name=output_files,json=outputFiles,proto3" json:"output_files,omitempty"` + // A list of the output directories that the client expects to retrieve from + // the action. Only the listed directories will be returned (an entire + // directory structure will be returned as a + // [Tree][build.bazel.remote.execution.v2.Tree] message digest, see + // [OutputDirectory][build.bazel.remote.execution.v2.OutputDirectory]), as + // well as files listed in `output_files`. Other files or directories that + // may be created during command execution are discarded. + // + // The paths are relative to the working directory of the action execution. + // The paths are specified using a single forward slash (`/`) as a path + // separator, even if the execution platform natively uses a different + // separator. The path MUST NOT include a trailing slash, nor a leading slash, + // being a relative path. The special value of empty string is allowed, + // although not recommended, and can be used to capture the entire working + // directory tree, including inputs. + // + // In order to ensure consistent hashing of the same Action, the output paths + // MUST be sorted lexicographically by code point (or, equivalently, by UTF-8 + // bytes). + // + // An output directory cannot be duplicated or have the same path as any of + // the listed output files. An output directory is allowed to be a parent of + // another output directory. + // + // Directories leading up to the output directories (but not the output + // directories themselves) are created by the worker prior to execution, even + // if they are not explicitly part of the input root. + // + // DEPRECATED since 2.1: Use `output_paths` instead. + OutputDirectories []string `protobuf:"bytes,4,rep,name=output_directories,json=outputDirectories,proto3" json:"output_directories,omitempty"` + // A list of the output paths that the client expects to retrieve from the + // action. Only the listed paths will be returned to the client as output. + // The type of the output (file or directory) is not specified, and will be + // determined by the server after action execution. If the resulting path is + // a file, it will be returned in an + // [OutputFile][build.bazel.remote.execution.v2.OutputFile]) typed field. + // If the path is a directory, the entire directory structure will be returned + // as a [Tree][build.bazel.remote.execution.v2.Tree] message digest, see + // [OutputDirectory][build.bazel.remote.execution.v2.OutputDirectory]) + // Other files or directories that may be created during command execution + // are discarded. + // + // The paths are relative to the working directory of the action execution. + // The paths are specified using a single forward slash (`/`) as a path + // separator, even if the execution platform natively uses a different + // separator. The path MUST NOT include a trailing slash, nor a leading slash, + // being a relative path. + // + // In order to ensure consistent hashing of the same Action, the output paths + // MUST be deduplicated and sorted lexicographically by code point (or, + // equivalently, by UTF-8 bytes). + // + // Directories leading up to the output paths are created by the worker prior + // to execution, even if they are not explicitly part of the input root. + // + // New in v2.1: this field supersedes the DEPRECATED `output_files` and + // `output_directories` fields. If `output_paths` is used, `output_files` and + // `output_directories` will be ignored! + OutputPaths []string `protobuf:"bytes,7,rep,name=output_paths,json=outputPaths,proto3" json:"output_paths,omitempty"` + // The platform requirements 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. + // A detailed lexicon for this can be found in the accompanying platform.md. + Platform *Platform `protobuf:"bytes,5,opt,name=platform,proto3" json:"platform,omitempty"` + // The working directory, relative to the input root, for the command to run + // in. It must be a directory which exists in the input tree. If it is left + // empty, then the action is run in the input root. + WorkingDirectory string `protobuf:"bytes,6,opt,name=working_directory,json=workingDirectory,proto3" json:"working_directory,omitempty"` + // A list of keys for node properties the client expects to retrieve for + // output files and directories. Keys are either names of string-based + // [NodeProperty][build.bazel.remote.execution.v2.NodeProperty] or + // names of fields in [NodeProperties][build.bazel.remote.execution.v2.NodeProperties]. + // In order to ensure that equivalent `Action`s always hash to the same + // value, the node properties MUST be lexicographically sorted by name. + // Sorting of strings is done by code point, equivalently, by the UTF-8 bytes. + // + // The interpretation of string-based properties is server-dependent. If a + // property is not recognized by the server, the server will return an + // `INVALID_ARGUMENT`. + OutputNodeProperties []string `protobuf:"bytes,8,rep,name=output_node_properties,json=outputNodeProperties,proto3" json:"output_node_properties,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Command) Reset() { *m = Command{} } @@ -302,8 +497,12 @@ func (m *Command) GetOutputNodeProperties() []string { return nil } +// An `EnvironmentVariable` is one variable to set in the running program's +// environment. type Command_EnvironmentVariable struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The variable name. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The variable value. Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -349,7 +548,16 @@ func (m *Command_EnvironmentVariable) GetValue() string { return "" } +// A `Platform` is a set of requirements, such as hardware, operating system, or +// compiler toolchain, for an +// [Action][build.bazel.remote.execution.v2.Action]'s execution +// environment. A `Platform` is represented as a series of key-value pairs +// representing the properties that are required of the platform. type Platform struct { + // The properties that make up this platform. In order to ensure that + // equivalent `Platform`s always hash to the same value, the properties MUST + // be lexicographically sorted by name, and then by value. Sorting of strings + // is done by code point, equivalently, by the UTF-8 bytes. Properties []*Platform_Property `protobuf:"bytes,1,rep,name=properties,proto3" json:"properties,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -388,8 +596,27 @@ func (m *Platform) GetProperties() []*Platform_Property { return nil } +// A single property for the environment. The server is responsible for +// specifying the property `name`s that it accepts. If an unknown `name` is +// provided in the requirements for an +// [Action][build.bazel.remote.execution.v2.Action], the server SHOULD +// reject the execution request. If permitted by the server, the same `name` +// may occur multiple times. +// +// The server is also responsible for specifying the interpretation of +// property `value`s. For instance, a property describing how much RAM must be +// available may be interpreted as allowing a worker with 16GB to fulfill a +// request for 8GB, while a property describing the OS environment on which +// the action must be performed may require an exact match with the worker's +// OS. +// +// The server MAY use the `value` of one or more properties to determine how +// it sets up the execution environment, such as by making specific system +// files available to the worker. type Platform_Property struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The property name. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The property value. Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -435,14 +662,93 @@ func (m *Platform_Property) GetValue() string { return "" } +// A `Directory` represents a directory node in a file tree, containing zero or +// more children [FileNodes][build.bazel.remote.execution.v2.FileNode], +// [DirectoryNodes][build.bazel.remote.execution.v2.DirectoryNode] and +// [SymlinkNodes][build.bazel.remote.execution.v2.SymlinkNode]. +// Each `Node` contains its name in the directory, either the digest of its +// content (either a file blob or a `Directory` proto) or a symlink target, as +// well as possibly some metadata about the file or directory. +// +// In order to ensure that two equivalent directory trees hash to the same +// value, the following restrictions MUST be obeyed when constructing a +// a `Directory`: +// +// * Every child in the directory must have a path of exactly one segment. +// Multiple levels of directory hierarchy may not be collapsed. +// * Each child in the directory must have a unique path segment (file name). +// Note that while the API itself is case-sensitive, the environment where +// the Action is executed may or may not be case-sensitive. That is, it is +// legal to call the API with a Directory that has both "Foo" and "foo" as +// children, but the Action may be rejected by the remote system upon +// execution. +// * The files, directories and symlinks in the directory must each be sorted +// in lexicographical order by path. The path strings must be sorted by code +// point, equivalently, by UTF-8 bytes. +// * The [NodeProperties][build.bazel.remote.execution.v2.NodeProperty] of files, +// directories, and symlinks must be sorted in lexicographical order by +// property name. +// +// A `Directory` that obeys the restrictions is said to be in canonical form. +// +// As an example, the following could be used for a file named `bar` and a +// directory named `foo` with an executable file named `baz` (hashes shortened +// for readability): +// +// ```json +// // (Directory proto) +// { +// files: [ +// { +// name: "bar", +// digest: { +// hash: "4a73bc9d03...", +// size: 65534 +// }, +// node_properties: [ +// { +// "name": "MTime", +// "value": "2017-01-15T01:30:15.01Z" +// } +// ] +// } +// ], +// directories: [ +// { +// name: "foo", +// digest: { +// hash: "4cf2eda940...", +// size: 43 +// } +// } +// ] +// } +// +// // (Directory proto with hash "4cf2eda940..." and size 43) +// { +// files: [ +// { +// name: "baz", +// digest: { +// hash: "b2c941073e...", +// size: 1294, +// }, +// is_executable: true +// } +// ] +// } +// ``` type Directory struct { - Files []*FileNode `protobuf:"bytes,1,rep,name=files,proto3" json:"files,omitempty"` - Directories []*DirectoryNode `protobuf:"bytes,2,rep,name=directories,proto3" json:"directories,omitempty"` - Symlinks []*SymlinkNode `protobuf:"bytes,3,rep,name=symlinks,proto3" json:"symlinks,omitempty"` - NodeProperties *NodeProperties `protobuf:"bytes,5,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The files in the directory. + Files []*FileNode `protobuf:"bytes,1,rep,name=files,proto3" json:"files,omitempty"` + // The subdirectories in the directory. + Directories []*DirectoryNode `protobuf:"bytes,2,rep,name=directories,proto3" json:"directories,omitempty"` + // The symlinks in the directory. + Symlinks []*SymlinkNode `protobuf:"bytes,3,rep,name=symlinks,proto3" json:"symlinks,omitempty"` + NodeProperties *NodeProperties `protobuf:"bytes,5,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Directory) Reset() { *m = Directory{} } @@ -498,8 +804,15 @@ func (m *Directory) GetNodeProperties() *NodeProperties { return nil } +// A single property for [FileNodes][build.bazel.remote.execution.v2.FileNode], +// [DirectoryNodes][build.bazel.remote.execution.v2.DirectoryNode], and +// [SymlinkNodes][build.bazel.remote.execution.v2.SymlinkNode]. The server is +// responsible for specifying the property `name`s that it accepts. If +// permitted by the server, the same `name` may occur multiple times. type NodeProperty struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The property name. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The property value. Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -545,9 +858,18 @@ func (m *NodeProperty) GetValue() string { return "" } +// Node properties for [FileNodes][build.bazel.remote.execution.v2.FileNode], +// [DirectoryNodes][build.bazel.remote.execution.v2.DirectoryNode], and +// [SymlinkNodes][build.bazel.remote.execution.v2.SymlinkNode]. The server is +// responsible for specifying the properties that it accepts. +// type NodeProperties struct { - Properties []*NodeProperty `protobuf:"bytes,1,rep,name=properties,proto3" json:"properties,omitempty"` - Mtime *timestamp.Timestamp `protobuf:"bytes,2,opt,name=mtime,proto3" json:"mtime,omitempty"` + // A list of string-based + // [NodeProperties][build.bazel.remote.execution.v2.NodeProperty]. + Properties []*NodeProperty `protobuf:"bytes,1,rep,name=properties,proto3" json:"properties,omitempty"` + // The file's last modification timestamp. + Mtime *timestamp.Timestamp `protobuf:"bytes,2,opt,name=mtime,proto3" json:"mtime,omitempty"` + // The UNIX file mode, e.g., 0755. UnixMode *wrappers.UInt32Value `protobuf:"bytes,3,opt,name=unix_mode,json=unixMode,proto3" json:"unix_mode,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -600,9 +922,13 @@ func (m *NodeProperties) GetUnixMode() *wrappers.UInt32Value { return nil } +// A `FileNode` represents a single file and associated metadata. type FileNode struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - Digest *Digest `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"` + // The name of the file. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The digest of the file's content. + Digest *Digest `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"` + // True if file is executable, false otherwise. IsExecutable bool `protobuf:"varint,4,opt,name=is_executable,json=isExecutable,proto3" json:"is_executable,omitempty"` NodeProperties *NodeProperties `protobuf:"bytes,6,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -663,8 +989,16 @@ func (m *FileNode) GetNodeProperties() *NodeProperties { return nil } +// A `DirectoryNode` represents a child of a +// [Directory][build.bazel.remote.execution.v2.Directory] which is itself +// a `Directory` and its associated metadata. type DirectoryNode struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The name of the directory. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The digest of the + // [Directory][build.bazel.remote.execution.v2.Directory] object + // represented. See [Digest][build.bazel.remote.execution.v2.Digest] + // for information about how to take the digest of a proto message. Digest *Digest `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -710,8 +1044,19 @@ func (m *DirectoryNode) GetDigest() *Digest { return nil } +// A `SymlinkNode` represents a symbolic link. type SymlinkNode struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The name of the symlink. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The target path of the symlink. The path separator is a forward slash `/`. + // The target path can be relative to the parent directory of the symlink or + // it can be an absolute path starting with `/`. Support for absolute paths + // can be checked using the [Capabilities][build.bazel.remote.execution.v2.Capabilities] + // API. `..` components are allowed anywhere in the target path as logical + // canonicalization may lead to different behavior in the presence of + // directory symlinks (e.g. `foo/../bar` may not be the same as `bar`). + // To reduce potential cache misses, canonicalization is still recommended + // where this is possible without impacting correctness. Target string `protobuf:"bytes,2,opt,name=target,proto3" json:"target,omitempty"` NodeProperties *NodeProperties `protobuf:"bytes,4,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -765,8 +1110,42 @@ func (m *SymlinkNode) GetNodeProperties() *NodeProperties { return nil } +// A content digest. A digest for a given blob consists of the size of the blob +// and its hash. The hash algorithm to use is defined by the server. +// +// The size is considered to be an integral part of the digest and cannot be +// separated. That is, even if the `hash` field is correctly specified but +// `size_bytes` is not, the server MUST reject the request. +// +// The reason for including the size in the digest is as follows: in a great +// many cases, the server needs to know the size of the blob it is about to work +// with prior to starting an operation with it, such as flattening Merkle tree +// structures or streaming it to a worker. Technically, the server could +// implement a separate metadata store, but this results in a significantly more +// complicated implementation as opposed to having the client specify the size +// up-front (or storing the size along with the digest in every message where +// digests are embedded). This does mean that the API leaks some implementation +// details of (what we consider to be) a reasonable server implementation, but +// we consider this to be a worthwhile tradeoff. +// +// When a `Digest` is used to refer to a proto message, it always refers to the +// message in binary encoded form. To ensure consistent hashing, clients and +// servers MUST ensure that they serialize messages according to the following +// rules, even if there are alternate valid encodings for the same message: +// +// * Fields are serialized in tag order. +// * There are no unknown fields. +// * There are no duplicate fields. +// * Fields are serialized according to the default semantics for their type. +// +// Most protocol buffer implementations will always follow these rules when +// serializing, but care should be taken to avoid shortcuts. For instance, +// concatenating two messages to merge them may produce duplicate fields. type Digest struct { - Hash string `protobuf:"bytes,1,opt,name=hash,proto3" json:"hash,omitempty"` + // The hash. In the case of SHA-256, it will always be a lowercase hex string + // exactly 64 characters long. + Hash string `protobuf:"bytes,1,opt,name=hash,proto3" json:"hash,omitempty"` + // The size of the blob, in bytes. SizeBytes int64 `protobuf:"varint,2,opt,name=size_bytes,json=sizeBytes,proto3" json:"size_bytes,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -812,16 +1191,27 @@ func (m *Digest) GetSizeBytes() int64 { return 0 } +// ExecutedActionMetadata contains details about a completed execution. type ExecutedActionMetadata struct { - Worker string `protobuf:"bytes,1,opt,name=worker,proto3" json:"worker,omitempty"` - QueuedTimestamp *timestamp.Timestamp `protobuf:"bytes,2,opt,name=queued_timestamp,json=queuedTimestamp,proto3" json:"queued_timestamp,omitempty"` - WorkerStartTimestamp *timestamp.Timestamp `protobuf:"bytes,3,opt,name=worker_start_timestamp,json=workerStartTimestamp,proto3" json:"worker_start_timestamp,omitempty"` - WorkerCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,4,opt,name=worker_completed_timestamp,json=workerCompletedTimestamp,proto3" json:"worker_completed_timestamp,omitempty"` - InputFetchStartTimestamp *timestamp.Timestamp `protobuf:"bytes,5,opt,name=input_fetch_start_timestamp,json=inputFetchStartTimestamp,proto3" json:"input_fetch_start_timestamp,omitempty"` - InputFetchCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,6,opt,name=input_fetch_completed_timestamp,json=inputFetchCompletedTimestamp,proto3" json:"input_fetch_completed_timestamp,omitempty"` - ExecutionStartTimestamp *timestamp.Timestamp `protobuf:"bytes,7,opt,name=execution_start_timestamp,json=executionStartTimestamp,proto3" json:"execution_start_timestamp,omitempty"` - ExecutionCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,8,opt,name=execution_completed_timestamp,json=executionCompletedTimestamp,proto3" json:"execution_completed_timestamp,omitempty"` - OutputUploadStartTimestamp *timestamp.Timestamp `protobuf:"bytes,9,opt,name=output_upload_start_timestamp,json=outputUploadStartTimestamp,proto3" json:"output_upload_start_timestamp,omitempty"` + // The name of the worker which ran the execution. + Worker string `protobuf:"bytes,1,opt,name=worker,proto3" json:"worker,omitempty"` + // When was the action added to the queue. + QueuedTimestamp *timestamp.Timestamp `protobuf:"bytes,2,opt,name=queued_timestamp,json=queuedTimestamp,proto3" json:"queued_timestamp,omitempty"` + // When the worker received the action. + WorkerStartTimestamp *timestamp.Timestamp `protobuf:"bytes,3,opt,name=worker_start_timestamp,json=workerStartTimestamp,proto3" json:"worker_start_timestamp,omitempty"` + // When the worker completed the action, including all stages. + WorkerCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,4,opt,name=worker_completed_timestamp,json=workerCompletedTimestamp,proto3" json:"worker_completed_timestamp,omitempty"` + // When the worker started fetching action inputs. + InputFetchStartTimestamp *timestamp.Timestamp `protobuf:"bytes,5,opt,name=input_fetch_start_timestamp,json=inputFetchStartTimestamp,proto3" json:"input_fetch_start_timestamp,omitempty"` + // When the worker finished fetching action inputs. + InputFetchCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,6,opt,name=input_fetch_completed_timestamp,json=inputFetchCompletedTimestamp,proto3" json:"input_fetch_completed_timestamp,omitempty"` + // When the worker started executing the action command. + ExecutionStartTimestamp *timestamp.Timestamp `protobuf:"bytes,7,opt,name=execution_start_timestamp,json=executionStartTimestamp,proto3" json:"execution_start_timestamp,omitempty"` + // When the worker completed executing the action command. + ExecutionCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,8,opt,name=execution_completed_timestamp,json=executionCompletedTimestamp,proto3" json:"execution_completed_timestamp,omitempty"` + // When the worker started uploading action outputs. + OutputUploadStartTimestamp *timestamp.Timestamp `protobuf:"bytes,9,opt,name=output_upload_start_timestamp,json=outputUploadStartTimestamp,proto3" json:"output_upload_start_timestamp,omitempty"` + // When the worker finished uploading action outputs. OutputUploadCompletedTimestamp *timestamp.Timestamp `protobuf:"bytes,10,opt,name=output_upload_completed_timestamp,json=outputUploadCompletedTimestamp,proto3" json:"output_upload_completed_timestamp,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -923,21 +1313,169 @@ func (m *ExecutedActionMetadata) GetOutputUploadCompletedTimestamp() *timestamp. return nil } +// An ActionResult represents the result of an +// [Action][build.bazel.remote.execution.v2.Action] being run. +// +// It is advised that at least one field (for example +// `ActionResult.execution_metadata.Worker`) have a non-default value, to +// ensure that the serialized value is non-empty, which can then be used +// as a basic data sanity check. type ActionResult struct { - OutputFiles []*OutputFile `protobuf:"bytes,2,rep,name=output_files,json=outputFiles,proto3" json:"output_files,omitempty"` - OutputFileSymlinks []*OutputSymlink `protobuf:"bytes,10,rep,name=output_file_symlinks,json=outputFileSymlinks,proto3" json:"output_file_symlinks,omitempty"` - OutputSymlinks []*OutputSymlink `protobuf:"bytes,12,rep,name=output_symlinks,json=outputSymlinks,proto3" json:"output_symlinks,omitempty"` - OutputDirectories []*OutputDirectory `protobuf:"bytes,3,rep,name=output_directories,json=outputDirectories,proto3" json:"output_directories,omitempty"` - OutputDirectorySymlinks []*OutputSymlink `protobuf:"bytes,11,rep,name=output_directory_symlinks,json=outputDirectorySymlinks,proto3" json:"output_directory_symlinks,omitempty"` - ExitCode int32 `protobuf:"varint,4,opt,name=exit_code,json=exitCode,proto3" json:"exit_code,omitempty"` - StdoutRaw []byte `protobuf:"bytes,5,opt,name=stdout_raw,json=stdoutRaw,proto3" json:"stdout_raw,omitempty"` - StdoutDigest *Digest `protobuf:"bytes,6,opt,name=stdout_digest,json=stdoutDigest,proto3" json:"stdout_digest,omitempty"` - StderrRaw []byte `protobuf:"bytes,7,opt,name=stderr_raw,json=stderrRaw,proto3" json:"stderr_raw,omitempty"` - StderrDigest *Digest `protobuf:"bytes,8,opt,name=stderr_digest,json=stderrDigest,proto3" json:"stderr_digest,omitempty"` - ExecutionMetadata *ExecutedActionMetadata `protobuf:"bytes,9,opt,name=execution_metadata,json=executionMetadata,proto3" json:"execution_metadata,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The output files of the action. For each output file requested in the + // `output_files` or `output_paths` field of the Action, if the corresponding + // file existed after the action completed, a single entry will be present + // either in this field, or the `output_file_symlinks` field if the file was + // a symbolic link to another file (`output_symlinks` field after v2.1). + // + // If an output listed in `output_files` was found, but was a directory rather + // than a regular file, the server will return a FAILED_PRECONDITION. + // If the action does not produce the requested output, then that output + // will be omitted from the list. The server is free to arrange the output + // list as desired; clients MUST NOT assume that the output list is sorted. + OutputFiles []*OutputFile `protobuf:"bytes,2,rep,name=output_files,json=outputFiles,proto3" json:"output_files,omitempty"` + // The output files of the action that are symbolic links to other files. Those + // may be links to other output files, or input files, or even absolute paths + // outside of the working directory, if the server supports + // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.CacheCapabilities.SymlinkAbsolutePathStrategy]. + // For each output file requested in the `output_files` or `output_paths` + // field of the Action, if the corresponding file existed after + // the action completed, a single entry will be present either in this field, + // or in the `output_files` field, if the file was not a symbolic link. + // + // If an output symbolic link of the same name as listed in `output_files` of + // the Command was found, but its target type was not a regular file, the + // server will return a FAILED_PRECONDITION. + // If the action does not produce the requested output, then that output + // will be omitted from the list. The server is free to arrange the output + // list as desired; clients MUST NOT assume that the output list is sorted. + // + // DEPRECATED as of v2.1. Servers that wish to be compatible with v2.0 API + // should still populate this field in addition to `output_symlinks`. + OutputFileSymlinks []*OutputSymlink `protobuf:"bytes,10,rep,name=output_file_symlinks,json=outputFileSymlinks,proto3" json:"output_file_symlinks,omitempty"` + // New in v2.1: this field will only be populated if the command + // `output_paths` field was used, and not the pre v2.1 `output_files` or + // `output_directories` fields. + // The output paths of the action that are symbolic links to other paths. Those + // may be links to other outputs, or inputs, or even absolute paths + // outside of the working directory, if the server supports + // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.CacheCapabilities.SymlinkAbsolutePathStrategy]. + // A single entry for each output requested in `output_paths` + // field of the Action, if the corresponding path existed after + // the action completed and was a symbolic link. + // + // If the action does not produce a requested output, then that output + // will be omitted from the list. The server is free to arrange the output + // list as desired; clients MUST NOT assume that the output list is sorted. + OutputSymlinks []*OutputSymlink `protobuf:"bytes,12,rep,name=output_symlinks,json=outputSymlinks,proto3" json:"output_symlinks,omitempty"` + // The output directories of the action. For each output directory requested + // in the `output_directories` or `output_paths` field of the Action, if the + // corresponding directory existed after the action completed, a single entry + // will be present in the output list, which will contain the digest of a + // [Tree][build.bazel.remote.execution.v2.Tree] message containing the + // directory tree, and the path equal exactly to the corresponding Action + // output_directories member. + // + // As an example, suppose the Action had an output directory `a/b/dir` and the + // execution produced the following contents in `a/b/dir`: a file named `bar` + // and a directory named `foo` with an executable file named `baz`. Then, + // output_directory will contain (hashes shortened for readability): + // + // ```json + // // OutputDirectory proto: + // { + // path: "a/b/dir" + // tree_digest: { + // hash: "4a73bc9d03...", + // size: 55 + // } + // } + // // Tree proto with hash "4a73bc9d03..." and size 55: + // { + // root: { + // files: [ + // { + // name: "bar", + // digest: { + // hash: "4a73bc9d03...", + // size: 65534 + // } + // } + // ], + // directories: [ + // { + // name: "foo", + // digest: { + // hash: "4cf2eda940...", + // size: 43 + // } + // } + // ] + // } + // children : { + // // (Directory proto with hash "4cf2eda940..." and size 43) + // files: [ + // { + // name: "baz", + // digest: { + // hash: "b2c941073e...", + // size: 1294, + // }, + // is_executable: true + // } + // ] + // } + // } + // ``` + // If an output of the same name as listed in `output_files` of + // the Command was found in `output_directories`, but was not a directory, the + // server will return a FAILED_PRECONDITION. + OutputDirectories []*OutputDirectory `protobuf:"bytes,3,rep,name=output_directories,json=outputDirectories,proto3" json:"output_directories,omitempty"` + // The output directories of the action that are symbolic links to other + // directories. Those may be links to other output directories, or input + // directories, or even absolute paths outside of the working directory, + // if the server supports + // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.CacheCapabilities.SymlinkAbsolutePathStrategy]. + // For each output directory requested in the `output_directories` field of + // the Action, if the directory existed after the action completed, a + // single entry will be present either in this field, or in the + // `output_directories` field, if the directory was not a symbolic link. + // + // If an output of the same name was found, but was a symbolic link to a file + // instead of a directory, the server will return a FAILED_PRECONDITION. + // If the action does not produce the requested output, then that output + // will be omitted from the list. The server is free to arrange the output + // list as desired; clients MUST NOT assume that the output list is sorted. + // + // DEPRECATED as of v2.1. Servers that wish to be compatible with v2.0 API + // should still populate this field in addition to `output_symlinks`. + OutputDirectorySymlinks []*OutputSymlink `protobuf:"bytes,11,rep,name=output_directory_symlinks,json=outputDirectorySymlinks,proto3" json:"output_directory_symlinks,omitempty"` + // The exit code of the command. + ExitCode int32 `protobuf:"varint,4,opt,name=exit_code,json=exitCode,proto3" json:"exit_code,omitempty"` + // The standard output buffer of the action. The server SHOULD NOT inline + // stdout unless requested by the client in the + // [GetActionResultRequest][build.bazel.remote.execution.v2.GetActionResultRequest] + // message. The server MAY omit inlining, even if requested, and MUST do so if inlining + // would cause the response to exceed message size limits. + StdoutRaw []byte `protobuf:"bytes,5,opt,name=stdout_raw,json=stdoutRaw,proto3" json:"stdout_raw,omitempty"` + // The digest for a blob containing the standard output of the action, which + // can be retrieved from the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + StdoutDigest *Digest `protobuf:"bytes,6,opt,name=stdout_digest,json=stdoutDigest,proto3" json:"stdout_digest,omitempty"` + // The standard error buffer of the action. The server SHOULD NOT inline + // stderr unless requested by the client in the + // [GetActionResultRequest][build.bazel.remote.execution.v2.GetActionResultRequest] + // message. The server MAY omit inlining, even if requested, and MUST do so if inlining + // would cause the response to exceed message size limits. + StderrRaw []byte `protobuf:"bytes,7,opt,name=stderr_raw,json=stderrRaw,proto3" json:"stderr_raw,omitempty"` + // The digest for a blob containing the standard error of the action, which + // can be retrieved from the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + StderrDigest *Digest `protobuf:"bytes,8,opt,name=stderr_digest,json=stderrDigest,proto3" json:"stderr_digest,omitempty"` + // The details of the execution that originally produced this result. + ExecutionMetadata *ExecutedActionMetadata `protobuf:"bytes,9,opt,name=execution_metadata,json=executionMetadata,proto3" json:"execution_metadata,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *ActionResult) Reset() { *m = ActionResult{} } @@ -1042,10 +1580,24 @@ func (m *ActionResult) GetExecutionMetadata() *ExecutedActionMetadata { return nil } +// An `OutputFile` is similar to a +// [FileNode][build.bazel.remote.execution.v2.FileNode], but it is used as an +// output in an `ActionResult`. It allows a full file path rather than +// only a name. type OutputFile struct { - Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` - Digest *Digest `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"` - IsExecutable bool `protobuf:"varint,4,opt,name=is_executable,json=isExecutable,proto3" json:"is_executable,omitempty"` + // The full path of the file relative to the working directory, including the + // filename. The path separator is a forward slash `/`. Since this is a + // relative path, it MUST NOT begin with a leading forward slash. + Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` + // The digest of the file's content. + Digest *Digest `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"` + // True if file is executable, false otherwise. + IsExecutable bool `protobuf:"varint,4,opt,name=is_executable,json=isExecutable,proto3" json:"is_executable,omitempty"` + // The contents of the file if inlining was requested. The server SHOULD NOT inline + // file contents unless requested by the client in the + // [GetActionResultRequest][build.bazel.remote.execution.v2.GetActionResultRequest] + // message. The server MAY omit inlining, even if requested, and MUST do so if inlining + // would cause the response to exceed message size limits. Contents []byte `protobuf:"bytes,5,opt,name=contents,proto3" json:"contents,omitempty"` NodeProperties *NodeProperties `protobuf:"bytes,7,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -1113,8 +1665,16 @@ func (m *OutputFile) GetNodeProperties() *NodeProperties { return nil } +// A `Tree` contains all the +// [Directory][build.bazel.remote.execution.v2.Directory] protos in a +// single directory Merkle tree, compressed into one message. type Tree struct { - Root *Directory `protobuf:"bytes,1,opt,name=root,proto3" json:"root,omitempty"` + // The root directory in the tree. + Root *Directory `protobuf:"bytes,1,opt,name=root,proto3" json:"root,omitempty"` + // All the child directories: the directories referred to by the root and, + // recursively, all its children. In order to reconstruct the directory tree, + // the client must take the digests of each of the child directories and then + // build up a tree starting from the `root`. Children []*Directory `protobuf:"bytes,2,rep,name=children,proto3" json:"children,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1160,8 +1720,17 @@ func (m *Tree) GetChildren() []*Directory { return nil } +// An `OutputDirectory` is the output in an `ActionResult` corresponding to a +// directory's full contents rather than a single file. type OutputDirectory struct { - Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` + // The full path of the directory relative to the working directory. The path + // separator is a forward slash `/`. Since this is a relative path, it MUST + // NOT begin with a leading forward slash. The empty string value is allowed, + // and it denotes the entire working directory. + Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` + // The digest of the encoded + // [Tree][build.bazel.remote.execution.v2.Tree] proto containing the + // directory's contents. TreeDigest *Digest `protobuf:"bytes,3,opt,name=tree_digest,json=treeDigest,proto3" json:"tree_digest,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1207,8 +1776,21 @@ func (m *OutputDirectory) GetTreeDigest() *Digest { return nil } +// An `OutputSymlink` is similar to a +// [Symlink][build.bazel.remote.execution.v2.SymlinkNode], but it is used as an +// output in an `ActionResult`. +// +// `OutputSymlink` is binary-compatible with `SymlinkNode`. type OutputSymlink struct { - Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` + // The full path of the symlink relative to the working directory, including the + // filename. The path separator is a forward slash `/`. Since this is a + // relative path, it MUST NOT begin with a leading forward slash. + Path string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"` + // The target path of the symlink. The path separator is a forward slash `/`. + // The target path can be relative to the parent directory of the symlink or + // it can be an absolute path starting with `/`. Support for absolute paths + // can be checked using the [Capabilities][build.bazel.remote.execution.v2.Capabilities] + // API. `..` components are allowed anywhere in the target path. Target string `protobuf:"bytes,2,opt,name=target,proto3" json:"target,omitempty"` NodeProperties *NodeProperties `protobuf:"bytes,4,opt,name=node_properties,json=nodeProperties,proto3" json:"node_properties,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -1262,7 +1844,17 @@ func (m *OutputSymlink) GetNodeProperties() *NodeProperties { return nil } +// An `ExecutionPolicy` can be used to control the scheduling of the action. type ExecutionPolicy struct { + // The priority (relative importance) of this action. Generally, a lower value + // means that the action should be run sooner than actions having a greater + // priority value, but the interpretation of a given value is server- + // dependent. A priority of 0 means the *default* priority. Priorities may be + // positive or negative, and such actions should run later or sooner than + // actions having the default priority, respectively. The particular semantics + // of this field is up to the server. In particular, every server will have + // their own supported range of priorities, and will decide how these map into + // scheduling policy. Priority int32 `protobuf:"varint,1,opt,name=priority,proto3" json:"priority,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1301,7 +1893,17 @@ func (m *ExecutionPolicy) GetPriority() int32 { return 0 } +// A `ResultsCachePolicy` is used for fine-grained control over how action +// outputs are stored in the CAS and Action Cache. type ResultsCachePolicy struct { + // The priority (relative importance) of this content in the overall cache. + // Generally, a lower value means a longer retention time or other advantage, + // but the interpretation of a given value is server-dependent. A priority of + // 0 means a *default* value, decided by the server. + // + // The particular semantics of this field is up to the server. In particular, + // every server will have their own supported range of priorities, and will + // decide how these map into retention/eviction policy. Priority int32 `protobuf:"varint,1,opt,name=priority,proto3" json:"priority,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1340,11 +1942,38 @@ func (m *ResultsCachePolicy) GetPriority() int32 { return 0 } +// A request message for +// [Execution.Execute][build.bazel.remote.execution.v2.Execution.Execute]. type ExecuteRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - SkipCacheLookup bool `protobuf:"varint,3,opt,name=skip_cache_lookup,json=skipCacheLookup,proto3" json:"skip_cache_lookup,omitempty"` - ActionDigest *Digest `protobuf:"bytes,6,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` - ExecutionPolicy *ExecutionPolicy `protobuf:"bytes,7,opt,name=execution_policy,json=executionPolicy,proto3" json:"execution_policy,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // If true, the action will be executed even if its result is already + // present in the [ActionCache][build.bazel.remote.execution.v2.ActionCache]. + // The execution is still allowed to be merged with other in-flight executions + // of the same action, however - semantically, the service MUST only guarantee + // that the results of an execution with this field set were not visible + // before the corresponding execution request was sent. + // Note that actions from execution requests setting this field set are still + // eligible to be entered into the action cache upon completion, and services + // SHOULD overwrite any existing entries that may exist. This allows + // skip_cache_lookup requests to be used as a mechanism for replacing action + // cache entries that reference outputs no longer available or that are + // poisoned in any way. + // If false, the result may be served from the action cache. + SkipCacheLookup bool `protobuf:"varint,3,opt,name=skip_cache_lookup,json=skipCacheLookup,proto3" json:"skip_cache_lookup,omitempty"` + // The digest of the [Action][build.bazel.remote.execution.v2.Action] to + // execute. + ActionDigest *Digest `protobuf:"bytes,6,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` + // An optional policy for execution of the action. + // The server will have a default policy if this is not provided. + ExecutionPolicy *ExecutionPolicy `protobuf:"bytes,7,opt,name=execution_policy,json=executionPolicy,proto3" json:"execution_policy,omitempty"` + // An optional policy for the results of this execution in the remote cache. + // The server will have a default policy if this is not provided. + // This may be applied to both the ActionResult and the associated blobs. ResultsCachePolicy *ResultsCachePolicy `protobuf:"bytes,8,opt,name=results_cache_policy,json=resultsCachePolicy,proto3" json:"results_cache_policy,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1411,8 +2040,15 @@ func (m *ExecuteRequest) GetResultsCachePolicy() *ResultsCachePolicy { return nil } +// A `LogFile` is a log stored in the CAS. type LogFile struct { - Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The digest of the log contents. + Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // This is a hint as to the purpose of the log, and is set to true if the log + // is human-readable text that can be usefully displayed to a user, and false + // otherwise. For instance, if a command-line client wishes to print the + // server logs to the terminal for a failed action, this allows it to avoid + // displaying a binary file. HumanReadable bool `protobuf:"varint,2,opt,name=human_readable,json=humanReadable,proto3" json:"human_readable,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1458,15 +2094,41 @@ func (m *LogFile) GetHumanReadable() bool { return false } +// The response message for +// [Execution.Execute][build.bazel.remote.execution.v2.Execution.Execute], +// which will be contained in the [response +// field][google.longrunning.Operation.response] of the +// [Operation][google.longrunning.Operation]. type ExecuteResponse struct { - Result *ActionResult `protobuf:"bytes,1,opt,name=result,proto3" json:"result,omitempty"` - CachedResult bool `protobuf:"varint,2,opt,name=cached_result,json=cachedResult,proto3" json:"cached_result,omitempty"` - Status *status.Status `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"` - ServerLogs map[string]*LogFile `protobuf:"bytes,4,rep,name=server_logs,json=serverLogs,proto3" json:"server_logs,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` - Message string `protobuf:"bytes,5,opt,name=message,proto3" json:"message,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The result of the action. + Result *ActionResult `protobuf:"bytes,1,opt,name=result,proto3" json:"result,omitempty"` + // True if the result was served from cache, false if it was executed. + CachedResult bool `protobuf:"varint,2,opt,name=cached_result,json=cachedResult,proto3" json:"cached_result,omitempty"` + // If the status has a code other than `OK`, it indicates that the action did + // not finish execution. For example, if the operation times out during + // execution, the status will have a `DEADLINE_EXCEEDED` code. Servers MUST + // use this field for errors in execution, rather than the error field on the + // `Operation` object. + // + // If the status code is other than `OK`, then the result MUST NOT be cached. + // For an error status, the `result` field is optional; the server may + // populate the output-, stdout-, and stderr-related fields if it has any + // information available, such as the stdout and stderr of a timed-out action. + Status *status.Status `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"` + // An optional list of additional log outputs the server wishes to provide. A + // server can use this to return execution-specific logs however it wishes. + // This is intended primarily to make it easier for users to debug issues that + // may be outside of the actual job execution, such as by identifying the + // worker executing the action or by providing logs from the worker's setup + // phase. The keys SHOULD be human readable so that a client can display them + // to a user. + ServerLogs map[string]*LogFile `protobuf:"bytes,4,rep,name=server_logs,json=serverLogs,proto3" json:"server_logs,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` + // Freeform informational message with details on the execution of the action + // that may be displayed to the user upon failure or when requested explicitly. + Message string `protobuf:"bytes,5,opt,name=message,proto3" json:"message,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *ExecuteResponse) Reset() { *m = ExecuteResponse{} } @@ -1529,6 +2191,7 @@ func (m *ExecuteResponse) GetMessage() string { return "" } +// The current stage of action execution. type ExecutionStage struct { XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1560,14 +2223,28 @@ func (m *ExecutionStage) XXX_DiscardUnknown() { var xxx_messageInfo_ExecutionStage proto.InternalMessageInfo +// Metadata about an ongoing +// [execution][build.bazel.remote.execution.v2.Execution.Execute], which +// will be contained in the [metadata +// field][google.longrunning.Operation.response] of the +// [Operation][google.longrunning.Operation]. type ExecuteOperationMetadata struct { - Stage ExecutionStage_Value `protobuf:"varint,1,opt,name=stage,proto3,enum=build.bazel.remote.execution.v2.ExecutionStage_Value" json:"stage,omitempty"` - ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` - StdoutStreamName string `protobuf:"bytes,3,opt,name=stdout_stream_name,json=stdoutStreamName,proto3" json:"stdout_stream_name,omitempty"` - StderrStreamName string `protobuf:"bytes,4,opt,name=stderr_stream_name,json=stderrStreamName,proto3" json:"stderr_stream_name,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The current stage of execution. + Stage ExecutionStage_Value `protobuf:"varint,1,opt,name=stage,proto3,enum=build.bazel.remote.execution.v2.ExecutionStage_Value" json:"stage,omitempty"` + // The digest of the [Action][build.bazel.remote.execution.v2.Action] + // being executed. + ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` + // If set, the client can use this resource name with + // [ByteStream.Read][google.bytestream.ByteStream.Read] to stream the + // standard output from the endpoint hosting streamed responses. + StdoutStreamName string `protobuf:"bytes,3,opt,name=stdout_stream_name,json=stdoutStreamName,proto3" json:"stdout_stream_name,omitempty"` + // If set, the client can use this resource name with + // [ByteStream.Read][google.bytestream.ByteStream.Read] to stream the + // standard error from the endpoint hosting streamed responses. + StderrStreamName string `protobuf:"bytes,4,opt,name=stderr_stream_name,json=stderrStreamName,proto3" json:"stderr_stream_name,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *ExecuteOperationMetadata) Reset() { *m = ExecuteOperationMetadata{} } @@ -1623,7 +2300,11 @@ func (m *ExecuteOperationMetadata) GetStderrStreamName() string { return "" } +// A request message for +// [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution]. type WaitExecutionRequest struct { + // The name of the [Operation][google.longrunning.Operation] + // returned by [Execute][build.bazel.remote.execution.v2.Execution.Execute]. Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1662,11 +2343,28 @@ func (m *WaitExecutionRequest) GetName() string { return "" } +// A request message for +// [ActionCache.GetActionResult][build.bazel.remote.execution.v2.ActionCache.GetActionResult]. type GetActionResultRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` - InlineStdout bool `protobuf:"varint,3,opt,name=inline_stdout,json=inlineStdout,proto3" json:"inline_stdout,omitempty"` - InlineStderr bool `protobuf:"varint,4,opt,name=inline_stderr,json=inlineStderr,proto3" json:"inline_stderr,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // The digest of the [Action][build.bazel.remote.execution.v2.Action] + // whose result is requested. + ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` + // A hint to the server to request inlining stdout in the + // [ActionResult][build.bazel.remote.execution.v2.ActionResult] message. + InlineStdout bool `protobuf:"varint,3,opt,name=inline_stdout,json=inlineStdout,proto3" json:"inline_stdout,omitempty"` + // A hint to the server to request inlining stderr in the + // [ActionResult][build.bazel.remote.execution.v2.ActionResult] message. + InlineStderr bool `protobuf:"varint,4,opt,name=inline_stderr,json=inlineStderr,proto3" json:"inline_stderr,omitempty"` + // A hint to the server to inline the contents of the listed output files. + // Each path needs to exactly match one file path in either `output_paths` or + // `output_files` (DEPRECATED since v2.1) in the + // [Command][build.bazel.remote.execution.v2.Command] message. InlineOutputFiles []string `protobuf:"bytes,5,rep,name=inline_output_files,json=inlineOutputFiles,proto3" json:"inline_output_files,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1733,10 +2431,24 @@ func (m *GetActionResultRequest) GetInlineOutputFiles() []string { return nil } +// A request message for +// [ActionCache.UpdateActionResult][build.bazel.remote.execution.v2.ActionCache.UpdateActionResult]. type UpdateActionResultRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` - ActionResult *ActionResult `protobuf:"bytes,3,opt,name=action_result,json=actionResult,proto3" json:"action_result,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // The digest of the [Action][build.bazel.remote.execution.v2.Action] + // whose result is being uploaded. + ActionDigest *Digest `protobuf:"bytes,2,opt,name=action_digest,json=actionDigest,proto3" json:"action_digest,omitempty"` + // The [ActionResult][build.bazel.remote.execution.v2.ActionResult] + // to store in the cache. + ActionResult *ActionResult `protobuf:"bytes,3,opt,name=action_result,json=actionResult,proto3" json:"action_result,omitempty"` + // An optional policy for the results of this execution in the remote cache. + // The server will have a default policy if this is not provided. + // This may be applied to both the ActionResult and the associated blobs. ResultsCachePolicy *ResultsCachePolicy `protobuf:"bytes,4,opt,name=results_cache_policy,json=resultsCachePolicy,proto3" json:"results_cache_policy,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1796,8 +2508,16 @@ func (m *UpdateActionResultRequest) GetResultsCachePolicy() *ResultsCachePolicy return nil } +// A request message for +// [ContentAddressableStorage.FindMissingBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.FindMissingBlobs]. type FindMissingBlobsRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // A list of the blobs to check. BlobDigests []*Digest `protobuf:"bytes,2,rep,name=blob_digests,json=blobDigests,proto3" json:"blob_digests,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1843,7 +2563,10 @@ func (m *FindMissingBlobsRequest) GetBlobDigests() []*Digest { return nil } +// A response message for +// [ContentAddressableStorage.FindMissingBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.FindMissingBlobs]. type FindMissingBlobsResponse struct { + // A list of the blobs requested *not* present in the storage. MissingBlobDigests []*Digest `protobuf:"bytes,2,rep,name=missing_blob_digests,json=missingBlobDigests,proto3" json:"missing_blob_digests,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1882,8 +2605,16 @@ func (m *FindMissingBlobsResponse) GetMissingBlobDigests() []*Digest { return nil } +// A request message for +// [ContentAddressableStorage.BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs]. type BatchUpdateBlobsRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // The individual upload requests. Requests []*BatchUpdateBlobsRequest_Request `protobuf:"bytes,2,rep,name=requests,proto3" json:"requests,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1929,8 +2660,11 @@ func (m *BatchUpdateBlobsRequest) GetRequests() []*BatchUpdateBlobsRequest_Reque return nil } +// A request corresponding to a single blob that the client wants to upload. type BatchUpdateBlobsRequest_Request struct { - Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The digest of the blob. This MUST be the digest of `data`. + Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The raw binary data. Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1976,7 +2710,10 @@ func (m *BatchUpdateBlobsRequest_Request) GetData() []byte { return nil } +// A response message for +// [ContentAddressableStorage.BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs]. type BatchUpdateBlobsResponse struct { + // The responses to the requests. Responses []*BatchUpdateBlobsResponse_Response `protobuf:"bytes,1,rep,name=responses,proto3" json:"responses,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2015,8 +2752,11 @@ func (m *BatchUpdateBlobsResponse) GetResponses() []*BatchUpdateBlobsResponse_Re return nil } +// A response corresponding to a single blob that the client tried to upload. type BatchUpdateBlobsResponse_Response struct { - Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The blob digest to which this response corresponds. + Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The result of attempting to upload that blob. Status *status.Status `protobuf:"bytes,2,opt,name=status,proto3" json:"status,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2062,8 +2802,16 @@ func (m *BatchUpdateBlobsResponse_Response) GetStatus() *status.Status { return nil } +// A request message for +// [ContentAddressableStorage.BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs]. type BatchReadBlobsRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // The individual blob digests. Digests []*Digest `protobuf:"bytes,2,rep,name=digests,proto3" json:"digests,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2109,7 +2857,10 @@ func (m *BatchReadBlobsRequest) GetDigests() []*Digest { return nil } +// A response message for +// [ContentAddressableStorage.BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs]. type BatchReadBlobsResponse struct { + // The responses to the requests. Responses []*BatchReadBlobsResponse_Response `protobuf:"bytes,1,rep,name=responses,proto3" json:"responses,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2148,9 +2899,13 @@ func (m *BatchReadBlobsResponse) GetResponses() []*BatchReadBlobsResponse_Respon return nil } +// A response corresponding to a single blob that the client tried to download. type BatchReadBlobsResponse_Response struct { - Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` - Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"` + // The digest to which this response corresponds. + Digest *Digest `protobuf:"bytes,1,opt,name=digest,proto3" json:"digest,omitempty"` + // The raw binary data. + Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"` + // The result of attempting to download that blob. Status *status.Status `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2203,10 +2958,29 @@ func (m *BatchReadBlobsResponse_Response) GetStatus() *status.Status { return nil } +// A request message for +// [ContentAddressableStorage.GetTree][build.bazel.remote.execution.v2.ContentAddressableStorage.GetTree]. type GetTreeRequest struct { - InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` - RootDigest *Digest `protobuf:"bytes,2,opt,name=root_digest,json=rootDigest,proto3" json:"root_digest,omitempty"` - PageSize int32 `protobuf:"varint,3,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"` + // 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. + InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` + // The digest of the root, which must be an encoded + // [Directory][build.bazel.remote.execution.v2.Directory] message + // stored in the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + RootDigest *Digest `protobuf:"bytes,2,opt,name=root_digest,json=rootDigest,proto3" json:"root_digest,omitempty"` + // A maximum page size to request. If present, the server will request no more + // than this many items. Regardless of whether a page size is specified, the + // server may place its own limit on the number of items to be returned and + // require the client to retrieve more items using a subsequent request. + PageSize int32 `protobuf:"varint,3,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"` + // A page token, which must be a value received in a previous + // [GetTreeResponse][build.bazel.remote.execution.v2.GetTreeResponse]. + // If present, the server will use that token as an offset, returning only + // that page and the ones that succeed it. PageToken string `protobuf:"bytes,4,opt,name=page_token,json=pageToken,proto3" json:"page_token,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2266,12 +3040,19 @@ func (m *GetTreeRequest) GetPageToken() string { return "" } +// A response message for +// [ContentAddressableStorage.GetTree][build.bazel.remote.execution.v2.ContentAddressableStorage.GetTree]. type GetTreeResponse struct { - Directories []*Directory `protobuf:"bytes,1,rep,name=directories,proto3" json:"directories,omitempty"` - NextPageToken string `protobuf:"bytes,2,opt,name=next_page_token,json=nextPageToken,proto3" json:"next_page_token,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The directories descended from the requested root. + Directories []*Directory `protobuf:"bytes,1,rep,name=directories,proto3" json:"directories,omitempty"` + // If present, signifies that there are more results which the client can + // retrieve by passing this as the page_token in a subsequent + // [request][build.bazel.remote.execution.v2.GetTreeRequest]. + // If empty, signifies that this is the last page of results. + NextPageToken string `protobuf:"bytes,2,opt,name=next_page_token,json=nextPageToken,proto3" json:"next_page_token,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *GetTreeResponse) Reset() { *m = GetTreeResponse{} } @@ -2313,7 +3094,14 @@ func (m *GetTreeResponse) GetNextPageToken() string { return "" } +// A request message for +// [Capabilities.GetCapabilities][build.bazel.remote.execution.v2.Capabilities.GetCapabilities]. type GetCapabilitiesRequest struct { + // 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. InstanceName string `protobuf:"bytes,1,opt,name=instance_name,json=instanceName,proto3" json:"instance_name,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2352,15 +3140,22 @@ func (m *GetCapabilitiesRequest) GetInstanceName() string { return "" } +// A response message for +// [Capabilities.GetCapabilities][build.bazel.remote.execution.v2.Capabilities.GetCapabilities]. type ServerCapabilities struct { - CacheCapabilities *CacheCapabilities `protobuf:"bytes,1,opt,name=cache_capabilities,json=cacheCapabilities,proto3" json:"cache_capabilities,omitempty"` + // Capabilities of the remote cache system. + CacheCapabilities *CacheCapabilities `protobuf:"bytes,1,opt,name=cache_capabilities,json=cacheCapabilities,proto3" json:"cache_capabilities,omitempty"` + // Capabilities of the remote execution system. ExecutionCapabilities *ExecutionCapabilities `protobuf:"bytes,2,opt,name=execution_capabilities,json=executionCapabilities,proto3" json:"execution_capabilities,omitempty"` - DeprecatedApiVersion *semver.SemVer `protobuf:"bytes,3,opt,name=deprecated_api_version,json=deprecatedApiVersion,proto3" json:"deprecated_api_version,omitempty"` - LowApiVersion *semver.SemVer `protobuf:"bytes,4,opt,name=low_api_version,json=lowApiVersion,proto3" json:"low_api_version,omitempty"` - HighApiVersion *semver.SemVer `protobuf:"bytes,5,opt,name=high_api_version,json=highApiVersion,proto3" json:"high_api_version,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // Earliest RE API version supported, including deprecated versions. + DeprecatedApiVersion *semver.SemVer `protobuf:"bytes,3,opt,name=deprecated_api_version,json=deprecatedApiVersion,proto3" json:"deprecated_api_version,omitempty"` + // Earliest non-deprecated RE API version supported. + LowApiVersion *semver.SemVer `protobuf:"bytes,4,opt,name=low_api_version,json=lowApiVersion,proto3" json:"low_api_version,omitempty"` + // Latest RE API version supported. + HighApiVersion *semver.SemVer `protobuf:"bytes,5,opt,name=high_api_version,json=highApiVersion,proto3" json:"high_api_version,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *ServerCapabilities) Reset() { *m = ServerCapabilities{} } @@ -2423,6 +3218,8 @@ func (m *ServerCapabilities) GetHighApiVersion() *semver.SemVer { return nil } +// The digest function used for converting values into keys for CAS and Action +// Cache. type DigestFunction struct { XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2454,6 +3251,7 @@ func (m *DigestFunction) XXX_DiscardUnknown() { var xxx_messageInfo_DigestFunction proto.InternalMessageInfo +// Describes the server/instance capabilities for updating the action cache. type ActionCacheUpdateCapabilities struct { UpdateEnabled bool `protobuf:"varint,1,opt,name=update_enabled,json=updateEnabled,proto3" json:"update_enabled,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -2493,6 +3291,10 @@ func (m *ActionCacheUpdateCapabilities) GetUpdateEnabled() bool { return false } +// Allowed values for priority in +// [ResultsCachePolicy][build.bazel.remoteexecution.v2.ResultsCachePolicy] and +// [ExecutionPolicy][build.bazel.remoteexecution.v2.ResultsCachePolicy] +// Used for querying both cache and execution valid priority ranges. type PriorityCapabilities struct { Priorities []*PriorityCapabilities_PriorityRange `protobuf:"bytes,1,rep,name=priorities,proto3" json:"priorities,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -2532,8 +3334,13 @@ func (m *PriorityCapabilities) GetPriorities() []*PriorityCapabilities_PriorityR return nil } +// Supported range of priorities, including boundaries. type PriorityCapabilities_PriorityRange struct { - MinPriority int32 `protobuf:"varint,1,opt,name=min_priority,json=minPriority,proto3" json:"min_priority,omitempty"` + // The minimum numeric value for this priority range, which represents the + // most urgent task or longest retained item. + MinPriority int32 `protobuf:"varint,1,opt,name=min_priority,json=minPriority,proto3" json:"min_priority,omitempty"` + // The maximum numeric value for this priority range, which represents the + // least urgent task or shortest retained item. MaxPriority int32 `protobuf:"varint,2,opt,name=max_priority,json=maxPriority,proto3" json:"max_priority,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2579,6 +3386,7 @@ func (m *PriorityCapabilities_PriorityRange) GetMaxPriority() int32 { return 0 } +// Describes how the server treats absolute symlink targets. type SymlinkAbsolutePathStrategy struct { XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2610,15 +3418,25 @@ func (m *SymlinkAbsolutePathStrategy) XXX_DiscardUnknown() { var xxx_messageInfo_SymlinkAbsolutePathStrategy proto.InternalMessageInfo +// Capabilities of the remote cache system. type CacheCapabilities struct { - DigestFunction []DigestFunction_Value `protobuf:"varint,1,rep,packed,name=digest_function,json=digestFunction,proto3,enum=build.bazel.remote.execution.v2.DigestFunction_Value" json:"digest_function,omitempty"` - ActionCacheUpdateCapabilities *ActionCacheUpdateCapabilities `protobuf:"bytes,2,opt,name=action_cache_update_capabilities,json=actionCacheUpdateCapabilities,proto3" json:"action_cache_update_capabilities,omitempty"` - CachePriorityCapabilities *PriorityCapabilities `protobuf:"bytes,3,opt,name=cache_priority_capabilities,json=cachePriorityCapabilities,proto3" json:"cache_priority_capabilities,omitempty"` - MaxBatchTotalSizeBytes int64 `protobuf:"varint,4,opt,name=max_batch_total_size_bytes,json=maxBatchTotalSizeBytes,proto3" json:"max_batch_total_size_bytes,omitempty"` - SymlinkAbsolutePathStrategy SymlinkAbsolutePathStrategy_Value `protobuf:"varint,5,opt,name=symlink_absolute_path_strategy,json=symlinkAbsolutePathStrategy,proto3,enum=build.bazel.remote.execution.v2.SymlinkAbsolutePathStrategy_Value" json:"symlink_absolute_path_strategy,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // All the digest functions supported by the remote cache. + // Remote cache may support multiple digest functions simultaneously. + DigestFunction []DigestFunction_Value `protobuf:"varint,1,rep,packed,name=digest_function,json=digestFunction,proto3,enum=build.bazel.remote.execution.v2.DigestFunction_Value" json:"digest_function,omitempty"` + // Capabilities for updating the action cache. + ActionCacheUpdateCapabilities *ActionCacheUpdateCapabilities `protobuf:"bytes,2,opt,name=action_cache_update_capabilities,json=actionCacheUpdateCapabilities,proto3" json:"action_cache_update_capabilities,omitempty"` + // Supported cache priority range for both CAS and ActionCache. + CachePriorityCapabilities *PriorityCapabilities `protobuf:"bytes,3,opt,name=cache_priority_capabilities,json=cachePriorityCapabilities,proto3" json:"cache_priority_capabilities,omitempty"` + // Maximum total size of blobs to be uploaded/downloaded using + // batch methods. A value of 0 means no limit is set, although + // in practice there will always be a message size limitation + // of the protocol in use, e.g. GRPC. + MaxBatchTotalSizeBytes int64 `protobuf:"varint,4,opt,name=max_batch_total_size_bytes,json=maxBatchTotalSizeBytes,proto3" json:"max_batch_total_size_bytes,omitempty"` + // Whether absolute symlink targets are supported. + SymlinkAbsolutePathStrategy SymlinkAbsolutePathStrategy_Value `protobuf:"varint,5,opt,name=symlink_absolute_path_strategy,json=symlinkAbsolutePathStrategy,proto3,enum=build.bazel.remote.execution.v2.SymlinkAbsolutePathStrategy_Value" json:"symlink_absolute_path_strategy,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *CacheCapabilities) Reset() { *m = CacheCapabilities{} } @@ -2681,14 +3499,19 @@ func (m *CacheCapabilities) GetSymlinkAbsolutePathStrategy() SymlinkAbsolutePath return SymlinkAbsolutePathStrategy_UNKNOWN } +// Capabilities of the remote execution system. type ExecutionCapabilities struct { - DigestFunction DigestFunction_Value `protobuf:"varint,1,opt,name=digest_function,json=digestFunction,proto3,enum=build.bazel.remote.execution.v2.DigestFunction_Value" json:"digest_function,omitempty"` - ExecEnabled bool `protobuf:"varint,2,opt,name=exec_enabled,json=execEnabled,proto3" json:"exec_enabled,omitempty"` + // Remote execution may only support a single digest function. + DigestFunction DigestFunction_Value `protobuf:"varint,1,opt,name=digest_function,json=digestFunction,proto3,enum=build.bazel.remote.execution.v2.DigestFunction_Value" json:"digest_function,omitempty"` + // Whether remote execution is enabled for the particular server/instance. + ExecEnabled bool `protobuf:"varint,2,opt,name=exec_enabled,json=execEnabled,proto3" json:"exec_enabled,omitempty"` + // Supported execution priority range. ExecutionPriorityCapabilities *PriorityCapabilities `protobuf:"bytes,3,opt,name=execution_priority_capabilities,json=executionPriorityCapabilities,proto3" json:"execution_priority_capabilities,omitempty"` - SupportedNodeProperties []string `protobuf:"bytes,4,rep,name=supported_node_properties,json=supportedNodeProperties,proto3" json:"supported_node_properties,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // Supported node properties. + SupportedNodeProperties []string `protobuf:"bytes,4,rep,name=supported_node_properties,json=supportedNodeProperties,proto3" json:"supported_node_properties,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *ExecutionCapabilities) Reset() { *m = ExecutionCapabilities{} } @@ -2744,8 +3567,11 @@ func (m *ExecutionCapabilities) GetSupportedNodeProperties() []string { return nil } +// Details for the tool used to call the API. type ToolDetails struct { - ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"` + // Name of the tool, e.g. bazel. + ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"` + // Version of the tool used for the request, e.g. 5.0.3. ToolVersion string `protobuf:"bytes,2,opt,name=tool_version,json=toolVersion,proto3" json:"tool_version,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -2791,14 +3617,34 @@ func (m *ToolDetails) GetToolVersion() string { return "" } +// An optional Metadata to attach to any RPC request to tell the server about an +// external context of the request. The server may use this for logging or other +// purposes. To use it, the client attaches the header to the call using the +// canonical proto serialization: +// +// * name: `build.bazel.remote.execution.v2.requestmetadata-bin` +// * contents: the base64 encoded binary `RequestMetadata` message. +// Note: the gRPC library serializes binary headers encoded in base 64 by +// default (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests). +// Therefore, if the gRPC library is used to pass/retrieve this +// metadata, the user may ignore the base64 encoding and assume it is simply +// serialized as a binary message. type RequestMetadata struct { - ToolDetails *ToolDetails `protobuf:"bytes,1,opt,name=tool_details,json=toolDetails,proto3" json:"tool_details,omitempty"` - ActionId string `protobuf:"bytes,2,opt,name=action_id,json=actionId,proto3" json:"action_id,omitempty"` - ToolInvocationId string `protobuf:"bytes,3,opt,name=tool_invocation_id,json=toolInvocationId,proto3" json:"tool_invocation_id,omitempty"` - CorrelatedInvocationsId string `protobuf:"bytes,4,opt,name=correlated_invocations_id,json=correlatedInvocationsId,proto3" json:"correlated_invocations_id,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // The details for the tool invoking the requests. + ToolDetails *ToolDetails `protobuf:"bytes,1,opt,name=tool_details,json=toolDetails,proto3" json:"tool_details,omitempty"` + // An identifier that ties multiple requests to the same action. + // For example, multiple requests to the CAS, Action Cache, and Execution + // API are used in order to compile foo.cc. + ActionId string `protobuf:"bytes,2,opt,name=action_id,json=actionId,proto3" json:"action_id,omitempty"` + // An identifier that ties multiple actions together to a final result. + // For example, multiple actions are required to build and run foo_test. + ToolInvocationId string `protobuf:"bytes,3,opt,name=tool_invocation_id,json=toolInvocationId,proto3" json:"tool_invocation_id,omitempty"` + // An identifier to tie multiple tool invocations together. For example, + // runs of foo_test, bar_test and baz_test on a post-submit of a given patch. + CorrelatedInvocationsId string `protobuf:"bytes,4,opt,name=correlated_invocations_id,json=correlatedInvocationsId,proto3" json:"correlated_invocations_id,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *RequestMetadata) Reset() { *m = RequestMetadata{} } @@ -3143,7 +3989,76 @@ const _ = grpc.SupportPackageIsVersion4 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type ExecutionClient interface { + // Execute an action remotely. + // + // In order to execute an action, the client must first upload all of the + // inputs, the + // [Command][build.bazel.remote.execution.v2.Command] to run, and the + // [Action][build.bazel.remote.execution.v2.Action] into the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + // It then calls `Execute` with an `action_digest` referring to them. The + // server will run the action and eventually return the result. + // + // The input `Action`'s fields MUST meet the various canonicalization + // requirements specified in the documentation for their types so that it has + // the same digest as other logically equivalent `Action`s. The server MAY + // enforce the requirements and return errors if a non-canonical input is + // received. It MAY also proceed without verifying some or all of the + // requirements, such as for performance reasons. If the server does not + // verify the requirement, then it will treat the `Action` as distinct from + // another logically equivalent action if they hash differently. + // + // Returns a stream of + // [google.longrunning.Operation][google.longrunning.Operation] messages + // describing the resulting execution, with eventual `response` + // [ExecuteResponse][build.bazel.remote.execution.v2.ExecuteResponse]. The + // `metadata` on the operation is of type + // [ExecuteOperationMetadata][build.bazel.remote.execution.v2.ExecuteOperationMetadata]. + // + // If the client remains connected after the first response is returned after + // the server, then updates are streamed as if the client had called + // [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution] + // until the execution completes or the request reaches an error. The + // operation can also be queried using [Operations + // API][google.longrunning.Operations.GetOperation]. + // + // The server NEED NOT implement other methods or functionality of the + // Operations API. + // + // Errors discovered during creation of the `Operation` will be reported + // as gRPC Status errors, while errors that occurred while running the + // action will be reported in the `status` field of the `ExecuteResponse`. The + // server MUST NOT set the `error` field of the `Operation` proto. + // The possible errors include: + // + // * `INVALID_ARGUMENT`: One or more arguments are invalid. + // * `FAILED_PRECONDITION`: One or more errors occurred in setting up the + // action requested, such as a missing input or command or no worker being + // available. The client may be able to fix the errors and retry. + // * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run + // the action. + // * `UNAVAILABLE`: Due to a transient condition, such as all workers being + // occupied (and the server does not support a queue), the action could not + // be started. The client should retry. + // * `INTERNAL`: An internal error occurred in the execution engine or the + // worker. + // * `DEADLINE_EXCEEDED`: The execution timed out. + // * `CANCELLED`: The operation was cancelled by the client. This status is + // only possible if the server implements the Operations API CancelOperation + // method, and it was called for the current execution. + // + // In the case of a missing input or command, the server SHOULD additionally + // send a [PreconditionFailure][google.rpc.PreconditionFailure] error detail + // where, for each requested blob not present in the CAS, there is a + // `Violation` with a `type` of `MISSING` and a `subject` of + // `"blobs/{hash}/{size}"` indicating the digest of the missing blob. Execute(ctx context.Context, in *ExecuteRequest, opts ...grpc.CallOption) (Execution_ExecuteClient, error) + // Wait for an execution operation to complete. When the client initially + // makes the request, the server immediately responds with the current status + // of the execution. The server will leave the request stream open until the + // operation completes, and then respond with the completed operation. The + // server MAY choose to stream additional updates as execution progresses, + // such as to provide an update as to the state of the execution. WaitExecution(ctx context.Context, in *WaitExecutionRequest, opts ...grpc.CallOption) (Execution_WaitExecutionClient, error) } @@ -3221,7 +4136,76 @@ func (x *executionWaitExecutionClient) Recv() (*longrunning.Operation, error) { // ExecutionServer is the server API for Execution service. type ExecutionServer interface { + // Execute an action remotely. + // + // In order to execute an action, the client must first upload all of the + // inputs, the + // [Command][build.bazel.remote.execution.v2.Command] to run, and the + // [Action][build.bazel.remote.execution.v2.Action] into the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage]. + // It then calls `Execute` with an `action_digest` referring to them. The + // server will run the action and eventually return the result. + // + // The input `Action`'s fields MUST meet the various canonicalization + // requirements specified in the documentation for their types so that it has + // the same digest as other logically equivalent `Action`s. The server MAY + // enforce the requirements and return errors if a non-canonical input is + // received. It MAY also proceed without verifying some or all of the + // requirements, such as for performance reasons. If the server does not + // verify the requirement, then it will treat the `Action` as distinct from + // another logically equivalent action if they hash differently. + // + // Returns a stream of + // [google.longrunning.Operation][google.longrunning.Operation] messages + // describing the resulting execution, with eventual `response` + // [ExecuteResponse][build.bazel.remote.execution.v2.ExecuteResponse]. The + // `metadata` on the operation is of type + // [ExecuteOperationMetadata][build.bazel.remote.execution.v2.ExecuteOperationMetadata]. + // + // If the client remains connected after the first response is returned after + // the server, then updates are streamed as if the client had called + // [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution] + // until the execution completes or the request reaches an error. The + // operation can also be queried using [Operations + // API][google.longrunning.Operations.GetOperation]. + // + // The server NEED NOT implement other methods or functionality of the + // Operations API. + // + // Errors discovered during creation of the `Operation` will be reported + // as gRPC Status errors, while errors that occurred while running the + // action will be reported in the `status` field of the `ExecuteResponse`. The + // server MUST NOT set the `error` field of the `Operation` proto. + // The possible errors include: + // + // * `INVALID_ARGUMENT`: One or more arguments are invalid. + // * `FAILED_PRECONDITION`: One or more errors occurred in setting up the + // action requested, such as a missing input or command or no worker being + // available. The client may be able to fix the errors and retry. + // * `RESOURCE_EXHAUSTED`: There is insufficient quota of some resource to run + // the action. + // * `UNAVAILABLE`: Due to a transient condition, such as all workers being + // occupied (and the server does not support a queue), the action could not + // be started. The client should retry. + // * `INTERNAL`: An internal error occurred in the execution engine or the + // worker. + // * `DEADLINE_EXCEEDED`: The execution timed out. + // * `CANCELLED`: The operation was cancelled by the client. This status is + // only possible if the server implements the Operations API CancelOperation + // method, and it was called for the current execution. + // + // In the case of a missing input or command, the server SHOULD additionally + // send a [PreconditionFailure][google.rpc.PreconditionFailure] error detail + // where, for each requested blob not present in the CAS, there is a + // `Violation` with a `type` of `MISSING` and a `subject` of + // `"blobs/{hash}/{size}"` indicating the digest of the missing blob. Execute(*ExecuteRequest, Execution_ExecuteServer) error + // Wait for an execution operation to complete. When the client initially + // makes the request, the server immediately responds with the current status + // of the execution. The server will leave the request stream open until the + // operation completes, and then respond with the completed operation. The + // server MAY choose to stream additional updates as execution progresses, + // such as to provide an update as to the state of the execution. WaitExecution(*WaitExecutionRequest, Execution_WaitExecutionServer) error } @@ -3305,7 +4289,38 @@ var _Execution_serviceDesc = grpc.ServiceDesc{ // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type ActionCacheClient interface { + // Retrieve a cached execution result. + // + // Implementations SHOULD ensure that any blobs referenced from the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] + // are available at the time of returning the + // [ActionResult][build.bazel.remote.execution.v2.ActionResult] and will be + // for some period of time afterwards. The lifetimes of the referenced blobs SHOULD be increased + // if necessary and applicable. + // + // Errors: + // + // * `NOT_FOUND`: The requested `ActionResult` is not in the cache. GetActionResult(ctx context.Context, in *GetActionResultRequest, opts ...grpc.CallOption) (*ActionResult, error) + // Upload a new execution result. + // + // In order to allow the server to perform access control based on the type of + // action, and to assist with client debugging, the client MUST first upload + // the [Action][build.bazel.remote.execution.v2.Execution] that produced the + // result, along with its + // [Command][build.bazel.remote.execution.v2.Command], into the + // `ContentAddressableStorage`. + // + // Server implementations MAY modify the + // `UpdateActionResultRequest.action_result` and return an equivalent value. + // + // Errors: + // + // * `INVALID_ARGUMENT`: One or more arguments are invalid. + // * `FAILED_PRECONDITION`: One or more errors occurred in updating the + // action result, such as a missing command or action. + // * `RESOURCE_EXHAUSTED`: There is insufficient storage space to add the + // entry to the cache. UpdateActionResult(ctx context.Context, in *UpdateActionResultRequest, opts ...grpc.CallOption) (*ActionResult, error) } @@ -3337,7 +4352,38 @@ func (c *actionCacheClient) UpdateActionResult(ctx context.Context, in *UpdateAc // ActionCacheServer is the server API for ActionCache service. type ActionCacheServer interface { + // Retrieve a cached execution result. + // + // Implementations SHOULD ensure that any blobs referenced from the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] + // are available at the time of returning the + // [ActionResult][build.bazel.remote.execution.v2.ActionResult] and will be + // for some period of time afterwards. The lifetimes of the referenced blobs SHOULD be increased + // if necessary and applicable. + // + // Errors: + // + // * `NOT_FOUND`: The requested `ActionResult` is not in the cache. GetActionResult(context.Context, *GetActionResultRequest) (*ActionResult, error) + // Upload a new execution result. + // + // In order to allow the server to perform access control based on the type of + // action, and to assist with client debugging, the client MUST first upload + // the [Action][build.bazel.remote.execution.v2.Execution] that produced the + // result, along with its + // [Command][build.bazel.remote.execution.v2.Command], into the + // `ContentAddressableStorage`. + // + // Server implementations MAY modify the + // `UpdateActionResultRequest.action_result` and return an equivalent value. + // + // Errors: + // + // * `INVALID_ARGUMENT`: One or more arguments are invalid. + // * `FAILED_PRECONDITION`: One or more errors occurred in updating the + // action result, such as a missing command or action. + // * `RESOURCE_EXHAUSTED`: There is insufficient storage space to add the + // entry to the cache. UpdateActionResult(context.Context, *UpdateActionResultRequest) (*ActionResult, error) } @@ -3413,9 +4459,85 @@ var _ActionCache_serviceDesc = grpc.ServiceDesc{ // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type ContentAddressableStorageClient interface { + // Determine if blobs are present in the CAS. + // + // Clients can use this API before uploading blobs to determine which ones are + // already present in the CAS and do not need to be uploaded again. + // + // Servers SHOULD increase the lifetimes of the referenced blobs if necessary and + // applicable. + // + // There are no method-specific errors. FindMissingBlobs(ctx context.Context, in *FindMissingBlobsRequest, opts ...grpc.CallOption) (*FindMissingBlobsResponse, error) + // Upload many blobs at once. + // + // The server may enforce a limit of the combined total size of blobs + // to be uploaded using this API. This limit may be obtained using the + // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. + // Requests exceeding the limit should either be split into smaller + // chunks or uploaded using the + // [ByteStream API][google.bytestream.ByteStream], as appropriate. + // + // This request is equivalent to calling a Bytestream `Write` request + // on each individual blob, in parallel. The requests may succeed or fail + // independently. + // + // Errors: + // + // * `INVALID_ARGUMENT`: The client attempted to upload more than the + // server supported limit. + // + // Individual requests may return the following errors, additionally: + // + // * `RESOURCE_EXHAUSTED`: There is insufficient disk quota to store the blob. + // * `INVALID_ARGUMENT`: The + // [Digest][build.bazel.remote.execution.v2.Digest] does not match the + // provided data. BatchUpdateBlobs(ctx context.Context, in *BatchUpdateBlobsRequest, opts ...grpc.CallOption) (*BatchUpdateBlobsResponse, error) + // Download many blobs at once. + // + // The server may enforce a limit of the combined total size of blobs + // to be downloaded using this API. This limit may be obtained using the + // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. + // Requests exceeding the limit should either be split into smaller + // chunks or downloaded using the + // [ByteStream API][google.bytestream.ByteStream], as appropriate. + // + // This request is equivalent to calling a Bytestream `Read` request + // on each individual blob, in parallel. The requests may succeed or fail + // independently. + // + // Errors: + // + // * `INVALID_ARGUMENT`: The client attempted to read more than the + // server supported limit. + // + // Every error on individual read will be returned in the corresponding digest + // status. BatchReadBlobs(ctx context.Context, in *BatchReadBlobsRequest, opts ...grpc.CallOption) (*BatchReadBlobsResponse, error) + // Fetch the entire directory tree rooted at a node. + // + // This request must be targeted at a + // [Directory][build.bazel.remote.execution.v2.Directory] stored in the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] + // (CAS). The server will enumerate the `Directory` tree recursively and + // return every node descended from the root. + // + // The GetTreeRequest.page_token parameter can be used to skip ahead in + // the stream (e.g. when retrying a partially completed and aborted request), + // by setting it to a value taken from GetTreeResponse.next_page_token of the + // last successfully processed GetTreeResponse). + // + // The exact traversal order is unspecified and, unless retrieving subsequent + // pages from an earlier request, is not guaranteed to be stable across + // multiple invocations of `GetTree`. + // + // If part of the tree is missing from the CAS, the server will return the + // portion present and omit the rest. + // + // Errors: + // + // * `NOT_FOUND`: The requested tree root is not present in the CAS. GetTree(ctx context.Context, in *GetTreeRequest, opts ...grpc.CallOption) (ContentAddressableStorage_GetTreeClient, error) } @@ -3488,9 +4610,85 @@ func (x *contentAddressableStorageGetTreeClient) Recv() (*GetTreeResponse, error // ContentAddressableStorageServer is the server API for ContentAddressableStorage service. type ContentAddressableStorageServer interface { + // Determine if blobs are present in the CAS. + // + // Clients can use this API before uploading blobs to determine which ones are + // already present in the CAS and do not need to be uploaded again. + // + // Servers SHOULD increase the lifetimes of the referenced blobs if necessary and + // applicable. + // + // There are no method-specific errors. FindMissingBlobs(context.Context, *FindMissingBlobsRequest) (*FindMissingBlobsResponse, error) + // Upload many blobs at once. + // + // The server may enforce a limit of the combined total size of blobs + // to be uploaded using this API. This limit may be obtained using the + // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. + // Requests exceeding the limit should either be split into smaller + // chunks or uploaded using the + // [ByteStream API][google.bytestream.ByteStream], as appropriate. + // + // This request is equivalent to calling a Bytestream `Write` request + // on each individual blob, in parallel. The requests may succeed or fail + // independently. + // + // Errors: + // + // * `INVALID_ARGUMENT`: The client attempted to upload more than the + // server supported limit. + // + // Individual requests may return the following errors, additionally: + // + // * `RESOURCE_EXHAUSTED`: There is insufficient disk quota to store the blob. + // * `INVALID_ARGUMENT`: The + // [Digest][build.bazel.remote.execution.v2.Digest] does not match the + // provided data. BatchUpdateBlobs(context.Context, *BatchUpdateBlobsRequest) (*BatchUpdateBlobsResponse, error) + // Download many blobs at once. + // + // The server may enforce a limit of the combined total size of blobs + // to be downloaded using this API. This limit may be obtained using the + // [Capabilities][build.bazel.remote.execution.v2.Capabilities] API. + // Requests exceeding the limit should either be split into smaller + // chunks or downloaded using the + // [ByteStream API][google.bytestream.ByteStream], as appropriate. + // + // This request is equivalent to calling a Bytestream `Read` request + // on each individual blob, in parallel. The requests may succeed or fail + // independently. + // + // Errors: + // + // * `INVALID_ARGUMENT`: The client attempted to read more than the + // server supported limit. + // + // Every error on individual read will be returned in the corresponding digest + // status. BatchReadBlobs(context.Context, *BatchReadBlobsRequest) (*BatchReadBlobsResponse, error) + // Fetch the entire directory tree rooted at a node. + // + // This request must be targeted at a + // [Directory][build.bazel.remote.execution.v2.Directory] stored in the + // [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage] + // (CAS). The server will enumerate the `Directory` tree recursively and + // return every node descended from the root. + // + // The GetTreeRequest.page_token parameter can be used to skip ahead in + // the stream (e.g. when retrying a partially completed and aborted request), + // by setting it to a value taken from GetTreeResponse.next_page_token of the + // last successfully processed GetTreeResponse). + // + // The exact traversal order is unspecified and, unless retrieving subsequent + // pages from an earlier request, is not guaranteed to be stable across + // multiple invocations of `GetTree`. + // + // If part of the tree is missing from the CAS, the server will return the + // portion present and omit the rest. + // + // Errors: + // + // * `NOT_FOUND`: The requested tree root is not present in the CAS. GetTree(*GetTreeRequest, ContentAddressableStorage_GetTreeServer) error } @@ -3621,6 +4819,14 @@ var _ContentAddressableStorage_serviceDesc = grpc.ServiceDesc{ // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type CapabilitiesClient interface { + // GetCapabilities returns the server capabilities configuration of the + // remote endpoint. + // Only the capabilities of the services supported by the endpoint will + // be returned: + // * Execution + CAS + Action Cache endpoints should return both + // CacheCapabilities and ExecutionCapabilities. + // * Execution only endpoints should return ExecutionCapabilities. + // * CAS + Action Cache only endpoints should return CacheCapabilities. GetCapabilities(ctx context.Context, in *GetCapabilitiesRequest, opts ...grpc.CallOption) (*ServerCapabilities, error) } @@ -3643,6 +4849,14 @@ func (c *capabilitiesClient) GetCapabilities(ctx context.Context, in *GetCapabil // CapabilitiesServer is the server API for Capabilities service. type CapabilitiesServer interface { + // GetCapabilities returns the server capabilities configuration of the + // remote endpoint. + // Only the capabilities of the services supported by the endpoint will + // be returned: + // * Execution + CAS + Action Cache endpoints should return both + // CacheCapabilities and ExecutionCapabilities. + // * Execution only endpoints should return ExecutionCapabilities. + // * CAS + Action Cache only endpoints should return CacheCapabilities. GetCapabilities(context.Context, *GetCapabilitiesRequest) (*ServerCapabilities, error) } diff --git a/build/bazel/remote/logstream/v1/remote_logstream.pb.go b/build/bazel/remote/logstream/v1/remote_logstream.pb.go index 1e918eaf..405668fd 100755 --- a/build/bazel/remote/logstream/v1/remote_logstream.pb.go +++ b/build/bazel/remote/logstream/v1/remote_logstream.pb.go @@ -24,7 +24,12 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package +// Contains all information necessary to create a new LogStream resource. type CreateLogStreamRequest struct { + // Required. The parent resource of the created LogStream. + // The list of valid types of parent resources of LogStreams is up to the + // implementing server. + // Example: projects/123 Parent string `protobuf:"bytes,1,opt,name=parent,proto3" json:"parent,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -63,8 +68,33 @@ func (m *CreateLogStreamRequest) GetParent() string { return "" } +// A handle to a log (an ordered sequence of bytes). type LogStream struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // Structured name of the resource in the format: + // {parent=**}/logstreams/{logstream_id} + // Example: projects/123/logstreams/456-def + // Attempting to call the Byte Stream API's `Write` RPC with a LogStream's + // `name` as the value for `ByteStream.Write.resource_name` is an error. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // Resource name to pass to `ByteStream.Write` in the format: + // {parent=**}/logstreams/{logstream_id}/{write_token} + // Example: projects/123/logstreams/456-def/789-ghi + // Attempting to call the Byte Stream API's `Read` RPC with a LogStream's + // `write_resource_name` as the value for `ByteStream.Write.resource_name` + // is an error. + // + // `write_resource_name` is separate from `name` to ensure that only the + // intended writers can write to a given LogStream. Writers must address write + // operations to the `write_resource_name`, not the `name`, and must have + // permission to write LogStreams. `write_resource_name` embeds a secret token + // and should be protected accordingly; a mishandled `write_resource_name` can + // result in unintended writers corrupting the LogStream. Therefore, the field + // should be excluded from calls to any calls which retrieve LogStream + // metadata (i.e.: `GetLogStream`). + // + // Bytes written to this resource must to be readable when `ByteStream.Read` + // is called with the `name` resource. + // Reading a write_resource_name must return an INVALID_ARGUMENT error. WriteResourceName string `protobuf:"bytes,2,opt,name=write_resource_name,json=writeResourceName,proto3" json:"write_resource_name,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -152,6 +182,12 @@ const _ = grpc.SupportPackageIsVersion4 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type LogStreamServiceClient interface { + // Create a LogStream which may be written to. + // + // The returned LogStream resource name will include a `write_resource_name` + // which is the resource to use when writing to the LogStream. + // Callers of CreateLogStream are expected to NOT publish the + // `write_resource_name`. CreateLogStream(ctx context.Context, in *CreateLogStreamRequest, opts ...grpc.CallOption) (*LogStream, error) } @@ -174,6 +210,12 @@ func (c *logStreamServiceClient) CreateLogStream(ctx context.Context, in *Create // LogStreamServiceServer is the server API for LogStreamService service. type LogStreamServiceServer interface { + // Create a LogStream which may be written to. + // + // The returned LogStream resource name will include a `write_resource_name` + // which is the resource to use when writing to the LogStream. + // Callers of CreateLogStream are expected to NOT publish the + // `write_resource_name`. CreateLogStream(context.Context, *CreateLogStreamRequest) (*LogStream, error) } diff --git a/build/bazel/semver/semver.pb.go b/build/bazel/semver/semver.pb.go index a29df454..1ffaca54 100755 --- a/build/bazel/semver/semver.pb.go +++ b/build/bazel/semver/semver.pb.go @@ -20,10 +20,17 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package +// The full version of a given tool. type SemVer struct { - Major int32 `protobuf:"varint,1,opt,name=major,proto3" json:"major,omitempty"` - Minor int32 `protobuf:"varint,2,opt,name=minor,proto3" json:"minor,omitempty"` - Patch int32 `protobuf:"varint,3,opt,name=patch,proto3" json:"patch,omitempty"` + // The major version, e.g 10 for 10.2.3. + Major int32 `protobuf:"varint,1,opt,name=major,proto3" json:"major,omitempty"` + // The minor version, e.g. 2 for 10.2.3. + Minor int32 `protobuf:"varint,2,opt,name=minor,proto3" json:"minor,omitempty"` + // The patch version, e.g 3 for 10.2.3. + Patch int32 `protobuf:"varint,3,opt,name=patch,proto3" json:"patch,omitempty"` + // The pre-release version. Either this field or major/minor/patch fields + // must be filled. They are mutually exclusive. Pre-release versions are + // assumed to be earlier than any released versions. Prerelease string `protobuf:"bytes,4,opt,name=prerelease,proto3" json:"prerelease,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"`