executionv2grpc

package
v1.6.2-20230602030542-... Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: unknown License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	Execution_Execute_FullMethodName       = "/build.bazel.remote.execution.v2.Execution/Execute"
	Execution_WaitExecution_FullMethodName = "/build.bazel.remote.execution.v2.Execution/WaitExecution"
)
View Source 
const (
	ActionCache_GetActionResult_FullMethodName    = "/build.bazel.remote.execution.v2.ActionCache/GetActionResult"
	ActionCache_UpdateActionResult_FullMethodName = "/build.bazel.remote.execution.v2.ActionCache/UpdateActionResult"
)
View Source 
const (
	ContentAddressableStorage_FindMissingBlobs_FullMethodName = "/build.bazel.remote.execution.v2.ContentAddressableStorage/FindMissingBlobs"
	ContentAddressableStorage_BatchUpdateBlobs_FullMethodName = "/build.bazel.remote.execution.v2.ContentAddressableStorage/BatchUpdateBlobs"
	ContentAddressableStorage_BatchReadBlobs_FullMethodName   = "/build.bazel.remote.execution.v2.ContentAddressableStorage/BatchReadBlobs"
	ContentAddressableStorage_GetTree_FullMethodName          = "/build.bazel.remote.execution.v2.ContentAddressableStorage/GetTree"
)
View Source 
const (
	Capabilities_GetCapabilities_FullMethodName = "/build.bazel.remote.execution.v2.Capabilities/GetCapabilities"
)

Variables

View Source 
var ActionCache_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "build.bazel.remote.execution.v2.ActionCache",
	HandlerType: (*ActionCacheServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "GetActionResult",
			Handler:    _ActionCache_GetActionResult_Handler,
		},
		{
			MethodName: "UpdateActionResult",
			Handler:    _ActionCache_UpdateActionResult_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "build/bazel/remote/execution/v2/remote_execution.proto",
}

ActionCache_ServiceDesc is the grpc.ServiceDesc for ActionCache service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

View Source 
var Capabilities_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "build.bazel.remote.execution.v2.Capabilities",
	HandlerType: (*CapabilitiesServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "GetCapabilities",
			Handler:    _Capabilities_GetCapabilities_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "build/bazel/remote/execution/v2/remote_execution.proto",
}

Capabilities_ServiceDesc is the grpc.ServiceDesc for Capabilities service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

View Source 
var ContentAddressableStorage_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "build.bazel.remote.execution.v2.ContentAddressableStorage",
	HandlerType: (*ContentAddressableStorageServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "FindMissingBlobs",
			Handler:    _ContentAddressableStorage_FindMissingBlobs_Handler,
		},
		{
			MethodName: "BatchUpdateBlobs",
			Handler:    _ContentAddressableStorage_BatchUpdateBlobs_Handler,
		},
		{
			MethodName: "BatchReadBlobs",
			Handler:    _ContentAddressableStorage_BatchReadBlobs_Handler,
		},
	},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "GetTree",
			Handler:       _ContentAddressableStorage_GetTree_Handler,
			ServerStreams: true,
		},
	},
	Metadata: "build/bazel/remote/execution/v2/remote_execution.proto",
}

ContentAddressableStorage_ServiceDesc is the grpc.ServiceDesc for ContentAddressableStorage service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

View Source 
var Execution_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "build.bazel.remote.execution.v2.Execution",
	HandlerType: (*ExecutionServer)(nil),
	Methods:     []grpc.MethodDesc{},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "Execute",
			Handler:       _Execution_Execute_Handler,
			ServerStreams: true,
		},
		{
			StreamName:    "WaitExecution",
			Handler:       _Execution_WaitExecution_Handler,
			ServerStreams: true,
		},
	},
	Metadata: "build/bazel/remote/execution/v2/remote_execution.proto",
}

Execution_ServiceDesc is the grpc.ServiceDesc for Execution service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func RegisterActionCacheServer 

func RegisterActionCacheServer(s grpc.ServiceRegistrar, srv ActionCacheServer)

