À propos du projet

grpc-web est une implémentation JavaScript de gRPC pour les clients navigateurs, maintenue dans le dépôt grpc/grpc-web. Comme les navigateurs ne peuvent pas ouvrir de connexions gRPC HTTP/2 brutes, les clients gRPC-web communiquent avec les services gRPC via un proxy spécial ; Envoy est le proxy par défaut, et le projet documente également l'interopérabilité avec le proxy Go gRPC-web, Apache APISIX et le module gRPC de Nginx. Le projet fournit deux éléments principaux. Premièrement, une bibliothèque d'exécution publiée sur npm sous le nom `grpc-web`, désormais entièrement écrite en TypeScript, offrant ainsi une sécurité de type de première classe, zéro dépendance d'exécution et des définitions de types intégrées. Deuxièmement, un plugin protoc, `protoc-gen-grpc-web`, qui génère des stubs de service client à partir de définitions `.proto`. La génération associe généralement le plugin standard `--js_out` (pour les classes de messages protobuf) avec `--grpc-web_out` (pour le stub de service), et peut être regroupée avec Browserify, Webpack ou Closure Compiler. Les modes RPC pris en charge sont les appels unaires et le streaming côté serveur. Le streaming côté serveur n'est disponible qu'en mode de format fil `grpcwebtext`, où les charges utiles sont encodées en base64 et envoyées avec `Content-Type: application/grpc-web-text`. Un mode binaire, `grpcweb`, utilise `Content-Type: application/grpc-web+proto` avec des charges utiles protobuf binaires mais ne prend en charge que les appels unaires. Le streaming bidirectionnel et côté client n'est actuellement pas pris en charge. La génération de code propose plusieurs styles d'importation : `closure` (par défaut, utilisant `goog.require()`), `commonjs` (utilisant `require()`), `commonjs+dts` (stubs CommonJS plus un fichier de typage `.d.ts`), et `typescript` (sortie TypeScript complète). Les styles `commonjs+dts` et `typescript` ne sont pris en charge que par `--grpc-web_out`, pas par `--js_out`. Le README inclut un exemple concret de génération de code TypeScript avec le format fil binaire, produisant un client de service TypeScript, un module protobuf JavaScript et un fichier de définition `.d.ts` correspondant. L'utilisation du client est simple : instanciez un client de service avec une URL de proxy, construisez un message de requête et appelez le RPC avec des métadonnées facultatives et un rappel. Le streaming côté serveur renvoie un objet de flux avec des événements `data`, `status` et `end`, plus une méthode `cancel()`. Un délai peut être défini en passant un en-tête `deadline` contenant un horodatage Unix en millisecondes. Deux styles de client sont disponibles : les clients basés sur des rappels et les clients basés sur des promesses, bien que la variante Promise ne puisse pas accéder aux rappels `.on(...)` pour les métadonnées et le statut. Des intercepteurs personnalisés peuvent être implémentés et enchaînés pour des fonctionnalités telles que l'authentification et les nouvelles tentatives. Deux types d'intercepteurs existent : `UnaryInterceptor`, qui intercepte les RPC unaires et ne peut être utilisé qu'avec les clients Promise, et `StreamInterceptor`, plus polyvalent et fonctionnant avec les clients réguliers. Le dépôt inclut un exemple Hello World qui guide à travers la définition d'un service avec des tampons de protocole, l'implémentation d'un service gRPC Node.js, la configuration du proxy Envoy, la génération de classes protobuf et de stubs client, et la compilation des dépendances JS en une bibliothèque statique. Une démo Echo plus avancée peut être exécutée avec Docker Compose et expose une page navigateur pour tester le streaming. Le README mentionne également les intégrations écosystémiques, y compris les frameworks serveur Armeria (JVM) et Tonic (Rust) avec prise en charge gRPC-web, et une démo de compatibilité Vite. Un document de feuille de route décrit les travaux futurs, y compris la prise en charge de frameworks web spécifiques aux langages pour Python, Java et Node.