Access GRPC headers

[anthony-swirldslabs]

PBJ GRPC server and client need to expose an API for applications to access GRPC headers and be able to add custom headers. This way the applications would be able to exchange various meta information (e.g. for traceability purposes) along with the actual data in GRPC requests/replies.

This epic covers:

1. The design of the API
2. The implementation on the client side
3. The implementation on the server side

[timfn-hg]

A first pass at what it would look like is something like:

public interface Pipeline<T> extends Flow.Subscriber<T> {
	
	default void onNext(T item, Map<String, String> headers) throws RuntimeException { }

}


public interface ServiceInterface extends AutoCloseable {
	interface RequestOptions {
		default Map<String, String> staticHeaders() {
			return Map.of();
		}
	}
}

The Pipeline example would allow us to exchange headers on a per-request/response basis. The ServiceInterface example would allow us to create a set of headers that would be included on each request/response. Technically, the ServiceInterface change can be removed and we just always add the additional headers per-request. If the same header is sent via both paths, the Pipeline#onNext header will overwrite the RequestOptions header.

Use case:
There are two types of data I want to share: 1) static connection identifier that doesn't change throughout the life of the connection and 2) a unique ID per request. For # 1, setting the static information in the RequestOptions as the client is built will be able to cover this. For # 2 the Pipeline changes will permit me to include a unique ID for each call. The consumer would then be able to receive the combined headers.

Example:
Via RequestOptions I add the header ("X-Stream-Id", "ABC123") and then via the Pipeline onNext, I add the header ("X-Request-Id", "123-456-789"). The consumer should receive both headers.

[anthony-swirldslabs]

@timfn-hg : please note that the GRPC protocol specification uses HTTP2 headers to exchange the extra custom information. The HTTP2 headers can only be transmitted once per a given HTTP2 connection before any data (requests from the client, or responses from the server) start being transmitted. Per the HTTP2 and GRPC specifications, it's impossible to send additional headers in the middle of an active HTTP2 connection.

To put it another way, technically, the GRPC/HTTP2 headers are a PbjGrpcClient-level concept, rather than a PbjGrpcCall-level concept. We can still support the API similar to the one that you describe above. However, it's important to understand that the client would have to define custom headers before creating a PbjGrpcClient instance, and it cannot change them afterwards. Similarly, a server would send its headers when the PbjGrpcClient opens a connection, and these server-side headers will remain static for every GRPC call performed via that PbjGrpcClient instance because they all will reuse the same HTTP2 connection.

Your application would need to create new PbjGrpcClient instances if/when it needs to change the headers that it sends to the server. This, of course, is slightly more expensive than running all GRPC calls via a single client because the latter approach would just open lightweight streams over a single HTTP2 connection instead of opening new connections for each request.

[anthony-swirldslabs]

@timfn-hg : I may have spoken too soon. There may be a way to associate different metadata with different requests. We create a new stream for every call, and each stream sends its own headers. This is where we pass the metadata.

So your client application may still have a single PbjGrpcClient instance with a single HTTP2 connection to the server.

Then, using this client instance, you can create multiple client stubs (e.g. the GreeterInterface.GreeterClient) with different RequestOptions that contain different metadata. This way you can send requests to the server with different metadata, all using the same single HTTP2 connection to the server.