Skip to main content

hyprstream_core/server/
mod.rs

1//! Hyprstream server implementation with OpenAI-compatible API
2//!
3//! This module provides the main HTTP server with:
4//! - OpenAI-compatible API endpoints at /oai/v1
5//! - Model management at /models
6
7use anyhow::Result;
8use axum::http::StatusCode;
9use axum::{
10    extract::State, middleware as axum_middleware, response::IntoResponse, routing::get, Json,
11    Router,
12};
13use std::net::SocketAddr;
14use std::sync::Arc;
15use std::time::Duration;
16use tokio::net::TcpListener;
17use tokio::sync::Notify;
18use tower_http::{timeout::TimeoutLayer, trace::TraceLayer};
19use tracing::info;
20
21pub mod middleware;
22pub mod routes;
23pub mod state;
24pub mod tls;
25
26use axum::Extension;
27pub use middleware::AuthenticatedUser;
28use state::ServerState;
29
30/// Extract user identity from optional authenticated user extension.
31/// Returns "anonymous" if no authentication present.
32pub fn extract_user(auth_user: Option<&Extension<AuthenticatedUser>>) -> String {
33    auth_user
34        .map(|Extension(u)| u.user.clone())
35        .unwrap_or_else(|| "anonymous".to_owned())
36}
37
38/// Extract the subject and its authority-verified hosted-account policy domain.
39pub fn extract_policy_identity(
40    auth_user: Option<&Extension<AuthenticatedUser>>,
41) -> Result<(String, String), &'static str> {
42    let Extension(user) = auth_user.ok_or("authenticated identity missing")?;
43    Ok((user.user.clone(), user.authorization_domain()?))
44}
45
46/// Create the main application router
47pub fn create_app(state: ServerState) -> Router {
48    // Validate the complete cross-face registry before constructing any live
49    // route. Duplicate ids/routes, empty justifications, or a face/handler
50    // mismatch are startup-fatal rather than test-only findings.
51    if let Err(error) = crate::mac::public_exemptions::validate() {
52        panic!("invalid public exemption registry: {error}");
53    }
54
55    // H1b (#765): register the 9P-over-WebTransport handler for the QUIC
56    // path-mux `/9p` arm, co-located with H1a's axum `/9p` WS route below so
57    // both planes share one `ServerState` (export mount + ticket validator).
58    // Idempotent; the per-service QUIC endpoint (built in `hyprstream-service`,
59    // which can't depend on this crate) picks it up via the process-global.
60    routes::ninep::register_ninep_wt_handler(state.clone());
61
62    // Clone config for middleware
63    let cors_config = state.config.cors.clone();
64    let timeout_duration = Duration::from_secs(state.config.request_timeout_secs);
65    let resource_auth_state = state.resource_auth_state();
66
67    // Public routes (no auth required).
68    //
69    // #1273 / epic #1267: the unmediated public set is the reviewed
70    // `mac::public_exemptions` registry. These routes are built FROM the
71    // registry — adding an unmediated route requires appending a reviewed
72    // `PublicExemption` entry plus a handler arm below (two review surfaces).
73    // Every route NOT here stays on the protected (auth-mediated) router; the
74    // default is mediated, never permissive. See `mac::public_exemptions`.
75    let (public_routes, browser_provisioning_routes) = build_public_routes_from_registry(
76        Arc::clone(&state.public_route_rate_limiter),
77        Arc::clone(&state.browser_provisioning_rate_limiter),
78    );
79
80    // Protected routes (auth required). CORS only controls which browser
81    // origins may read responses; it never supplies identity or authority.
82    // The verified token drives tenant resolution (the DID's hosted-account
83    // binding) and the enforcing MAC path; `Origin` is not an authorization
84    // or tenant input.
85    let protected_routes = Router::new()
86        // OpenAI-compatible API routes at /oai/v1
87        .nest("/oai/v1", routes::openai::create_router())
88        // Model management routes
89        .nest("/models", routes::models::create_router())
90        // rate_limit added first (inner) → runs after auth sees the authenticated subject
91        .layer(axum_middleware::from_fn_with_state(
92            resource_auth_state.clone(),
93            middleware::rate_limit_middleware,
94        ))
95        .layer(axum_middleware::from_fn_with_state(
96            resource_auth_state,
97            middleware::auth_middleware,
98        ));
99
100    let mut app = public_routes
101        .merge(browser_provisioning_routes)
102        .merge(protected_routes)
103        // Add middleware (order matters: timeout should be before state)
104        .layer(TimeoutLayer::with_status_code(
105            StatusCode::REQUEST_TIMEOUT,
106            timeout_duration,
107        ))
108        .layer(TraceLayer::new_for_http())
109        .with_state(state);
110
111    // Add CORS middleware if enabled (should be outermost)
112    if cors_config.enabled {
113        app = app.layer(middleware::cors_layer(&cors_config));
114    }
115
116    app
117}
118
119/// Build the main-app public (unmediated) routers from the reviewed
120/// `mac::public_exemptions` registry (#1273 / epic #1267).
121///
122/// Returns `(public_routes, browser_provisioning_routes)`. The caller merges
123/// them and applies `.with_state(state)`. Wiring is driven by iterating the
124/// registry, so an unmediated route cannot appear without a reviewed
125/// `PublicExemption` entry plus a handler arm in the exhaustive match below.
126fn build_public_routes_from_registry(
127    public_route_rate_limiter: Arc<crate::server::middleware::RateLimiter>,
128    browser_provisioning_rate_limiter: Arc<crate::server::middleware::RateLimiter>,
129) -> (Router<ServerState>, Router<ServerState>) {
130    use crate::mac::public_exemptions::{for_face, HttpFace, PublicRouteHandler, RouteMethod};
131
132    let mut public_routes: Router<ServerState> = Router::new();
133    let mut rate_limited_public_routes: Router<ServerState> = Router::new();
134    let mut browser_provisioning_routes: Router<ServerState> = Router::new();
135
136    for exemption in for_face(HttpFace::MainApp) {
137        // Every reviewed MainApp public route is GET today. Fail closed if a
138        // non-GET route is added: extend this builder with method dispatch and
139        // update the registry snapshot test in the same PR.
140        assert_eq!(
141            exemption.method,
142            RouteMethod::Get,
143            "non-GET MainApp public route {:?} requires method dispatch in \
144             build_public_routes_from_registry",
145            exemption.id,
146        );
147        // Exhaustive match: wiring a new public route requires a handler arm
148        // here AND a registry entry — the double review touch that keeps the
149        // exempt set from silently growing.
150        match exemption.handler {
151            PublicRouteHandler::HealthCheck => {
152                public_routes = public_routes.route(exemption.path, get(health_check));
153            }
154            PublicRouteHandler::OauthProtectedResourceMetadata => {
155                rate_limited_public_routes = rate_limited_public_routes
156                    .route(exemption.path, get(oauth_protected_resource_metadata));
157            }
158            PublicRouteHandler::Export9pMetadata => {
159                rate_limited_public_routes = rate_limited_public_routes
160                    .route(exemption.path, get(routes::ninep::export9p_metadata));
161            }
162            PublicRouteHandler::WirePlanesMetadata => {
163                rate_limited_public_routes = rate_limited_public_routes
164                    .route(exemption.path, get(routes::ninep::wire_planes_metadata));
165            }
166            PublicRouteHandler::NinepWebSocket => {
167                rate_limited_public_routes =
168                    rate_limited_public_routes.route(exemption.path, get(routes::ninep::ninep_ws));
169            }
170            PublicRouteHandler::BrowserProvisioning => {
171                // Public browser provisioning is independently rate-limited
172                // before the handler can resolve accepted state or perform
173                // hybrid signing; it rides its own sub-router + layer.
174                browser_provisioning_routes = browser_provisioning_routes
175                    .route(
176                        exemption.path,
177                        get(routes::browser_provisioning::browser_provisioning),
178                    )
179                    .layer(axum_middleware::from_fn_with_state(
180                        Arc::clone(&browser_provisioning_rate_limiter),
181                        middleware::browser_provisioning_rate_limit_middleware,
182                    ));
183            }
184        }
185    }
186
187    // Public metadata and the 9P pre-upgrade path have no authenticated
188    // subject. Meter them through one non-client-selectable bucket while
189    // keeping liveness probes out of the failure domain.
190    public_routes = public_routes.merge(rate_limited_public_routes.layer(
191        axum_middleware::from_fn_with_state(
192            public_route_rate_limiter,
193            middleware::public_route_rate_limit_middleware,
194        ),
195    ));
196
197    (public_routes, browser_provisioning_routes)
198}
199
200/// Health check endpoint
201async fn health_check() -> impl IntoResponse {
202    Json(serde_json::json!({
203        "status": "healthy",
204        "service": "hyprstream",
205        "version": env!("CARGO_PKG_VERSION")
206    }))
207}
208
209/// Protected Resource Metadata (RFC 9728) for the OAI server.
210///
211/// Advertises the OAuth authorization server that protects this resource.
212async fn oauth_protected_resource_metadata(State(state): State<ServerState>) -> impl IntoResponse {
213    let mut meta = crate::services::oauth::protected_resource_metadata(
214        &state.resource_url,
215        &state.oauth_issuer_url,
216    );
217    meta.resource_name = Some("HyprStream OpenAI-Compatible API".to_owned());
218    meta.scopes_supported = Some(vec!["infer:model:*".into(), "read:model:*".into()]);
219    Json(meta)
220}
221
222/// Start the HTTP server (plain, no TLS).
223pub async fn start_server(addr: SocketAddr, state: ServerState) -> Result<()> {
224    let app = create_app(state);
225
226    info!("Starting Hyprstream server on {}", addr);
227    info!("OpenAI-compatible API available at http://{}/oai/v1", addr);
228
229    let listener = TcpListener::bind(addr).await?;
230    axum::serve(listener, app).await?;
231
232    Ok(())
233}
234
235/// Start the HTTPS server with TLS.
236///
237/// Resolves TLS configuration from the global `[tls]` section, with optional
238/// per-service cert/key overrides. Uses `serve_app()` for HTTPS or falls back to HTTP.
239pub async fn start_server_tls(
240    addr: SocketAddr,
241    state: ServerState,
242    shutdown: Arc<Notify>,
243) -> Result<()> {
244    let hypr_config = crate::config::HyprConfig::load().unwrap_or_default();
245    let rustls_config = tls::resolve_rustls_config(
246        &hypr_config.tls,
247        &hypr_config.account,
248        hypr_config.oai.tls_cert.as_ref(),
249        hypr_config.oai.tls_key.as_ref(),
250    )
251    .await?;
252
253    let scheme = if rustls_config.is_some() {
254        "https"
255    } else {
256        "http"
257    };
258    info!("OpenAI-compatible API available at {scheme}://{addr}/oai/v1");
259
260    let app = create_app(state);
261    tls::serve_app(addr, app, rustls_config, shutdown, "Hyprstream")
262        .await
263        .map_err(|e| anyhow::anyhow!("{}", e))
264}
265
266#[cfg(test)]
267mod tests {
268    #![allow(clippy::unwrap_used, clippy::expect_used)]
269
270    use super::*;
271    use crate::mac::public_exemptions::{self, for_face, HttpFace};
272    use std::collections::BTreeSet;
273
274    /// Extract the concrete paths configured in an Axum router's live path
275    /// table. Axum has no public route-enumeration API; its `Debug`
276    /// implementation deliberately includes the path router's `Node.paths`
277    /// map. A dependency change that removes or changes that representation
278    /// fails this load-bearing test closed until the extractor is reviewed.
279    fn live_router_paths<S>(router: &Router<S>) -> BTreeSet<String> {
280        let debug = format!("{router:?}");
281        let path_router = debug
282            .split_once("path_router: ")
283            .map(|(_, rest)| rest)
284            .and_then(|rest| {
285                rest.split_once(", fallback_router: ")
286                    .map(|(paths, _)| paths)
287            })
288            .expect("Axum Router Debug must expose the live path_router");
289        let paths = path_router
290            .split_once("node: Node { paths: {")
291            .map(|(_, rest)| rest)
292            .and_then(|rest| rest.split_once("} }").map(|(paths, _)| paths))
293            .expect("Axum PathRouter Debug must expose the live Node.paths map");
294
295        paths
296            .split('"')
297            .skip(1)
298            .step_by(2)
299            .filter(|value| value.starts_with('/'))
300            .map(str::to_owned)
301            .collect()
302    }
303
304    /// #1273 load-bearing drift gate: the concrete, live public route table
305    /// must equal the reviewed registry exactly.
306    ///
307    /// This is intentionally stronger than checking that every registry entry
308    /// builds. Adding `.route("/bypass", ...)` directly to either public router
309    /// changes `live_router_paths` without changing the registry and fails this
310    /// equality. Conversely, a registry entry without a live route also fails.
311    /// Since the public set is exact, protected paths remain outside it and are
312    /// still mediated by `auth_middleware` when `create_app` merges the
313    /// protected router.
314    #[test]
315    fn public_exemptions_match_live_routes() {
316        public_exemptions::validate().expect("registry must be self-consistent before wiring");
317
318        let rate_limiter = Arc::new(middleware::RateLimiter::new(u32::MAX, 3600));
319        let (public, browser_provisioning) =
320            build_public_routes_from_registry(Arc::clone(&rate_limiter), rate_limiter);
321        let live = live_router_paths(&public.merge(browser_provisioning));
322        let registered = for_face(HttpFace::MainApp)
323            .map(|exemption| exemption.path.to_owned())
324            .collect::<BTreeSet<_>>();
325
326        assert_eq!(
327            live, registered,
328            "live unmediated main-app routes diverged from PUBLIC_EXEMPTIONS"
329        );
330        assert!(
331            !live.contains("/models") && !live.contains("/oai/v1"),
332            "protected route roots must never appear in the public router"
333        );
334    }
335}