QGrpcHttp2Channel Class

Description détaillée

La classe QGrpcHttp2Channel implémente l'interface QAbstractGrpcChannel, permettant ainsi gRPC™ la communication via le protocole HTTP/2.

HTTP/2 présente plusieurs avantages par rapport à son prédécesseur, HTTP/1.1, ce qui rend QGrpcHttp2Channel particulièrement adapté aux applications en temps réel et hautement performantes qui nécessitent une communication efficace, sans compromettre la sécurité ni la fiabilité, grâce à l’utilisation de connexions TCP multiplexées.

Le canal peut être personnalisé avec la prise en charge SSL, un protocole « serializationFormat » sur mesure ou d’autres options en le créant à l’aide d’un objet ` QGrpcChannelOptions ` contenant les personnalisations requises.

Schéma de transport

L’implémentation de QGrpcHttp2Channel privilégie différentes méthodes de transport en fonction de l’ hostUri fournie, du fichier scheme et des options. Les critères suivants s’appliquent :

Content-Type

Le type de contenu dans l'gRPC via HTTP/2 détermine le format de sérialisation du message. Il doit commencer par « application/grpc » et peut inclure un suffixe. Le format suit ce schéma :

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

Par exemple :

• application/grpc+proto spécifie l’encodage Protobuf.
• application/grpc+json spécifie l’encodage JSON.

Le format de sérialisation peut être configuré soit en spécifiant l’ content-type dans les métadonnées, soit en définissant directement serializationFormat. Par défaut, le type de contenu application/grpc est utilisé.

Pour configurer QGrpcHttp2Channel avec le format de sérialisation JSON à l’aide des métadonnées « content-type » :

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

Pour un sérialiseur personnalisé et un format de sérialisation « content-type », vous pouvez définir directement le format de sérialisation :

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)
);

Cela utilise DummySerializer pour l'encodage et le décodage des messages avec le suffixe dummy. Pour le transport HTTP/2, cela se traduit par le type de contenu application/grpc+dummy.

Clés de métadonnées réservées

Les métadonnées sont transmises sous forme d’en-têtes HTTP/2 : les clés sont des chaînes ASCII insensibles à la casse, les valeurs peuvent être des chaînes ASCII ou des données binaires. Les clés suivantes sont réservées par HTTP/2 ou le protocole gRPC et sont supprimées des métadonnées utilisateur lors de la construction de la requête :

• Les pseudo-en-têtes HTTP/2 (toute clé commençant par :).
• Toute clé comportant le préfixe grpc- ou qtgrpc-.
• te, content-type, user-agent.

Un content-type fourni par l’utilisateur est toujours pris en compte lors de la construction du canal pour la détection automatique du sérialiseur (voir Content-Type) ; il n’est toutefois pas transmis en tant qu’entrée Custom-Metadata.

Pour plus d’informations sur les en-têtes HTTP/2, voir la RFC 7540, section 8.1.2.

Fenêtres de réception

Le contrôle de flux HTTP/2 limite la quantité de données qu’un expéditeur peut transmettre avant que le destinataire ne les accuse réception. Le canal communique deux de ces limites au serveur, les fenêtres de réception:

• La fenêtre de flux plafonne les données non acquittées d’un seul RPC.
• La fenêtre de connexion limite le volume cumulé des données non acquittées de tous les RPC partageant une même connexion.

Une fenêtre limite les données en transit, et non la taille d’un transfert. Comme les accusés de réception nécessitent un aller-retour sur le réseau, cela limite également le débit :

maximum throughput = window / round-trip time

Les deux fenêtres sont configurées en octets via des variables d’environnement :

• QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE pour la fenêtre de flux ; (valeur par défaut : 4 MiB)
• QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE pour la fenêtre de connexion ; (valeur par défaut : quatre fois la fenêtre de flux, 16 MiB)

Le fait de définir uniquement ` QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE ` fait automatiquement passer la fenêtre de connexion à quatre fois la fenêtre de flux. Définissez explicitement ` QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE ` pour utiliser un rapport différent.