func RegisterCapabilitiesServer 

func RegisterCapabilitiesServer(s grpc.ServiceRegistrar, srv CapabilitiesServer)

func RegisterContentAddressableStorageServer 

func RegisterContentAddressableStorageServer(s grpc.ServiceRegistrar, srv ContentAddressableStorageServer)

func RegisterExecutionServer 

func RegisterExecutionServer(s grpc.ServiceRegistrar, srv ExecutionServer)

Types

type ActionCacheClient 

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 *v2.GetActionResultRequest, opts ...grpc.CallOption) (*v2.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 *v2.UpdateActionResultRequest, opts ...grpc.CallOption) (*v2.ActionResult, error)
}

ActionCacheClient is the client API for ActionCache service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

The action cache API is used to query whether a given action has already been performed and, if so, retrieve its result. Unlike the [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage], which addresses blobs by their own content, the action cache addresses the [ActionResult][build.bazel.remote.execution.v2.ActionResult] by a digest of the encoded [Action][build.bazel.remote.execution.v2.Action] which produced them.

The lifetime of entries in the action cache is implementation-specific, but the server SHOULD assume that more recently used entries are more likely to be used again.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

func NewActionCacheClient 

func NewActionCacheClient(cc grpc.ClientConnInterface) ActionCacheClient

type ActionCacheServer 

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, *v2.GetActionResultRequest) (*v2.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, *v2.UpdateActionResultRequest) (*v2.ActionResult, error)
}

ActionCacheServer is the server API for ActionCache service. All implementations should embed UnimplementedActionCacheServer for forward compatibility.

The action cache API is used to query whether a given action has already been performed and, if so, retrieve its result. Unlike the [ContentAddressableStorage][build.bazel.remote.execution.v2.ContentAddressableStorage], which addresses blobs by their own content, the action cache addresses the [ActionResult][build.bazel.remote.execution.v2.ActionResult] by a digest of the encoded [Action][build.bazel.remote.execution.v2.Action] which produced them.

The lifetime of entries in the action cache is implementation-specific, but the server SHOULD assume that more recently used entries are more likely to be used again.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

type CapabilitiesClient 

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.
	//
	// There are no method-specific errors.
	GetCapabilities(ctx context.Context, in *v2.GetCapabilitiesRequest, opts ...grpc.CallOption) (*v2.ServerCapabilities, error)
}

CapabilitiesClient is the client API for Capabilities service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

The Capabilities service may be used by remote execution clients to query various server properties, in order to self-configure or return meaningful error messages.

The query may include a particular `instance_name`, in which case the values returned will pertain to that instance.

func NewCapabilitiesClient 

func NewCapabilitiesClient(cc grpc.ClientConnInterface) CapabilitiesClient

type CapabilitiesServer 

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.
	//
	// There are no method-specific errors.
	GetCapabilities(context.Context, *v2.GetCapabilitiesRequest) (*v2.ServerCapabilities, error)
}

CapabilitiesServer is the server API for Capabilities service. All implementations should embed UnimplementedCapabilitiesServer for forward compatibility.

The Capabilities service may be used by remote execution clients to query various server properties, in order to self-configure or return meaningful error messages.

The query may include a particular `instance_name`, in which case the values returned will pertain to that instance.

type ContentAddressableStorageClient 

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 *v2.FindMissingBlobsRequest, opts ...grpc.CallOption) (*v2.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 *v2.BatchUpdateBlobsRequest, opts ...grpc.CallOption) (*v2.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 *v2.BatchReadBlobsRequest, opts ...grpc.CallOption) (*v2.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 *v2.GetTreeRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[v2.GetTreeResponse], error)
}

ContentAddressableStorageClient is the client API for ContentAddressableStorage service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

The CAS (content-addressable storage) is used to store the inputs to and outputs from the execution service. Each piece of content is addressed by the digest of its binary data.

