Skip to main content

Crate cpa_server

Crate cpa_server 

Source
Expand description

HTTP surface: routes and client-key auth over an axum-independent runtime.

Re-exports§

pub use runtime::Runtime;

Modules§

body_limit
server.max-request-body-bytes, Go v8.0.35 maxRequestBodyBytesMiddleware (dd7b4334). Off by default. When set, a declared Content-Length over the limit is refused before anything is read, and every other body ends in [TooLarge] as soon as it passes the limit, so whoever reads it (request capture, client auth plugins, handlers) answers Go’s 413 for its route.
capabilities
Per-attempt model capability binding (Go sdk/cliproxy/auth/api_key_model_capabilities.go).
cooldown_store
routing.cooldown.save-cooldown-status: cooldowns persisted as one .cds file per credential under auth-dir (Go sdk/cliproxy/auth/cooldown_state.go). The files use Go’s layout and field names, so state survives a switch between CLIProxyAPI and cliproxy-rs in either direction.
dispatch
The provider-neutral attempt loop every inference route runs (Go BaseAPIHandler.Execute*WithAuthManager plus Manager.Execute*).
home_session
Home picks kept by pooled upstream sockets (Go HomeDispatchSelection as an ExecutionLifecycle, retainHomeWebsocketSelection and retainedHomeSessionSelection).
keepalive
Go’s optional GET /keep-alive (sdk/api WithKeepAliveEndpoint, internal/api/server_keepalive.go). Embedders mount it; the Go binary never does, so the binary here does not either. Each request is a heartbeat; when none arrives for timeout, the callback runs once. Dropping the router stops the watcher, as Go’s Server.Stop does.
lcp
Go’s Merkle longest-common-prefix session matcher (sdk/cliproxy/session/lcp.go).
listener
The API listener (Go internal/api/server.go Start): plain HTTP, or HTTPS when server.tls.enable is set, with server.tls.cert and server.tls.key loaded once at startup.
logging
The process log (Go internal/logging/global_logger.go, log_dir_cleaner.go and util.SetLogLevel): Go’s line format, stdout or a rotating main.log, the log-directory size cleaner and the debug level switch. The binary’s --log-file replaces only stdout: logging-to-file still writes main.log and the cleaner still runs.
management
Management API (v8, plus the few legacy v0 reads the dashboard predates).
model_updater
Model catalog updaters (Go internal/registry/catalog_sources.go): one updater each for models.json, the Codex client catalog and the Devin catalog. Each reads its effective source ([effective_sources]) now and every three hours, validates what it read, and publishes it only while that source is still the configured one. A failed read or an invalid catalog keeps the last valid one. A config reload that changes a source switches the updater at once; a read still running for the old source is dropped.
observability
HTTP access logging, following internal/logging/gin_logger.go (v8.0.35).
persist
Remote persistence for config and auth files (Go’s storePersister and the token store’s Delete). The Postgres, git and object stores mirror their content into a local workspace; the server keeps working on those files and reports each change here so the store can push it.
plugins
The plugin host in the server (Go sdk/cliproxy/service_plugins.go, internal/api/server_management.go): one cpa_plugin::Host per runtime, synced with every published config by a single worker so the latest config always wins.
pprof
Optional, separate debug listener (sdk/cliproxy/pprof_server.go, v8.0.35). One task owns the listener and its connections, so a stale config application or failed listener cannot stop its replacement. No API or management middleware runs here.
registry
The dynamic model registry lives in cpa_core::registry::dynamic so translators and shared helpers can read capabilities; this module publishes the runtime’s copy.
remote
Credentials dispatched by a control plane instead of the local scheduler (Go Home mode: pickHomeDispatchSelection / executeHomeOnce). While a dispatcher is installed every request routes to provider home, each pick asks the dispatcher for one credential, and the credential’s lease ends with a release the dispatcher reports back. The dispatcher owns cooldowns and retry limits; nothing is recorded in the local scheduler.
request_logging
Go request_logging.go / response_writer.go and request_logger_writer.go. Request bodies in these files are intentionally unredacted, as in Go. Headers and URL queries are masked before writing; management routes are never captured.
runtime
Axum-independent runtime: config snapshot, credential store, selection, credential preparation and attempt outcomes.
safe_mode
Template-key startup guard (Go cmd/server/main.go and server_middleware.go).
scheduler
Credential routing policy. Config parsing remains owned by cpa-core; integration publishes this policy through Runtime::publish_policy.
usage
Go internal/redisqueue: the in-memory usage queue that management’s GET /observability/usage/queue drains. The request path enqueues one JSON record per upstream request (Go queuedUsageDetail); records older than the retention window are pruned on every access.
watching
Hot reload of config.yaml and the auth directory (Go internal/watcher).

Constants§

MAX_REQUEST_BYTES

Functions§

app
The served app: the API routes, with rest (the management router, which owns gin’s NoRoute and its plugin routes) answering every path the API does not register. axum allows one fallback per merged router, so rest sits behind the API instead of being merged into it.
install_registry
Installs the runtime’s model registry as the translators’ capability lookup (cpa_core::registry::lookup_model). Call once at startup.
router
The API routes alone; unregistered paths get gin’s bare NoRoute 404.