grpc-java CallCredentials without thisUsesUnstableApi? - grpc

Question

I've got a gRPC server acting as a proxy. It forwards a few auth-related headers in a ServerInterceptor/ClientInterceptor pair. See below for most of the code.
My question is: the only way I've seen so far to set Metadata headers for outgoing gRPC calls is to make a subclass of CallCredentials. To do that, though, you need to confess your sins by implementing the thisUsesUnstableApi method.
Is there any stable alternative to making a subclass of CallCredentials?
The ServerInterceptor grabs the relevant headers out of Metadata and stuffs them in the Context:
#Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
ServerCall<ReqT, RespT> call,
final Metadata requestHeaders,
ServerCallHandler<ReqT, RespT> next) {
Context contextWithAuth = Context.current();
// Cutting out my utility classes that won't help those looking for an example.
for (...) {
contextWithAuth = contextWithAuth.withValue(Context.key(foo), requestHeaders.get(Metadata.Key.of(...)));
}
return Contexts.interceptCall(contextWithAuth, call, requestHeaders, next);
}
The ClientInterceptor grabs the headers out of the Context and stuffs them in the outgoing Metadata:
#Override
public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
return next.newCall(
method,
callOptions.withCallCredentials(
new CallCredentials() {
#Override
public void applyRequestMetadata(
RequestInfo requestInfo, Executor appExecutor, MetadataApplier applier) {
try {
Metadata headers = new Metadata();
for (...) {
headers.put(Metadata.Key.of(...), Context.key(...).get());
}
applier.apply(headers);
} catch (RuntimeException e) {
applier.fail(Status.UNAUTHENTICATED.withCause(e));
}
}
#Override
public void thisUsesUnstableApi() {
}
}));
}

Answer 1

Most header processing is handled with ClientInterceptors (and ServerInterceptors). For example, to add a header to a client:
#Override
public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
return new new SimpleForwardingClientCall<ReqT, RespT>(next.newCall(method, callOptions)) {
#Override
public void start(Listener<RespT> responseListener, Metadata headers) {
headers.put(MY_HEADER_KEY, "someValue");
super.start(responseListener, headers);
}
}
}
CallCredentials is less powerful and more powerful than ClientInterceptors. It can only add request headers, but it is easy to make asynchronous and it has access to precise connection information (security, remote ip, etc). Easy asynchronous is very helpful when needing do I/O to obtain an OAuth token and being able to access security information of the transport is helpful to ensure that it is safe to transmit the bearer token. It is also called just before sending the RPC so the token can be very fresh. This doesn't sound all that relevant for you.
If you are wanting to use CallCredentials and just bothered by the unstable API then you can encourage it to be stabilized on its experimental-tracking issue. It is an older API and hasn't changed much, so may be close to stabilization.
(Aside: the annoying thisUsesUnstableApi() method is because the name CallCredentials is stable, so users can pass them around safely, but implementing it and calling it is unstable. That is a rare situation so the method is there to warn you.)
If you are making a proxy, it may be easier to use ClientCall and ServerCall directly, without the stubs. That carries the cost of needing to manage flow control directly (e.g., calling request()), but overall might be a better fit. You also may be interested in my fully-generic proxy example.