Most of the binary data stored in the CAS is opaque to the execution engine, and is only used as a communication medium. In order to build an [Action][build.bazel.remote.execution.v2.Action], however, the client will need to also upload the [Command][build.bazel.remote.execution.v2.Command] and input root [Directory][build.bazel.remote.execution.v2.Directory] for the Action. The Command and Directory messages must be marshalled to wire format and then uploaded under the hash as with any other piece of content. In practice, the input root directory is likely to refer to other Directories in its hierarchy, which must also each be uploaded on their own.

For small file uploads the client should group them together and call [BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs].

For large uploads, the client must use the [Write method][google.bytestream.ByteStream.Write] of the ByteStream API.

For uncompressed data, The `WriteRequest.resource_name` is of the following form: `{instance_name}/uploads/{uuid}/blobs/{digest_function/}{hash}/{size}{/optional_metadata}`

Where:

  • `instance_name` is an identifier used to distinguish between the various instances on the server. Syntax and semantics of this field are defined by the server; Clients must not make any assumptions about it (e.g., whether it spans multiple path segments or not). If it is the empty path, the leading slash is omitted, so that the `resource_name` becomes `uploads/{uuid}/blobs/{digest_function/}{hash}/{size}{/optional_metadata}`. To simplify parsing, a path segment cannot equal any of the following keywords: `blobs`, `uploads`, `actions`, `actionResults`, `operations`, `capabilities` or `compressed-blobs`.
  • `uuid` is a version 4 UUID generated by the client, used to avoid collisions between concurrent uploads of the same data. Clients MAY reuse the same `uuid` for uploading different blobs.
  • `digest_function` is a lowercase string form of a `DigestFunction.Value` enum, indicating which digest function was used to compute `hash`. If the digest function used is one of MD5, MURMUR3, SHA1, SHA256, SHA384, SHA512, or VSO, this component MUST be omitted. In that case the server SHOULD infer the digest function using the length of the `hash` and the digest functions announced in the server's capabilities.
  • `hash` and `size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being uploaded.
  • `optional_metadata` is implementation specific data, which clients MAY omit. Servers MAY ignore this metadata.

Data can alternatively be uploaded in compressed form, with the following `WriteRequest.resource_name` form: `{instance_name}/uploads/{uuid}/compressed-blobs/{compressor}/{digest_function/}{uncompressed_hash}/{uncompressed_size}{/optional_metadata}`

Where:

  • `instance_name`, `uuid`, `digest_function` and `optional_metadata` are defined as above.
  • `compressor` is a lowercase string form of a `Compressor.Value` enum other than `identity`, which is supported by the server and advertised in [CacheCapabilities.supported_compressor][build.bazel.remote.execution.v2.CacheCapabilities.supported_compressor].
  • `uncompressed_hash` and `uncompressed_size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being uploaded, once uncompressed. Servers MUST verify that these match the uploaded data once uncompressed, and MUST return an `INVALID_ARGUMENT` error in the case of mismatch.

Note that when writing compressed blobs, the `WriteRequest.write_offset` in the initial request in a stream refers to the offset in the uncompressed form of the blob. In subsequent requests, `WriteRequest.write_offset` MUST be the sum of the first request's 'WriteRequest.write_offset' and the total size of all the compressed data bundles in the previous requests. Note that this mixes an uncompressed offset with a compressed byte length, which is nonsensical, but it is done to fit the semantics of the existing ByteStream protocol.

Uploads of the same data MAY occur concurrently in any form, compressed or uncompressed.

Clients SHOULD NOT use gRPC-level compression for ByteStream API `Write` calls of compressed blobs, since this would compress already-compressed data.

When attempting an upload, if another client has already completed the upload (which may occur in the middle of a single upload if another client uploads the same blob concurrently), the request will terminate immediately without error, and with a response whose `committed_size` is the value `-1` if this is a compressed upload, or with the full size of the uploaded file if this is an uncompressed upload (regardless of how much data was transmitted by the client). If the client completes the upload but the [Digest][build.bazel.remote.execution.v2.Digest] does not match, an `INVALID_ARGUMENT` error will be returned. In either case, the client should not attempt to retry the upload.

