routing-engine — API Contracts

Status: populated | Last updated: 2026-04-18

1. gRPC Service Definition

syntax = "proto3";

package ghasi.sms.routing.v1;

option go_package = "github.com/ghasitech/sms-gateway/routing-engine/gen/routing/v1";

// RoutingService — select the best operator for a given SMS send request.
service RoutingService {
  // SelectOperator resolves the optimal SMPP operator for a given destination,
  // account, and message type. Called by sms-orchestrator on every outbound message.
  rpc SelectOperator (SelectOperatorRequest) returns (OperatorConfig);
}

message SelectOperatorRequest {
  // E.164 destination number, e.g. "+447911123456"
  string to             = 1;
  // UUID of the account sending the message
  string account_id     = 2;
  // Type of message being sent
  MessageType message_type = 3;
}

message OperatorConfig {
  // Internal UUID of the selected operator
  string operator_id  = 1;
  // SMPP server hostname or IP
  string host         = 2;
  // SMPP server port
  int32  port         = 3;
  // SMPP system_id bind credential
  string system_id    = 4;
  // Max transactions per second allowed on this operator connection
  int32  tps_limit    = 5;
  // Routing strategy that was applied
  RoutingStrategy strategy = 6;
}

enum MessageType {
  MESSAGE_TYPE_UNSPECIFIED = 0;
  MESSAGE_TYPE_SMS         = 1;
  MESSAGE_TYPE_FLASH       = 2;
  MESSAGE_TYPE_WAP         = 3;
}

enum RoutingStrategy {
  ROUTING_STRATEGY_UNSPECIFIED = 0;
  ROUTING_STRATEGY_COST        = 1;
  ROUTING_STRATEGY_PRIORITY    = 2;
  ROUTING_STRATEGY_FAILOVER    = 3;
}

1.1 gRPC Error Codes

gRPC Status	Meaning
OK (0)	Operator resolved successfully
INVALID_ARGUMENT (3)	to is not E.164, or account_id is missing
NOT_FOUND (5)	No routing rule or prefix match for destination
UNAVAILABLE (14)	All candidate operators are unhealthy
INTERNAL (13)	Unexpected service-side error

1.2 Transport

• Protocol: gRPC over HTTP/2
• TLS: mTLS (mutual TLS) — client cert required; issued by cluster-internal CA
• Port: 50051 (in-cluster only; not exposed via Kong)
• Interceptors: logging, metrics (Prometheus counter/histogram per method), deadline propagation

---

2. HTTP Management Endpoints

These endpoints are served on port 3001 (not fronted by Kong).

Method	Path	Description
GET	/health	Liveness probe — always 200 if process is alive
GET	/ready	Readiness probe — checks Redis + PostgreSQL connectivity
GET	/metrics	Prometheus metrics scrape endpoint

GET /ready — Response Schemas

200 OK:

{
  "status": "ready",
  "checks": {
    "redis": "ok",
    "postgres": "ok"
  }
}

503 Service Unavailable:

{
  "status": "not_ready",
  "checks": {
    "redis": "ok",
    "postgres": "error: connection refused"
  }
}

---

3. NATS Subscription (Inbound Only)

Subject	Stream	Consumer group	Direction
operator.health	OPERATOR_EVENTS	routing-engine-health	CONSUME only

Payload schema: see EVENT_SCHEMAS → OperatorHealthEvent.

The service does not publish any NATS subjects.