build.bazel.remote.execution.v2.ContentAddressableStorageClient.kt Maven / Gradle / Ivy

Go to download
package build.bazel.remote.execution.v2

import com.google.api.kgax.Retry
import com.google.api.kgax.grpc.ClientCallOptions
import com.google.api.kgax.grpc.ClientCallOptions.Builder
import com.google.api.kgax.grpc.GrpcBasicRetry
import com.google.api.kgax.grpc.GrpcClientStub
import com.google.api.kgax.grpc.ServerStreamingCall
import com.google.api.kgax.grpc.pager
import com.google.api.kgax.grpc.prepare
import com.google.longrunning.OperationsClientStub
import io.grpc.ManagedChannel
import io.grpc.ManagedChannelBuilder
import java.util.concurrent.TimeUnit
import javax.annotation.Generated
import kotlin.Boolean
import kotlin.Int
import kotlin.Long
import kotlin.String
import kotlin.Unit
import kotlin.collections.List
import kotlin.jvm.JvmOverloads
import kotlin.jvm.JvmStatic
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope

/**
 *
 *
 *
 *
 * [Product Documentation](http://www.google.com)
 */
@Generated("com.google.api.kotlin.generator.GRPCGenerator")
class ContentAddressableStorageClient private constructor(
    val channel: ManagedChannel,
    val options: ClientCallOptions,
    factory: Stubs.Factory? = null
) {
    private val stubs: Stubs = factory?.create(channel, options) ?: Stubs(
            ContentAddressableStorageClientStub(channel).prepare(options),
            OperationsClientStub(channel).prepare(options))

    /**
     * Prepare for an API call by setting any desired options. For example:
     *
     * ```
     * val client = ContentAddressableStorageClient.create()
     * val response = client.prepare {
     *     withMetadata("my-custom-header", listOf("some", "thing"))
     * }.findMissingBlobs(request)
     * ```
     *
     * You may save the client returned by this call and reuse it if you
     * plan to make multiple requests with the same settings.
     */
    fun prepare(init: ClientCallOptions.Builder.() -> Unit): ContentAddressableStorageClient {
        val optionsBuilder = ClientCallOptions.Builder(options)
        optionsBuilder.init()
        return ContentAddressableStorageClient(channel, optionsBuilder.build())
    }

    /**
     * Shutdown the [channel] associated with this client.
     */
    fun shutdownChannel(waitForSeconds: Long = 5) {
        channel.shutdown().awaitTermination(waitForSeconds, TimeUnit.SECONDS)
    }

    /**
     * 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.
     *
     * For example:
     * ```
     * val client = ContentAddressableStorageClient.create()
     * val result = client.findMissingBlobs(
     *     findMissingBlobsRequest {
     *     }
     * )
     * ```
     *
     * @param request the request object for the API call
     */
    suspend fun findMissingBlobs(request: FindMissingBlobsRequest): FindMissingBlobsResponse =
            stubs.api.execute(context = "findMissingBlobs") {
        it.findMissingBlobs(request)
    }

    /**
     * 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.
     *
     * For example:
     * ```
     * val client = ContentAddressableStorageClient.create()
     * val result = client.batchUpdateBlobs(
     *     batchUpdateBlobsRequest {
     *     }
     * )
     * ```
     *
     * @param request the request object for the API call
     */
    suspend fun batchUpdateBlobs(request: BatchUpdateBlobsRequest): BatchUpdateBlobsResponse =
            stubs.api.execute(context = "batchUpdateBlobs") {
        it.batchUpdateBlobs(request)
    }

    /**
     * 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.
     *
     * For example:
     * ```
     * val client = ContentAddressableStorageClient.create()
     * val result = client.batchReadBlobs(
     *     batchReadBlobsRequest {
     *     }
     * )
     * ```
     *
     * @param request the request object for the API call
     */
    suspend fun batchReadBlobs(request: BatchReadBlobsRequest): BatchReadBlobsResponse =
            stubs.api.execute(context = "batchReadBlobs") {
        it.batchReadBlobs(request)
    }

    /**
     * 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.
     *
     * For example:
     * ```
     * val client = ContentAddressableStorageClient.create()
     * val result = client.getTree(
     *     getTreeRequest {
     *     }
     * )
     * ```
     */
    fun getTree(request: GetTreeRequest): ServerStreamingCall =
            stubs.api.executeServerStreaming(context = "getTree") { stub, observer ->
        stub.getTree(request, observer)
    }

    /**
     * Utilities for creating a fully configured ContentAddressableStorageClient.
     */
    companion object {
        /**
         * Default scopes to use. Use [prepare] to override as needed.
         */
        @JvmStatic
        val ALL_SCOPES: List = listOf()

        /**
         * Default operations to retry on failure. Use [prepare] to override as needed.
         *
         * Note: This setting controls client side retries. If you enable
         * server managed retries on the channel do not use this.
         */
        @JvmStatic
        val RETRY: Retry = GrpcBasicRetry(mapOf())

        /**
         * Create a ContentAddressableStorageClient with the provided [channel], [options], or stub
         * [factory].
         */
        @JvmStatic
        @JvmOverloads
        fun create(
            channel: ManagedChannel? = null,
            options: ClientCallOptions? = null,
            factory: Stubs.Factory? = null
        ): ContentAddressableStorageClient = ContentAddressableStorageClient(
            channel ?: createChannel(),
            options ?: ClientCallOptions(),
            factory
        )

        /**
         * Create a [ManagedChannel] to use with a ContentAddressableStorageClient.
         *
         * [enableRetry] can be used to enable server managed retries, which is currently
         * experimental. You should not use any client retry settings if you enable it.
         */
        @JvmStatic
        @JvmOverloads
        fun createChannel(
            host: String = "",
            port: Int = 443,
            enableRetry: Boolean = false
        ): ManagedChannel {
            val builder = ManagedChannelBuilder.forAddress(host, port)
            if (enableRetry) {
                builder.enableRetry()
            }
            return builder.build()
        }
    }

    class Stubs(val api: GrpcClientStub, val operation:
            GrpcClientStub) {
        interface Factory {
            fun create(channel: ManagedChannel, options: ClientCallOptions): Stubs
        }
    }
}