Small downloads can be grouped and requested in a batch via [BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs].

For large downloads, the client must use the [Read method][google.bytestream.ByteStream.Read] of the ByteStream API.

For uncompressed data, The `ReadRequest.resource_name` is of the following form: `{instance_name}/blobs/{digest_function/}{hash}/{size}` Where `instance_name`, `digest_function`, `hash` and `size` are defined as for uploads.

Data can alternatively be downloaded in compressed form, with the following `ReadRequest.resource_name` form: `{instance_name}/compressed-blobs/{compressor}/{digest_function/}{uncompressed_hash}/{uncompressed_size}`

Where:

  • `instance_name`, `compressor` and `digest_function` are defined as for uploads.
  • `uncompressed_hash` and `uncompressed_size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being downloaded, once uncompressed. Clients MUST verify that these match the downloaded data once uncompressed, and take appropriate steps in the case of failure such as retrying a limited number of times or surfacing an error to the user.

When downloading compressed blobs:

  • `ReadRequest.read_offset` refers to the offset in the uncompressed form of the blob.
  • Servers MUST return `INVALID_ARGUMENT` if `ReadRequest.read_limit` is non-zero.
  • Servers MAY use any compression level they choose, including different levels for different blobs (e.g. choosing a level designed for maximum speed for data known to be incompressible).
  • Clients SHOULD NOT use gRPC-level compression, since this would compress already-compressed data.

Servers MUST be able to provide data for all recently advertised blobs in each of the compression formats that the server supports, as well as in uncompressed form.

The lifetime of entries in the CAS is implementation specific, but it SHOULD be long enough to allow for newly-added and recently looked-up entries to be used in subsequent calls (e.g. to [Execute][build.bazel.remote.execution.v2.Execution.Execute]).

Servers MUST behave as though empty blobs are always available, even if they have not been uploaded. Clients MAY optimize away the uploading or downloading of empty blobs.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

func NewContentAddressableStorageClient 

func NewContentAddressableStorageClient(cc grpc.ClientConnInterface) ContentAddressableStorageClient

type ContentAddressableStorageServer 

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, *v2.FindMissingBlobsRequest) (*v2.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, *v2.BatchUpdateBlobsRequest) (*v2.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, *v2.BatchReadBlobsRequest) (*v2.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(*v2.GetTreeRequest, grpc.ServerStreamingServer[v2.GetTreeResponse]) error
}

ContentAddressableStorageServer is the server API for ContentAddressableStorage service. All implementations should embed UnimplementedContentAddressableStorageServer for forward compatibility.

The CAS (content-addressable storage) is used to store the inputs to and outputs from the execution service. Each piece of content is addressed by the digest of its binary data.

Most of the binary data stored in the CAS is opaque to the execution engine, and is only used as a communication medium. In order to build an [Action][build.bazel.remote.execution.v2.Action], however, the client will need to also upload the [Command][build.bazel.remote.execution.v2.Command] and input root [Directory][build.bazel.remote.execution.v2.Directory] for the Action. The Command and Directory messages must be marshalled to wire format and then uploaded under the hash as with any other piece of content. In practice, the input root directory is likely to refer to other Directories in its hierarchy, which must also each be uploaded on their own.

For small file uploads the client should group them together and call [BatchUpdateBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchUpdateBlobs].

For large uploads, the client must use the [Write method][google.bytestream.ByteStream.Write] of the ByteStream API.

For uncompressed data, The `WriteRequest.resource_name` is of the following form: `{instance_name}/uploads/{uuid}/blobs/{digest_function/}{hash}/{size}{/optional_metadata}`

Where:

  • `instance_name` is an identifier used to distinguish between the various instances on the server. Syntax and semantics of this field are defined by the server; Clients must not make any assumptions about it (e.g., whether it spans multiple path segments or not). If it is the empty path, the leading slash is omitted, so that the `resource_name` becomes `uploads/{uuid}/blobs/{digest_function/}{hash}/{size}{/optional_metadata}`. To simplify parsing, a path segment cannot equal any of the following keywords: `blobs`, `uploads`, `actions`, `actionResults`, `operations`, `capabilities` or `compressed-blobs`.
  • `uuid` is a version 4 UUID generated by the client, used to avoid collisions between concurrent uploads of the same data. Clients MAY reuse the same `uuid` for uploading different blobs.
  • `digest_function` is a lowercase string form of a `DigestFunction.Value` enum, indicating which digest function was used to compute `hash`. If the digest function used is one of MD5, MURMUR3, SHA1, SHA256, SHA384, SHA512, or VSO, this component MUST be omitted. In that case the server SHOULD infer the digest function using the length of the `hash` and the digest functions announced in the server's capabilities.
  • `hash` and `size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being uploaded.
  • `optional_metadata` is implementation specific data, which clients MAY omit. Servers MAY ignore this metadata.

