Un amont gRPC

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : guide produit ; l'appeler : guide développeur.

Objectif : servir un service gRPC à des clients gRPC, à un navigateur (gRPC-Web) et en REST/JSON, depuis son seul .proto.

Commande - l'équipe de l'amont annote son .proto : la correspondance REST standard (google.api.http) et ce dont Flexway a besoin en plus (flexway.v1.operation, le pendant des x-flexway-*). Puis elle construit le jeu de descripteurs :

syntax = "proto3";
package shop.v1;                          // le nom gRPC est shop.v1.Orders/GetOrder

import "flexway/v1/options.proto";       // à copier depuis le tag que vous exécutez : services/gateway/api/flexway/v1/options.proto
import "google/api/annotations.proto";   // depuis buf.build/googleapis/googleapis, ci-dessous

service Orders {
  rpc GetOrder(GetOrderRequest) returns (Order) {
    option (google.api.http) = { get: "/v1/shop/orders/{id}" };
    option (flexway.v1.operation) = { upstream: "orders" security: [ { scopes: ["orders:read"] } ] };
  }
}

v=<version>   # le Flexway que vous exécutez
mkdir -p flexway/v1 && curl -fsSLo flexway/v1/options.proto \
  "https://raw.githubusercontent.com/flexwiz/flexway/v$v/services/gateway/api/flexway/v1/options.proto"
cat > buf.yaml <<'YAML'
version: v2
deps: [buf.build/googleapis/googleapis]
YAML
buf dep update
buf build -o orders.binpb       # ou : protoc --include_imports --descriptor_set_out=orders.binpb ...

contracts:
  protobuf: [./orders.binpb]
upstreams:
  orders: { url: http://orders.internal:9000, protocol: grpc }   # h2c dans un maillage

Vérif :

grpcurl -plaintext -protoset orders.binpb -H "authorization: Bearer $TOKEN" \
  -d '{"id":"42"}' localhost:8080 shop.v1.Orders/GetOrder               # gRPC, sur le port de trafic
curl -H "authorization: Bearer $TOKEN" localhost:8080/v1/shop/orders/42  # la même opération en REST

Les deux appels sont une seule opération, shop.v1.Orders/GetOrder : même identité, même débit, même quota, même ligne d'audit. Un refus arrive en google.rpc.Status au client gRPC (le code du problème dans ErrorInfo.reason), en RFC 9457 au client REST. Une erreur de l'amont arrive au client REST en problème upstream_status, son statut gRPC dans l'extension grpc. Un flux serveur est un text/event-stream en REST.

Pour un navigateur (gRPC-Web), la politique cors expose grpc-status, grpc-message et grpc-status-details-bin (expose_headers) et accepte x-grpc-web, x-user-agent et grpc-timeout (allow_headers) : sans eux, le navigateur ne lit pas un refus. Refusés au chargement à cette version : variable sur plusieurs segments ({name=shelves/*}), joker, verbe (:cancel), google.api.http sur un flux client ou bidirectionnel - ceux-là restent servis en gRPC seulement.