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.
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:
methodis the gRPC full method name without a leading slash,avp.Vault/Push, the form a gRPC runtime's full method name takes.metadatacarriesauthorizationon an authenticated call and nothing else; it holds the bearer token, a credential the channel must not log.- Passing
deadlineto 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
unaryon 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-binkeys.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
maxInboundMessageSizeis 4 MiB): a reply over the channel's limit fails locally withRESOURCE_EXHAUSTED, which the library reports astoo_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#vaultRpcChannelruns 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 ClassesModifier and TypeInterfaceDescriptionstatic final classThe outcome of one call: the response message onOK, else the status code, its message and the trailers. -
Method Summary
Modifier and TypeMethodDescriptionStarts 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/Pullrequest- the encoded request messagemetadata- the request metadata:authorizationon an authenticated call, else emptydeadline- the deadline to give the call- Returns:
- the call's outcome; never
null - Since:
- 1.1.0
-