Context
BSFG requires a narrow, typed boundary API for AppendFact, FetchFacts, ConfirmReceipt, and PutObject. The API must remain maintainable as an appliance surface, support protobuf contracts, work well with ordinary HTTP infrastructure, and avoid unnecessary transport ceremony.
The design target is not a general-purpose service mesh. It is a small, explicit boundary protocol layered over zone-local durable logs.
Options Considered
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| gRPC | Use protobuf contracts over the gRPC protocol. | strong ecosystem gravity good code generation well-known RPC model |
more operational ceremony less curl-friendly HTTP/2 dependency is more central |
| Connect RPC (Selected) | Use protobuf contracts over the Connect protocol. | typed protobuf API works over ordinary HTTP infrastructure curl-friendly unary surface lower appliance friction |
smaller ecosystem than gRPC streaming remains available but is not the core model |
| Plain JSON/HTTP | Use ad hoc JSON endpoints without protobuf RPC contracts. | simple to inspect manually minimal client requirements |
weak contract discipline harder long-term evolution more semantic drift |
| Custom TCP protocol | Define a bespoke wire protocol for BSFG operations. | maximal wire control narrowest possible transport surface |
highest maintenance burden custom framing, tooling, and observability required poor fit for maintainable appliance goal |
Decision
BSFG will expose its boundary API using Connect RPC.
The protobuf service surface remains the canonical contract:
AppendFact
FetchFacts
ConfirmReceipt
PutObject
FetchFacts uses unary paged pull rather than long-lived streaming. Connect RPC therefore serves as a typed, maintainable control plane over the underlying JetStream-based fact log.
Consequences
Benefits:
- typed protocol without committing to heavier RPC ceremony
- easy debugging and simpler appliance operations
- clear separation between boundary API and internal log substrate
- future compatibility with protobuf-centered tooling remains strong
Tradeoffs:
- the chosen protocol has less ecosystem gravity than gRPC
- some infrastructure defaults and examples will need to be adapted rather than copied directly