Skip to content
Kessel

Package: {service}.{major_version}

Package for code specific to service and API version, where {service} is the separately versioned service (e.g. “inventory” or “rbac”) and {major_version} is the major revision of the API (e.g. v1beta2, v1, v2), such as generated client code.

Hand-written code MAY be added to these package(s), if it is version-specific.

  • This MAY depend on peer packages.
  • For example, middleware or utilities which integrate with this version can be placed here (such as {prefix}.rbac.v2 for easy Workspace lookups).

.rbac (or any other {service}) may be nested for RBAC/service-specific utilities which are also specific to that service-API version.

  • For example, {prefix}.inventory.v1beta2.rbac for creating SubjectReferences, ResourceReferences, etc, following RBAC’s well-known schema).

Special notes about ClientBuilder

Section titled “Special notes about ClientBuilder”

The ClientBuilder incorporates best practices for that language. This means by definition, behavior may be language specific in more ways than is typical of this specification.

For example, in the Python reference implementation, the default configuration, when not using asyncio, might use single-threaded unary streams for a performance improvement.

Additionally, not all languages are consistent in their treatment of Channels, ChannelOptions, and Stub configuration. In this case, the ClientBuilder is meant to be consistent despite these differences, within reason. For example, in some languages (Python, Go), everything meaningful is configured on the Channel itself. In some languages (Java), the stub itself contains CallOptions. In some languages, the Channel provides built-in methods for configuring it. In other languages, you have to provide CallOptions yourself, etc.

While the builders are specific to a service and version, they MAY delegate to or inherit from generic gRPC code in the grpc package (e.g., a base class).

Classes

ClientBuilder

A builder for constructing stubs for the package's service and version with "out of the box" defaults. These defaults configure recommending settings and integrations defined by the Kessel team.

If you would like more control over channel or stub construction, use the gRPC API directly, though this is not recommended.

Example:

inventory = inventory.v1beta2.ClientBuilder(target)
    .oauth2ClientAuthenticated(OAuth2ClientCredentials(
        client_id="example",
        client_secret="example",
        token_url="example.com/token))
    .build()

Constructors

  • ClientBuilder (target : string)

    Start a builder using the provided target URI.

    target : string

    The target URI for routing and discovery.

    For gRPC the scheme of the URI determines how name resolution works. dns:// will use DNS to resolve the host name to IPs and service configuration (from a TXT record).

    Omitting a scheme is valid. In that case, "dns" is used.

    For more information, see the gRPC docs.

    Default configuration:

    • Use runtime-default TLS configuration for channel credential
    • Python should enable use of single-threaded unary streams when asyncio is not used
    • Otherwise, uses stock gRPC defaults (note: no keep alive)

Methods

  • oauth2ClientAuthenticated (oauth2ClientCredentials : OAuth2ClientCredentials, channelCredentials? : ChannelCredentials)

    Configures CallCredentials using the OAuth2 Client Credentials grant.

    oauth2ClientCredentials : OAuth2ClientCredentials

    Configures the OAuth2 Client Credentials grant in order to authenticate the client for each remote procedure call (RPC). Tokens are refreshed automatically when needed.

    channelCredentials? : ChannelCredentials

    The gRPC ChannelCredentials to use for each channel connection. This authenticates the server (e.g. through TLS) and, optionally, your client (e.g. through mutual TLS).

    If not explicitly provided, the ClientBuilder MUST default to using TLS to authenticate the server with the runtime's default trust bundle and TLS configuration.

  • authenticated (callCredentials? : CallCredentials, channelCredential? : ChannelCredentials)
    callCredentials? : CallCredentials

    The gRPC CallCredentials to use for each remote procedure call (RPC). This authenticates the client to the server.

    See oauth2ClientAuthenticated to authenticate using OAuth2 Client Credentials.

    channelCredential? : ChannelCredentials

    See above ChannelCredentials param description.

  • unauthenticated (channelCredential? : ChannelCredentials)

    Configures only a ChannelCredentials to secure communication with the server. The client is not authenticated.

    channelCredential? : ChannelCredentials

    See above ChannelCredentials param description.

  • insecure ()

    Configures insecure communication with the server (e.g. for testing). Neither the client nor the server is authenticated.

  • build () : {Service}Stub (and possibly the channel – see description)

    Constructs the generated stub for the package's service and version following the builder's configuration.

    Resource Management: Some languages (e.g. Python, Java, Go) have connection abstractions that are separate from the stub (Python: Channel, Java: ManagedChannel, Go: Client) and require explicit cleanup to prevent resource leaks.

    Return Value:

    • If the stub has a close() method: return the stub directly
    • If the stub lacks a close() method: return a tuple (Stub, Closeable) where Closeable is the resource that needs cleanup

    This pattern ensures consistent resource management across all language implementations.

  • buildAsync () : (Async) {Service}Stub
    Only inPythonJavaScript

    Like build, but constructs a stub with async primitives.

    For JavaScript, this returns a Promise-based stub API.

    For Python, this returns a stub using asyncio.

    Implementation note: Wrapping the generated stubs is not ideal, but if it has to be done, ensure the wrapper is consistent with the stub API.