use std::net::SocketAddr;
use std::sync::Arc;
use parking_lot::Mutex;
use super::api_keys::ApiKeyStore;
use super::auth::{AuthConfig, AuthLayerState, OriginLayerState};
use super::{ServerRuntime, admin, mcp_http};
use crate::live_index::{LiveIndex, SharedIndex};
use crate::protocol::SymForgeServer;
use crate::sidecar::governor::RequestGovernor;
use crate::stel::ledger_store::StelLedgerStore;
use crate::watcher::WatcherInfo;
pub const DEFAULT_LISTEN: &str = "127.0.0.1:8787";
#[derive(Debug, Clone)]
pub struct ServeArgs {
pub listen: String,
pub api_key: Option<String>,
pub api_key_env: Option<String>,
}
impl Default for ServeArgs {
fn default() -> Self {
Self {
listen: DEFAULT_LISTEN.to_string(),
api_key: None,
api_key_env: None,
}
}
}
pub fn resolve_api_key(api_key: Option<&str>, api_key_env: Option<&str>) -> Option<String> {
if let Some(key) = api_key
&& !key.is_empty()
{
return Some(key.to_string());
}
if let Some(var) = api_key_env
&& let Ok(value) = std::env::var(var)
&& !value.is_empty()
{
return Some(value);
}
None
}
pub fn enforce_api_key_source_policy(
api_key: Option<&str>,
is_loopback: bool,
) -> Result<(), super::auth::AuthStartupError> {
let inline_present = matches!(api_key, Some(key) if !key.is_empty());
if !inline_present {
return Ok(());
}
if !is_loopback {
return Err(super::auth::AuthStartupError::InlineKeyOnNonLoopback);
}
let msg = "WARNING: --api-key was passed inline; it is visible in process listings \
(ps / Task Manager). Prefer --api-key-env <VAR> so the secret stays out of argv.";
tracing::warn!("{msg}");
eprintln!("{msg}");
Ok(())
}
pub fn is_loopback_addr(addr: &SocketAddr) -> bool {
addr.ip().is_loopback()
}
pub fn bind_listener(addr: SocketAddr) -> std::io::Result<tokio::net::TcpListener> {
let domain = if addr.is_ipv4() {
socket2::Domain::IPV4
} else {
socket2::Domain::IPV6
};
let socket = socket2::Socket::new(domain, socket2::Type::STREAM, Some(socket2::Protocol::TCP))?;
socket.set_reuse_address(true)?;
socket.set_nonblocking(true)?;
socket.bind(&addr.into())?;
socket.listen(1024)?;
let std_listener: std::net::TcpListener = socket.into();
tokio::net::TcpListener::from_std(std_listener)
}
#[derive(Debug, thiserror::Error)]
pub enum ServeError {
#[error("invalid --listen address {addr:?}: {source}")]
InvalidListen {
addr: String,
#[source]
source: std::net::AddrParseError,
},
#[error(transparent)]
Startup(#[from] super::auth::AuthStartupError),
#[error("failed to bind {addr}: {source}")]
Bind {
addr: SocketAddr,
#[source]
source: std::io::Error,
},
#[error("failed to load project index for serving: {source}")]
IndexLoad {
#[source]
source: anyhow::Error,
},
#[error("operator server error: {source}")]
Serve {
#[source]
source: std::io::Error,
},
}
fn load_serve_index() -> Result<(SharedIndex, Option<std::path::PathBuf>), ServeError> {
match crate::discovery::find_project_root() {
Some(root) => {
let index =
LiveIndex::load(&root).map_err(|source| ServeError::IndexLoad { source })?;
Ok((index, Some(root)))
}
None => Ok((LiveIndex::empty(), None)),
}
}
fn build_serve_runtime(
index: SharedIndex,
repo_root: Option<std::path::PathBuf>,
auth: AuthConfig,
) -> ServerRuntime {
let project_name = repo_root
.as_ref()
.and_then(|root| root.file_name())
.and_then(|name| name.to_str())
.unwrap_or("project")
.to_string();
let ledger_store: Option<Arc<StelLedgerStore>> =
repo_root
.as_ref()
.and_then(|root| match crate::paths::ensure_symforge_dir(root) {
Ok(dir) => Some(Arc::new(StelLedgerStore::open(
&dir,
format!("serve-{}", std::process::id()),
))),
Err(error) => {
tracing::warn!(
root = %root.display(),
%error,
"could not ensure symforge data dir; STEL ledger will not persist"
);
None
}
});
let watcher_info = Arc::new(Mutex::new(WatcherInfo::default()));
let mut protocol = SymForgeServer::new(
Arc::clone(&index),
project_name,
watcher_info,
repo_root.clone(),
None,
);
if let Some(store) = ledger_store.as_ref() {
protocol = protocol.with_stel_ledger_store(Arc::clone(store));
}
let protocol = Arc::new(protocol);
let governor = Arc::new(RequestGovernor::new());
let runtime_store = ledger_store.map(|store| (*store).clone());
let key_store: Option<Arc<ApiKeyStore>> =
repo_root
.as_ref()
.and_then(|root| match crate::paths::ensure_symforge_dir(root) {
Ok(dir) => Some(Arc::new(ApiKeyStore::open(&dir))),
Err(error) => {
tracing::warn!(
root = %root.display(),
%error,
"could not ensure symforge data dir; API-key store unavailable"
);
None
}
});
let mut runtime = ServerRuntime::build_runtime(index, protocol, governor, auth, runtime_store);
if let Some(store) = key_store {
runtime = runtime.with_key_store(store);
}
runtime
}
pub async fn run(args: ServeArgs) -> Result<(), ServeError> {
let api_key = resolve_api_key(args.api_key.as_deref(), args.api_key_env.as_deref());
let auth = AuthConfig::new(api_key);
let addr: SocketAddr = args
.listen
.parse()
.map_err(|source| ServeError::InvalidListen {
addr: args.listen.clone(),
source,
})?;
let is_loopback = is_loopback_addr(&addr);
enforce_api_key_source_policy(args.api_key.as_deref(), is_loopback)?;
auth.refuse_to_start(is_loopback)?;
let (index, repo_root) = load_serve_index()?;
let onboarding_root = repo_root.clone();
let runtime = build_serve_runtime(index, repo_root, auth.clone());
let listener = bind_listener(addr).map_err(|source| ServeError::Bind { addr, source })?;
let local_addr = listener
.local_addr()
.map_err(|source| ServeError::Bind { addr, source })?;
let mcp_router = mcp_http::build_mcp_router(&runtime, local_addr);
let admin_router = admin::build_admin_router(&runtime);
let merged = mcp_router.merge(admin_router);
let origin_state = OriginLayerState::from_bind_addr(local_addr);
let gated = super::apply_origin_gate(merged, origin_state);
let mut auth_state = AuthLayerState::new(auth, is_loopback);
if let Some(store) = runtime.key_store() {
auth_state = auth_state.with_key_store(Arc::clone(store));
}
let app = super::apply_bearer_auth(gated, auth_state);
let attach_url = format!(
"http://{host}:{port}{path}",
host = local_addr.ip(),
port = local_addr.port(),
path = mcp_http::MCP_PATH,
);
println!("{attach_url}");
if let Some(root) = onboarding_root.as_ref() {
let state_path = crate::cli::onboarding::state_path(root);
let mut sink = crate::cli::onboarding::StderrSink;
let detection = crate::server::aap::AapDetection::resolve();
let aap_banner = detection.detected.then(|| {
let admin_url = format!(
"http://{host}:{port}{path}",
host = local_addr.ip(),
port = local_addr.port(),
path = crate::server::admin::ADMIN_PATH,
);
crate::cli::onboarding::AapBanner {
admin_url,
embed_path_dep: crate::server::aap::embed_cargo_snippet(),
}
});
crate::cli::onboarding::maybe_show_banner_with_aap(
&state_path,
env!("CARGO_PKG_VERSION"),
&attach_url,
aap_banner.as_ref(),
&mut sink,
);
}
tracing::info!(
addr = %local_addr,
auth = if runtime.auth().requires_auth(is_loopback) { "required" } else { "loopback-open" },
"operator server listening; MCP surface mounted at {}",
mcp_http::MCP_PATH
);
let shutdown = async {
#[cfg(unix)]
{
use tokio::signal::unix::{SignalKind, signal};
let mut sigterm = signal(SignalKind::terminate()).ok();
match sigterm.as_mut() {
Some(term) => {
tokio::select! {
_ = tokio::signal::ctrl_c() => {}
_ = term.recv() => {}
}
}
None => {
let _ = tokio::signal::ctrl_c().await;
}
}
}
#[cfg(not(unix))]
{
let _ = tokio::signal::ctrl_c().await;
}
tracing::info!("shutdown signal received, stopping operator server");
};
axum::serve(listener, app)
.with_graceful_shutdown(shutdown)
.await
.map_err(|source| ServeError::Serve { source })?;
tracing::info!("operator server shut down cleanly");
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use std::sync::Mutex;
static ENV_LOCK: Mutex<()> = Mutex::new(());
#[test]
fn resolve_api_key_prefers_inline_over_env() {
let _guard = ENV_LOCK.lock().unwrap();
let var = "SYMFORGE_TEST_SERVE_KEY_PREFER";
#[allow(unsafe_code)] unsafe {
std::env::set_var(var, "from_env")
};
let resolved = resolve_api_key(Some("from_inline"), Some(var));
assert_eq!(resolved.as_deref(), Some("from_inline"));
#[allow(unsafe_code)] unsafe {
std::env::remove_var(var)
};
}
#[test]
fn resolve_api_key_falls_back_to_env() {
let _guard = ENV_LOCK.lock().unwrap();
let var = "SYMFORGE_TEST_SERVE_KEY_FALLBACK";
#[allow(unsafe_code)] unsafe {
std::env::set_var(var, "from_env")
};
let resolved = resolve_api_key(None, Some(var));
assert_eq!(resolved.as_deref(), Some("from_env"));
#[allow(unsafe_code)] unsafe {
std::env::remove_var(var)
};
}
#[test]
fn resolve_api_key_none_when_unset() {
let _guard = ENV_LOCK.lock().unwrap();
let var = "SYMFORGE_TEST_SERVE_KEY_UNSET";
#[allow(unsafe_code)] unsafe {
std::env::remove_var(var)
};
assert_eq!(resolve_api_key(None, Some(var)), None);
assert_eq!(resolve_api_key(None, None), None);
assert_eq!(resolve_api_key(Some(""), None), None);
}
#[test]
fn inline_key_on_loopback_is_allowed_with_warning() {
assert!(enforce_api_key_source_policy(Some("k"), true).is_ok());
}
#[test]
fn inline_key_on_non_loopback_is_refused() {
let err = enforce_api_key_source_policy(Some("k"), false)
.expect_err("inline key on non-loopback must refuse");
assert_eq!(
err,
super::super::auth::AuthStartupError::InlineKeyOnNonLoopback
);
}
#[test]
fn no_inline_key_passes_policy_on_any_bind() {
assert!(enforce_api_key_source_policy(None, true).is_ok());
assert!(enforce_api_key_source_policy(None, false).is_ok());
assert!(enforce_api_key_source_policy(Some(""), false).is_ok());
}
#[tokio::test]
async fn run_refuses_inline_key_on_non_loopback() {
let args = ServeArgs {
listen: "0.0.0.0:8787".to_string(),
api_key: Some("inline-secret".to_string()),
api_key_env: None,
};
let err = run(args)
.await
.expect_err("non-loopback + inline key must refuse");
assert!(matches!(
err,
ServeError::Startup(super::super::auth::AuthStartupError::InlineKeyOnNonLoopback)
));
}
#[test]
fn is_loopback_addr_classifies_v4_and_v6() {
assert!(is_loopback_addr(&SocketAddr::new(
IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)),
8787
)));
assert!(is_loopback_addr(&SocketAddr::new(
IpAddr::V6(Ipv6Addr::LOCALHOST),
8787
)));
assert!(!is_loopback_addr(&SocketAddr::new(
IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)),
8787
)));
assert!(!is_loopback_addr(&SocketAddr::new(
IpAddr::V4(Ipv4Addr::new(192, 168, 1, 10)),
8787
)));
}
#[tokio::test]
async fn run_refuses_non_loopback_without_key() {
let args = ServeArgs {
listen: "0.0.0.0:8787".to_string(),
api_key: None,
api_key_env: None,
};
let err = run(args)
.await
.expect_err("non-loopback + no key must refuse");
assert!(matches!(err, ServeError::Startup(_)));
}
#[tokio::test]
async fn run_rejects_unparseable_listen() {
let args = ServeArgs {
listen: "not-an-address".to_string(),
api_key: Some("k".to_string()),
api_key_env: None,
};
let err = run(args).await.expect_err("bad --listen must error");
assert!(matches!(err, ServeError::InvalidListen { .. }));
}
#[tokio::test]
async fn bind_listener_binds_ephemeral_loopback_port() {
let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
let listener = bind_listener(addr).expect("bind ephemeral loopback");
let local = listener.local_addr().expect("local_addr");
assert!(local.ip().is_loopback());
assert_ne!(local.port(), 0, "OS must assign a concrete port");
}
}