Integration Hub gRPC Service Reference

service IntegrationHubService {
  // Provider Registry
  rpc RegisterProvider(RegisterProviderRequest)               returns (RegisterProviderResponse);
  rpc RetrieveProvider(RetrieveProviderRequest)               returns (RetrieveProviderResponse);
  rpc ListProviders(ListProvidersRequest)                     returns (ListProvidersResponse);
  rpc UpdateProvider(UpdateProviderRequest)                   returns (UpdateProviderResponse);
  rpc DeleteProvider(DeleteProviderRequest)                   returns (DeleteProviderResponse);
  rpc RetrieveProviderHealth(RetrieveProviderHealthRequest)   returns (RetrieveProviderHealthResponse);

  // Outbound Calls
  rpc CallProvider(CallProviderRequest)                       returns (CallProviderResponse);

  // Dead Letter Queue
  rpc ListDLQ(ListDLQRequest)                                 returns (ListDLQResponse);
  rpc RetryDLQEntry(RetryDLQEntryRequest)                     returns (RetryDLQEntryResponse);
  rpc RetryAllDLQ(RetryAllDLQRequest)                         returns (RetryAllDLQResponse);
  rpc DeleteDLQEntry(DeleteDLQEntryRequest)                   returns (DeleteDLQEntryResponse);
}

enum ProviderType {
  PROVIDER_TYPE_UNSPECIFIED = 0;
  PROVIDER_TYPE_PAYMENT     = 1;
  PROVIDER_TYPE_SMS         = 2;
  PROVIDER_TYPE_EMAIL       = 3;
  PROVIDER_TYPE_ANALYTICS   = 4;
  PROVIDER_TYPE_ADVERTISING = 5;
  PROVIDER_TYPE_CUSTOM      = 6;
}

enum AuthType {
  AUTH_TYPE_UNSPECIFIED = 0;
  AUTH_TYPE_API_KEY     = 1;
  AUTH_TYPE_OAUTH2      = 2;
  AUTH_TYPE_BASIC       = 3;
  AUTH_TYPE_BEARER      = 4;
  AUTH_TYPE_HMAC        = 5;
}

enum ProviderStatus {
  PROVIDER_STATUS_UNSPECIFIED = 0;
  PROVIDER_STATUS_ACTIVE      = 1;
  PROVIDER_STATUS_DEGRADED    = 2; // Slow or partial failures
  PROVIDER_STATUS_DOWN        = 3; // Consistently failing
  PROVIDER_STATUS_DISABLED    = 4; // Administratively disabled
}

enum CircuitBreakerState {
  CIRCUIT_BREAKER_STATE_UNSPECIFIED = 0;
  CIRCUIT_BREAKER_STATE_CLOSED      = 1; // Normal: requests pass through
  CIRCUIT_BREAKER_STATE_HALF_OPEN   = 2; // Probe: 1 test request allowed
  CIRCUIT_BREAKER_STATE_OPEN        = 3; // Tripped: requests fail fast (503)
}

CLOSED ──5 consecutive failures in 30s──► OPEN
                                            │
                                       wait 60s
                                            │
                                        HALF_OPEN
                                            │
                              ┌─── 1 probe request ───┐
                              │                       │
                           success               failure
                              │                       │
                           CLOSED                   OPEN

message Provider {
  string              id                    = 1;
  string              tenant_id             = 2;
  string              name                  = 3;
  ProviderType        type                  = 4;
  string              base_url              = 5;
  AuthType            auth_type             = 6;
  ProviderStatus      status                = 7;
  CircuitBreakerState circuit_breaker_state = 8;
  map<string, string> config                = 9;  // timeout_sec, retry_count, etc.
  string              created_at            = 10; // ISO 8601 UTC
  string              updated_at            = 11; // ISO 8601 UTC
  // NOTE: credentials are NEVER returned in responses.
}

message ProviderHealth {
  string              provider_id          = 1;
  ProviderStatus      status               = 2;
  CircuitBreakerState circuit_breaker_state = 3;
  int64               last_success_at_ms   = 4; // Unix milliseconds; 0 if never
  int64               last_failure_at_ms   = 5; // Unix milliseconds; 0 if never
  int32               consecutive_failures = 6;
}

message DLQEntry {
  string              id            = 1;
  string              provider_id   = 2;
  string              tenant_id     = 3;
  string              method        = 4; // HTTP method of original request
  string              url           = 5; // Full URL of original request
  map<string, string> headers       = 6;
  bytes               body          = 7;
  string              error         = 8; // Last error message
  int32               attempts      = 9;
  string              last_retry_at = 10; // ISO 8601 UTC; empty if never retried
  string              created_at    = 11; // ISO 8601 UTC
}

