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>,
api_key: Option<String>,
api_key_env: Option<String>,
deadline: Duration,
) -> anyhow::Result<ServerSessionDescriptor> {
let bound_addr = select_free_addr_std(preferred)
.map_err(|e| anyhow::anyhow!("could not select a free operator-server port: {e}"))?;
let serve_args = ServeArgs {
listen: bound_addr.to_string(),
explicit_listen: true,
api_key,
api_key_env,
};
std::thread::Builder::new()
.name(format!("symforge-serve-{}", bound_addr.port()))
.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 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 {
return std::net::TcpListener::bind(addr)?.local_addr();
}
if let Ok(listener) = std::net::TcpListener::bind(addr) {
return listener.local_addr();
}
}
for port in crate::server::serve::operator_port_candidates() {
let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port);
if let Ok(listener) = std::net::TcpListener::bind(addr) {
return listener.local_addr();
}
}
Err(std::io::Error::new(
std::io::ErrorKind::AddrInUse,
"no free operator port available in 8000-8999 or 5000-5999",
))
}
#[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
);
Ok(())
}
pub fn run_admin<B: crate::cli::browser::BrowserOpener + ?Sized>(
args: &AdminCliArgs,
ctx: &crate::cli::setup::SetupContext,
browser: &B,
) -> anyhow::Result<AdminOutcome> {
use crate::cli::operator_profile::OperatorSetupProfile;
let project_base = ctx.project_base();
let existing_profile = OperatorSetupProfile::load(&project_base);
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), None, None, ADMIN_SERVE_START_DEADLINE)?;
persist_started_port(&project_base, 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(
project_base: &std::path::Path,
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,
},
};
if let Err(error) = profile.save(project_base) {
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 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), 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(),
}
}
#[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), 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");
OperatorSetupProfile::new(
InstallationType::Server,
running_port,
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(project.path())
.expect("persist profile");
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin(&AdminCliArgs { no_open: false }, &ctx, &browser)
.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");
assert!(OperatorSetupProfile::load(project.path()).is_none());
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin(&AdminCliArgs { no_open: false }, &ctx, &browser)
.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(project.path()).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), 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");
OperatorSetupProfile::new(
InstallationType::Server,
running.bound_addr.port(),
AuthPosture::LoopbackNoKey,
&[],
1,
)
.save(project.path())
.expect("persist profile");
let ctx = ctx_over(home.path(), project.path());
let browser = NoopBrowserOpener::default();
let outcome = run_admin(&AdminCliArgs { no_open: true }, &ctx, &browser)
.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"));
}
}