Les valeurs par défaut saturent les réseaux locaux et la plupart des liaisons Internet. Elles s’avèrent insuffisantes sur les liaisons rapides présentant de longs temps aller-retour. Par exemple, une application reçoit des messages volumineux provenant d’un serveur distant :

link: 1 Gbit/s (125 MB/s), 100 ms round-trip time

Le serveur envoie une fenêtre de flux de données, puis attend un aller-retour pour recevoir l’accusé de réception. Avec la fenêtre par défaut, il transmet au maximum 4 Mio toutes les 100 ms :

4 MiB / 0.1 s = 42 MB/s, 34% of the 125 MB/s the link carries

Pour saturer la liaison, la fenêtre doit contenir tout ce que la liaison transmet au cours d’un aller-retour, soit le produit bande passante-délai (BDP) de la liaison :

BDP = 125 MB/s x 0.1 s = 12.5 MB

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=12500000
12.5 MB / 0.1 s = 125 MB/s, the link is saturated

Les RPC simultanés partagent une seule fenêtre de réception de connexion. Tant que chaque flux est lu en continu, le volume total de données en transit reste limité par le BDP. Cependant, si un flux n’est pas lu, ses données mises en mémoire tampon occupent une partie de la fenêtre de connexion partagée et peuvent bloquer d’autres flux. Une bonne règle empirique consiste à dimensionner la fenêtre de connexion en fonction de la somme de toutes les fenêtres de flux actives simultanément. Pour huit transferts parallèles sur la liaison ci-dessus :

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=12500000       (12.5 MB = BDP)
QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE=100000000  (8 x 12.5 MB)

Chaque RPC peut utiliser la totalité des 125 Mo/s lorsqu’il est le seul transfert actif. Avec huit RPC simultanés, ceux-ci se partagent la liaison à raison d’environ 15 Mo/s chacun. Dans le pire des cas, si l’application cesse de lire à partir de tous les flux, le canal peut mettre en mémoire tampon jusqu’à 100 Mo de données.

Une autre solution consiste à dimensionner les fenêtres de flux de manière à ce qu’elles tiennent toutes ensemble dans une fenêtre de connexion égale au BDP. Cela limite le volume maximal de données mises en mémoire tampon, mais restreint chaque RPC à la part qui lui est allouée, même lorsqu’il transfère seul :

QT_GRPC_HTTP2_STREAM_RECEIVE_WINDOW_SIZE=1562500        (12.5 MB / 8)
QT_GRPC_HTTP2_CONNECTION_RECEIVE_WINDOW_SIZE=12500000   (= BDP)

Chaque RPC est limité à environ 15 Mo/s, qu’il transfère seul ou aux côtés de sept autres. L’avantage est que le canal ne met jamais en mémoire tampon plus d’environ 12,5 Mo de données non lues.

Utilisez des fenêtres de flux de taille maximale lorsque la réduction de la latence de transfert est plus importante que l’utilisation de la mémoire. Utilisez des fenêtres de flux plus petites lorsque la limitation de la consommation de mémoire est la priorité. Dans les deux cas, veillez à ce que la fenêtre de connexion soit suffisamment grande pour contenir plusieurs fenêtres de flux ; sinon, un seul flux non lu peut épuiser la fenêtre de connexion partagée et bloquer tous les autres RPC.

Les deux fenêtres acceptent des valeurs allant jusqu’à 2147483647 octets. La fenêtre de flux a une valeur minimale de 1024 octets, ce qui permet aux récepteurs disposant d’une mémoire limitée de restreindre la mise en mémoire tampon par flux ; la fenêtre de connexion a une valeur minimale de 65535 octets, ce qui correspond à la fenêtre initiale du protocole.

Valeurs par défaut des variables d’environnement

Certains paramètres de canal peuvent être configurés via des variables d’environnement. Celles-ci sont évaluées lors de la création de chaque canal. Si une variable d’environnement n’est pas définie, la valeur par défaut intégrée est utilisée.