Interface VaultRpcChannel

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface VaultRpcChannel
Host seam that carries the vault's unary calls to an AVP host over the gRPC profile (AVP SPEC 10.3). Optional: without one, a vault host mapped to a grpc:// or grpcs:// address cannot be reached and its connection fails with NOT_CONFIGURED. The library ships no gRPC client of its own; a host adapts its own gRPC runtime with a byte-array marshaller, and may route the call through any tunnel or gateway it likes. The library frames each request and verifies each answer exactly as over HTTP/JSON: a channel moves bytes and learns nothing it could not see on the wire.

The contract:

  • method is the gRPC full method name without a leading slash, avp.Vault/Push, the form a gRPC runtime's full method name takes. metadata carries authorization on an authenticated call and nothing else; it holds the bearer token, a credential the channel must not log.
  • Passing deadline to the call is the channel's job. The library cancels the returned future (cancel(true)) when the deadline plus one second has passed, when the calling thread is interrupted, and when the runtime closes; the channel should cancel its call when that happens.
  • The library calls unary on one of the runtime's executor threads and waits there, so the channel completes the future from its own threads, never from a task queued on that executor.
  • VaultRpcChannel.Reply.trailers() are the response headers and trailers merged: keys lowercase ASCII, one value per key, the last one winning, no -bin keys. VaultRpcChannel.Reply.status(int, String, Map) normalizes the map it is given that way.
  • The channel enforces its own inbound message limit, and that limit MUST be at least 16 MiB, the largest answer a vault host may send (a pull of a large repository reaches it). gRPC runtimes default lower (grpc-java's maxInboundMessageSize is 4 MiB): a reply over the channel's limit fails locally with RESOURCE_EXHAUSTED, which the library reports as too_large, so the call can never succeed. The library also refuses a reply message over 16 MiB as a protocol failure, but only once the bytes are in memory.
  • The runtime never closes a channel: the host owns its lifecycle. The factory set with AltsRuntime.Builder#vaultRpcChannel runs at most once per mapped address per runtime, and the runtime keeps that channel until it closes, when it forgets it without closing it.

A future that completes exceptionally, a channel that throws, and the statuses CANCELLED, DEADLINE_EXCEEDED and UNAVAILABLE are NETWORK; a RESOURCE_EXHAUSTED whose message is not quota_exceeded is too_large (INVALID_INPUT), never a rate limit; a status outside the profile's table (UNKNOWN, UNIMPLEMENTED, INTERNAL, DATA_LOSS and the like) is PROTOCOL, since the host does not speak the profile; a null future or reply is PROTOCOL.

Since:
1.1.0
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    The outcome of one call: the response message on OK, else the status code, its message and the trailers.
  • Method Summary

    Modifier and Type
    Method
    Description
    unary(String method, byte[] request, Map<String,String> metadata, Duration deadline)
    Starts one unary call.
  • Method Details

    • unary

      CompletableFuture<VaultRpcChannel.Reply> unary(String method, byte[] request, Map<String,String> metadata, Duration deadline)
      Starts one unary call.
      Parameters:
      method - the full method name without a leading slash, avp.Vault/Pull
      request - the encoded request message
      metadata - the request metadata: authorization on an authenticated call, else empty
      deadline - the deadline to give the call
      Returns:
      the call's outcome; never null
      Since:
      1.1.0