mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:24:24 +00:00
merge-fwe: FW16 E5: AgentLink, the link host: start, move, stop and retry the agents' control server and publish its connection file
This commit is contained in:
@@ -0,0 +1,247 @@
|
||||
//! The link host: the control server an app runs for agents while its settings let them in.
|
||||
|
||||
use std::fmt;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::sync::mpsc::Receiver;
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use craft_ui::runtime::motion;
|
||||
use craft_ui::runtime::windows::WindowHost;
|
||||
use egui::ViewportId;
|
||||
use serde::{Serialize, Serializer};
|
||||
|
||||
use super::{AgentSettings, Connection, TOKEN_FILE, remove_connection, write_connection};
|
||||
use crate::control::ControlRequest;
|
||||
use crate::security;
|
||||
use crate::server::{self, Listening};
|
||||
|
||||
/// How long after a failed start [`AgentLink::sync`] tries again with the same settings, so
|
||||
/// freeing a taken port is enough.
|
||||
pub const RETRY: Duration = Duration::from_secs(5);
|
||||
|
||||
/// Why agents cannot connect, or what the app could not apply. `Display` is the English sentence
|
||||
/// for logs and `ui.inspect`; the Agents page shows its own words.
|
||||
#[derive(Clone, Debug, PartialEq, Eq)]
|
||||
#[non_exhaustive]
|
||||
pub enum LinkProblem {
|
||||
/// Allow Agent Control is off.
|
||||
NotAllowed,
|
||||
/// The app has no settings folder (no home folder).
|
||||
NoSettingsFolder,
|
||||
/// The token file could not be read or written.
|
||||
TokenFile(String),
|
||||
/// The control server could not listen on `port`.
|
||||
Listen {
|
||||
/// The port asked for (0 is any).
|
||||
port: u16,
|
||||
/// Why.
|
||||
error: String,
|
||||
},
|
||||
/// The connection file could not be written; nothing listens without it.
|
||||
Publish(String),
|
||||
/// The app's own note ([`AgentLink::note`]), such as a folder it could not use.
|
||||
App(String),
|
||||
}
|
||||
|
||||
impl fmt::Display for LinkProblem {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
Self::NotAllowed => f.write_str("Agents can't connect: Allow Agent Control is off in the preferences file."),
|
||||
Self::NoSettingsFolder => f.write_str("Agents can't connect: the app has no settings folder (no home folder)."),
|
||||
Self::TokenFile(e) => write!(f, "Agents can't connect: the token file could not be written: {e}"),
|
||||
Self::Listen { port, error } => write!(f, "Couldn't listen on 127.0.0.1:{port}: {error}"),
|
||||
Self::Publish(e) => write!(f, "Couldn't publish the agent connection: {e}"),
|
||||
Self::App(note) => f.write_str(note),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Where the link stands, for the Agents page and `ui.inspect`. Serialised as
|
||||
/// `{"port", "launchFlags", "error"}`, `error` being the problem's `Display` text.
|
||||
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
#[non_exhaustive]
|
||||
pub struct AgentLinkStatus {
|
||||
/// The port agents can connect on while the server runs.
|
||||
pub port: Option<u16>,
|
||||
/// The launch options (`--control`) manage the connection; the settings don't.
|
||||
pub launch_flags: bool,
|
||||
/// Why agents can't connect, or what could not be applied.
|
||||
#[serde(rename = "error", serialize_with = "problem_text")]
|
||||
pub problem: Option<LinkProblem>,
|
||||
}
|
||||
|
||||
fn problem_text<S: Serializer>(problem: &Option<LinkProblem>, s: S) -> Result<S::Ok, S::Error> {
|
||||
match problem {
|
||||
Some(p) => s.collect_str(p),
|
||||
None => s.serialize_none(),
|
||||
}
|
||||
}
|
||||
|
||||
/// What one [`AgentLink::sync`] did, for the app to follow.
|
||||
#[derive(Debug, Default)]
|
||||
#[non_exhaustive]
|
||||
pub struct LinkUpdate {
|
||||
/// A server started: its requests arrive here. The app drains it as its control channel.
|
||||
pub requests: Option<Receiver<ControlRequest>>,
|
||||
/// The server that ran stopped: the app drops its control channel.
|
||||
pub stopped: bool,
|
||||
/// The settings applied or the link's state changed: the app rebuilds what agents may read and
|
||||
/// write (its policy, its folders) from [`AgentLink::status`] and the settings.
|
||||
pub changed: bool,
|
||||
}
|
||||
|
||||
/// The server while it runs; dropping it stops the server and removes the connection file.
|
||||
struct Running {
|
||||
server: Listening,
|
||||
dir: PathBuf,
|
||||
/// The `controlPort` setting it was started for (0 is any).
|
||||
port_pref: u32,
|
||||
}
|
||||
|
||||
impl Drop for Running {
|
||||
fn drop(&mut self) {
|
||||
remove_connection(&self.dir, std::process::id());
|
||||
log::info!("agent connection on {} stopped", self.server.addr);
|
||||
}
|
||||
}
|
||||
|
||||
/// The control server an app runs for agents while its settings let them in, and the connection
|
||||
/// file the app's `<id>-cli mcp` finds it by. The token stays in the settings folder across
|
||||
/// launches ([`TOKEN_FILE`]). Dropping the link stops the server and removes the connection file
|
||||
/// if this process wrote it.
|
||||
pub struct AgentLink {
|
||||
dir: Option<PathBuf>,
|
||||
app: String,
|
||||
running: Option<Running>,
|
||||
/// The server the launch options started; while it is there, the settings change nothing.
|
||||
launch: Option<Listening>,
|
||||
/// The settings of the last sync that ran, once one ran.
|
||||
applied: Option<Option<AgentSettings>>,
|
||||
retry_at: Option<Instant>,
|
||||
retry: Duration,
|
||||
status: AgentLinkStatus,
|
||||
}
|
||||
|
||||
impl fmt::Debug for AgentLink {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.debug_struct("AgentLink").field("dir", &self.dir).field("status", &self.status).finish_non_exhaustive()
|
||||
}
|
||||
}
|
||||
|
||||
impl AgentLink {
|
||||
/// A link that keeps its token and connection file in `settings_dir` and names `app` (the
|
||||
/// app's version string) in the connection file. Nothing runs until [`Self::sync`].
|
||||
pub fn new(settings_dir: Option<PathBuf>, app: impl Into<String>) -> Self {
|
||||
Self {
|
||||
dir: settings_dir,
|
||||
app: app.into(),
|
||||
running: None,
|
||||
launch: None,
|
||||
applied: None,
|
||||
retry_at: None,
|
||||
retry: RETRY,
|
||||
status: AgentLinkStatus::default(),
|
||||
}
|
||||
}
|
||||
|
||||
/// The server `--control` started: the status names its port and the launch options, and
|
||||
/// [`Self::sync`] changes nothing.
|
||||
pub fn from_launch(server: Listening) -> Self {
|
||||
let mut link = Self::new(None, String::new());
|
||||
link.status = AgentLinkStatus { port: Some(server.addr.port()), launch_flags: true, problem: None };
|
||||
link.launch = Some(server);
|
||||
link
|
||||
}
|
||||
|
||||
/// [`RETRY`] replaced by `delay`, so a test retries at once.
|
||||
#[doc(hidden)]
|
||||
pub fn retry_after(mut self, delay: Duration) -> Self {
|
||||
self.retry = delay;
|
||||
self
|
||||
}
|
||||
|
||||
/// Brings the server in line with `want` (`None`: agents may not connect): start it, restart it
|
||||
/// on another port, stop it, or keep it while other settings change. Does nothing while `want`
|
||||
/// equals the last call's and no retry of a failed start is due.
|
||||
pub fn sync(&mut self, want: Option<&AgentSettings>, host: &WindowHost) -> LinkUpdate {
|
||||
let mut update = LinkUpdate::default();
|
||||
if self.launch.is_some() {
|
||||
return update;
|
||||
}
|
||||
let now = motion::now();
|
||||
let retry_due = self.retry_at.is_some_and(|at| now >= at);
|
||||
if self.applied.as_ref().is_some_and(|applied| applied.as_ref() == want) && !retry_due {
|
||||
return update;
|
||||
}
|
||||
let before = (self.status.clone(), self.applied.clone());
|
||||
self.applied = Some(want.cloned());
|
||||
self.retry_at = None;
|
||||
self.status.problem = None;
|
||||
if let Err(problem) = self.apply(want, host, &mut update) {
|
||||
self.status.problem = Some(problem);
|
||||
}
|
||||
self.status.port = self.running.as_ref().map(|r| r.server.addr.port());
|
||||
update.changed = (&self.status, &self.applied) != (&before.0, &before.1);
|
||||
update
|
||||
}
|
||||
|
||||
fn apply(&mut self, want: Option<&AgentSettings>, host: &WindowHost, update: &mut LinkUpdate) -> Result<(), LinkProblem> {
|
||||
let Some(want) = want else {
|
||||
update.stopped = self.running.take().is_some();
|
||||
return Ok(());
|
||||
};
|
||||
// Allow Agent Control off refuses every control server, this one as `--control`.
|
||||
if !want.allow_agent_control {
|
||||
update.stopped = self.running.take().is_some();
|
||||
return Err(LinkProblem::NotAllowed);
|
||||
}
|
||||
let Some(dir) = self.dir.clone() else {
|
||||
update.stopped = self.running.take().is_some();
|
||||
return Err(LinkProblem::NoSettingsFolder);
|
||||
};
|
||||
if self.running.as_ref().is_some_and(|r| r.port_pref == want.control_port) {
|
||||
return Ok(());
|
||||
}
|
||||
update.stopped = self.running.take().is_some();
|
||||
// The setting's range is 0..=65535; anything else picks a free port.
|
||||
let port = u16::try_from(want.control_port).unwrap_or(0);
|
||||
match self.start(&dir, port, want.control_port, host) {
|
||||
Ok((running, requests)) => {
|
||||
log::info!("agents can connect on {}", running.server.addr);
|
||||
self.running = Some(running);
|
||||
update.requests = Some(requests);
|
||||
Ok(())
|
||||
}
|
||||
Err(problem) => {
|
||||
log::warn!("{problem}");
|
||||
self.retry_at = Some(motion::now() + self.retry);
|
||||
host.repaint_in(ViewportId::ROOT, self.retry.as_secs_f64());
|
||||
Err(problem)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The token from the settings folder (created `0600` when missing), the server, then the
|
||||
/// connection file. Any failure leaves nothing running.
|
||||
fn start(&self, dir: &Path, port: u16, port_pref: u32, host: &WindowHost) -> Result<(Running, Receiver<ControlRequest>), LinkProblem> {
|
||||
let token_file = dir.join(TOKEN_FILE);
|
||||
let token = security::server_token(None, Some(&token_file)).map_err(|e| LinkProblem::TokenFile(e.to_string()))?;
|
||||
let (requests, server) = server::listen(port, token, host.clone()).map_err(|e| LinkProblem::Listen { port, error: e.to_string() })?;
|
||||
let running = Running { server, dir: dir.to_path_buf(), port_pref };
|
||||
let connection = Connection::new(running.server.addr.port(), token_file, self.app.clone());
|
||||
write_connection(dir, &connection).map_err(|e| LinkProblem::Publish(e.to_string()))?;
|
||||
Ok((running, requests))
|
||||
}
|
||||
|
||||
/// Where the link stands.
|
||||
pub fn status(&self) -> &AgentLinkStatus {
|
||||
&self.status
|
||||
}
|
||||
|
||||
/// The app reports what it could not apply (a folder it could not use); shown until the next
|
||||
/// change.
|
||||
pub fn note(&mut self, problem: LinkProblem) {
|
||||
self.status.problem = Some(problem);
|
||||
}
|
||||
}
|
||||
@@ -32,11 +32,15 @@ pub use settings::{AgentSettings, WhenAppClosed, agents_allowed, folder};
|
||||
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod connection;
|
||||
#[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))]
|
||||
mod link;
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
mod switch;
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
pub use connection::{
|
||||
CONNECTION_FILE, Connection, PROBE_TIMEOUT, TOKEN_FILE, probe, read_connection, remove_connection, remove_stale_connection, write_connection,
|
||||
};
|
||||
#[cfg(all(feature = "agents", feature = "ui", not(target_arch = "wasm32")))]
|
||||
pub use link::{AgentLink, AgentLinkStatus, LinkProblem, LinkUpdate, RETRY};
|
||||
#[cfg(all(feature = "agents", not(target_arch = "wasm32")))]
|
||||
pub use switch::{AgentSwitch, POLL, launcher_allows, mcp_flag};
|
||||
|
||||
@@ -7,12 +7,15 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
|
||||
use std::time::Duration;
|
||||
|
||||
use craft_automation::agents::{
|
||||
AgentSwitch, CONNECTION_FILE, Connection, TOKEN_FILE, agents_allowed, read_connection, remove_connection, remove_stale_connection,
|
||||
write_connection,
|
||||
AgentLink, AgentSettings, AgentSwitch, CONNECTION_FILE, Connection, LinkProblem, PROBE_TIMEOUT, TOKEN_FILE, agents_allowed, probe, read_connection,
|
||||
remove_connection, remove_stale_connection, write_connection,
|
||||
};
|
||||
use craft_automation::server;
|
||||
use craft_host::Wake;
|
||||
use craft_ui::runtime::motion;
|
||||
use craft_ui::runtime::windows::WindowHost;
|
||||
use craft_ui::testing::trial;
|
||||
use egui::Context;
|
||||
|
||||
fn temp_dir(tag: &str) -> tempfile::TempDir {
|
||||
tempfile::Builder::new().prefix(&format!("craft-agents-{tag}-")).tempdir().expect("a temp dir")
|
||||
@@ -144,3 +147,153 @@ fn a_damaged_foreign_or_stale_connection_file_counts_as_none() {
|
||||
remove_stale_connection(dir);
|
||||
assert!(!dir.join(CONNECTION_FILE).exists(), "nothing listens on {closed}");
|
||||
}
|
||||
|
||||
fn host() -> WindowHost {
|
||||
WindowHost::of(&Context::default())
|
||||
}
|
||||
|
||||
fn on(port: u32) -> AgentSettings {
|
||||
AgentSettings { control_port: port, ..AgentSettings::default() }
|
||||
}
|
||||
|
||||
/// A port nothing listens on: bound, then closed.
|
||||
fn free_port() -> u16 {
|
||||
TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port()
|
||||
}
|
||||
|
||||
/// Off publishes nothing; on publishes the bound port and this process, and something answers there; a folder-only
|
||||
/// change keeps the port and gives no new channel; off removes the file and frees the port.
|
||||
#[trial]
|
||||
fn turning_agents_on_publishes_a_reachable_connection_and_off_removes_it() {
|
||||
let dir = temp_dir("link");
|
||||
let host = host();
|
||||
let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "MyApp 1.0");
|
||||
let off = link.sync(None, &host);
|
||||
assert!(off.requests.is_none() && !off.stopped && !off.changed);
|
||||
assert_eq!(read_connection(dir.path()).unwrap(), None);
|
||||
|
||||
let started = link.sync(Some(&on(0)), &host);
|
||||
assert!(started.requests.is_some() && started.changed);
|
||||
let port = link.status().port.expect("listening");
|
||||
let c = read_connection(dir.path()).unwrap().expect("published");
|
||||
assert_eq!((c.port, c.pid, c.app.as_str()), (port, std::process::id(), "MyApp 1.0"));
|
||||
assert!(probe(port, PROBE_TIMEOUT));
|
||||
let token = std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap();
|
||||
|
||||
let folders = AgentSettings { read_root: "/in".into(), ..on(0) };
|
||||
let kept = link.sync(Some(&folders), &host);
|
||||
assert!(kept.requests.is_none() && !kept.stopped && kept.changed, "a folder change keeps the server");
|
||||
assert_eq!(link.status().port, Some(port));
|
||||
assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token);
|
||||
|
||||
let stopped = link.sync(None, &host);
|
||||
assert!(stopped.stopped && stopped.changed);
|
||||
assert_eq!(link.status().port, None);
|
||||
assert!(!dir.path().join(CONNECTION_FILE).exists());
|
||||
TcpListener::bind(("127.0.0.1", port)).expect("the port is free");
|
||||
}
|
||||
|
||||
/// A new port restarts the server with the same token; a taken port is named, publishes nothing, and is tried again
|
||||
/// without a setting change until it is free.
|
||||
#[trial]
|
||||
fn a_new_port_restarts_with_the_same_token_and_a_taken_port_is_retried() {
|
||||
let dir = temp_dir("link-port");
|
||||
let host = host();
|
||||
let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x").retry_after(Duration::ZERO);
|
||||
assert!(link.sync(Some(&on(0)), &host).requests.is_some());
|
||||
let token = std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap();
|
||||
|
||||
let wanted = free_port();
|
||||
let moved = link.sync(Some(&on(u32::from(wanted))), &host);
|
||||
assert!(moved.stopped && moved.requests.is_some());
|
||||
assert_eq!(link.status().port, Some(wanted));
|
||||
assert_eq!(read_connection(dir.path()).unwrap().expect("published").port, wanted);
|
||||
assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token, "the token is kept across restarts");
|
||||
|
||||
let taken = TcpListener::bind("127.0.0.1:0").unwrap();
|
||||
let taken_port = taken.local_addr().unwrap().port();
|
||||
let failed = link.sync(Some(&on(u32::from(taken_port))), &host);
|
||||
assert!(failed.stopped && failed.requests.is_none());
|
||||
assert!(matches!(link.status().problem, Some(LinkProblem::Listen { port, .. }) if port == taken_port), "{:?}", link.status());
|
||||
assert_eq!(link.status().port, None);
|
||||
assert_eq!(read_connection(dir.path()).unwrap(), None, "nothing listens without a file, and no file without a listener");
|
||||
|
||||
// Still taken: the retry fails the same way and changes nothing.
|
||||
let again = link.sync(Some(&on(u32::from(taken_port))), &host);
|
||||
assert!(again.requests.is_none() && !again.changed);
|
||||
drop(taken);
|
||||
let retried = link.sync(Some(&on(u32::from(taken_port))), &host);
|
||||
assert!(retried.requests.is_some() && retried.changed, "freeing the port is enough");
|
||||
assert_eq!(link.status().port, Some(taken_port));
|
||||
assert_eq!(link.status().problem, None);
|
||||
assert_eq!(std::fs::read_to_string(dir.path().join(TOKEN_FILE)).unwrap(), token);
|
||||
}
|
||||
|
||||
/// Ten syncs with the same settings start one server.
|
||||
#[trial]
|
||||
fn an_unchanged_sync_starts_nothing() {
|
||||
let dir = temp_dir("link-same");
|
||||
let host = host();
|
||||
let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x");
|
||||
let updates: Vec<_> = (0..10).map(|_| link.sync(Some(&on(0)), &host)).collect();
|
||||
assert_eq!(updates.iter().filter(|u| u.requests.is_some()).count(), 1);
|
||||
assert_eq!(updates.iter().filter(|u| u.changed).count(), 1);
|
||||
assert!(updates.iter().all(|u| !u.stopped));
|
||||
assert!(link.status().port.is_some());
|
||||
}
|
||||
|
||||
/// Allow Agent Control off, no settings folder and an unusable token file each keep agents out: no channel, no file,
|
||||
/// and the port is free.
|
||||
#[trial]
|
||||
fn allow_agent_control_off_and_no_settings_folder_keep_agents_out() {
|
||||
let host = host();
|
||||
let dir = temp_dir("link-off");
|
||||
let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x");
|
||||
assert!(link.sync(Some(&on(0)), &host).requests.is_some());
|
||||
let port = link.status().port.expect("listening");
|
||||
let refused = link.sync(Some(&AgentSettings { allow_agent_control: false, ..on(0) }), &host);
|
||||
assert!(refused.stopped && refused.requests.is_none());
|
||||
assert_eq!(link.status().problem, Some(LinkProblem::NotAllowed));
|
||||
assert!(!dir.path().join(CONNECTION_FILE).exists());
|
||||
TcpListener::bind(("127.0.0.1", port)).expect("the port is free");
|
||||
|
||||
let mut homeless = AgentLink::new(None, "x");
|
||||
assert!(homeless.sync(Some(&on(0)), &host).requests.is_none());
|
||||
assert_eq!(homeless.status().problem, Some(LinkProblem::NoSettingsFolder));
|
||||
|
||||
let bad = temp_dir("link-token");
|
||||
std::fs::create_dir(bad.path().join(TOKEN_FILE)).unwrap();
|
||||
let wanted = free_port();
|
||||
let mut link = AgentLink::new(Some(bad.path().to_path_buf()), "x");
|
||||
assert!(link.sync(Some(&on(u32::from(wanted))), &host).requests.is_none());
|
||||
assert!(matches!(link.status().problem, Some(LinkProblem::TokenFile(_))), "{:?}", link.status());
|
||||
assert!(!bad.path().join(CONNECTION_FILE).exists());
|
||||
TcpListener::bind(("127.0.0.1", wanted)).expect("nothing listens");
|
||||
let status = serde_json::to_value(link.status()).unwrap();
|
||||
assert!(status["error"].as_str().unwrap().starts_with("Agents can't connect: the token file"), "{status}");
|
||||
}
|
||||
|
||||
/// Dropping the link stops its server and removes its connection file.
|
||||
#[trial]
|
||||
fn dropping_the_link_removes_its_connection_file() {
|
||||
let dir = temp_dir("link-drop");
|
||||
let mut link = AgentLink::new(Some(dir.path().to_path_buf()), "x");
|
||||
assert!(link.sync(Some(&on(0)), &host()).requests.is_some());
|
||||
let port = link.status().port.expect("listening");
|
||||
drop(link);
|
||||
assert!(!dir.path().join(CONNECTION_FILE).exists());
|
||||
TcpListener::bind(("127.0.0.1", port)).expect("the port is free");
|
||||
}
|
||||
|
||||
/// A server the launch options started is reported with its port, and the settings change nothing.
|
||||
#[trial]
|
||||
fn from_launch_reports_the_launch_flags() {
|
||||
let (_requests, server) = server::listen(0, "0".repeat(64), host()).expect("started");
|
||||
let port = server.addr.port();
|
||||
let mut link = AgentLink::from_launch(server);
|
||||
assert_eq!((link.status().port, link.status().launch_flags), (Some(port), true));
|
||||
let update = link.sync(None, &host());
|
||||
assert!(!update.stopped && !update.changed && update.requests.is_none());
|
||||
assert_eq!(link.status().port, Some(port));
|
||||
assert_eq!(serde_json::to_value(link.status()).unwrap(), serde_json::json!({"port": port, "launchFlags": true, "error": null}));
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user