openkind_api/
lib.rs

1//! `openkind-api`: HTTP and gRPC transport protocols, middleware, and SDK compatibility surface.
2//!
3//! # Architecture & Responsibilities
4//! `openkind-api` provides dual transport interfaces for `openkind`:
5//! - **HTTP/REST Transport** ([`http`]): Axum 0.8 router serving `POST /v1/systemone` (canonical),
6//!   `POST /v1/system_one` (SDK alias), `GET /v1/models`, `GET /health`, and `GET /metrics`.
7//!   `GET /playground` ([`playground`]) serves an embedded web UI when the daemon opts in.
8//! - **gRPC Transport** ([`grpc`]): Tonic 0.14 service implementing `openkind.SystemOne/Evaluate`.
9//!
10//! Both transports route evaluation requests through `openkind_engine::dispatch`, decoupling transport
11//! encoding from inference backend execution.
12//!
13//! # Middleware & Wire Compatibility
14//! As specified in `docs/ARCHITECTURE.md`:
15//! - Outermost Request ID layer stamps `x-typesafe-request-id` on every response, including errors and 401s.
16//! - Constant-time Bearer token gate on `/v1/*` routes when `OPENKIND_API_KEY` (or `TYPESAFE_API_KEY`) is configured.
17//! - Error mapping with `Retry-After` and `retry-after-ms` headers on rate limits (429) and overload (529).
18
19#![warn(missing_docs)]
20
21/// Unofficial bulk Arrow IPC endpoint (`POST /v1/arrow`, opt-in).
22pub mod arrow;
23/// HTTP error mapping and Axum response conversion.
24pub mod error;
25/// Tonic gRPC service implementation for `openkind.SystemOne`.
26pub mod grpc;
27/// Axum HTTP router and endpoint handlers.
28pub mod http;
29/// Request ID, authentication, and rate limiting middleware.
30pub mod middleware;
31/// Model metadata structures and descriptors.
32pub mod models;
33/// Embedded web playground served at `GET /playground` (opt-in).
34pub mod playground;
35/// Optional proxy-cache hook consulted by the evaluation handlers.
36pub mod proxy;
37
38pub use arrow::{arrow_batch, ArrowBatchRequest, ARROW_CONTENT_TYPE};
39pub use error::ApiError;
40pub use http::{
41    router, router_daemon, router_daemon_with_arrow, router_with_auth, router_with_state,
42};
43pub use middleware::{AuthConfig, RateLimitConfig, RateLimiter, RequestLimits, REQUEST_ID_HEADER};
44pub use models::{ModelInfo, ModelsResponse};
45pub use proxy::{ProxyOutcome, ProxySource, SystemProxy};
46
47use std::sync::Arc;
48
49use openkind_engine::EngineRegistry;
50
51/// Shared application state passed to every axum handler and tonic method.
52#[derive(Clone)]
53pub struct AppState {
54    /// Thread-safe registry mapping model aliases to their decision engine instances.
55    pub registry: Arc<EngineRegistry>,
56    /// Optional daemon-owned local model lifecycle for the playground.
57    pub playground_models: Option<Arc<dyn playground::PlaygroundModels>>,
58    /// Optional proxy-cache hook (installed by the daemon in proxy mode).
59    pub proxy: Option<Arc<dyn proxy::SystemProxy>>,
60    /// Process-local weighted admission gate for Arrow batch work.
61    pub(crate) arrow_admission: Arc<tokio::sync::Semaphore>,
62}
63
64impl AppState {
65    /// Construct a new `AppState` wrapping the given engine registry.
66    pub fn new(registry: EngineRegistry) -> Self {
67        Self {
68            registry: Arc::new(registry),
69            playground_models: None,
70            proxy: None,
71            arrow_admission: Arc::new(tokio::sync::Semaphore::new(arrow::ARROW_ADMISSION_UNITS)),
72        }
73    }
74}
openkind_api/lib.rs

openkind_api/
lib.rs