Data can alternatively be uploaded in compressed form, with the following `WriteRequest.resource_name` form: `{instance_name}/uploads/{uuid}/compressed-blobs/{compressor}/{digest_function/}{uncompressed_hash}/{uncompressed_size}{/optional_metadata}`

Where:

  • `instance_name`, `uuid`, `digest_function` and `optional_metadata` are defined as above.
  • `compressor` is a lowercase string form of a `Compressor.Value` enum other than `identity`, which is supported by the server and advertised in [CacheCapabilities.supported_compressor][build.bazel.remote.execution.v2.CacheCapabilities.supported_compressor].
  • `uncompressed_hash` and `uncompressed_size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being uploaded, once uncompressed. Servers MUST verify that these match the uploaded data once uncompressed, and MUST return an `INVALID_ARGUMENT` error in the case of mismatch.

Note that when writing compressed blobs, the `WriteRequest.write_offset` in the initial request in a stream refers to the offset in the uncompressed form of the blob. In subsequent requests, `WriteRequest.write_offset` MUST be the sum of the first request's 'WriteRequest.write_offset' and the total size of all the compressed data bundles in the previous requests. Note that this mixes an uncompressed offset with a compressed byte length, which is nonsensical, but it is done to fit the semantics of the existing ByteStream protocol.

Uploads of the same data MAY occur concurrently in any form, compressed or uncompressed.

Clients SHOULD NOT use gRPC-level compression for ByteStream API `Write` calls of compressed blobs, since this would compress already-compressed data.

When attempting an upload, if another client has already completed the upload (which may occur in the middle of a single upload if another client uploads the same blob concurrently), the request will terminate immediately without error, and with a response whose `committed_size` is the value `-1` if this is a compressed upload, or with the full size of the uploaded file if this is an uncompressed upload (regardless of how much data was transmitted by the client). If the client completes the upload but the [Digest][build.bazel.remote.execution.v2.Digest] does not match, an `INVALID_ARGUMENT` error will be returned. In either case, the client should not attempt to retry the upload.

Small downloads can be grouped and requested in a batch via [BatchReadBlobs][build.bazel.remote.execution.v2.ContentAddressableStorage.BatchReadBlobs].

For large downloads, the client must use the [Read method][google.bytestream.ByteStream.Read] of the ByteStream API.

For uncompressed data, The `ReadRequest.resource_name` is of the following form: `{instance_name}/blobs/{digest_function/}{hash}/{size}` Where `instance_name`, `digest_function`, `hash` and `size` are defined as for uploads.

Data can alternatively be downloaded in compressed form, with the following `ReadRequest.resource_name` form: `{instance_name}/compressed-blobs/{compressor}/{digest_function/}{uncompressed_hash}/{uncompressed_size}`

Where:

  • `instance_name`, `compressor` and `digest_function` are defined as for uploads.
  • `uncompressed_hash` and `uncompressed_size` refer to the [Digest][build.bazel.remote.execution.v2.Digest] of the data being downloaded, once uncompressed. Clients MUST verify that these match the downloaded data once uncompressed, and take appropriate steps in the case of failure such as retrying a limited number of times or surfacing an error to the user.

When downloading compressed blobs:

  • `ReadRequest.read_offset` refers to the offset in the uncompressed form of the blob.
  • Servers MUST return `INVALID_ARGUMENT` if `ReadRequest.read_limit` is non-zero.
  • Servers MAY use any compression level they choose, including different levels for different blobs (e.g. choosing a level designed for maximum speed for data known to be incompressible).
  • Clients SHOULD NOT use gRPC-level compression, since this would compress already-compressed data.

Servers MUST be able to provide data for all recently advertised blobs in each of the compression formats that the server supports, as well as in uncompressed form.

The lifetime of entries in the CAS is implementation specific, but it SHOULD be long enough to allow for newly-added and recently looked-up entries to be used in subsequent calls (e.g. to [Execute][build.bazel.remote.execution.v2.Execution.Execute]).

Servers MUST behave as though empty blobs are always available, even if they have not been uploaded. Clients MAY optimize away the uploading or downloading of empty blobs.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

type ContentAddressableStorage_GetTreeClient 

type ContentAddressableStorage_GetTreeClient = grpc.ServerStreamingClient[v2.GetTreeResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type ContentAddressableStorage_GetTreeServer 

type ContentAddressableStorage_GetTreeServer = grpc.ServerStreamingServer[v2.GetTreeResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type ExecutionClient 

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/{digest_function/}{hash}/{size}"` indicating the digest of the
	// missing blob. The `subject` is formatted the same way as the
	// `resource_name` provided to
	// [ByteStream.Read][google.bytestream.ByteStream.Read], with the leading
	// instance name omitted. `digest_function` MUST thus be omitted if its value
	// is one of MD5, MURMUR3, SHA1, SHA256, SHA384, SHA512, or VSO.
	//
	// The server does not need to guarantee that a call to this method leads to
	// at most one execution of the action. The server MAY execute the action
	// multiple times, potentially in parallel. These redundant executions MAY
	// continue to run, even if the operation is completed.
	Execute(ctx context.Context, in *v2.ExecuteRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[longrunningpb.Operation], 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 *v2.WaitExecutionRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[longrunningpb.Operation], error)
}

