gRPC Client

IntelligenceClient Structure

grpc/client.rs wraps three generated tonic clients into a single struct:

pub struct IntelligenceClient {
    chat_client: ChatClient<Channel>,
    resource_client: ResourceServiceClient<Channel>,
    health_client: HealthClient<Channel>,
}

The client is instantiated once at startup, stored in AppState, and cloned per request (tonic clients are Clone + Send + Sync).

Startup Connection Strategy

This means auth, user, and admin endpoints remain fully operational even when the Intelligence service is down. Chat endpoints will fail at the RPC call with UNAVAILABLE → mapped to HTTP 503.

RPC Timeouts

All RPC calls use per-operation timeout guards:

pub struct RpcTimeouts {
    pub chat: Duration,      // 1200s = 20 minutes
    pub stream: Duration,    // 300s  = 5 minutes
    pub resource: Duration,  // 3000s = 50 minutes
    pub health: Duration,    // 5s
}

The chat timeout accommodates long multi-turn context windows with large LLM responses. The resource timeout accommodates large document ingestion with web scraping.

Retry Configuration

pub struct RetryConfig {
    pub max_retries: u32,          // 3
    pub initial_backoff: Duration, // 100ms
    pub max_backoff: Duration,     // 10s
    pub multiplier: f64,           // 2.0 (exponential)
}

Retryable gRPC status codes:

• Unavailable — service temporarily down
• DeadlineExceeded — transient timeout (retried with fresh timeout)
• ResourceExhausted — rate limit, retried after backoff
• Aborted — optimistic concurrency failure

Non-retryable codes: NotFound, PermissionDenied, InvalidArgument, Unauthenticated, Internal (bug, not transient).

gRPC Channel Configuration

Method Reference

Streaming retries: stream_chat is not retried because the SSE response has already started streaming to the client. A mid-stream retry would result in duplicate tokens. The client must reconnect.