use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::time::{Duration, Instant};
use clap::Args;
use crate::server::admin::ADMIN_PATH;
use crate::server::mcp_http::MCP_PATH;
use crate::server::serve::{self, ServeArgs};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ServerSessionDescriptor {
pub bound_addr: SocketAddr,
pub dashboard_url: String,
pub attach_url: String,
pub reachable: bool,
}
impl ServerSessionDescriptor {
pub fn for_addr(bound_addr: SocketAddr, reachable: bool) -> Self {
Self {
dashboard_url: format!("http://{bound_addr}{ADMIN_PATH}"),
attach_url: format!("http://{bound_addr}{MCP_PATH}"),
bound_addr,
reachable,
}
}
}
pub fn operator_server_reachable(addr: SocketAddr, timeout: Duration) -> bool {
let Ok(runtime) = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
else {
return false;
};
runtime.block_on(async move {
let Ok(client) = reqwest::Client::builder().timeout(timeout).build() else {
return false;
};
let url = format!("http://{addr}/api/v1/summary");
client.get(url).send().await.is_ok()
})
}
pub fn start_operator_server(
preferred: Option<SocketAddr>,
explicit: bool,
api_key: Option<String>,
api_key_env: Option<String>,
deadline: Duration,
) -> anyhow::Result<ServerSessionDescriptor> {
let requested = preferred.map_or_else(
|| crate::server::serve::DEFAULT_LISTEN.to_string(),
|addr| addr.to_string(),
);
let (bound_tx, bound_rx) = std::sync::mpsc::sync_channel(1);
let serve_args = ServeArgs {
listen: requested,
explicit_listen: explicit,
api_key,
api_key_env,
bound_addr_tx: Some(bound_tx),
};
std::thread::Builder::new()
.name("symforge-serve".to_string())
.spawn(move || {
let runtime = match tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
{
Ok(rt) => rt,
Err(error) => {
tracing::error!(%error, "operator serve-start: failed to build runtime");
return;
}
};
if let Err(error) = runtime.block_on(serve::run(serve_args)) {
tracing::error!(%error, "operator serve-start: serve::run exited with error");
}
})
.map_err(|e| anyhow::anyhow!("could not spawn operator-server thread: {e}"))?;
let bound_addr = match bound_rx.recv_timeout(deadline) {
Ok(Ok(addr)) => addr,
Ok(Err(bind_error)) => anyhow::bail!("operator server failed to start: {bind_error}"),
Err(_) => anyhow::bail!(
"operator server did not report a bound address within {deadline:?} \
(index load + bind)"
),
};
let start = Instant::now();
let probe_timeout = Duration::from_millis(250);
let poll_interval = Duration::from_millis(50);
while start.elapsed() < deadline {
if operator_server_reachable(bound_addr, probe_timeout) {
return Ok(ServerSessionDescriptor::for_addr(bound_addr, true));
}
std::thread::sleep(poll_interval);
}
anyhow::bail!("operator server did not become reachable on {bound_addr} within {deadline:?}")
}
pub(crate) fn select_free_addr_std(preferred: Option<SocketAddr>) -> std::io::Result<SocketAddr> {
if let Some(addr) = preferred {
if addr.port() != 0 {
if let Ok(listener) = std::net::TcpListener::bind(addr) {
return listener.local_addr();
}
} else if let Some(resolved) = first_free_operator_addr(addr.ip()) {
return Ok(resolved);
}
}
first_free_operator_addr(IpAddr::V4(Ipv4Addr::LOCALHOST)).ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::AddrInUse,
"no free operator port available in 8000-8999 or 5000-5999",
)
})
}
fn first_free_operator_addr(host: IpAddr) -> Option<SocketAddr> {
crate::server::serve::operator_port_candidates().find_map(|port| {
let addr = SocketAddr::new(host, port);
std::net::TcpListener::bind(addr)
.ok()
.and_then(|listener| listener.local_addr().ok())
})
}
#[derive(Args, Debug, Clone)]
pub struct AdminCliArgs {
#[arg(long)]
pub no_open: bool,
}
#[derive(Debug)]
pub struct AdminOutcome {
pub session: ServerSessionDescriptor,
pub reused_server: bool,
pub browser_outcome: crate::cli::browser::BrowserOpenOutcome,
}
const ADMIN_REACHABILITY_TIMEOUT: Duration = Duration::from_millis(500);
pub(crate) const ADMIN_SERVE_START_DEADLINE: Duration = Duration::from_secs(60);
pub fn run(args: AdminCliArgs) -> anyhow::Result<()> {
let ctx = crate::cli::setup::SetupContext::from_env()?;
let browser = crate::cli::browser::OsBrowserOpener;
let outcome = run_admin(&args, &ctx, &browser)?;
if outcome.reused_server {
eprintln!(
"Operator dashboard already running — {}",
outcome.session.dashboard_url
);
} else {
eprintln!(
"Started operator dashboard — {}",
outcome.session.dashboard_url
);
}
eprintln!("Attach: {}", outcome.session.attach_url);
eprintln!(
"Browser: {:?} — open {}",
outcome.browser_outcome, outcome.session.dashboard_url
);
serve_foreground_if_started(&outcome, block_until_ctrl_c)
}
pub(crate) const FOREGROUND_SERVE_NOTICE: &str =
"Serving the operator dashboard in the foreground — press Ctrl-C to stop.";
fn serve_foreground_if_started(
outcome: &AdminOutcome,
wait_for_shutdown: impl FnOnce(&ServerSessionDescriptor) -> anyhow::Result<()>,
) -> anyhow::Result<()> {
if outcome.reused_server {
return Ok(());
}
eprintln!("{FOREGROUND_SERVE_NOTICE}");
wait_for_shutdown(&outcome.session)
}
fn block_until_ctrl_c(_session: &ServerSessionDescriptor) -> anyhow::Result<()> {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()?;
runtime.block_on(tokio::signal::ctrl_c())?;
Ok(())
}
pub fn run_admin<B: crate::cli::browser::BrowserOpener + ?Sized>(
args: &AdminCliArgs,
ctx: &crate::cli::setup::SetupContext,
browser: &B,
) -> anyhow::Result<AdminOutcome> {
let placement = crate::paths::process_control_state_placement();
run_admin_with_control_state(args, ctx, browser, placement.directory())
}
#[doc(hidden)]
pub fn run_admin_with_control_state<B: crate::cli::browser::BrowserOpener + ?Sized>(
args: &AdminCliArgs,
ctx: &crate::cli::setup::SetupContext,
browser: &B,
control_state_dir: Option<&crate::domain::ControlStateDir>,
) -> anyhow::Result<AdminOutcome> {
use crate::cli::operator_profile::OperatorSetupProfile;
let _ = ctx;
let existing_profile = control_state_dir.and_then(OperatorSetupProfile::load);
let mut reused_server = false;
let mut session: Option<ServerSessionDescriptor> = None;
if let Some(profile) = existing_profile.as_ref() {
let addr = loopback_addr_std(profile.port);
if operator_server_reachable(addr, ADMIN_REACHABILITY_TIMEOUT) {
session = Some(ServerSessionDescriptor::for_addr(addr, true));
reused_server = true;
}
}
let session = match session {
Some(s) => s,
None => {
let preferred = preferred_start_addr(existing_profile.as_ref());
let started = start_operator_server(
Some(preferred),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)?;
persist_started_port(control_state_dir, existing_profile.as_ref(), &started);
started
}
};
let browser_outcome = if args.no_open {
crate::cli::browser::BrowserOpenOutcome::Skipped
} else {
browser.open_url(&session.dashboard_url)
};
Ok(AdminOutcome {
session,
reused_server,
browser_outcome,
})
}
fn loopback_addr_std(port: u16) -> SocketAddr {
SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port)
}
fn preferred_start_addr(
existing_profile: Option<&crate::cli::operator_profile::OperatorSetupProfile>,
) -> SocketAddr {
if let Some(profile) = existing_profile {
return loopback_addr_std(profile.port);
}
crate::server::serve::DEFAULT_LISTEN
.parse()
.unwrap_or_else(|_| loopback_addr_std(0))
}
fn persist_started_port(
control_state_dir: Option<&crate::domain::ControlStateDir>,
existing_profile: Option<&crate::cli::operator_profile::OperatorSetupProfile>,
started: &ServerSessionDescriptor,
) {
use crate::cli::operator_profile::{AuthPosture, OperatorSetupProfile};
let port = started.bound_addr.port();
let updated_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_millis() as i64;
let profile = match existing_profile {
Some(prior) => OperatorSetupProfile {
port,
updated_ms,
..prior.clone()
},
None => OperatorSetupProfile {
installation_type: crate::cli::setup::InstallationType::Server,
port,
auth_posture: AuthPosture::LoopbackNoKey,
harnesses: Vec::new(),
updated_ms,
},
};
let Some(control_state_dir) = control_state_dir else {
tracing::warn!("admin: process control state unavailable; started port not persisted");
return;
};
if let Err(error) = profile.save(control_state_dir) {
tracing::warn!(%error, "admin: could not persist the started operator-server port");
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn descriptor_derives_urls_from_bound_addr() {
let addr: SocketAddr = "127.0.0.1:8787".parse().unwrap();
let desc = ServerSessionDescriptor::for_addr(addr, true);
assert_eq!(desc.dashboard_url, "http://127.0.0.1:8787/admin");
assert_eq!(desc.attach_url, "http://127.0.0.1:8787/mcp");
assert!(desc.reachable);
assert_eq!(desc.bound_addr, addr);
}
#[test]
fn select_free_addr_std_never_returns_an_ephemeral_port() {
fn in_operator_range(port: u16) -> bool {
(8000..=8999).contains(&port) || (5000..=5999).contains(&port)
}
let explicit_any = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
for preferred in [None, Some(explicit_any)] {
let addr = select_free_addr_std(preferred).expect("an operator port is free");
assert!(
in_operator_range(addr.port()),
"selected port must be operator-range, not ephemeral: {addr}"
);
}
}
#[test]
fn concurrent_starts_with_no_preference_both_come_up() {
let first = start_operator_server(None, false, None, None, ADMIN_SERVE_START_DEADLINE)
.expect("first operator server should come up");
let second = start_operator_server(None, false, None, None, ADMIN_SERVE_START_DEADLINE)
.expect("second operator server should come up");
assert_ne!(
first.bound_addr, second.bound_addr,
"each start must own a distinct port"
);
}
#[test]
fn occupied_preference_falls_back_instead_of_failing() {
let first = start_operator_server(None, false, None, None, ADMIN_SERVE_START_DEADLINE)
.expect("first operator server should come up");
let second = start_operator_server(
Some(first.bound_addr),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)
.expect("an occupied preference must fall back, not fail");
assert_ne!(
first.bound_addr, second.bound_addr,
"the second start must land on a different, genuinely free port"
);
}
#[test]
fn explicit_demand_fails_loudly_instead_of_falling_back() {
let first = start_operator_server(None, false, None, None, ADMIN_SERVE_START_DEADLINE)
.expect("first operator server should come up");
let result = start_operator_server(
Some(first.bound_addr),
true,
None,
None,
ADMIN_SERVE_START_DEADLINE,
);
assert!(
result.is_err(),
"an explicit demand for an occupied port must fail loudly, not fall back: {result:?}"
);
}
#[test]
fn reachable_false_on_dead_port() {
let scratch = std::net::TcpListener::bind("127.0.0.1:0").expect("scratch bind");
let dead = scratch.local_addr().expect("local_addr");
drop(scratch);
assert!(
!operator_server_reachable(dead, Duration::from_millis(300)),
"a freed port has no server; reachability must be false"
);
}
#[test]
fn reachable_true_against_a_real_serve() {
let preferred = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let desc = start_operator_server(
Some(preferred),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)
.expect("operator server should become reachable");
assert!(desc.reachable);
assert!(desc.bound_addr.ip().is_loopback());
assert_ne!(desc.bound_addr.port(), 0, "a concrete port was bound");
assert_eq!(
desc.dashboard_url,
format!("http://{}/admin", desc.bound_addr)
);
assert!(
operator_server_reachable(desc.bound_addr, Duration::from_millis(500)),
"a standalone reachability probe must see the running server"
);
}
use crate::cli::browser::{BrowserOpenOutcome, NoopBrowserOpener};
use crate::cli::operator_profile::{AuthPosture, OperatorSetupProfile};
use crate::cli::setup::{InstallationType, SetupContext};
fn ctx_over(home: &std::path::Path, project: &std::path::Path) -> SetupContext {
SetupContext {
home: home.to_path_buf(),
working_dir: project.to_path_buf(),
}
}
fn control_over(home: &std::path::Path) -> crate::domain::ControlStateDir {
crate::domain::ControlStateDir::new(home.join("control"))
}
#[test]
fn run_admin_reuses_running_server_on_profile_port() {
let preferred = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let running = start_operator_server(
Some(preferred),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)
.expect("operator server should come up");
let running_port = running.bound_addr.port();
let project = tempfile::tempdir().expect("temp project");
let home = tempfile::tempdir().expect("temp home");
let control = control_over(home.path());
OperatorSetupProfile::new(
InstallationType::Server,
running_port,
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(&control)
.expect("persist profile");
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin_with_control_state(
&AdminCliArgs { no_open: false },
&ctx,
&browser,
Some(&control),
)
.expect("admin should reuse the running server");
assert!(
outcome.reused_server,
"must reuse, not start a second server"
);
assert_eq!(
outcome.session.bound_addr.port(),
running_port,
"reused descriptor names the running server's port (SC-004)"
);
assert_eq!(browser.opened_urls().len(), 1);
assert_eq!(
browser.opened_urls()[0],
outcome.session.dashboard_url,
"the reused dashboard URL is the one opened"
);
}
#[test]
fn run_admin_starts_and_persists_when_none_running() {
let project = tempfile::tempdir().expect("temp project");
let home = tempfile::tempdir().expect("temp home");
let control = control_over(home.path());
assert!(OperatorSetupProfile::load(&control).is_none());
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin_with_control_state(
&AdminCliArgs { no_open: false },
&ctx,
&browser,
Some(&control),
)
.expect("admin should start a server when none runs");
assert!(!outcome.reused_server, "no server ran; must start one");
assert!(outcome.session.reachable);
assert!(
operator_server_reachable(outcome.session.bound_addr, Duration::from_millis(500)),
"the reported URL must actually be reachable (FR-020)"
);
assert_eq!(browser.opened_urls().len(), 1);
let profile = OperatorSetupProfile::load(&control).expect("port persisted");
assert_eq!(profile.port, outcome.session.bound_addr.port());
}
#[test]
fn run_admin_no_open_does_not_open_browser() {
let preferred = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let running = start_operator_server(
Some(preferred),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)
.expect("operator server should come up");
let project = tempfile::tempdir().expect("temp project");
let home = tempfile::tempdir().expect("temp home");
let control = control_over(home.path());
OperatorSetupProfile::new(
InstallationType::Server,
running.bound_addr.port(),
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(&control)
.expect("persist profile");
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin_with_control_state(
&AdminCliArgs { no_open: true },
&ctx,
&browser,
Some(&control),
)
.expect("admin --no-open should report without opening");
assert!(
browser.opened_urls().is_empty(),
"no_open suppresses the open"
);
assert_eq!(outcome.browser_outcome, BrowserOpenOutcome::Skipped);
assert!(outcome.session.dashboard_url.ends_with("/admin"));
}
#[test]
fn admin_keeps_serving_after_fresh_start_until_shutdown() {
let project = tempfile::tempdir().expect("temp project");
let home = tempfile::tempdir().expect("temp home");
let control = control_over(home.path());
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin_with_control_state(
&AdminCliArgs { no_open: true },
&ctx,
&browser,
Some(&control),
)
.expect("admin should start a server when none runs");
assert!(!outcome.reused_server, "no server ran; must start one");
let waited = std::cell::Cell::new(false);
serve_foreground_if_started(&outcome, |session| {
waited.set(true);
assert!(
operator_server_reachable(session.bound_addr, Duration::from_millis(500)),
"freshly-started server must be reachable while admin holds the foreground"
);
std::thread::sleep(Duration::from_millis(300));
assert!(
operator_server_reachable(session.bound_addr, Duration::from_millis(500)),
"the started server must STAY reachable (D21: it must not die after start)"
);
Ok(())
})
.expect("foreground wait returns cleanly on shutdown");
assert!(
waited.get(),
"a freshly-started server must hold the foreground (D21 fix); pre-fix `run` returned immediately"
);
assert!(
FOREGROUND_SERVE_NOTICE.contains("Ctrl-C"),
"the foreground notice must tell the operator how to stop it"
);
}
#[test]
fn admin_does_not_hold_foreground_when_reusing() {
let preferred = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
let running = start_operator_server(
Some(preferred),
false,
None,
None,
ADMIN_SERVE_START_DEADLINE,
)
.expect("operator server should come up");
let project = tempfile::tempdir().expect("temp project");
let home = tempfile::tempdir().expect("temp home");
let control = control_over(home.path());
OperatorSetupProfile::new(
InstallationType::Server,
running.bound_addr.port(),
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(&control)
.expect("persist profile");
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin_with_control_state(
&AdminCliArgs { no_open: true },
&ctx,
&browser,
Some(&control),
)
.expect("admin should reuse the running server");
assert!(outcome.reused_server, "must reuse the running server");
let waited = std::cell::Cell::new(false);
serve_foreground_if_started(&outcome, |_session| {
waited.set(true);
Ok(())
})
.expect("reuse path returns cleanly");
assert!(
!waited.get(),
"reuse path must NOT hold the foreground — another process owns the server"
);
}
}