car_server_core/
lib.rs

1// Raise the recursion limit so the deeply-nested async block at the
2// `accept_async` -> `run_dispatch` call site doesn't trip the rustc
3// query-depth limit on Windows / Linux. The default 128 is fine on
4// macOS but the larger query graph on the other platforms pushes
5// through the threshold; 256 has comfortable headroom. (Same fix
6// `car-server` carries; the library inherits the same call-site
7// shape.)
8#![recursion_limit = "256"]
9
10//! Transport-neutral library extracted from `car-server`.
11//!
12//! Holds the JSON-RPC dispatcher, per-client session state, and the
13//! WebSocket channel plumbing. The standalone `car-server` binary is
14//! a thin wrapper that loads `~/.car/env`, initializes telemetry,
15//! spawns the dream loop, binds a TCP listener, and on each
16//! connection calls [`run_dispatch`].
17//!
18//! Embedders (e.g. the future `tokhn-daemon` at U7) construct a
19//! [`ServerState`] via [`ServerState::embedded`] (or
20//! [`ServerStateConfig`] for advanced wiring), accept WebSocket
21//! connections in their own listener, and call [`run_dispatch`]
22//! directly — without re-implementing the dispatcher.
23//!
24//! ## Library boundary contract
25//!
26//! Per the U1 plan, this library MUST NOT:
27//! - spawn the dream loop (caller decides),
28//! - initialize telemetry (caller decides),
29//! - load `~/.car/env` (caller decides).
30//!
31//! Those bootstraps stay in the embedder's `main`. This contract
32//! prevents the dual-memgine bug U7 mitigates: if the library
33//! silently spawned its own dream loop, embedded users would end up
34//! with two memgine engines (the embedder's plus the library's).
35//!
36//! ## Lock primitive
37//!
38//! `ClientSession.memgine` uses `Arc<tokio::sync::Mutex<MemgineEngine>>`
39//! per the "one-wrapper rule" — dispatcher handlers can hold the lock
40//! across `.await` points without risking poisoning, and tokio's
41//! `Mutex` does not poison so a panicking handler does not poison the
42//! engine for sibling connections.
43
44pub mod admission;
45pub mod handler;
46pub mod host;
47pub mod session;
48
49pub use admission::{InferenceAdmission, ENV_MAX_CONCURRENT};
50pub use handler::{handle_connection, run_dispatch, JsonRpcError, JsonRpcMessage, JsonRpcResponse};
51pub use session::{
52    ClientSession, ServerState, ServerStateConfig, WsChannel, WsMemgineIngestSink,
53    WsToolExecutor, WsVoiceEventSink,
54};
car_server_core/lib.rs

car_server_core/
lib.rs
