cognee_http_server/
lib.rs

1//! Cognee HTTP server library — OSS surface.
2//!
3//! Provides `RouterBuilder` (the embedder-facing injection seam) and a
4//! free-function `build_router` shorthand. Closed embedders use
5//! `RouterBuilder` to splice the moved auth / api-keys / users / sync /
6//! checks / permissions routers back onto the OSS surface and to install
7//! an `AuthResolver` / `ExtraAuthValidator` against the
8//! `AuthenticatedUser` extractor.
9//!
10//! Pure-OSS callers (and tests) use `build_router(state)` which is
11//! equivalent to `RouterBuilder::new(state).build()`.
12//!
13//! The standalone `cognee-http-server` binary is a thin shell over
14//! `build_router` + `axum::serve`.
15
16pub mod auth;
17pub mod auth_resolver;
18pub mod cloud_client;
19pub mod components;
20pub mod config;
21pub mod dto;
22pub mod error;
23pub mod health;
24pub mod lifecycle;
25pub mod middleware;
26pub mod multipart;
27pub mod notebook_runner;
28pub mod observability;
29pub mod openapi;
30pub mod permissions;
31pub mod pipelines;
32pub mod responses;
33pub mod responses_dispatch;
34mod router_builder;
35pub mod routers;
36pub mod state;
37pub mod sync;
38pub mod telemetry;
39pub mod wiring;
40
41pub use config::HttpServerConfig;
42pub use error::{ApiError, ServerError};
43pub use router_builder::{RouterBuilder, build_router};
44pub use state::AppState;
45
46use std::net::SocketAddr;
47
48// ─── Graceful shutdown signal ─────────────────────────────────────────────────
49
50/// Waits for SIGTERM or SIGINT (Ctrl-C).
51///
52/// Only compiled when the `bin` feature is enabled so the library does not
53/// require `tokio/signal`.
54#[cfg(feature = "bin")]
55async fn shutdown_signal(state: AppState) {
56    use tokio::signal;
57
58    let ctrl_c = async {
59        signal::ctrl_c()
60            .await
61            .expect("failed to install Ctrl+C handler");
62    };
63
64    #[cfg(unix)]
65    let terminate = async {
66        signal::unix::signal(signal::unix::SignalKind::terminate())
67            .expect("failed to install SIGTERM handler")
68            .recv()
69            .await;
70    };
71
72    #[cfg(not(unix))]
73    let terminate = std::future::pending::<()>();
74
75    tokio::select! {
76        () = ctrl_c => {}
77        () = terminate => {}
78    }
79
80    lifecycle::on_shutdown(&state).await;
81}
82
83// ─── run ──────────────────────────────────────────────────────────────────────
84
85/// Bind `addr`, build the router, and serve until a shutdown signal.
86///
87/// This is the main entry point for both the standalone binary and embedders
88/// that want a ready-made server loop.
89pub async fn run(addr: SocketAddr, state: AppState) -> Result<(), ServerError> {
90    let app = build_router(state.clone()).await?;
91    let listener = tokio::net::TcpListener::bind(addr).await?;
92
93    tracing::info!("listening on {addr}");
94
95    #[cfg(feature = "bin")]
96    {
97        axum::serve(listener, app)
98            .with_graceful_shutdown(shutdown_signal(state))
99            .await
100            .map_err(|e| ServerError::Other(anyhow::anyhow!(e)))?;
101    }
102
103    #[cfg(not(feature = "bin"))]
104    {
105        // Library consumers that call `run()` without the `bin` feature get a
106        // server without graceful shutdown — they manage termination themselves.
107        axum::serve(listener, app)
108            .await
109            .map_err(|e| ServerError::Other(anyhow::anyhow!(e)))?;
110    }
111
112    Ok(())
113}
cognee_http_server/lib.rs

cognee_http_server/
lib.rs