ExecutionClient is the client API for Execution service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

The Remote Execution API is used to execute an [Action][build.bazel.remote.execution.v2.Action] on the remote workers.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

func NewExecutionClient 

func NewExecutionClient(cc grpc.ClientConnInterface) ExecutionClient

type ExecutionServer 

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/{digest_function/}{hash}/{size}"` indicating the digest of the
	// missing blob. The `subject` is formatted the same way as the
	// `resource_name` provided to
	// [ByteStream.Read][google.bytestream.ByteStream.Read], with the leading
	// instance name omitted. `digest_function` MUST thus be omitted if its value
	// is one of MD5, MURMUR3, SHA1, SHA256, SHA384, SHA512, or VSO.
	//
	// The server does not need to guarantee that a call to this method leads to
	// at most one execution of the action. The server MAY execute the action
	// multiple times, potentially in parallel. These redundant executions MAY
	// continue to run, even if the operation is completed.
	Execute(*v2.ExecuteRequest, grpc.ServerStreamingServer[longrunningpb.Operation]) 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(*v2.WaitExecutionRequest, grpc.ServerStreamingServer[longrunningpb.Operation]) error
}

ExecutionServer is the server API for Execution service. All implementations should embed UnimplementedExecutionServer for forward compatibility.

The Remote Execution API is used to execute an [Action][build.bazel.remote.execution.v2.Action] on the remote workers.

As with other services in the Remote Execution API, any call may return an error with a [RetryInfo][google.rpc.RetryInfo] error detail providing information about when the client should retry the request; clients SHOULD respect the information provided.

type Execution_ExecuteClient 

