Prise en charge de gRPC

bext sert gRPC de manière native sur le même port HTTP : aucun proxy side-car ni écouteur séparé n'est requis. Les requêtes HTTP/2 avec content-type: application/grpc sont automatiquement acheminées vers le gestionnaire gRPC.

Activation de gRPC#

Ajoutez une section [grpc] à bext.config.toml et enregistrez vos services :

toml

[grpc]
enabled = true

[[grpc.services]]
name = "greeter"
proto = "proto/greeter.proto"
handler = "plugins/greeter-service"

[[grpc.services]]
name = "orders"
proto = "proto/orders.proto"
handler = "plugins/order-service"

Chaque entrée de service nécessite :

Champ	Description
`name`	Nom logique utilisé dans les journaux et les métriques.
`proto`	Chemin d'accès au fichier `.proto` définissant le service.
`handler`	Plugin ou module qui implémente les méthodes de service.

bext analyse le .proto au démarrage et génère la table de routage. Si un client appelle une méthode non déclarée dans le proto, il reçoit UNIMPLEMENTED immédiatement.

Transcodage grpc-web#

Les clients du navigateur ne peuvent pas utiliser gRPC natif (pas de bandes-annonces HTTP/2 dans la récupération du navigateur). bext détecte Content-Type: application/grpc-web ou application/grpc-web+proto et transcode automatiquement :

Cadrage codé en base64 pour grpc-web-text
Cadrage binaire pour grpc-web+proto
En-têtes CORS injectés à partir de la configuration [cors] du site

Aucun proxy Envoy ou grpc-web distinct n’est nécessaire.

Compatibilité des plugins#

Les plugins qui gèrent les requêtes gRPC déclarent la prise en charge du protocole dans leur manifeste :

toml

# plugin.toml
[plugin]
name = "greeter-service"
protocols = ["http", "grpc"]

Un plugin qui déclare uniquement protocols = ["http"] ne recevra jamais d'appels gRPC. Cela évite le routage accidentel et rend la prise en charge du protocole explicite.

Dans un gestionnaire gRPC, le plugin reçoit un GrpcRequest avec le message décodé et les métadonnées :

rust

fn greet(req: GrpcRequest<HelloRequest>) -> GrpcResult<HelloReply> {
    Ok(HelloReply {
        message: format!("Hello, {}!", req.message.name),
    })
}

Authentification#

L'authentification fonctionne via les métadonnées gRPC. Les clients définissent la clé de métadonnées authorization avec un jeton Bearer, et le middleware Auth de bext la valide exactement comme il le ferait pour un en-tête HTTP Authorization :

code

authorization: Bearer eyJhbGciOi...

Les mêmes fournisseurs d'authentification (JWT, clé API, OAuth) s'appliquent aux appels gRPC. Les demandes refusées reçoivent les codes d’état UNAUTHENTICATED ou PERMISSION_DENIED.

Intégration du cache#

Les appels gRPC unaires (requête-réponse) peuvent être mis en cache. bext hache le nom du service, le nom de la méthode et le message de demande sérialisé pour produire une clé de cache. Activer par méthode :

toml

[[grpc.services]]
name = "catalog"
proto = "proto/catalog.proto"
handler = "plugins/catalog-service"

[grpc.services.cache]
methods = ["GetProduct", "ListCategories"]
ttl_secs = 60

Les appels en streaming ne sont jamais mis en cache.

Streaming#

bext prend en charge les quatre types d'appels gRPC :

Taper	Description
Unaire	Une seule demande, une seule réponse.
Diffusion sur serveur	Requête unique, flux de réponses.
Diffusion client	Flux de demandes, réponse unique.
Bidi streaming	Flux duplex intégral dans les deux sens.

Les appels en streaming respectent le paramètre max_concurrent_streams du site issu de la configuration [http2]. Les flux inactifs sont récoltés après stream_idle_secs (300 par défaut).

Réflexion#

Lorsque reflection = true est défini dans la section [grpc], bext expose le service gRPC Server Reflection afin que des outils tels que grpcurl et Postman puissent introspecter les services disponibles sans fichier .proto local :

toml

[grpc]
enabled = true
reflection = true

Vérification de la santé#

bext implémente le protocole standard de vérification de l'état gRPC ( grpc.health.v1.Health ). Chaque service enregistré est signalé comme SERVING une fois son gestionnaire chargé. Utilisez ceci pour les sondes d'équilibrage de charge :

bash

grpcurl -plaintext localhost:443 grpc.health.v1.Health/Check

Indicateur de fonctionnalité#

La prise en charge de gRPC nécessite l'indicateur de fonctionnalité grpc au moment de la compilation :

bash

bext build --features grpc

Sans cet indicateur, la section de configuration [grpc] est ignorée et aucun routage gRPC n'est compilé.

Conseil

Les appels en streaming (serveur, client et bidi) ne sont jamais mis en cache : seules les méthodes unaires (demande/réponse) sont éligibles. Définissez explicitement methods dans [grpc.services.cache] pour éviter de mettre accidentellement en cache les appels non idempotents.

Conseil

Les clients de navigateur ne peuvent pas utiliser gRPC natif. Si vos consommateurs incluent des interfaces Web, activez le transcodage grpc-web (intégré) et vérifiez que Content-Type: application/grpc-web+proto atteint bext sans modification — Les réécritures CDN ou proxy de cet en-tête interrompront le transcodage en silence.

En rapport#

WebSockets — alternative au navigateur en temps réel lorsque grpc-web ne convient pas
Capacité d'authentification — Validation des clés JWT et API appliquée aux métadonnées gRPC
Aperçu des plugins — comment les plugins du gestionnaire gRPC sont empaquetés et chargés
Référence de configuration — liste complète des champs bext.config.toml
Guide de mise en cache — TTL et mécanismes de clé de cache utilisés par la mise en cache de méthode unaire

Links#

grpc.io — site officiel du projet gRPC, spécification du protocole et guides linguistiques