About gRPC¶
A gRPC realization of the wes-contract is published alongside the REST realization. It is additive — the same message shapes, the same idempotency rules, the same reconciliation model. gRPC is an FG.AI-to-FG.AI accelerator, not a separate contract.
Third-party integrators do not need gRPC. The REST contract documented elsewhere on this site is the universal baseline; gRPC is an optional optimization both parties can choose if both support it.
See WMS ADR-0023 for the decision.
When to consider gRPC¶
Situation |
REST vs gRPC |
|---|---|
Third-party planner or executor |
REST. Universally implementable; no codegen toolchain assumption. |
gRPC. HTTP/2 multiplexing + protobuf serialization noticeably reduces per-event overhead at peak warehouse load. |
|
gRPC. Streaming RPCs fit the pattern. |
|
Mixed third-party + FG.AI on the same warehouse |
REST. Mixed-mode is not supported per warehouse. |
Major-version lockstep¶
REST (v1.2) and gRPC (v1.3) track major versions in lockstep. Within a major they may drift on minor releases — gRPC sometimes adopts new optional fields ahead of REST when the wire change is cheap on protobuf and expensive on JSON.
A breaking change ships as /wes/v2/ on REST and a v2 package on gRPC, simultaneously. There is never a major-version skew between the two realizations.
Protobuf source¶
Protobuf definitions live in SiriusVoyager/wes-contract/proto/fgai/wms_wes/v1/. Generated Java, Python, and TypeScript stubs are published under gen/{java,python,ts}/ in the same repo.
Pin to the contract version (e.g. wes-contract:1.3.0) the same way as REST consumers — through the appropriate language package manager.
Wire-format compatibility¶
Wire-format compatibility with protobuf-java is pinned per the FG.AI schemas repo (see ~/Projects/fgai/CLAUDE.md — Pitfall 6). Java consumers must use the protobuf version declared by wes-contract/gen/java/pom.xml’s <protobuf.version>. Python consumers pin protobuf==<exact>. Drift here produces silent wire-format incompatibilities that no test will catch until production.
Semantic equivalence¶
A gRPC adopter must produce semantically identical state changes to a REST adopter against the same planner or executor. The reconciler does not distinguish — a window with movements posted half via gRPC and half via REST reconciles the same as a homogeneous window.
This is the property that lets FG.AI-to-FG.AI deployments migrate from REST to gRPC without breaking any third-party integrator who sees the same events through their own REST channel.