type Execution_ExecuteClient = grpc.ServerStreamingClient[longrunningpb.Operation]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type Execution_ExecuteServer 

type Execution_ExecuteServer = grpc.ServerStreamingServer[longrunningpb.Operation]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type Execution_WaitExecutionClient 

type Execution_WaitExecutionClient = grpc.ServerStreamingClient[longrunningpb.Operation]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type Execution_WaitExecutionServer 

type Execution_WaitExecutionServer = grpc.ServerStreamingServer[longrunningpb.Operation]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type UnimplementedActionCacheServer 

type UnimplementedActionCacheServer struct{}

UnimplementedActionCacheServer should be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedActionCacheServer) GetActionResult 

func (UnimplementedActionCacheServer) GetActionResult(context.Context, *v2.GetActionResultRequest) (*v2.ActionResult, error)

func (UnimplementedActionCacheServer) UpdateActionResult 

func (UnimplementedActionCacheServer) UpdateActionResult(context.Context, *v2.UpdateActionResultRequest) (*v2.ActionResult, error)

type UnimplementedCapabilitiesServer 

type UnimplementedCapabilitiesServer struct{}

UnimplementedCapabilitiesServer should be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedCapabilitiesServer) GetCapabilities 

func (UnimplementedCapabilitiesServer) GetCapabilities(context.Context, *v2.GetCapabilitiesRequest) (*v2.ServerCapabilities, error)

type UnimplementedContentAddressableStorageServer 

type UnimplementedContentAddressableStorageServer struct{}

UnimplementedContentAddressableStorageServer should be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedContentAddressableStorageServer) BatchReadBlobs 

func (UnimplementedContentAddressableStorageServer) BatchReadBlobs(context.Context, *v2.BatchReadBlobsRequest) (*v2.BatchReadBlobsResponse, error)

func (UnimplementedContentAddressableStorageServer) BatchUpdateBlobs 

func (UnimplementedContentAddressableStorageServer) BatchUpdateBlobs(context.Context, *v2.BatchUpdateBlobsRequest) (*v2.BatchUpdateBlobsResponse, error)

func (UnimplementedContentAddressableStorageServer) FindMissingBlobs 

func (UnimplementedContentAddressableStorageServer) FindMissingBlobs(context.Context, *v2.FindMissingBlobsRequest) (*v2.FindMissingBlobsResponse, error)

func (UnimplementedContentAddressableStorageServer) GetTree 

func (UnimplementedContentAddressableStorageServer) GetTree(*v2.GetTreeRequest, grpc.ServerStreamingServer[v2.GetTreeResponse]) error

type UnimplementedExecutionServer 

type UnimplementedExecutionServer struct{}

UnimplementedExecutionServer should be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedExecutionServer) Execute 

func (UnimplementedExecutionServer) Execute(*v2.ExecuteRequest, grpc.ServerStreamingServer[longrunningpb.Operation]) error

func (UnimplementedExecutionServer) WaitExecution 

func (UnimplementedExecutionServer) WaitExecution(*v2.WaitExecutionRequest, grpc.ServerStreamingServer[longrunningpb.Operation]) error

type UnsafeActionCacheServer 

type UnsafeActionCacheServer interface {
	// contains filtered or unexported methods
}

UnsafeActionCacheServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to ActionCacheServer will result in compilation errors.

type UnsafeCapabilitiesServer 

type UnsafeCapabilitiesServer interface {
	// contains filtered or unexported methods
}

UnsafeCapabilitiesServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to CapabilitiesServer will result in compilation errors.

type UnsafeContentAddressableStorageServer 

type UnsafeContentAddressableStorageServer interface {
	// contains filtered or unexported methods
}

UnsafeContentAddressableStorageServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to ContentAddressableStorageServer will result in compilation errors.

type UnsafeExecutionServer 

type UnsafeExecutionServer interface {
	// contains filtered or unexported methods
}

UnsafeExecutionServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to ExecutionServer will result in compilation errors.

Source Files

  • remote_execution_grpc.pb.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.