routing-engine — Sync Contract
Status: populated | Last updated: 2026-04-18
This document defines what other services depend on from routing-engine and what routing-engine depends on from others.
1. Consumers of routing-engine
| Service | Interface | Dependency type | SLA expectation |
|---|---|---|---|
sms-orchestrator | gRPC RoutingService/SelectOperator | Synchronous, blocking hot path | P95 ≤ 50 ms; availability 99.9% |
sms-orchestrator must not proceed with message dispatch without a valid OperatorConfig response. If routing-engine returns UNAVAILABLE or NOT_FOUND, the orchestrator should move the message to the dead-letter queue.
2. Dependencies of routing-engine
| Dependency | Interface | Failure mode if unavailable |
|---|---|---|
PostgreSQL ops_routing schema | Read-only SQL via connection pool | Service cannot resolve cache misses; returns UNAVAILABLE to callers |
| Redis | SET/GET/MGET/SCAN | Cache miss fallback to DB still works; health cache reads return empty (assume all operators healthy with degraded accuracy) |
NATS JetStream operator.health | Consumer | Health cache becomes stale; TTL auto-expires after 60 s; no crash |
3. Schema Stability Guarantees
gRPC Proto
| Field | Stability |
|---|---|
SelectOperatorRequest.to | Stable |
SelectOperatorRequest.account_id | Stable |
SelectOperatorRequest.message_type | Stable — new enum values may be added; callers should handle UNSPECIFIED |
OperatorConfig.* | Stable |
| New fields may be added | Non-breaking (proto3 default values) |
| Fields will not be removed or renumbered | Guaranteed |
NATS Event Contracts
routing-engine consumes OperatorHealthEvent. Any breaking change to that schema must be co-ordinated with operator-management-service. Version field "version": "1.0" allows consumers to gate behaviour by schema version.
4. Versioning Policy
- gRPC package is
ghasi.sms.routing.v1— breaking changes require av2package and a migration window. - The existing
v1proto will be maintained for a minimum of 90 days afterv2is available.