Custom Metadata Transmission

What is gRPC Metadata?

Why Use Metadata?

Metadata Structure & Types

Client: Sending Request Metadata

Client: Sending Metadata Example

package com.coddykit.grpc;

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.Metadata;
import io.grpc.stub.MetadataUtils;
import io.grpc.StatusRuntimeException;
import java.util.concurrent.TimeUnit;

public class GrpcClient {
  private final ManagedChannel channel;
  private final GreeterGrpc.GreeterBlockingStub blockingStub;

  public GrpcClient(String host, int port) {
    this.channel = ManagedChannelBuilder.forAddress(host, port)
        .usePlaintext()
        .build();
    blockingStub = GreeterGrpc.newBlockingStub(channel);
  }

  public void shutdown() throws InterruptedException {
    channel.shutdown().awaitTermination(5, TimeUnit.SECONDS);
  }

  public void sayHello(String name, String customValue) {
    System.out.println("Sending custom-key: " + customValue);
    HelloRequest request = HelloRequest.newBuilder().setName(name).build();

    // 1. Create Metadata object
    Metadata headers = new Metadata();
    // 2. Define a Metadata.Key for your header
    Metadata.Key<String> customKey = Metadata.Key.of(
        "custom-key", Metadata.ASCII_STRING_MARSHALLER);
    // 3. Put the key-value pair into Metadata
    headers.put(customKey, customValue);
    
    // 4. Attach metadata to the stub
    GreeterGrpc.GreeterBlockingStub stubWithMetadata = 
        MetadataUtils.attachHeaders(blockingStub, headers);

    try {
      HelloReply response = stubWithMetadata.SayHello(request);
      System.out.println("Greeting: " + response.getMessage());
    } catch (StatusRuntimeException e) {
      System.err.println("RPC failed: " + e.getStatus());
    }
  }

  public static void main(String[] args) throws Exception {
    GrpcClient client = new GrpcClient("localhost", 50051);
    try {
      client.sayHello("CoddyKit User", "my-session-id-123");
    } finally {
      client.shutdown();
    }
  }
}

Server: Receiving Request Metadata

Server: Receiving Metadata Example

package com.coddykit.grpc;

import io.grpc.Context;
import io.grpc.Metadata;
import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.ServerCall;
import io.grpc.ServerCallHandler;
import io.grpc.ServerInterceptor;
import io.grpc.stub.StreamObserver;
import java.io.IOException;

public class GrpcServer {
  private Server server;

  // Context.Key to store the custom value for the service method
  private static final Context.Key<String> CUSTOM_VALUE_CTX_KEY = Context.key("custom-value");

  private void start() throws IOException {
    int port = 50051;
    server = ServerBuilder.forPort(port)
        .addService(new GreeterService())
        .intercept(new CustomHeaderInterceptor()) // Add our interceptor
        .build()
        .start();
    System.out.println("Server started, listening on " + port);
    Runtime.getRuntime().addShutdownHook(new Thread(() -> {
      System.err.println("*** shutting down server");
      try { GrpcServer.this.stop(); } 
      catch (InterruptedException e) { e.printStackTrace(System.err); }
      System.err.println("*** server shut down");
    }));
  }

  private void stop() throws InterruptedException {
    if (server != null) { server.shutdown().awaitTermination(); }
  }

  private void blockUntilShutdown() throws InterruptedException {
    if (server != null) { server.awaitTermination(); }
  }

  public static void main(String[] args) throws Exception {
    final GrpcServer server = new GrpcServer();
    server.start();
    server.blockUntilShutdown();
  }

  static class GreeterService extends GreeterGrpc.GreeterImplBase {
    @Override
    public void SayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
      // Retrieve custom value from Context
      String customValue = CUSTOM_VALUE_CTX_KEY.get();
      System.out.println("Service received custom-key: " + customValue);

      HelloReply reply = HelloReply.newBuilder()
          .setMessage("Hello " + request.getName() + 
                      "! Custom value: " + customValue)
          .build();
      responseObserver.onNext(reply);
      responseObserver.onCompleted();
    }
  }

  static class CustomHeaderInterceptor implements ServerInterceptor {
    // Define the Metadata.Key for our custom header
    private static final Metadata.Key<String> CUSTOM_KEY = 
        Metadata.Key.of("custom-key", Metadata.ASCII_STRING_MARSHALLER);

    @Override
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
        ServerCall<ReqT, RespT> call,
        Metadata headers,
        ServerCallHandler<ReqT, RespT> next) {

      // Get the custom value from incoming headers
      String customValue = headers.get(CUSTOM_KEY);
      System.out.println("Interceptor received custom-key: " + customValue);

      // Store the custom value in the Context for the service to access
      Context context = Context.current().withValue(CUSTOM_VALUE_CTX_KEY, customValue);
      
      // Proceed with the call within the new context
      return Context.current().call(() -> next.startCall(call, headers));
    }
  }
}

Server: Sending Response Metadata

Client: Receiving Response Metadata

Metadata Use Cases

Recap: Metadata in gRPC