Protocols

A summary of every wire protocol used by Cognitora and which binary speaks it.

Public surface

HTTP (OpenAI)

The only externally exposed protocol. cgn-router listens on [router].listen_http. JSON over HTTP/1.1 + text/event-stream for streaming responses. See OpenAI HTTP surface.

Internal control plane

gRPC over mTLS

Every cross-process RPC inside Cognitora uses gRPC over TCP with mutual TLS. The .proto files at proto/cognitora/v1/ are the source of truth; see gRPC surface.

mTLS material is loaded by cgn-tls::server_tls / cgn-tls::client_tls from the paths in [security]. Trust root defaults to a single cluster CA generated by cgn-ctl pki bootstrap for dev, or whatever your external CA issues.

gRPC over Unix Domain Socket

cgn-agent ↔ colocated cgn-kvcached use a UDS at /run/cognitora/kv.sock. No TLS — filesystem permissions (0660, owned by cognitora:cognitora) guard the channel. This is the only deliberate exception to "mTLS everywhere".

The choice is intentional: the agent and kvcached are always on the same host (Helm uses a DaemonSet for the agent and an emptyDir for the socket); skipping TLS saves ~5 µs per call without weakening the threat model.

Cluster state

etcd v3

Every binary that needs cluster state speaks etcd's gRPC API directly via etcd-client. Two key prefixes:

• /cognitora/nodes/<node_id> — NodeHealth JSON written by every agent every [agent].heartbeat. Stale entries (TTL 3×heartbeat) are filtered on read.
• /cognitora/routing/policy — RoutingPolicy JSON written by the operator (or cgn-ctl cluster set-policy). Watched by every router; updates land in < 1 s.

etcd talks TLS by default; the credentials come from [cluster].etcd (comma-separated endpoints) and [cluster].etcd_ca_file / etcd_cert_file / etcd_key_file.

Data plane (KV transport)

QUIC

cgn-kvcached exposes a QUIC listener (quinn) on [kv].listen_quic. Used for cross-host KV block fetches. mTLS- rooted at the same cluster CA. 0-RTT enabled for repeat peers.

Wire format: a Frame header (bincode) + a raw block payload. The codec lives in cgn-kv::transport::quic.

RDMA (optional, Linux only)

Same Frame codec, different bottom half. Built when the binary is compiled with --features rdma (which links ibverbs). The chosen transport per-peer is decided at runtime: if both peers report has_rdma_nic = true and a SR-IOV virtual function is available, we use RDMA; otherwise we fall back to QUIC.

Telemetry plane

Prometheus over HTTP

Every binary serves /metrics on its admin port (:9091 for router/agent/kvcached, :9092 for metrics). No TLS — admin ports bind 127.0.0.1 by default; the Helm chart never exposes them as Services.

OTLP/gRPC (optional)

When OTEL_EXPORTER_OTLP_ENDPOINT is set, every binary exports spans to that collector. The default sampler is parent-based ratio at 1%. Cognitora doesn't ship its own collector — Tempo / Jaeger / Honeycomb / Datadog all work.

Summary table

* The OpenAI HTTP API is intentionally unencrypted at the application boundary; production deployments terminate TLS at an ingress (the Helm chart wires IngressController annotations for both Nginx and Traefik).