message CallResponse {
  int32               status_code = 1; // HTTP status code from external provider
  map<string, string> headers     = 2;
  bytes               body        = 3;
  int64               latency_ms  = 4;
}

message RegisterProviderRequest {
  string              tenant_id   = 1; // Required.
  string              name        = 2; // Required. Human-readable name (e.g. "Stripe Production").
  ProviderType        type        = 3; // Required.
  string              base_url    = 4; // Required. e.g. "https://api.stripe.com".
  AuthType            auth_type   = 5; // Required.
  bytes               credentials = 6; // Required. Raw JSON credentials — encrypted at rest.
  map<string, string> config      = 7; // Optional. e.g. {"timeout_sec": "10", "retry_count": "3"}.
}

message RegisterProviderResponse {
  Provider provider = 1; // Credentials field absent — never returned.
}

message RetrieveProviderRequest {
  string id        = 1; // Required. Provider UUID.
  string tenant_id = 2; // Required. Authorization scope validation.
}

message RetrieveProviderResponse {
  Provider provider = 1;
}

message ListProvidersRequest {
  string         tenant_id  = 1; // Required.
  ProviderType   type       = 2; // 0 = all types.
  ProviderStatus status     = 3; // 0 = all statuses.
  int32          page_size  = 4;
  string         page_token = 5;
}

message ListProvidersResponse {
  repeated Provider data            = 1;
  string            next_page_token = 2;
}

message UpdateProviderRequest {
  string          id          = 1; // Required. Provider UUID.
  string          tenant_id   = 2; // Required.
  optional string name        = 3;
  optional string base_url    = 4;
  bytes           credentials = 5; // Empty = no credential change.
  map<string, string> config  = 6; // Empty map = no config change.
  optional ProviderStatus status = 7;
}

message UpdateProviderResponse {
  Provider provider = 1;
}

message DeleteProviderRequest {
  string id        = 1; // Required.
  string tenant_id = 2; // Required.
}

message DeleteProviderResponse {}

message RetrieveProviderHealthRequest {
  string id        = 1; // Required.
  string tenant_id = 2; // Required.
}

message RetrieveProviderHealthResponse {
  ProviderHealth health = 1;
}

message CallProviderRequest {
  string              provider_id     = 1; // Required. Provider UUID.
  string              tenant_id       = 2; // Required.
  string              method          = 3; // Required. "GET"|"POST"|"PATCH"|"DELETE".
  string              path            = 4; // Required. Appended to provider.base_url.
  map<string, string> headers         = 5; // Additional headers. Auth is auto-injected.
  bytes               body            = 6; // Request body bytes.
  string              idempotency_key = 7; // UUID v7. Required for non-idempotent methods.
}

CallProvider RPC
      │
      ▼
Rate limit check (INTEGRATION_RATE_LIMIT_PER_SEC=100)
      │
      ▼
Circuit Breaker state?
  ├─ OPEN  → return UNAVAILABLE immediately (fail-fast, no network call)
  └─ CLOSED / HALF_OPEN → proceed
      │
      ▼
Inject credentials from encrypted store
      │
      ▼
HTTP request to external provider
      │
      ├─ Success (2xx) → return CallProviderResponse
      └─ Failure → retry (up to config.retry_count, exponential backoff)
                        │
                        └─ After max retries → write DLQEntry → return UNAVAILABLE

message CallProviderResponse {
  CallResponse response = 1; // Contains status_code, headers, body, latency_ms
}

message ListDLQRequest {
  string tenant_id   = 1; // Required.
  string provider_id = 2; // Optional: filter by provider.
  int32  page_size   = 3;
  string page_token  = 4;
}

message ListDLQResponse {
  repeated DLQEntry data            = 1;
  string            next_page_token = 2;
}

message RetryDLQEntryRequest {
  string id        = 1; // Required. DLQEntry UUID.
  string tenant_id = 2; // Required.
}

message RetryDLQEntryResponse {
  DLQEntry entry   = 1; // Updated entry with incremented attempts count.
  bool     success = 2; // true if retry succeeded; false if still failing.
}

message RetryAllDLQRequest {
  string tenant_id   = 1; // Required.
  string provider_id = 2; // Optional: retry only entries for this provider.
}

message RetryAllDLQResponse {
  int32 total     = 1; // Total DLQ entries processed.
  int32 succeeded = 2; // Entries successfully replayed.
  int32 failed    = 3; // Entries still failing after retry.
}

message DeleteDLQEntryRequest {
  string id        = 1; // Required. DLQEntry UUID.
  string tenant_id = 2; // Required.
}

message DeleteDLQEntryResponse {}