QGrpcHttp2Channel Class

Detailed Description

The QGrpcHttp2Channel class implements QAbstractGrpcChannel, enabling gRPC™ communication carried over HTTP/2 framing.

HTTP/2 introduces several advantages over its predecessor, HTTP/1.1, making QGrpcHttp2Channel well-suited for high-performance, real-time applications that require efficient communication, without sacrificing security or reliability, by using multiplexed TCP connections.

The channel can be customized with SSL support, a custom serializationFormat, or other options by constructing it with a QGrpcChannelOptions containing the required customizations.

Transportation scheme

The QGrpcHttp2Channel implementation prefers different transportation methods based on the provided hostUri, scheme and options. The following criteria applies:

Content-Type

The content-type in gRPC over HTTP/2 determines the message serialization format. It must start with application/grpc and can include a suffix. The format follows this scheme:

"content-type": "application/grpc" [("+proto" / "+json" / {custom})]

For example:

• application/grpc+proto specifies Protobuf encoding.
• application/grpc+json specifies JSON encoding.

The serialization format can be configured either by specifying the content-type inside the metadata or by setting the serializationFormat directly. By default, the application/grpc content-type is used.

To configure QGrpcHttp2Channel with the JSON serialization format using content-type metadata:

auto jsonChannel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50051"_L1),
    QGrpcChannelOptions().setMetadata({
        { "content-type"_ba, "application/grpc+json"_ba },
    })
);

For a custom serializer and content-type, you can directly set the serialization format:

class DummySerializer : public QAbstractProtobufSerializer
{
    ...
};
QGrpcSerializationFormat dummyFormat("dummy", std::make_shared<DummySerializer>());

auto dummyChannel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50051"_L1),
    QGrpcChannelOptions().setSerializationFormat(dummyFormat)
);

This uses DummySerializer for encoding and decoding messages with the dummy suffix. For HTTP/2 transportation this results in the application/grpc+dummy content-type.

Reserved metadata keys

Metadata is transmitted as HTTP/2 headers: keys are case-insensitive ASCII strings, values may be ASCII strings or binary data. The following keys are reserved by HTTP/2 or the gRPC protocol and are dropped from user metadata when the request is built:

• HTTP/2 pseudo-headers (any key starting with :).
• Any key with the grpc- or qtgrpc- prefix.
• te, content-type, user-agent.

A user-provided content-type is still consulted at channel construction for serializer auto-detection (see Content-Type); it is not, however, forwarded as a Custom-Metadata entry.

For more information on HTTP/2 headers, see RFC 7540, Section 8.1.2.