Skip to main content

hyprstream_core/services/
oai.rs

1//! OAIService - OpenAI-compatible HTTP API
2//!
3//! The HTTP server handles OpenAI API requests and uses authenticated RPC
4//! clients to reach Model, Policy, and Registry services.
5//!
6//! # Architecture
7//!
8//! ```text
9//! HTTP Clients ──► HTTP Server (Axum) ──► OAIService
10//!                        │
11//!                        ├──► ModelClient ──► ModelService
12//!                        └──► PolicyClient ──► PolicyService
13//! ```
14//!
15//! # Usage
16//!
17//! OAIService is typically started via the factory system:
18//!
19//! ```ignore
20//! // In config.toml
21//! [services]
22//! startup = ["event", "registry", "policy", "model", "oai"]
23//!
24//! [oai]
25//! host = "0.0.0.0"
26//! port = 8080
27//! ```
28
29use crate::config::{OAIConfig, TlsConfig};
30use crate::server::tls::{bind_listener, resolve_rustls_config, serve_bound};
31use crate::server::{create_app, state::ServerState};
32use anyhow::Result;
33use hyprstream_service::Spawnable;
34use std::net::SocketAddr;
35use std::sync::Arc;
36use std::time::Duration;
37use tokio::sync::Notify;
38use tracing::info;
39
40/// Service name for registry and logging
41pub const SERVICE_NAME: &str = "oai";
42
43const MODEL_MISSING_TENANT_DENIAL: &str = "authorization denied: no verified tenant domain";
44
45/// Prove that the tenantless OAI service can reach the authenticated Model
46/// dispatcher while preserving Model's tenant boundary.
47///
48/// The generated-module helper preserves the canonical method binding and
49/// returns a typed response only after the response envelope has been
50/// decrypted and verified against the resolved Model identity. Classify the
51/// expected denial only after that verification.
52pub(crate) async fn prove_model_reachability_denial(
53    client: &hyprstream_rpc_std::model_client::ModelClient,
54) -> Result<(), hyprstream_rpc::error::RpcError> {
55    use crate::services::generated::model_client::verified_health_check_response;
56    use hyprstream_rpc_std::model_client::ModelResponseVariant;
57
58    let response = verified_health_check_response(client)
59        .await
60        .map_err(|error| {
61            hyprstream_rpc::error::RpcError::SpawnFailed(format!(
62                "OAI Model reachability transport/authentication/response failed: {error}"
63            ))
64        })?;
65    match response {
66        ModelResponseVariant::Error(error)
67            if error.code == "INTERNAL"
68                && error.message == MODEL_MISSING_TENANT_DENIAL
69                && error.details.is_empty() =>
70        {
71            Ok(())
72        }
73        ModelResponseVariant::HealthCheckResult(_) => {
74            Err(hyprstream_rpc::error::RpcError::SpawnFailed(
75                "OAI tenantless Model reachability probe was unexpectedly authorized".to_owned(),
76            ))
77        }
78        response => Err(hyprstream_rpc::error::RpcError::SpawnFailed(format!(
79            "OAI Model reachability returned an unexpected authenticated response: {response:?}"
80        ))),
81    }
82}
83
84pub(crate) async fn healthy_registry(
85    client: &hyprstream_rpc_std::registry_client::RegistryClient,
86) -> Result<(), hyprstream_rpc::error::RpcError> {
87    let health = client.health_check().await.map_err(|error| {
88        hyprstream_rpc::error::RpcError::SpawnFailed(format!(
89            "OAI native Registry readiness: {error}"
90        ))
91    })?;
92    if health.status != "healthy" {
93        return Err(hyprstream_rpc::error::RpcError::SpawnFailed(format!(
94            "OAI native Registry readiness returned status {:?}",
95            health.status
96        )));
97    }
98    Ok(())
99}
100
101pub(crate) async fn await_required_native_dependencies(
102    model: &hyprstream_rpc_std::model_client::ModelClient,
103    registry: &hyprstream_rpc_std::registry_client::RegistryClient,
104    shutdown: Arc<Notify>,
105    timeout: Duration,
106) -> Result<(), hyprstream_rpc::error::RpcError> {
107    let checks = async {
108        prove_model_reachability_denial(model).await?;
109        healthy_registry(registry).await?;
110        Ok(())
111    };
112
113    tokio::select! {
114        _ = shutdown.notified() => Err(hyprstream_rpc::error::RpcError::SpawnFailed(
115            "OAI native dependency readiness cancelled".to_owned(),
116        )),
117        result = tokio::time::timeout(timeout, checks) => {
118            result.map_err(|_| hyprstream_rpc::error::RpcError::SpawnFailed(format!(
119                "OAI native dependency readiness timed out after {} milliseconds",
120                timeout.as_millis()
121            )))?
122        }
123    }
124}
125
126/// OAIService - OpenAI-compatible HTTP API
127///
128/// The HTTP server handles requests through authenticated Model, Policy, and
129/// Registry clients. OAI has no inbound RPC control schema or handler.
130pub struct OAIService {
131    /// OAI-specific configuration (host, port, TLS)
132    config: OAIConfig,
133
134    /// Global TLS configuration (passed from factory, avoids re-loading config)
135    tls_config: TlsConfig,
136
137    /// Account-zone configuration (epic #1158, A3) — used for DNS-01 wildcard
138    /// TLS provisioning. Passed from the factory to avoid re-loading config.
139    account_config: crate::account::AccountZoneConfig,
140
141    /// Shared server state containing clients and metrics
142    server_state: ServerState,
143
144    /// Required deployments must prove their outbound native dependencies
145    /// before advertising HTTP readiness.
146    native_dependencies_required: bool,
147}
148
149impl OAIService {
150    /// Create a new OAIService
151    ///
152    /// # Arguments
153    ///
154    /// * `config` - OAI configuration (host, port, TLS settings)
155    /// * `tls_config` - Global TLS configuration
156    /// * `server_state` - Shared state with RPC clients and metrics
157    /// * `native_dependencies_required` - gate readiness on authenticated
158    ///   Model reachability and Registry health responses
159    pub fn new(
160        config: OAIConfig,
161        tls_config: TlsConfig,
162        account_config: crate::account::AccountZoneConfig,
163        server_state: ServerState,
164        native_dependencies_required: bool,
165    ) -> Self {
166        Self {
167            config,
168            tls_config,
169            account_config,
170            server_state,
171            native_dependencies_required,
172        }
173    }
174
175    /// Get the HTTP bind address
176    pub fn http_addr(&self) -> Result<SocketAddr> {
177        let addr_str = format!("{}:{}", self.config.host, self.config.port);
178        addr_str
179            .parse()
180            .map_err(|e| anyhow::anyhow!("Invalid address: {}", e))
181    }
182
183    async fn await_native_dependencies(
184        &self,
185        shutdown: Arc<Notify>,
186    ) -> Result<(), hyprstream_rpc::error::RpcError> {
187        if !self.native_dependencies_required {
188            return Ok(());
189        }
190
191        await_required_native_dependencies(
192            &self.server_state.model_client,
193            &self.server_state.registry,
194            shutdown,
195            Duration::from_secs(30),
196        )
197        .await
198    }
199
200    pub(crate) async fn run_inner(
201        self: Box<Self>,
202        shutdown: Arc<Notify>,
203        on_ready: Option<tokio::sync::oneshot::Sender<()>>,
204    ) -> Result<(), hyprstream_rpc::error::RpcError> {
205        // Parse HTTP bind address
206        let addr = self.http_addr().map_err(|e| {
207            hyprstream_rpc::error::RpcError::SpawnFailed(format!("Invalid HTTP address: {e}"))
208        })?;
209
210        // Resolve TLS configuration (tls_config passed from factory, not re-loaded)
211        let rustls_config = resolve_rustls_config(
212            &self.tls_config,
213            &self.account_config,
214            self.config.tls_cert.as_ref(),
215            self.config.tls_key.as_ref(),
216        )
217        .await
218        .map_err(|e| hyprstream_rpc::error::RpcError::SpawnFailed(format!("TLS config: {e}")))?;
219
220        let scheme = if rustls_config.is_some() {
221            "https"
222        } else {
223            "http"
224        };
225
226        // Create HTTP server
227        let app = create_app(self.server_state.clone());
228
229        info!("OpenAI-compatible API available at {scheme}://{addr}/oai/v1");
230
231        // PREBIND the HTTP(S) listener BEFORE any readiness signal: an
232        // occupied port fails here, before the supervisor is told the
233        // service is ready (#1585 YuI7 companion correction).
234        let bound = bind_listener(addr, rustls_config, "OAIService")?;
235
236        // Required deployments use the process-owned bootstrap Iroh
237        // endpoint for outbound RPC. Prove the actual Model and Registry
238        // request paths before exposing the HTTP face as ready. Policy was
239        // already probed by process authority-store initialization before
240        // this factory ran.
241        self.await_native_dependencies(Arc::clone(&shutdown))
242            .await?;
243
244        // Signal ready only after the listener and required native
245        // dependencies are ready.
246        if let Some(tx) = on_ready {
247            let _ = tx.send(());
248        }
249
250        // Notify systemd that service is ready
251        let _ = hyprstream_rpc::notify::ready();
252
253        // Run HTTP(S) server with graceful shutdown; the serving result
254        // propagates (post-READY runtime failure — recorded lifecycle gap).
255        serve_bound(bound, app, shutdown, "OAIService").await
256    }
257}
258
259impl Spawnable for OAIService {
260    fn name(&self) -> &str {
261        SERVICE_NAME
262    }
263
264    fn registrations(
265        &self,
266    ) -> Vec<(
267        hyprstream_rpc::SocketKind,
268        hyprstream_rpc::transport::TransportConfig,
269    )> {
270        Vec::new()
271    }
272
273    fn run(
274        self: Box<Self>,
275        shutdown: Arc<Notify>,
276        on_ready: Option<tokio::sync::oneshot::Sender<()>>,
277    ) -> Result<(), hyprstream_rpc::error::RpcError> {
278        // Create multi-threaded runtime for HTTP server
279        let rt = tokio::runtime::Builder::new_multi_thread()
280            .enable_all()
281            .build()
282            .map_err(|e| hyprstream_rpc::error::RpcError::SpawnFailed(format!("runtime: {e}")))?;
283
284        rt.block_on(self.run_inner(shutdown, on_ready))
285    }
286}
287
288#[cfg(test)]
289mod tests {
290    use super::*;
291
292    #[test]
293    fn test_service_name() {
294        assert_eq!(SERVICE_NAME, "oai");
295    }
296}