Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(spaces): every running Space of a signed-in computer shows on your account and phone (#6487)

ddupont1ca3a30cfebf
diff --git a/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
index c53bea3842..8348626104 100644
--- a/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
@@ -157,6 +157,7 @@ cua spaces create [OPTIONS] [IMAGE]
| <span id="cua-spaces-create--durable"></span>`--durable` | boolean | `false` | Keep it on your machines (with `--on auto`): when its machine goes away it is created again on another one, with the same name (its disk starts fresh). `cua spaces delete <name>` deletes it for good. |
| <span id="cua-spaces-create--children"></span>`--children` | boolean | `false` | Let it make child Spaces of its own: `cua`, the SDKs and the agent's tools in it create, list and delete Spaces that belong to it, on this computer, never wider than it (`cua spaces children`). Agent runs turn this on by themselves. |
| <span id="cua-spaces-create--forkable"></span>`--forkable` | boolean | `false` | A fork source (a "bake" Space): a local QEMU VM's guest RAM is a shared file, so `cua sb checkpoint` takes milliseconds and forks of its checkpoints share its pages. Other kinds ignore it. |
+| <span id="cua-spaces-create--no-relay"></span>`--no-relay` | boolean | `false` | Keep it off your cua.ai account. By default a Space running on a computer signed in and sharing is listed there, so your phone and your other computers see and open it (`cua config set relay.spaces off` turns that off for all of them). A child Space follows its parent. Same as `--label cua.relay=off`. |
| <span id="cua-spaces-create--widen"></span>`--widen` | boolean | `false` | With --parent: let its network be more open than its parent's (recorded on the Space). |
**Examples**
diff --git a/docs/content/docs/spaces/concepts/runtime-conformance.mdx b/docs/content/docs/spaces/concepts/runtime-conformance.mdx
index f1236df131..213e438ad9 100644
--- a/docs/content/docs/spaces/concepts/runtime-conformance.mdx
+++ b/docs/content/docs/spaces/concepts/runtime-conformance.mdx
@@ -37,6 +37,11 @@ does with them, and shows how Cua checks them.
ready answers with its own token and nothing else opens it, not even the
member's own secret, and it behaves as one that started cold. A runtime
that cannot claim a member refuses a pool in plain words and starts cold.
+- **A running Space is on your account.** While the computer is signed in
+ and sharing, the Space is listed on your cua.ai account, so your phone and
+ your other computers see and open it, and it leaves the account when it
+ stops or is deleted. This is the same for a macOS VM, a QEMU VM, a
+ container and a microVM, and it needs no step of yours.
- **Delete leaves nothing.** No Space, process, container or network remains.
A runtime that cannot keep a promise refuses it at once, in plain words that
diff --git a/docs/content/docs/spaces/guides/phone.mdx b/docs/content/docs/spaces/guides/phone.mdx
index e95061fe9c..97504a5554 100644
--- a/docs/content/docs/spaces/guides/phone.mdx
+++ b/docs/content/docs/spaces/guides/phone.mdx
@@ -40,6 +40,27 @@ if you last unlocked more than five minutes ago, so a stolen, unlocked phone is
not instant access. It is on by default; Settings, Privacy turns it off. A phone
with no passcode cannot be asked anything, and Settings says so.
+## Which Spaces it shows
+
+Every Space running on a computer that is signed in and sharing is on your
+account, so the phone lists it without a step from you, whichever way it was
+made: in the Mac app, with `cua spaces create`, from an SDK, by an agent or by
+a job. A new Space shows up a few seconds after it runs, and while you are
+creating many at once they are listed once you pause. A Space leaves the list when it stops or is deleted, and when you sign
+out of the computer. Only your account reaches them, and a Space you have not
+shared with anyone stays yours alone.
+
+To keep one Space off your account, make it with `--no-relay`
+(`cua spaces create --no-relay`); a child Space follows its parent. To keep all
+of them off, turn the setting off. `cua spaces ls` says which Spaces stay off.
+
+```bash test="cli-shape" id="relay-spaces-off"
+cua config set relay.spaces off
+```
+
+A Space you added by its address (`cua spaces add`) was not made by Cua and is
+never listed this way.
+
## What you can do
- Start a task: write the job, pick an agent and the computer it runs on, and
diff --git a/libs/cua/crates/cua-cli/src/host.rs b/libs/cua/crates/cua-cli/src/host.rs
index 0d8a57b7f6..54605652ba 100644
--- a/libs/cua/crates/cua-cli/src/host.rs
+++ b/libs/cua/crates/cua-cli/src/host.rs
@@ -496,6 +496,13 @@ Examples:
/// with `--durable`.
#[arg(long, value_name = "KEY=VALUE")]
label: Vec<String>,
+ /// Keep it off your cua.ai account. By default a Space running on a
+ /// computer signed in and sharing is listed there, so your phone and
+ /// your other computers see and open it (`cua config set
+ /// relay.spaces off` turns that off for all of them). A child Space
+ /// follows its parent. Same as `--label cua.relay=off`.
+ #[arg(long)]
+ no_relay: bool,
/// Its network: `internet` (the default: the internet and its own
/// tree; this computer, your local network, cloud metadata and other
/// trees are blocked), `none`, `localhost:5432,3000` (also this
@@ -1664,6 +1671,7 @@ pub async fn run_spaces_sdk(
region,
volumes,
label,
+ no_relay,
network,
egress_deny,
egress_allow,
@@ -1671,7 +1679,13 @@ pub async fn run_spaces_sdk(
widen,
} => {
let volumes = parse_volumes(&volumes)?;
- let labels = parse_labels(&label)?;
+ let mut labels = parse_labels(&label)?;
+ if no_relay {
+ labels.insert(
+ cua_spaces::registry::RELAY_LABEL.to_string(),
+ cua_spaces::registry::RelaySetting::Off.as_str().to_string(),
+ );
+ }
// One shape for the network: a preset and the lists.
let network_settings =
(network.is_some() || !egress_deny.is_empty() || !egress_allow.is_empty())
@@ -3959,10 +3973,14 @@ pub async fn run_spaces(
resources: &resources,
own_machine: spaces.this_relay_machine_id(),
};
+ let on_account = spaces.relay_states(&list);
if json {
let mut rows = ls_json(&list);
for (row, info) in rows.iter_mut().zip(&list) {
columns.annotate(info, row);
+ if let (Some(o), Some(state)) = (row.as_object_mut(), on_account.get(&info.id)) {
+ o.insert("relay".into(), (*state).into());
+ }
}
let mut body = serde_json::json!({ "spaces": rows, "machines": hosts, "durable": durable,
"relay_error": relay_error });
@@ -4006,6 +4024,20 @@ pub async fn run_spaces(
if let Some(e) = relay_error {
line(out, format!("(relay computers unavailable: {e})"));
}
+ let stay_off: Vec<&str> = list
+ .iter()
+ .filter(|i| on_account.get(&i.id) == Some(&"off"))
+ .map(|i| i.shown_name())
+ .collect();
+ if !stay_off.is_empty() {
+ line(
+ out,
+ format!(
+ "(not on your cua.ai account, so your phone does not list {}: --no-relay, or `cua config set relay.spaces off`)",
+ stay_off.join(", ")
+ ),
+ );
+ }
if let Some(w) = columns.warning() {
line(out, w);
}
@@ -4317,6 +4349,18 @@ mod tests {
assert!(parse_spaces(&["create", "linux", "--widen"]).is_err());
}
+ #[test]
+ fn no_relay_keeps_a_space_off_the_account() {
+ match parse_spaces(&["create", "linux", "--no-relay"]).unwrap() {
+ SpacesCmd::Create { no_relay, .. } => assert!(no_relay),
+ other => panic!("{other:?}"),
+ }
+ match parse_spaces(&["create", "linux"]).unwrap() {
+ SpacesCmd::Create { no_relay, .. } => assert!(!no_relay),
+ other => panic!("{other:?}"),
+ }
+ }
+
#[test]
fn label_flags_parse_filter_and_show() {
let words = |w: &[&str]| w.iter().map(|s| s.to_string()).collect::<Vec<_>>();
diff --git a/libs/cua/crates/cua-daemon/src/server.rs b/libs/cua/crates/cua-daemon/src/server.rs
index 90f0a3480e..e939b37df3 100644
--- a/libs/cua/crates/cua-daemon/src/server.rs
+++ b/libs/cua/crates/cua-daemon/src/server.rs
@@ -131,6 +131,17 @@ const IDLE_RUNTIME_CHECK: Duration = Duration::from_secs(300);
/// Space's settings.
#[cfg(feature = "spaces")]
const NETWORK_RECONCILE: Duration = Duration::from_secs(15);
+
+/// How often the Spaces listed on the account are looked at again without
+/// being woken.
+#[cfg(feature = "spaces")]
+const PUBLISH_TO_RELAY: Duration = Duration::from_secs(15);
+/// The next pass when the last one left Spaces waiting.
+#[cfg(feature = "spaces")]
+const PUBLISH_MORE: Duration = Duration::from_secs(4);
+/// Changes this close together are one pass.
+#[cfg(feature = "spaces")]
+const PUBLISH_COALESCE: Duration = Duration::from_secs(2);
/// First maintenance pass after start.
const MAINTENANCE_FIRST: Duration = Duration::from_secs(60);
/// How often the daemon checks that its home is still there.
@@ -778,6 +789,66 @@ pub async fn start(runtime: Runtime, config: ServerConfig) -> Result<DaemonHandl
}
}));
}
+ // Spaces running on this computer are listed on the signed-in account
+ // (the phone and the owner's other computers open them): a Space made
+ // by any path, one that was already here, and one that stopped or was
+ // deleted are kept in line with the relay (`relay.spaces`).
+ #[cfg(feature = "spaces")]
+ {
+ let rt = shared.runtime.clone();
+ let mut rx = shared.shutdown.subscribe();
+ tasks.push(tokio::spawn(async move {
+ // The first look comes after the daemon settled, at a different
+ // moment on every computer.
+ let mut wait = cua_spaces::share::jitter(Duration::from_secs(5));
+ let spaces = rt.spaces().clone();
+ loop {
+ let changed = tokio::select! {
+ _ = rx.changed() => return,
+ _ = tokio::time::sleep(wait) => false,
+ _ = cua_spaces::share::PUBLISH_CHANGED.notified() => true,
+ };
+ if changed {
+ // A burst of changes is one pass.
+ tokio::select! {
+ _ = rx.changed() => return,
+ _ = tokio::time::sleep(cua_spaces::share::jitter(PUBLISH_COALESCE)) => {}
+ }
+ }
+ // A shutdown never waits for a pass that is still working.
+ let pass = tokio::spawn({
+ let spaces = spaces.clone();
+ async move { spaces.publish_to_relay().await }
+ });
+ let more = tokio::select! {
+ _ = rx.changed() => {
+ return;
+ }
+ r = pass => match r {
+ Ok(Ok(r)) => {
+ if !r.published.is_empty() || !r.unpublished.is_empty() {
+ tracing::info!(
+ listed = r.published.len(),
+ taken_off = r.unpublished.len(),
+ "Spaces on the account updated"
+ );
+ }
+ r.more
+ }
+ Ok(Err(e)) => {
+ tracing::debug!(error = %e, "Spaces on the account not updated");
+ false
+ }
+ Err(_) => false,
+ },
+ };
+ // A pass with nothing to do asks the relay for nothing, so
+ // the interval is cheap; more waiting is picked up sooner.
+ wait =
+ cua_spaces::share::jitter(if more { PUBLISH_MORE } else { PUBLISH_TO_RELAY });
+ }
+ }));
+ }
// The automatic cloud sweep (`CUA_CLOUD_SWEEP_SECS`, 0: off).
#[cfg(feature = "byoc")]
tasks.extend(crate::cloud_sweep::spawn(
diff --git a/libs/cua/crates/cua-daemon/src/spaces_svc.rs b/libs/cua/crates/cua-daemon/src/spaces_svc.rs
index 89d99ee2b9..9b7726e35e 100644
--- a/libs/cua/crates/cua-daemon/src/spaces_svc.rs
+++ b/libs/cua/crates/cua-daemon/src/spaces_svc.rs
@@ -267,6 +267,8 @@ pub(crate) mod imp {
.map_err(|e| st(e.into()))?,
parent: opt(r.parent),
widen: r.widen,
+ // Opting out travels as the `cua.relay=off` label.
+ relay: None,
})
}
diff --git a/libs/cua/crates/cua-daemon/tests/relay_spaces.rs b/libs/cua/crates/cua-daemon/tests/relay_spaces.rs
new file mode 100644
index 0000000000..0bc6633fe7
--- /dev/null
+++ b/libs/cua/crates/cua-daemon/tests/relay_spaces.rs
@@ -0,0 +1,203 @@
+//! The daemon lists the Spaces running on this computer on the signed-in
+//! account's relay by itself: a Space created through the runtime shows on
+//! the relay without any call, leaves it when it stops or is deleted, and
+//! stays off when its owner opted out. The relay is the local fake relay, the
+//! Space's cua-spacesd a mock, the home a temp dir (never `~/.cua`).
+
+use async_trait::async_trait;
+use cua_daemon::server::{ServerConfig, start};
+use cua_daemon::{Runtime as DaemonRuntime, RuntimeConfig};
+use cua_host::testing::FakeRelay;
+use cua_sandbox_core::placement::On;
+use cua_sandbox_core::{
+ InstanceStatus, LocalEndpoints, LocalInstance, LocalRuntime, LocalStartSpec, LocalSummary,
+ RuntimeError,
+};
+use cua_spaces::{RelayAccount, SpaceCreate};
+use cua_spacesd_client::testing::{MockAuth, MockServer};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+struct Runtime {
+ port: u16,
+ stopped: Mutex<Vec<String>>,
+}
+
+impl Runtime {
+ fn instance(&self, name: &str, status: InstanceStatus) -> LocalInstance {
+ LocalInstance {
+ name: name.into(),
+ backend: "fake".into(),
+ status,
+ endpoints: LocalEndpoints {
+ host: "127.0.0.1".into(),
+ ports: [(3211u16, self.port)].into(),
+ ..Default::default()
+ },
+ }
+ }
+}
+
+#[async_trait]
+impl LocalRuntime for Runtime {
+ fn backend(&self) -> String {
+ "fake".into()
+ }
+ async fn start(&self, spec: &LocalStartSpec) -> Result<LocalInstance, RuntimeError> {
+ Ok(self.instance(&spec.name, InstanceStatus::Running))
+ }
+ fn power_control(&self, _: &str) -> Option<cua_sandbox_core::PowerControl> {
+ Some(cua_sandbox_core::PowerControl::Stop)
+ }
+ async fn stop(&self, name: &str) -> Result<(), RuntimeError> {
+ self.stopped.lock().unwrap().push(name.into());
+ Ok(())
+ }
+ async fn resume(&self, name: &str) -> Result<LocalInstance, RuntimeError> {
+ Ok(self.instance(name, InstanceStatus::Running))
+ }
+ async fn list(&self) -> Result<Vec<LocalSummary>, RuntimeError> {
+ Ok(vec![])
+ }
+ async fn status(&self, _: &str) -> Result<InstanceStatus, RuntimeError> {
+ Ok(InstanceStatus::Running)
+ }
+ async fn delete(&self, _: &str) -> Result<(), RuntimeError> {
+ Ok(())
+ }
+ async fn endpoints(&self, name: &str) -> Result<LocalEndpoints, RuntimeError> {
+ Ok(self.instance(name, InstanceStatus::Running).endpoints)
+ }
+}
+
+async fn until<T>(what: &str, mut f: impl AsyncFnMut() -> Option<T>) -> T {
+ let deadline = Instant::now() + Duration::from_secs(40);
+ loop {
+ if let Some(v) = f().await {
+ return v;
+ }
+ assert!(Instant::now() < deadline, "timed out: {what}");
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+}
+
+#[tokio::test]
+async fn the_daemon_lists_and_unlists_spaces_on_the_account() {
+ let home = tempfile::tempdir().unwrap();
+ // SAFETY: set before the runtime or any thread reads it.
+ unsafe { std::env::set_var("CUA_HOME", home.path()) };
+ let relay = FakeRelay::start().await;
+ relay.add_account("ada-token", "ada", Some("[email protected]"));
+ let driver = MockServer::start(MockAuth::default()).await;
+ driver.state.advertise(&["relay_attach"]);
+ let port: u16 = driver.url().rsplit(':').next().unwrap().parse().unwrap();
+ // The mock driver "dials the relay" when asked to attach.
+ {
+ let state = driver.state.clone();
+ let relay = relay.clone();
+ tokio::spawn(async move {
+ let mut last: Option<String> = None;
+ loop {
+ let now = state.relay_attached.lock().unwrap().clone();
+ match (now, &last) {
+ (Some(a), _) => {
+ relay.set_online(&a.machine_id, true, "0.1.0");
+ last = Some(a.machine_id);
+ }
+ (None, Some(m)) => {
+ relay.set_online(m, false, "0.1.0");
+ last = None;
+ }
+ _ => {}
+ }
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ });
+ }
+ let rt = Arc::new(Runtime {
+ port,
+ stopped: Mutex::default(),
+ });
+ let runtime = DaemonRuntime::new(RuntimeConfig {
+ state_dir: Some(home.path().join("sandboxes")),
+ spaces_home: Some(home.path().to_path_buf()),
+ local: Some(rt.clone()),
+ ..Default::default()
+ })
+ .unwrap();
+ let spaces = runtime.spaces().clone();
+ spaces.set_relay(Some(RelayAccount::new(
+ &relay.url,
+ Arc::new(cua_host::StaticToken("ada-token".into())),
+ )));
+ let handle = start(
+ runtime,
+ ServerConfig {
+ socket_path: None,
+ loopback: Some(([127, 0, 0, 1], 0).into()),
+ token: "owner".into(),
+ discovery_path: None,
+ bridge_ticket_ttl: Duration::from_secs(60),
+ },
+ )
+ .await
+ .unwrap();
+
+ let client = cua_host::RelayClient::new(&relay.url).unwrap();
+ let rows = || async {
+ client
+ .machines("ada-token")
+ .await
+ .unwrap()
+ .into_iter()
+ .filter(|m| m.id.starts_with("space-"))
+ .collect::<Vec<_>>()
+ };
+ let make = |name: &str, relay: Option<bool>| {
+ let spaces = spaces.clone();
+ let opts = SpaceCreate {
+ on: Some(On::Local),
+ image: Some("linux".into()),
+ name: Some(name.into()),
+ timeout: Some(Duration::from_secs(30)),
+ relay,
+ ..Default::default()
+ };
+ async move { spaces.create(opts).await.unwrap().ready().unwrap().id }
+ };
+
+ // Created: on the account within moments, with nobody calling anything.
+ let id = make("phone-visible", None).await;
+ until("the Space is on the relay", async || {
+ (rows().await.len() == 1).then_some(())
+ })
+ .await;
+ assert!(rows().await[0].online);
+
+ // Opted out: never listed.
+ make("private", Some(false)).await;
+ tokio::time::sleep(Duration::from_secs(2)).await;
+ assert_eq!(rows().await.len(), 1);
+
+ // Stopped: it leaves the account.
+ spaces.stop(&id).await.unwrap();
+ until("the stopped Space left the relay", async || {
+ rows().await.is_empty().then_some(())
+ })
+ .await;
+
+ // Started again: back.
+ spaces.start(&id).await.unwrap();
+ until("the started Space is back", async || {
+ (rows().await.len() == 1).then_some(())
+ })
+ .await;
+
+ // Deleted: gone.
+ spaces.delete(&id).await.unwrap();
+ until("the deleted Space left the relay", async || {
+ rows().await.is_empty().then_some(())
+ })
+ .await;
+ handle.shutdown();
+}
diff --git a/libs/cua/crates/cua-host/src/testing.rs b/libs/cua/crates/cua-host/src/testing.rs
index 4f5bba3521..f7c33213e5 100644
--- a/libs/cua/crates/cua-host/src/testing.rs
+++ b/libs/cua/crates/cua-host/src/testing.rs
@@ -235,6 +235,34 @@ pub struct FakeRelay {
/// `http://127.0.0.1:<port>`.
pub url: String,
state: Arc<Mutex<State_>>,
+ load: Arc<Load>,
+}
+
+/// What the fake relay was asked, for tests of how much a client costs it.
+#[derive(Default)]
+struct Load {
+ requests: std::sync::atomic::AtomicUsize,
+ in_flight: std::sync::atomic::AtomicUsize,
+ peak: std::sync::atomic::AtomicUsize,
+ delay_ms: std::sync::atomic::AtomicU64,
+}
+
+async fn count_load(
+ State(load): State<Arc<Load>>,
+ req: axum::extract::Request,
+ next: axum::middleware::Next,
+) -> Response {
+ use std::sync::atomic::Ordering::SeqCst;
+ load.requests.fetch_add(1, SeqCst);
+ let now = load.in_flight.fetch_add(1, SeqCst) + 1;
+ load.peak.fetch_max(now, SeqCst);
+ let delay = load.delay_ms.load(SeqCst);
+ if delay > 0 {
+ tokio::time::sleep(std::time::Duration::from_millis(delay)).await;
+ }
+ let r = next.run(req).await;
+ load.in_flight.fetch_sub(1, SeqCst);
+ r
}
fn err(status: StatusCode, message: &str) -> Response {
@@ -1211,6 +1239,7 @@ impl FakeRelay {
/// Starts on loopback `port` (0 = ephemeral).
pub async fn start_on(port: u16) -> Self {
let state: S = Arc::default();
+ let load: Arc<Load> = Arc::default();
let app = Router::new()
.route(
"/v1/info",
@@ -1250,7 +1279,11 @@ impl FakeRelay {
axum::routing::delete(pairing_revoke),
)
.fallback(proxied)
- .with_state(state.clone());
+ .with_state(state.clone())
+ .layer(axum::middleware::from_fn_with_state(
+ load.clone(),
+ count_load,
+ ));
let listener = tokio::net::TcpListener::bind(("127.0.0.1", port))
.await
.expect("bind fake relay");
@@ -1259,7 +1292,32 @@ impl FakeRelay {
tokio::spawn(async move {
let _ = axum::serve(listener, app).await;
});
- Self { url, state }
+ Self { url, state, load }
+ }
+
+ /// HTTP requests answered so far.
+ pub fn requests(&self) -> usize {
+ self.load.requests.load(std::sync::atomic::Ordering::SeqCst)
+ }
+
+ /// The most requests that were in flight at once since the last
+ /// [`Self::reset_load`].
+ pub fn peak_in_flight(&self) -> usize {
+ self.load.peak.load(std::sync::atomic::Ordering::SeqCst)
+ }
+
+ /// Zeroes [`Self::requests`] and [`Self::peak_in_flight`].
+ pub fn reset_load(&self) {
+ use std::sync::atomic::Ordering::SeqCst;
+ self.load.requests.store(0, SeqCst);
+ self.load.peak.store(0, SeqCst);
+ }
+
+ /// Every request takes `ms` more (a slow relay), 0 for none.
+ pub fn set_latency_ms(&self, ms: u64) {
+ self.load
+ .delay_ms
+ .store(ms, std::sync::atomic::Ordering::SeqCst);
}
/// Accepts `token` as the account `id` (with `email`).
diff --git a/libs/cua/crates/cua-sandbox-core/src/settings.rs b/libs/cua/crates/cua-sandbox-core/src/settings.rs
index 441c73070c..93061ff2bd 100644
--- a/libs/cua/crates/cua-sandbox-core/src/settings.rs
+++ b/libs/cua/crates/cua-sandbox-core/src/settings.rs
@@ -35,7 +35,7 @@ pub struct Key {
}
/// Every setting, in display order.
-pub const KEYS: [Key; 19] = [
+pub const KEYS: [Key; 20] = [
Key {
name: "default.on",
env: "CUA_DEFAULT_ON",
@@ -120,6 +120,12 @@ pub const KEYS: [Key; 19] = [
default: "on",
description: "when no location is given and a linked cloud has a budget (`cua cloud budget`), Spaces go to this machine first and overflow into your clouds when it is full, never past the budget (off: this machine only)",
},
+ Key {
+ name: "relay.spaces",
+ env: "CUA_RELAY_SPACES",
+ default: "on",
+ description: "while you are signed in and sharing, list the Spaces running on this computer on your cua.ai account, so your phone and your other computers see and open them (on, off). Only your account reaches them; off takes them off the account at once. A Space can opt out on its own (`--no-relay`)",
+ },
Key {
name: "cache.repos",
env: "CUA_CACHE_REPOS",
@@ -529,6 +535,20 @@ impl Settings {
.unwrap_or(true)
}
+ /// Whether this computer's running Spaces are listed on the signed-in
+ /// account's relay (`relay.spaces`, default on).
+ pub fn relay_spaces(&self) -> bool {
+ key("relay.spaces")
+ .map(|k| self.entry(k).value)
+ .map(|v| {
+ !matches!(
+ v.trim().to_ascii_lowercase().as_str(),
+ "off" | "false" | "0" | "no"
+ )
+ })
+ .unwrap_or(true)
+ }
+
/// The repo cache's settings: whether it is on (`cache.repos`, default
/// on) and its size cap in bytes (`cache.repos_size_gb`; `None`: auto).
pub fn repo_cache(&self) -> (bool, Option<u64>) {
@@ -598,6 +618,15 @@ pub fn normalize(key: Key, value: &str) -> Result<String, SettingsError> {
)));
}
},
+ "relay.spaces" => match v.to_ascii_lowercase().as_str() {
+ "1" | "true" | "yes" | "on" => "on".into(),
+ "0" | "false" | "no" | "off" => "off".into(),
+ _ => {
+ return Err(SettingsError(format!(
+ "relay.spaces: expected on or off, got {v:?}"
+ )));
+ }
+ },
"cache.repos" => match v.to_ascii_lowercase().as_str() {
"1" | "true" | "yes" | "on" => "on".into(),
"0" | "false" | "no" | "off" => "off".into(),
diff --git a/libs/cua/crates/cua-sdk/src/native/spaces.rs b/libs/cua/crates/cua-sdk/src/native/spaces.rs
index 69b2575c1e..59f821a069 100644
--- a/libs/cua/crates/cua-sdk/src/native/spaces.rs
+++ b/libs/cua/crates/cua-sdk/src/native/spaces.rs
@@ -4105,6 +4105,7 @@ impl Spaces {
instance_type: text(&options.instance_type),
region: text(&options.region),
tree: None,
+ relay: None,
})
.await?;
if options.children == Some(true)
diff --git a/libs/cua/crates/cua-spaces/src/registry.rs b/libs/cua/crates/cua-spaces/src/registry.rs
index 46e0c944e5..3682ebce15 100644
--- a/libs/cua/crates/cua-spaces/src/registry.rs
+++ b/libs/cua/crates/cua-spaces/src/registry.rs
@@ -125,6 +125,11 @@ pub struct SpaceMeta {
skip_serializing_if = "crate::clipboard::ClipboardSetting::is_default"
)]
pub clipboard: crate::clipboard::ClipboardSetting,
+ /// Whether the Space is listed on the owner's account while the
+ /// computer is signed in and sharing ([`RelaySetting`]). A child
+ /// follows its parent's `off`.
+ #[serde(default, skip_serializing_if = "RelaySetting::is_on")]
+ pub relay: RelaySetting,
}
impl SpaceMeta {
@@ -181,6 +186,45 @@ impl VolumeSetting {
}
}
+/// The label that keeps a Space off the owner's account at create
+/// (`cua.relay=off`; `--no-relay`).
+pub const RELAY_LABEL: &str = "cua.relay";
+
+/// Whether a Space is listed on the owner's cua.ai account (the phone and
+/// the owner's other computers see and open it).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RelaySetting {
+ /// Listed while the computer is signed in and sharing. The default.
+ #[default]
+ On,
+ /// Never listed: it stays on this computer.
+ Off,
+}
+
+impl RelaySetting {
+ pub fn is_on(&self) -> bool {
+ *self == RelaySetting::On
+ }
+
+ /// `on` or `off`.
+ pub fn as_str(self) -> &'static str {
+ match self {
+ RelaySetting::On => "on",
+ RelaySetting::Off => "off",
+ }
+ }
+
+ /// Parses `on` / `off`.
+ pub fn parse(s: &str) -> Result<Self> {
+ match s.trim().to_ascii_lowercase().as_str() {
+ "on" | "true" | "yes" => Ok(RelaySetting::On),
+ "off" | "false" | "no" => Ok(RelaySetting::Off),
+ other => Err(Error::invalid(format!("relay {other:?}: use on or off"))),
+ }
+ }
+}
+
fn is_false(b: &bool) -> bool {
!*b
}
diff --git a/libs/cua/crates/cua-spaces/src/share.rs b/libs/cua/crates/cua-spaces/src/share.rs
index fde9e48445..07e6883e45 100644
--- a/libs/cua/crates/cua-spaces/src/share.rs
+++ b/libs/cua/crates/cua-spaces/src/share.rs
@@ -152,8 +152,18 @@ pub struct ShareAudit {
struct Attached {
/// The relay machine id of an attached (non-host) Space.
machine: String,
+ /// Listed on the relay by Cua itself ([`publish`]), not by hand: Cua
+ /// also takes it off again.
+ #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+ auto: bool,
+ /// The account (its id) that listed it, for an automatic one.
+ #[serde(default, skip_serializing_if = "String::is_empty")]
+ account: String,
}
+mod publish;
+pub use publish::{CHANGED as PUBLISH_CHANGED, Off, PublishReport, breaker_wait, jitter};
+
/// Normalizes an invitee: an email (lowercased) or an account id. Teams and
/// organizations are not relay principals, so `team:` / `org:` entries are
/// refused with the reason.
@@ -367,6 +377,26 @@ impl Spaces {
.collect()
}
+ /// The relay machines Cua listed itself for Spaces on this computer
+ /// ([`publish`]): the Space is listed once, as the local one.
+ pub(crate) fn auto_published_machines(&self) -> std::collections::HashSet<String> {
+ self.attached()
+ .into_values()
+ .filter(|a| a.auto)
+ .map(|a| a.machine)
+ .collect()
+ }
+
+ /// Changes the attached Spaces under a lock, so Spaces attached side by
+ /// side do not overwrite each other.
+ fn update_attached(&self, f: impl FnOnce(&mut BTreeMap<String, Attached>)) -> Result<()> {
+ static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+ let _guard = LOCK.lock().unwrap_or_else(|e| e.into_inner());
+ let mut all = self.attached();
+ f(&mut all);
+ self.save_attached(&all)
+ }
+
fn save_attached(&self, all: &BTreeMap<String, Attached>) -> Result<()> {
let path = self.shares_path();
cua_home::guard_write(&path)?;
@@ -512,6 +542,14 @@ impl Spaces {
/// Space's driver is attached (registered on first share, re-attached
/// after the Space restarted).
async fn ensure_shared_machine(&self, space: &str) -> Result<String> {
+ self.ensure_shared_machine_with(space, true).await
+ }
+
+ /// [`Self::ensure_shared_machine`]; with `wait` false it asks the relay
+ /// for nothing it does not need: no read of the machine first (the caller
+ /// has the directory) and no polling until the driver is online (the
+ /// next pass sees it), so one Space costs the relay one registration.
+ async fn ensure_shared_machine_with(&self, space: &str, wait: bool) -> Result<String> {
let id = self.resolve(space)?;
let canonical = id.to_string();
let relay = self.relay()?;
@@ -528,12 +566,13 @@ impl Spaces {
}
let s = self.space(&canonical).await?;
s.require(RELAY_ATTACH_FEATURE)?;
- let mut all = self.attached();
+ let all = self.attached();
let machine = match all.get(&canonical) {
Some(a) => a.machine.clone(),
None => format!("space-{:016x}", rand::random::<u64>()),
};
- if let Ok(m) = client.machine(&token, &machine).await
+ if wait
+ && let Ok(m) = client.machine(&token, &machine).await
&& m.online
&& m.role == "owner"
{
@@ -581,17 +620,15 @@ impl Spaces {
})
.await
.map_err(|e| Error::Env(cua_spacesd_client::Error::from(e)))?;
- all.insert(
- canonical.clone(),
- Attached {
- machine: machine.clone(),
- },
- );
- self.save_attached(&all)?;
+ // Re-read under the lock: Spaces attach side by side, and a Space
+ // listed before keeps what was recorded about it.
+ self.update_attached(|all| {
+ all.entry(canonical.clone()).or_default().machine = machine.clone();
+ })?;
self.audit_share("attach", &canonical, &format!("machine={machine}"));
// The driver dials out on its own: wait (bounded) until the relay
// lists it online.
- for _ in 0..100 {
+ for _ in 0..if wait { 100 } else { 0 } {
if client
.machine(&token, &machine)
.await
diff --git a/libs/cua/crates/cua-spaces/src/share/publish.rs b/libs/cua/crates/cua-spaces/src/share/publish.rs
new file mode 100644
index 0000000000..55f46fec7a
--- /dev/null
+++ b/libs/cua/crates/cua-spaces/src/share/publish.rs
@@ -0,0 +1,800 @@
+//! Spaces of this computer on the owner's account: while the computer is
+//! signed in and sharing, every running local Space with a working
+//! cua-spacesd is registered on the relay (the same owner-only
+//! [`Spaces::relay_register`] a person can run by hand), so the phone and the
+//! owner's other computers list and open it with no extra step. One pass
+//! ([`Spaces::publish_to_relay`]) is the whole rule, and the daemon runs it
+//! whenever a Space is created, started, stopped, changed or deleted and every
+//! few seconds besides, so it covers a Space made by any path (the app, `cua`,
+//! an SDK, MCP, an agent's child, a compat layer) and the Spaces that were
+//! already here when this release arrived.
+//!
+//! - **Listed**: a `local:` Space that is running, whose cua-spacesd can join
+//! the relay, that has not opted out (`--no-relay`; a child follows its
+//! parent) and whose network lets it reach the relay.
+//! - **Not listed**: Spaces added by address (not made by Cua), Spaces a
+//! computer provides (already on the relay under their host), Spaces in the
+//! owner's cloud, and everything while `relay.spaces` / `CUA_RELAY_SPACES`
+//! is off or the host stopped sharing.
+//! - **Taken off** again: when the Space stops, is deleted (`delete` already
+//! does), opts out, or the switch goes off; when the owner signs out the
+//! Space's driver leaves the relay at once (no account, no calls), and the
+//! next sign-in lists it again. A Space the owner shared with other people
+//! stays as shared.
+//!
+//! Nothing new is stored: the machine token the relay mints stays inside the
+//! Space's driver, as for any registered Space, and the row is the owner's
+//! alone until they share it.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::PathBuf;
+use std::sync::{Arc, LazyLock, Mutex};
+use std::time::{Duration, Instant};
+
+use crate::{Result, SpaceId, Spaces};
+
+/// Woken when something that decides what is listed changed (a Space was
+/// created, started, stopped, deleted or opted out), so the daemon's loop
+/// runs a pass now instead of at its next tick.
+pub static CHANGED: tokio::sync::Notify = tokio::sync::Notify::const_new();
+
+/// How long a Space that could not be listed is left alone.
+const RETRY_AFTER: Duration = Duration::from_secs(60);
+/// Calls to the relay in flight at once.
+const AT_ONCE: usize = 4;
+/// Most registrations and removals one pass starts; the rest wait for the
+/// next pass ([`PublishReport::more`]).
+const PER_PASS: usize = 24;
+/// A Space younger than this is not listed yet, so one made and deleted
+/// within moments (a job, a test, a burst of throwaway Spaces) never reaches
+/// the relay.
+const SETTLE: Duration = Duration::from_secs(5);
+/// While Spaces are being made (the newest is younger than this), the pass
+/// leaves the relay alone, so a burst of creates has the machine to itself;
+/// it goes on after this much quiet, or once a Space has waited
+/// [`BUSY_LIMIT`].
+const BUSY: Duration = Duration::from_secs(3);
+/// The longest a Space waits for a burst of creates to end.
+const BUSY_LIMIT: Duration = Duration::from_secs(60);
+/// How long a registered Space is given to dial the relay before it is
+/// registered again.
+const DIAL_GRACE: Duration = Duration::from_secs(90);
+/// When nothing changed here, the relay is asked once in this long (plus up
+/// to a fifth) whether every listed Space is still online.
+const VERIFY_EVERY: Duration = Duration::from_secs(300);
+/// Longest pause after the relay failed.
+const BREAKER_MAX: Duration = Duration::from_secs(300);
+
+/// The relay failed: no calls until `open_until`, longer each time in a row.
+#[derive(Default)]
+struct Breaker {
+ fails: u32,
+ open_until: Option<Instant>,
+}
+
+/// `+-20%` so many computers do not move together.
+pub fn jitter(d: Duration) -> Duration {
+ d.mul_f64(0.8 + rand::random::<f64>() * 0.4)
+}
+
+/// How long to stop calling the relay after its `fails`th failure in a row:
+/// 5 s doubling to 5 min, with jitter, and never less than the relay's own
+/// `Retry-After`.
+pub fn breaker_wait(fails: u32, retry_after: Option<Duration>) -> Duration {
+ let base = Duration::from_secs(5)
+ .saturating_mul(1u32 << fails.saturating_sub(1).min(6))
+ .min(BREAKER_MAX);
+ jitter(base).max(retry_after.unwrap_or_default().min(BREAKER_MAX))
+}
+
+/// The wait the relay asked for in an error, and whether the error is the
+/// relay failing (so calls pause) rather than a Space being refused.
+fn relay_trouble(e: &crate::Error) -> Option<Option<Duration>> {
+ match e {
+ crate::Error::Relay(h) if h.is_transient() => Some(match h {
+ cua_host::Error::Throttled { retry_after_secs } => {
+ Some(Duration::from_secs(*retry_after_secs))
+ }
+ _ => None,
+ }),
+ _ => None,
+ }
+}
+
+struct Memo {
+ /// Spaces not tried again before this time.
+ retry_at: BTreeMap<String, Instant>,
+ /// Spaces whose driver already left the relay for want of an account.
+ left: BTreeSet<String>,
+ /// The Spaces that were to be listed when the last pass finished
+ /// without trouble; `None` while the last pass left work.
+ settled: Option<BTreeSet<String>>,
+ /// Registered Spaces that have until then to dial the relay.
+ dialing: BTreeMap<String, Instant>,
+ /// When the relay is asked next even if nothing changed.
+ verify_at: Instant,
+ breaker: Breaker,
+}
+
+impl Default for Memo {
+ fn default() -> Self {
+ Memo {
+ retry_at: Default::default(),
+ left: Default::default(),
+ settled: None,
+ dialing: Default::default(),
+ verify_at: Instant::now(),
+ breaker: Default::default(),
+ }
+ }
+}
+
+static MEMO: LazyLock<Mutex<BTreeMap<PathBuf, Memo>>> = LazyLock::new(Default::default);
+
+fn memo<T>(home: &std::path::Path, f: impl FnOnce(&mut Memo) -> T) -> T {
+ let mut all = MEMO.lock().unwrap_or_else(|e| e.into_inner());
+ f(all.entry(home.to_path_buf()).or_default())
+}
+
+/// What one pass did.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct PublishReport {
+ /// Spaces listed on the relay by this pass.
+ pub published: Vec<String>,
+ /// Spaces taken off the relay by this pass.
+ pub unpublished: Vec<String>,
+ /// Spaces that could not be listed now, with why (tried again later).
+ pub failed: Vec<(String, String)>,
+ /// More is waiting (the per-pass limit, or Spaces too new to list):
+ /// run the next pass soon, not at the usual interval.
+ pub more: bool,
+}
+
+/// Why nothing is listed now, or `None` when Spaces may be.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Off {
+ /// No relay account is configured.
+ NoAccount,
+ /// Nobody is signed in.
+ SignedOut,
+ /// `relay.spaces` / `CUA_RELAY_SPACES` is off.
+ Setting,
+ /// This computer stopped sharing (`cua host stop`, or paused signed out).
+ NotSharing,
+}
+
+impl Spaces {
+ fn relay_spaces_setting(&self) -> bool {
+ cua_sandbox_core::settings::Settings::load_with(self.home_dir().join("config.toml"), |k| {
+ std::env::var(k).ok()
+ })
+ .map(|s| s.relay_spaces())
+ .unwrap_or(true)
+ }
+
+ /// Whether this computer lists its Spaces on the account now, or why not.
+ pub async fn relay_publishing(&self) -> std::result::Result<(), Off> {
+ let Some(account) = self.relay_account() else {
+ return Err(Off::NoAccount);
+ };
+ if !self.relay_spaces_setting() {
+ return Err(Off::Setting);
+ }
+ // A computer set up to share that stopped (or paused until the owner
+ // signs in again) lists nothing; one never set up lists its Spaces
+ // once signed in.
+ if let Ok(Some(c)) = cua_host::Host::new(self.home_dir()).config()
+ && (!c.sharing || c.paused_signed_out)
+ {
+ return Err(Off::NotSharing);
+ }
+ if !account.tokens.signed_in().await {
+ return Err(Off::SignedOut);
+ }
+ Ok(())
+ }
+
+ /// The Spaces another of the owner's computers asked this one to make:
+ /// each is on the relay already, under this computer.
+ fn provided_here(&self) -> BTreeSet<String> {
+ cua_host::provided::load_provided(&cua_host::Host::new(self.home_dir()).paths().dir)
+ .unwrap_or_default()
+ .into_iter()
+ .map(|p| p.local_space)
+ .collect()
+ }
+
+ /// Whether the local Space `info` is on, as the runtime last recorded it
+ /// (any kind: a macOS VM, a QEMU VM, a container, a microVM). A Space
+ /// whose state is not recorded is neither on nor off.
+ fn recorded_running(&self, info: &crate::SpaceInfo) -> bool {
+ matches!(
+ SpaceId::parse(&info.id),
+ Ok(SpaceId::Local { name })
+ if self.inner.sandboxes.power_state(&name) == Some(cua_sandbox_core::PowerState::Running)
+ )
+ }
+
+ fn is_off(&self, info: &crate::SpaceInfo) -> bool {
+ matches!(
+ SpaceId::parse(&info.id),
+ Ok(SpaceId::Local { name })
+ if matches!(
+ self.inner.sandboxes.power_state(&name),
+ Some(cua_sandbox_core::PowerState::Stopped | cua_sandbox_core::PowerState::Suspended)
+ )
+ )
+ }
+
+ /// Whether `info` (a running local Space) is one to list: it can join
+ /// the relay and its network lets it reach it.
+ fn listable(
+ &self,
+ info: &crate::SpaceInfo,
+ meta: &BTreeMap<String, crate::registry::SpaceMeta>,
+ ) -> bool {
+ self.recorded_running(info) && self.listable_ignoring_state(info, meta)
+ }
+
+ /// [`Self::listable`] without the running state (a stopped Space that
+ /// could be listed is still taken off).
+ fn listable_ignoring_state(
+ &self,
+ info: &crate::SpaceInfo,
+ meta: &BTreeMap<String, crate::registry::SpaceMeta>,
+ ) -> bool {
+ if !info.id.starts_with("local:") {
+ return false;
+ }
+ if !info
+ .features
+ .iter()
+ .any(|f| f == super::RELAY_ATTACH_FEATURE)
+ {
+ return false;
+ }
+ // Opted out itself or through a parent.
+ let mut at = Some(info.id.clone());
+ let mut seen = BTreeSet::new();
+ while let Some(id) = at {
+ if !seen.insert(id.clone()) {
+ break;
+ }
+ let m = meta.get(&id);
+ if m.is_some_and(|m| {
+ !m.relay.is_on()
+ || m.labels.get(crate::registry::RELAY_LABEL).is_some_and(|v| {
+ crate::registry::RelaySetting::parse(v).is_ok_and(|s| !s.is_on())
+ })
+ }) {
+ return false;
+ }
+ at = m.and_then(|m| m.parent.clone());
+ }
+ // The Space dials the relay itself: with no network it never reaches
+ // it (`custom` starts from `internet` or `none`).
+ use cua_vmm::network::NetworkPreset as P;
+ let no_network = meta
+ .get(&info.id)
+ .and_then(|m| m.network.as_ref())
+ .is_some_and(|n| {
+ n.preset == P::None || (n.preset == P::Custom && n.custom_base == P::None)
+ });
+ !no_network
+ }
+
+ /// Where each local Space of `infos` stands on the account: `on` (listed
+ /// there now) or `off` (it stays off: `--no-relay`, a parent's `off`, or
+ /// `relay.spaces` off). A Space not in the map is neither (not running,
+ /// or not one this computer lists); `cua spaces ls` shows it.
+ pub fn relay_states(&self, infos: &[crate::SpaceInfo]) -> BTreeMap<String, &'static str> {
+ let meta = self.inner.registry.all_meta();
+ let setting = self.relay_spaces_setting();
+ let attached = self.attached();
+ let mut out = BTreeMap::new();
+ let provided = self.provided_here();
+ for info in infos
+ .iter()
+ .filter(|i| i.id.starts_with("local:") && !provided.contains(&i.id))
+ {
+ let mut able = info.clone();
+ able.features = vec![super::RELAY_ATTACH_FEATURE.into()];
+ if !setting || !self.listable_ignoring_state(&able, &meta) {
+ out.insert(info.id.clone(), "off");
+ } else if attached.get(&info.id).is_some_and(|a| a.auto) {
+ out.insert(info.id.clone(), "on");
+ }
+ }
+ out
+ }
+
+ /// One pass: lists what should be listed and takes off what should not.
+ /// Built for a relay that is shared by many computers:
+ ///
+ /// - Nothing that changed here means no call at all (the relay is asked
+ /// once in five minutes, with jitter, whether the listed Spaces are
+ /// still online).
+ /// - A pass reads the relay's directory once, then registers or removes
+ /// at most [`PER_PASS`] Spaces, [`AT_ONCE`] at a time, without waiting
+ /// for any of them to come online; the rest wait for the next pass.
+ /// - A Space younger than [`SETTLE`] is not listed yet, so one made and
+ /// deleted within moments never reaches the relay.
+ /// - When the relay fails (429, 5xx, not reached) calls stop for a
+ /// growing, jittered time that is never shorter than its `Retry-After`;
+ /// Spaces keep being made here meanwhile.
+ pub async fn publish_to_relay(&self) -> Result<PublishReport> {
+ let mut report = PublishReport::default();
+ let home = self.home_dir().to_path_buf();
+ let gate = self.relay_publishing().await;
+ let all = self.attached();
+ let auto: Vec<String> = all
+ .iter()
+ .filter(|(_, a)| a.auto)
+ .map(|(s, _)| s.clone())
+ .collect();
+
+ // Not publishing now: what this pass listed leaves.
+ if let Err(off) = gate {
+ if auto.is_empty() {
+ return Ok(report);
+ }
+ if off == Off::SignedOut || off == Off::NoAccount {
+ // No account to call the relay with: the driver stops
+ // dialing, and the next sign-in lists the Space again.
+ for space in auto {
+ if memo(&home, |m| m.left.insert(space.clone())) {
+ self.detach_attached_space(&space).await;
+ }
+ }
+ memo(&home, |m| {
+ m.settled = None;
+ m.dialing.clear();
+ });
+ return Ok(report);
+ }
+ if memo(&home, |m| {
+ m.breaker.open_until.is_some_and(|t| t > Instant::now())
+ }) {
+ return Ok(report);
+ }
+ let rows = self.owner_rows().await;
+ let rows = match rows {
+ Ok(r) => r,
+ Err(e) => {
+ self.relay_failed(&home, &e);
+ return Ok(report);
+ }
+ };
+ let removals = self.remove_all(&auto, &rows, &mut report).await;
+ report.more = removals;
+ memo(&home, |m| m.settled = None);
+ return Ok(report);
+ }
+ memo(&home, |m| m.left.clear());
+
+ // The relay failed lately: no calls yet.
+ if memo(&home, |m| {
+ m.breaker.open_until.is_some_and(|t| t > Instant::now())
+ }) {
+ return Ok(report);
+ }
+
+ let infos = self.list()?;
+ let meta = self.inner.registry.all_meta();
+ let provided = self.provided_here();
+ let now_unix = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0, |d| d.as_secs());
+ let mut young = false;
+ let want: Vec<&crate::SpaceInfo> = infos
+ .iter()
+ .filter(|i| !provided.contains(&i.id) && self.listable(i, &meta))
+ .filter(|i| {
+ let born = meta.get(&i.id).map_or(0, |m| m.created_at_unix);
+ let settled = born == 0 || now_unix.saturating_sub(born) >= SETTLE.as_secs();
+ young |= !settled;
+ settled
+ })
+ .collect();
+ let wanted: BTreeSet<String> = want.iter().map(|i| i.id.clone()).collect();
+
+ // Spaces are being made right now: listing them waits for a gap (but
+ // not for more than a minute).
+ let newest = meta
+ .iter()
+ .filter(|(id, _)| id.starts_with("local:"))
+ .map(|(_, m)| m.created_at_unix)
+ .max()
+ .unwrap_or(0);
+ let waited_long = want.iter().any(|i| {
+ let born = meta.get(&i.id).map_or(0, |m| m.created_at_unix);
+ !all.contains_key(&i.id)
+ && born != 0
+ && now_unix.saturating_sub(born) >= BUSY_LIMIT.as_secs()
+ });
+ if newest != 0
+ && now_unix.saturating_sub(newest) < BUSY.as_secs()
+ && !waited_long
+ && !wanted.is_empty()
+ {
+ report.more = true;
+ return Ok(report);
+ }
+
+ // Nothing listed and nothing to list: no call.
+ if wanted.is_empty() && auto.is_empty() {
+ memo(&home, |m| {
+ m.settled = (!young).then(|| wanted.clone());
+ m.verify_at = Instant::now() + jitter(VERIFY_EVERY);
+ });
+ report.more = young;
+ return Ok(report);
+ }
+
+ // Nothing changed since a pass that finished: no call.
+ let unchanged = memo(&home, |m| {
+ m.settled.as_ref() == Some(&wanted) && Instant::now() < m.verify_at
+ });
+ if unchanged && !young {
+ return Ok(report);
+ }
+
+ // The account may have changed since a Space was listed: its row
+ // belongs to the other account, so it is listed again as new.
+ let account = self.relay()?;
+ let subject = account.account_subject().await.unwrap_or_default();
+ for space in &auto {
+ let owner = all
+ .get(space)
+ .map(|a| a.account.clone())
+ .unwrap_or_default();
+ if !subject.is_empty() && !owner.is_empty() && owner != subject {
+ self.detach_attached_space(space).await;
+ let _ = self.update_attached(|now| {
+ now.remove(space);
+ });
+ }
+ }
+ let all = self.attached();
+
+ // One read of the directory serves the whole pass.
+ let rows = match self.owner_rows().await {
+ Ok(r) => r,
+ Err(e) => {
+ self.relay_failed(&home, &e);
+ report.failed.push((String::new(), e.to_string()));
+ return Ok(report);
+ }
+ };
+
+ // Off: automatically listed Spaces that stopped, opted out or went.
+ let mut leaving = Vec::new();
+ for space in all.iter().filter(|(_, a)| a.auto).map(|(s, _)| s) {
+ if wanted.contains(space) {
+ continue;
+ }
+ // A Space whose state is not known now is left as it is; one
+ // that is gone, stopped or opted out leaves.
+ let gone = match infos.iter().find(|i| &i.id == space) {
+ None => true,
+ Some(i) => {
+ self.is_off(i)
+ || !meta.get(space).is_none_or(|m| m.relay.is_on())
+ || !self.listable_ignoring_state(i, &meta)
+ }
+ };
+ if gone {
+ leaving.push(space.clone());
+ }
+ }
+
+ // On: Spaces that are not online and not on their way.
+ let now = Instant::now();
+ let due: Vec<String> = want
+ .iter()
+ .map(|i| i.id.clone())
+ .filter(|id| {
+ let online = all
+ .get(id)
+ .and_then(|a| rows.get(&a.machine))
+ .is_some_and(|m| m.online && m.role == "owner");
+ let (waiting, dialing) = memo(&home, |m| {
+ (
+ m.retry_at.get(id).is_some_and(|t| *t > now),
+ m.dialing.get(id).is_some_and(|t| *t > now),
+ )
+ });
+ !online && !waiting && !dialing
+ })
+ .collect();
+
+ let mut budget = PER_PASS;
+ let leave_now: Vec<String> = leaving.iter().take(budget).cloned().collect();
+ budget -= leave_now.len();
+ let join_now: Vec<String> = due.iter().take(budget).cloned().collect();
+ let over = leaving.len() + due.len() > PER_PASS;
+
+ let tripped = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let rows = Arc::new(rows);
+ use futures_util::StreamExt as _;
+ let removed: Vec<(String, bool)> = futures_util::stream::iter(leave_now)
+ .map(|space| {
+ let (rows, tripped, this) = (rows.clone(), tripped.clone(), self.clone());
+ async move {
+ if tripped.load(std::sync::atomic::Ordering::SeqCst) {
+ return (space, false);
+ }
+ let machine = this.attached().get(&space).map(|a| a.machine.clone());
+ let shared = machine.as_ref().and_then(|m| rows.get(m)).is_some_and(|m| {
+ !m.allow.is_empty() || !m.viewers.is_empty() || m.team.is_some()
+ });
+ let ok = this.unpublish_with(&space, shared).await;
+ if !ok {
+ tripped.store(true, std::sync::atomic::Ordering::SeqCst);
+ }
+ (space, ok)
+ }
+ })
+ .buffer_unordered(AT_ONCE)
+ .collect()
+ .await;
+ let mut trouble = false;
+ for (space, ok) in removed {
+ if ok {
+ report.unpublished.push(space);
+ } else {
+ // Shared Spaces stay (not trouble); a failed call is.
+ trouble |= self.attached().get(&space).is_some_and(|a| a.auto);
+ }
+ }
+
+ let results: Vec<(String, Option<Result<()>>)> = futures_util::stream::iter(join_now)
+ .map(|id| {
+ let (tripped, subject, this) = (tripped.clone(), subject.clone(), self.clone());
+ async move {
+ if trouble || tripped.load(std::sync::atomic::Ordering::SeqCst) {
+ return (id, None);
+ }
+ let fresh = !this.attached().contains_key(&id);
+ let r = this
+ .ensure_shared_machine_with(&id, false)
+ .await
+ .map(|_| ());
+ if let Err(e) = &r
+ && relay_trouble(e).is_some()
+ {
+ tripped.store(true, std::sync::atomic::Ordering::SeqCst);
+ }
+ if r.is_ok() && fresh {
+ // Listed by this pass, not by hand: this pass also
+ // takes it off again.
+ let _ = this.update_attached(|now| {
+ if let Some(a) = now.get_mut(&id) {
+ a.auto = true;
+ a.account = subject.clone();
+ }
+ });
+ this.audit_share("publish", &id, "automatic");
+ }
+ (id, Some(r))
+ }
+ })
+ .buffer_unordered(AT_ONCE)
+ .collect()
+ .await;
+ let mut skipped = false;
+ let mut relay_error: Option<(crate::Error, Option<Duration>)> = None;
+ for (id, r) in results {
+ match r {
+ None => skipped = true,
+ Some(Ok(())) => {
+ memo(&home, |m| {
+ m.retry_at.remove(&id);
+ m.dialing.insert(id.clone(), Instant::now() + DIAL_GRACE);
+ });
+ report.published.push(id);
+ }
+ Some(Err(e)) => {
+ tracing::debug!(space = %id, error = %e, "not listed on the relay now");
+ if let Some(wait) = relay_trouble(&e) {
+ let msg = e.to_string();
+ relay_error = Some((e, wait));
+ report.failed.push((id, msg));
+ } else {
+ memo(&home, |m| {
+ m.retry_at.insert(id.clone(), Instant::now() + RETRY_AFTER)
+ });
+ report.failed.push((id, e.to_string()));
+ }
+ }
+ }
+ }
+ if trouble && relay_error.is_none() {
+ // A removal failed against the relay.
+ relay_error = Some((crate::Error::invalid("removal failed"), None));
+ }
+ match relay_error {
+ Some((e, wait)) => {
+ memo(&home, |m| {
+ m.breaker.fails = m.breaker.fails.saturating_add(1);
+ m.breaker.open_until =
+ Some(Instant::now() + breaker_wait(m.breaker.fails, wait));
+ m.settled = None;
+ });
+ tracing::warn!(error = %e, "the relay is failing; Spaces are listed again later");
+ report.more = false;
+ }
+ None => {
+ let finished = !over && !skipped && !young && report.failed.is_empty();
+ memo(&home, |m| {
+ m.breaker = Breaker::default();
+ m.dialing.retain(|_, t| *t > Instant::now());
+ if finished {
+ m.settled = Some(wanted);
+ m.verify_at = Instant::now() + jitter(VERIFY_EVERY);
+ } else {
+ m.settled = None;
+ }
+ });
+ report.more = over || young;
+ }
+ }
+ Ok(report)
+ }
+
+ /// The owner's rows of the relay directory, by machine id: the pass's one
+ /// read.
+ async fn owner_rows(&self) -> Result<BTreeMap<String, crate::relay::RelayMachine>> {
+ let account = self.relay()?;
+ let token = account.tokens.access_token().await?;
+ let rows = account.client().await?.machines(&token).await?;
+ Ok(rows.into_iter().map(|m| (m.id.clone(), m)).collect())
+ }
+
+ /// Notes a failed call to the relay: no more calls for a while.
+ fn relay_failed(&self, home: &std::path::Path, e: &crate::Error) {
+ let wait = relay_trouble(e).flatten();
+ memo(home, |m| {
+ m.breaker.fails = m.breaker.fails.saturating_add(1);
+ m.breaker.open_until = Some(Instant::now() + breaker_wait(m.breaker.fails, wait));
+ m.settled = None;
+ });
+ tracing::warn!(error = %e, "the relay is failing; Spaces are listed again later");
+ }
+
+ /// Takes every Space of `spaces` off (the setting went off, or sharing
+ /// stopped), at most [`PER_PASS`] at a time. True when some are left.
+ async fn remove_all(
+ &self,
+ spaces: &[String],
+ rows: &BTreeMap<String, crate::relay::RelayMachine>,
+ report: &mut PublishReport,
+ ) -> bool {
+ use futures_util::StreamExt as _;
+ let batch: Vec<String> = spaces.iter().take(PER_PASS).cloned().collect();
+ let out: Vec<(String, bool)> = futures_util::stream::iter(batch)
+ .map(|space| {
+ let this = self.clone();
+ let shared = this
+ .attached()
+ .get(&space)
+ .and_then(|a| rows.get(&a.machine))
+ .is_some_and(|m| {
+ !m.allow.is_empty() || !m.viewers.is_empty() || m.team.is_some()
+ });
+ async move {
+ let ok = this.unpublish_with(&space, shared).await;
+ (space, ok)
+ }
+ })
+ .buffer_unordered(AT_ONCE)
+ .collect()
+ .await;
+ for (space, ok) in out {
+ if ok {
+ report.unpublished.push(space);
+ }
+ }
+ spaces.len() > PER_PASS
+ }
+
+ /// Takes a Space this pass listed off the relay: its driver leaves and
+ /// its row goes (one call). A Space shared with other people (`shared`,
+ /// from the directory) stays on the relay as shared: the owner decides
+ /// that. `true` when it left.
+ async fn unpublish_with(&self, space: &str, shared: bool) -> bool {
+ let Some(machine) = self.attached().get(space).map(|a| a.machine.clone()) else {
+ return false;
+ };
+ if shared {
+ let _ = self.update_attached(|now| {
+ if let Some(a) = now.get_mut(space) {
+ a.auto = false;
+ }
+ });
+ return false;
+ }
+ match self.detach(space, &machine).await {
+ Ok(()) => {
+ memo(self.home_dir(), |m| m.dialing.remove(space));
+ self.audit_share("unpublish", space, "automatic");
+ true
+ }
+ Err(e) => {
+ tracing::debug!(space, error = %e, "not taken off the relay now");
+ false
+ }
+ }
+ }
+
+ /// Opts a Space in or out of the account's relay (`--no-relay`). Off
+ /// takes it off at once when this computer is signed in.
+ pub async fn set_on_relay(&self, space: &str, on: bool) -> Result<crate::SpaceInfo> {
+ let id = self.resolve(space)?;
+ if !matches!(id, SpaceId::Local { .. }) {
+ return Err(crate::Error::invalid(format!(
+ "{id} is not a Space on this computer; only those are listed on your account by Cua"
+ )));
+ }
+ let canonical = id.to_string();
+ let setting = if on {
+ crate::registry::RelaySetting::On
+ } else {
+ crate::registry::RelaySetting::Off
+ };
+ self.inner
+ .registry
+ .update_meta(&canonical, |m| m.relay = setting)?;
+ memo(self.home_dir(), |m| m.settled = None);
+ CHANGED.notify_waiters();
+ if !on {
+ let _ = self.publish_to_relay().await;
+ }
+ self.info(&id)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn the_wait_after_a_failure_doubles_honors_retry_after_and_is_capped() {
+ for _ in 0..50 {
+ let w = |n, r| breaker_wait(n, r).as_secs_f64();
+ assert!((4.0..=6.0).contains(&w(1, None)), "{}", w(1, None));
+ assert!((8.0..=12.0).contains(&w(2, None)));
+ assert!((16.0..=24.0).contains(&w(3, None)));
+ assert!(w(30, None) <= 360.0, "capped");
+ assert!(w(30, None) >= 240.0);
+ // The relay's own Retry-After is a floor.
+ assert!(w(1, Some(Duration::from_secs(90))) >= 90.0);
+ // ...but an absurd one does not park the pass for hours.
+ assert!(w(1, Some(Duration::from_secs(86_400))) <= 300.0);
+ }
+ }
+
+ #[test]
+ fn jitter_stays_within_a_fifth() {
+ for _ in 0..200 {
+ let j = jitter(Duration::from_secs(15)).as_secs_f64();
+ assert!((12.0..=18.0).contains(&j), "{j}");
+ }
+ }
+
+ #[test]
+ fn only_a_failing_relay_trips_the_breaker() {
+ let transient = crate::Error::Relay(cua_host::Error::Throttled {
+ retry_after_secs: 7,
+ });
+ assert_eq!(
+ relay_trouble(&transient),
+ Some(Some(Duration::from_secs(7)))
+ );
+ let down = crate::Error::Relay(cua_host::Error::Relay("HTTP 503: gone".into()));
+ assert_eq!(relay_trouble(&down), Some(None));
+ let refused = crate::Error::Relay(cua_host::Error::PermissionDenied("no".into()));
+ assert_eq!(relay_trouble(&refused), None);
+ assert_eq!(relay_trouble(&crate::Error::invalid("x")), None);
+ }
+}
diff --git a/libs/cua/crates/cua-spaces/src/spaces.rs b/libs/cua/crates/cua-spaces/src/spaces.rs
index fadd47e14e..1e4f0ba987 100644
--- a/libs/cua/crates/cua-spaces/src/spaces.rs
+++ b/libs/cua/crates/cua-spaces/src/spaces.rs
@@ -136,6 +136,13 @@ pub struct SpaceCreate {
/// On a linked cloud: the region its host must be in. `None`: any the
/// cloud offers.
pub region: Option<String>,
+ /// `Some(false)`: keep the Space off the owner's account, so the phone
+ /// and the owner's other computers never see it (`--no-relay`; the
+ /// label `cua.relay=off` says the same on every path, the daemon's
+ /// included). `None` and `Some(true)`: it is listed while this computer
+ /// is signed in and sharing (the `relay.spaces` setting), and a child
+ /// follows its parent's `off`.
+ pub relay: Option<bool>,
}
/// Where [`SpaceCreate::progress`] reports go.
@@ -758,6 +765,14 @@ impl Spaces {
let facts = self.team_facts();
let provided_here: std::collections::HashSet<String> =
provided.iter().map(|p| p.relay_machine.clone()).collect();
+ // A Space this computer listed on the account itself is the local
+ // one, once.
+ #[cfg(feature = "spaces-agents")]
+ let provided_here = {
+ let mut here = provided_here;
+ here.extend(self.auto_published_machines());
+ here
+ };
let cache = self.inner.relay_cache.lock().expect("relay cache");
// Its name on the relay is the one your other devices see: a rename
// there (from another device) shows here too. The name it was
@@ -2575,6 +2590,10 @@ impl Spaces {
};
let expect_env = expects_spacesd(opts.image.as_deref(), opts.spacesd);
let labels = opts.labels.clone();
+ let relay_off = opts.relay == Some(false)
+ || labels
+ .get(crate::registry::RELAY_LABEL)
+ .is_some_and(|v| crate::registry::RelaySetting::parse(v).is_ok_and(|s| !s.is_on()));
let joined_tree = opts.tree.clone().filter(|_| opts.parent.is_none());
let egress = opts.egress.clone();
let network = crate::network::CreateNetwork {
@@ -2706,11 +2725,17 @@ impl Spaces {
let kept = self.inner.registry.update_meta(&id, |m| {
m.labels = labels.clone();
m.created_at_unix = now;
+ if relay_off {
+ m.relay = crate::registry::RelaySetting::Off;
+ }
// A member of a tree that started on another computer.
if let Some(t) = &joined_tree {
m.overlay_tree = Some(t.clone());
}
});
+ // The daemon lists it on the account without waiting for its tick.
+ #[cfg(feature = "spaces-agents")]
+ crate::share::PUBLISH_CHANGED.notify_waiters();
// The policy was enforced from the guest's first instruction
// (by this machine's runtime, or the host that created it).
let applied = match &kept {
@@ -3903,6 +3928,8 @@ impl Spaces {
let control = sandboxes
.power_control(name)
.unwrap_or(cua_sandbox_core::PowerControl::Stop);
+ #[cfg(feature = "spaces-agents")]
+ crate::share::PUBLISH_CHANGED.notify_waiters();
Ok(SpacePower::new(&id.to_string(), control, state))
}
// A Space in your own cloud: its sandbox stops and starts
diff --git a/libs/cua/crates/cua-spaces/tests/relay_publish.rs b/libs/cua/crates/cua-spaces/tests/relay_publish.rs
new file mode 100644
index 0000000000..3f4a4c54d2
--- /dev/null
+++ b/libs/cua/crates/cua-spaces/tests/relay_publish.rs
@@ -0,0 +1,778 @@
+//! Spaces running on this computer are listed on the signed-in account's
+//! relay on their own, so the phone and the owner's other computers see and
+//! open them: any kind of Space (macOS VM, QEMU VM, container, microVM), made
+//! by any path, or already here. Hermetic: the fake relay and one mock
+//! cua-spacesd per Space; nothing starts a VM or a container.
+
+use async_trait::async_trait;
+use cua_host::relay::AccountTokens;
+use cua_host::testing::FakeRelay;
+use cua_sandbox_core::placement::{Kind, On};
+use cua_sandbox_core::{
+ InstanceStatus, LocalEndpoints, LocalInstance, LocalRuntime, LocalStartSpec, LocalSummary,
+ RuntimeError, Sandboxes,
+};
+use cua_spaces::relay::StaticToken;
+use cua_spaces::{RelayAccount, SpaceCreate, Spaces};
+use cua_spacesd_client::testing::{MockAuth, MockServer};
+use std::collections::BTreeMap;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+/// A local runtime whose Space `name` has its cua-spacesd at a loopback
+/// port the test chose.
+#[derive(Default)]
+struct Runtime {
+ spacesd: Mutex<BTreeMap<String, u16>>,
+ /// One cua-spacesd answering for every Space not named above (bursts).
+ shared: Mutex<Option<u16>>,
+}
+
+#[async_trait]
+impl LocalRuntime for Runtime {
+ fn backend(&self) -> String {
+ "fake".into()
+ }
+ async fn start(&self, spec: &LocalStartSpec) -> Result<LocalInstance, RuntimeError> {
+ Ok(LocalInstance {
+ name: spec.name.clone(),
+ backend: "fake".into(),
+ status: InstanceStatus::Running,
+ endpoints: self.endpoints_of(&spec.name),
+ })
+ }
+ async fn stop(&self, _: &str) -> Result<(), RuntimeError> {
+ Ok(())
+ }
+ async fn resume(&self, name: &str) -> Result<LocalInstance, RuntimeError> {
+ Ok(LocalInstance {
+ name: name.into(),
+ backend: "fake".into(),
+ status: InstanceStatus::Running,
+ endpoints: self.endpoints_of(name),
+ })
+ }
+ async fn list(&self) -> Result<Vec<LocalSummary>, RuntimeError> {
+ Ok(vec![])
+ }
+ async fn status(&self, _: &str) -> Result<InstanceStatus, RuntimeError> {
+ Ok(InstanceStatus::Running)
+ }
+ async fn delete(&self, _: &str) -> Result<(), RuntimeError> {
+ Ok(())
+ }
+ async fn endpoints(&self, name: &str) -> Result<LocalEndpoints, RuntimeError> {
+ Ok(self.endpoints_of(name))
+ }
+}
+
+impl Runtime {
+ fn endpoints_of(&self, name: &str) -> LocalEndpoints {
+ let port = self
+ .spacesd
+ .lock()
+ .unwrap()
+ .get(name)
+ .copied()
+ .or(*self.shared.lock().unwrap());
+ LocalEndpoints {
+ host: "127.0.0.1".into(),
+ ports: port.map(|p| (3211u16, p)).into_iter().collect(),
+ ..Default::default()
+ }
+ }
+}
+
+/// An account that can be signed out and in again.
+struct Account(Mutex<Option<String>>);
+#[async_trait]
+impl AccountTokens for Account {
+ async fn access_token(&self) -> cua_host::Result<String> {
+ self.0
+ .lock()
+ .unwrap()
+ .clone()
+ .ok_or_else(|| cua_host::Error::Unauthenticated("signed out".into()))
+ }
+ async fn signed_in(&self) -> bool {
+ self.0.lock().unwrap().is_some()
+ }
+}
+
+/// The tests share one process, and one of them counts its open sockets:
+/// they run one at a time.
+static SERIAL: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+struct World {
+ _serial: tokio::sync::MutexGuard<'static, ()>,
+ relay: FakeRelay,
+ rt: Arc<Runtime>,
+ state: tempfile::TempDir,
+ home: tempfile::TempDir,
+ drivers: Mutex<BTreeMap<String, MockServer>>,
+ account: Arc<Account>,
+ spaces: Spaces,
+ stop: Arc<AtomicBool>,
+}
+
+impl Drop for World {
+ fn drop(&mut self) {
+ self.stop.store(true, Ordering::SeqCst);
+ }
+}
+
+impl World {
+ async fn new() -> World {
+ let serial = SERIAL.lock().await;
+ let relay = FakeRelay::start().await;
+ relay.add_account("ada-token", "ada", Some("[email protected]"));
+ relay.add_account("eve-token", "eve", Some("[email protected]"));
+ let rt = Arc::new(Runtime::default());
+ let state = tempfile::tempdir().unwrap();
+ let home = tempfile::tempdir().unwrap();
+ let account = Arc::new(Account(Mutex::new(Some("ada-token".into()))));
+ let spaces = Spaces::builder()
+ .home(home.path())
+ .sandboxes(
+ Sandboxes::builder()
+ .local(rt.clone())
+ .state_dir(state.path())
+ .build(),
+ )
+ .relay(RelayAccount::new(&relay.url, account.clone()))
+ .build();
+ World {
+ _serial: serial,
+ relay,
+ rt,
+ state,
+ home,
+ drivers: Mutex::new(BTreeMap::new()),
+ account,
+ spaces,
+ stop: Arc::new(AtomicBool::new(false)),
+ }
+ }
+
+ /// A cua-spacesd for the Space `name`, which "dials the relay" when
+ /// asked to attach.
+ async fn driver(&self, name: &str) {
+ let d = MockServer::start(MockAuth::default()).await;
+ d.state.advertise(&["relay_attach"]);
+ let port: u16 = d.url().rsplit(':').next().unwrap().parse().unwrap();
+ self.rt.spacesd.lock().unwrap().insert(name.into(), port);
+ let state = d.state.clone();
+ let relay = self.relay.clone();
+ let stop = self.stop.clone();
+ tokio::spawn(async move {
+ let mut last: Option<String> = None;
+ while !stop.load(Ordering::SeqCst) {
+ let now = state.relay_attached.lock().unwrap().clone();
+ match (now, &last) {
+ (Some(a), _) => {
+ relay.set_online(&a.machine_id, true, "0.1.0");
+ last = Some(a.machine_id);
+ }
+ // The driver left: the relay lists the machine offline.
+ (None, Some(m)) => {
+ relay.set_online(m, false, "0.1.0");
+ last = None;
+ }
+ (None, None) => {}
+ }
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ });
+ self.drivers.lock().unwrap().insert(name.into(), d);
+ }
+
+ fn attached(&self, name: &str) -> bool {
+ self.drivers.lock().unwrap()[name]
+ .state
+ .relay_attached
+ .lock()
+ .unwrap()
+ .is_some()
+ }
+
+ /// The owner's relay rows that are Spaces Cua registered.
+ async fn rows(&self) -> Vec<cua_host::Machine> {
+ cua_host::RelayClient::new(&self.relay.url)
+ .unwrap()
+ .machines("ada-token")
+ .await
+ .unwrap()
+ .into_iter()
+ .filter(|m| m.id.starts_with("space-"))
+ .collect()
+ }
+
+ /// One cua-spacesd for every Space made from now on.
+ async fn shared_driver(&self) -> MockServer {
+ let d = MockServer::start(MockAuth::default()).await;
+ d.state.advertise(&["relay_attach"]);
+ let port: u16 = d.url().rsplit(':').next().unwrap().parse().unwrap();
+ *self.rt.shared.lock().unwrap() = Some(port);
+ d
+ }
+
+ /// `n` Spaces made 16 at a time; the seconds it took.
+ async fn burst(&self, n: usize, prefix: &str) -> f64 {
+ use futures_util::StreamExt as _;
+ let started = std::time::Instant::now();
+ futures_util::stream::iter(0..n)
+ .map(|i| {
+ let spaces = self.spaces.clone();
+ let name = format!("{prefix}-{i}");
+ async move {
+ spaces
+ .create(SpaceCreate {
+ on: Some(On::Local),
+ image: Some("linux".into()),
+ name: Some(name),
+ timeout: Some(Duration::from_secs(60)),
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ }
+ })
+ .buffer_unordered(16)
+ .collect::<Vec<_>>()
+ .await;
+ started.elapsed().as_secs_f64()
+ }
+
+ fn age_all(&self) {
+ for i in self.spaces.list().unwrap() {
+ self.age(&i.id);
+ }
+ }
+
+ /// Makes the Space `id` old enough to be listed (a new one waits a few
+ /// seconds, so one made and deleted at once never reaches the relay).
+ fn age(&self, id: &str) {
+ self.spaces
+ .registry()
+ .update_meta(id, |m| m.created_at_unix = 1)
+ .unwrap();
+ }
+
+ async fn create(&self, name: &str, image: &str, kind: Kind) -> String {
+ self.driver(name).await;
+ let id = self
+ .spaces
+ .create(SpaceCreate {
+ on: Some(On::Local),
+ image: Some(image.into()),
+ kind,
+ name: Some(name.into()),
+ timeout: Some(Duration::from_secs(30)),
+ ..Default::default()
+ })
+ .await
+ .unwrap()
+ .ready()
+ .unwrap()
+ .id;
+ self.age(&id);
+ id
+ }
+
+ /// What the recorded state of the Space `name` says (a runtime turning
+ /// it off or on).
+ fn power(&self, name: &str, status: &str) {
+ let path = self.state.path().join(format!("{name}.json"));
+ let mut v: serde_json::Value =
+ serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+ v["status"] = status.into();
+ std::fs::write(path, v.to_string()).unwrap();
+ }
+}
+
+/// Every kind of Space runs the same rule: a running Space is on the
+/// account once a pass runs, a stopped one leaves it, and deleting takes
+/// its row with it.
+#[tokio::test]
+async fn every_kind_of_running_space_is_listed_and_unlisted_alike() {
+ let w = World::new().await;
+ let kinds = [
+ ("mac", "macos", Kind::Vm),
+ ("qemu", "ubuntu", Kind::Vm),
+ ("box", "linux", Kind::Container),
+ ("micro", "linux", Kind::MicroVm),
+ ];
+ let mut ids = vec![];
+ for (name, image, kind) in kinds {
+ ids.push((name, w.create(name, image, kind).await));
+ }
+ assert!(w.rows().await.is_empty(), "nothing yet: no pass has run");
+
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published.len(), 4, "{r:?}");
+ let rows = w.rows().await;
+ assert_eq!(rows.len(), 4);
+ // The owner's alone: shared with nobody, and another account sees none.
+ assert!(rows.iter().all(|m| m.role == "owner"
+ && m.allow.is_empty()
+ && m.viewers.is_empty()
+ && m.host.is_none()));
+ assert!(
+ cua_host::RelayClient::new(&w.relay.url)
+ .unwrap()
+ .machines("eve-token")
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ for (name, _) in &ids {
+ assert!(w.attached(name), "{name}'s driver joined the relay");
+ }
+ // A second pass changes nothing.
+ let again = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(again, Default::default());
+
+ // The local Space is listed once, not again as its relay machine.
+ w.spaces.relay_machines().await.unwrap();
+ let listed = w.spaces.list().unwrap();
+ assert_eq!(
+ listed.iter().filter(|i| i.id.starts_with("relay:")).count(),
+ 0,
+ "{listed:#?}"
+ );
+ assert_eq!(
+ w.spaces
+ .relay_states(&listed)
+ .values()
+ .filter(|s| **s == "on")
+ .count(),
+ 4
+ );
+
+ // Stopped: it leaves the account.
+ w.power("mac", "stopped");
+ w.power("qemu", "suspended");
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.unpublished.len(), 2, "{r:?}");
+ assert_eq!(w.rows().await.len(), 2);
+ assert!(!w.attached("mac") && !w.attached("qemu"));
+ // Started again: it is back.
+ w.power("mac", "running");
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published.len(), 1, "{r:?}");
+ assert_eq!(w.rows().await.len(), 3);
+
+ // Deleted: its row goes with it.
+ w.spaces.delete(&ids[2].1).await.unwrap();
+ assert_eq!(w.rows().await.len(), 2);
+}
+
+/// Only what Cua made is listed, and only if it did not opt out.
+#[tokio::test]
+async fn spaces_added_by_address_and_opted_out_ones_stay_off() {
+ let w = World::new().await;
+ // Added by address: not made by Cua.
+ let by_hand = MockServer::start(MockAuth::default()).await;
+ by_hand.state.advertise(&["relay_attach"]);
+ w.spaces
+ .add(&by_hand.url(), None, Some("by-hand".into()))
+ .await
+ .unwrap();
+
+ // `--no-relay` (the option) and `--label cua.relay=off` (the label every
+ // path carries), and a child of an opted-out Space.
+ w.driver("quiet").await;
+ w.driver("labelled").await;
+ w.driver("child").await;
+ w.driver("open").await;
+ let make = |name: &str, relay: Option<bool>, labels: &[(&str, &str)], parent: Option<&str>| {
+ let spaces = w.spaces.clone();
+ let opts = SpaceCreate {
+ on: Some(On::Local),
+ image: Some("linux".into()),
+ name: Some(name.into()),
+ timeout: Some(Duration::from_secs(30)),
+ relay,
+ labels: labels
+ .iter()
+ .map(|(k, v)| (k.to_string(), v.to_string()))
+ .collect(),
+ parent: parent.map(str::to_string),
+ ..Default::default()
+ };
+ async move {
+ let id = spaces.create(opts).await.unwrap().ready().unwrap().id;
+ spaces
+ .registry()
+ .update_meta(&id, |m| m.created_at_unix = 1)
+ .unwrap();
+ id
+ }
+ };
+ let quiet = make("quiet", Some(false), &[], None).await;
+ make("labelled", None, &[("cua.relay", "off")], None).await;
+ make("child", None, &[], Some(&quiet)).await;
+ make("open", None, &[], None).await;
+
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published, ["local:open"], "{r:?}");
+ assert_eq!(w.rows().await.len(), 1);
+ assert!(!w.attached("quiet") && !w.attached("labelled") && !w.attached("child"));
+ assert!(by_hand.state.relay_attached.lock().unwrap().is_none());
+
+ // `cua spaces ls` says which stay off.
+ let states = w.spaces.relay_states(&w.spaces.list().unwrap());
+ assert_eq!(states["local:quiet"], "off");
+ assert_eq!(states["local:labelled"], "off");
+ assert_eq!(states["local:child"], "off");
+ assert_eq!(states["local:open"], "on");
+ assert!(!states.contains_key("direct:by-hand"));
+
+ // Opting out later takes it off at once; opting in lists it again.
+ w.spaces.set_on_relay("local:open", false).await.unwrap();
+ assert!(w.rows().await.is_empty());
+ assert!(!w.attached("open"));
+ w.spaces.set_on_relay("local:open", true).await.unwrap();
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.rows().await.len(), 1);
+}
+
+/// A Space that was already here before this release is listed once it
+/// runs, whichever way it came to be.
+#[tokio::test]
+async fn a_space_that_was_already_here_is_listed() {
+ let w = World::new().await;
+ let id = w.create("old", "linux", Kind::Container).await;
+ // Its record predates the setting: nothing but the registry entry.
+ w.spaces
+ .registry()
+ .update_meta(&id, |m| *m = Default::default())
+ .unwrap();
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published, [id], "{r:?}");
+}
+
+/// The switch, the sign-out and a share.
+#[tokio::test]
+async fn the_switch_and_the_sign_out_take_spaces_off_and_back_on() {
+ let w = World::new().await;
+ w.create("a", "linux", Kind::Container).await;
+ w.create("b", "linux", Kind::Container).await;
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.rows().await.len(), 2);
+
+ // Signed out: no account to call the relay with, so each driver just
+ // stops dialing; the rows wait for the next sign-in.
+ *w.account.0.lock().unwrap() = None;
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert!(r.published.is_empty() && r.unpublished.is_empty());
+ assert!(
+ !w.attached("a") && !w.attached("b"),
+ "drivers left the relay"
+ );
+ // Not repeated every pass.
+ w.spaces.publish_to_relay().await.unwrap();
+ // The relay lists a machine whose driver left as offline.
+ tokio::time::sleep(Duration::from_millis(100)).await;
+
+ *w.account.0.lock().unwrap() = Some("ada-token".into());
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published.len(), 2, "{r:?}");
+ assert!(w.attached("a") && w.attached("b"));
+ assert_eq!(w.rows().await.len(), 2, "the same two rows, not four");
+
+ // The switch: `relay.spaces = off` (config file; the environment does
+ // the same) takes them off the account.
+ std::fs::write(
+ w.home.path().join("config.toml"),
+ "[relay]\nspaces = \"off\"\n",
+ )
+ .unwrap();
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.unpublished.len(), 2, "{r:?}");
+ assert!(w.rows().await.is_empty());
+ assert!(!w.attached("a"));
+ std::fs::write(
+ w.home.path().join("config.toml"),
+ "[relay]\nspaces = \"on\"\n",
+ )
+ .unwrap();
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.rows().await.len(), 2);
+
+ // A Space the owner shared with someone stays as shared when it stops.
+ let row = w.rows().await.remove(0);
+ let name = if w.attached("a") && row.name.contains('a') {
+ "a"
+ } else {
+ "b"
+ };
+ let machine = row.id.clone();
+ cua_host::RelayClient::new(&w.relay.url)
+ .unwrap()
+ .patch(
+ "ada-token",
+ &machine,
+ &cua_host::MachinePatch {
+ allow: Some(vec!["[email protected]".into()]),
+ ..Default::default()
+ },
+ )
+ .await
+ .unwrap();
+ let stopped = w
+ .spaces
+ .list()
+ .unwrap()
+ .into_iter()
+ .find(|i| w.spaces.registry().meta(&i.id).is_some() && i.name == row.name)
+ .map(|i| i.id)
+ .unwrap_or_else(|| format!("local:{name}"));
+ w.power(stopped.trim_start_matches("local:"), "stopped");
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.unpublished.len(), 0, "{r:?}");
+ assert!(w.relay.machine(&machine).is_some());
+}
+
+/// A static token is enough: no host setup is needed to be listed.
+#[tokio::test]
+async fn nothing_is_listed_without_an_account() {
+ let w = World::new().await;
+ w.create("lonely", "linux", Kind::Container).await;
+ let bare = Spaces::builder()
+ .home(w.home.path())
+ .sandboxes(
+ Sandboxes::builder()
+ .local(w.rt.clone())
+ .state_dir(w.state.path())
+ .build(),
+ )
+ .build();
+ assert_eq!(bare.publish_to_relay().await.unwrap(), Default::default());
+ assert!(w.rows().await.is_empty());
+ let _ = StaticToken("x".into());
+}
+
+/// A computer that stopped sharing lists nothing; sharing again lists its
+/// Spaces again (the same switch `cua host stop` and the app's sharing
+/// toggle use).
+#[tokio::test]
+async fn a_computer_that_stopped_sharing_lists_nothing() {
+ let w = World::new().await;
+ w.create("a", "linux", Kind::Container).await;
+ let host = |sharing: bool| {
+ let dir = w.home.path().join("host");
+ std::fs::create_dir_all(&dir).unwrap();
+ std::fs::write(
+ dir.join("config.json"),
+ serde_json::json!({
+ "mode": "relay", "name": "Studio", "runner": "process",
+ "driver_bin": "/nonexistent", "sharing": sharing,
+ })
+ .to_string(),
+ )
+ .unwrap();
+ };
+ host(true);
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.rows().await.len(), 1);
+ host(false);
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.unpublished.len(), 1, "{r:?}");
+ assert!(w.rows().await.is_empty());
+ host(true);
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.rows().await.len(), 1);
+}
+
+/// A Space another of the owner's computers asked this one to make is on
+/// the relay already, under this computer: it is not listed a second time.
+#[tokio::test]
+async fn a_space_a_host_provides_is_not_listed_twice() {
+ let w = World::new().await;
+ let id = w.create("provided", "linux", Kind::Container).await;
+ w.create("mine", "linux", Kind::Container).await;
+ cua_host::provided::save_provided(
+ &cua_host::Host::new(w.home.path()).paths().dir,
+ &[cua_host::provided::ProvidedSpace {
+ relay_machine: "0123456789abcdef".into(),
+ local_space: id,
+ name: "provided".into(),
+ ..Default::default()
+ }],
+ )
+ .unwrap();
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(r.published, ["local:mine"], "{r:?}");
+ assert_eq!(w.rows().await.len(), 1);
+}
+
+fn open_fds() -> usize {
+ std::fs::read_dir("/dev/fd").map(|d| d.count()).unwrap_or(0)
+}
+
+/// A burst of 200 creates is not slowed by listing Spaces, and costs the
+/// relay a registration each plus a few reads in all, never more than four
+/// calls at once; once everything is listed, idle passes cost nothing.
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn a_burst_of_200_creates_is_as_fast_and_cheap_for_the_relay() {
+ const N: usize = 200;
+ // Without any listing.
+ let without = {
+ let quiet = World::new().await;
+ let _d = quiet.shared_driver().await;
+ quiet.burst(N, "q").await
+ };
+
+ // With the pass running the way the daemon runs it, on a relay that
+ // takes 20 ms per call.
+ let w = World::new().await;
+ let _d2 = w.shared_driver().await;
+ w.relay.set_latency_ms(20);
+ w.relay.reset_load();
+ let running = Arc::new(AtomicBool::new(true));
+ let passes = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+ let looped = {
+ let (spaces, running, passes) = (w.spaces.clone(), running.clone(), passes.clone());
+ tokio::spawn(async move {
+ while running.load(Ordering::SeqCst) {
+ let _ = spaces.publish_to_relay().await;
+ passes.fetch_add(1, Ordering::SeqCst);
+ tokio::time::sleep(Duration::from_millis(300)).await;
+ }
+ })
+ };
+ let with = w.burst(N, "b").await;
+ running.store(false, Ordering::SeqCst);
+ looped.await.unwrap();
+ eprintln!("200 creates: {without:.2} s without listing, {with:.2} s with it");
+ assert!(
+ with <= without * 1.25 + 0.5,
+ "creating was slowed: {without:.2} s without, {with:.2} s with"
+ );
+
+ // Five seconds later every Space is old enough; the passes finish the job.
+ w.age_all();
+ let mut n_passes = passes.load(Ordering::SeqCst);
+ loop {
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ n_passes += 1;
+ if r.published.is_empty() && !r.more {
+ break;
+ }
+ assert!(n_passes < 60, "never finished");
+ }
+ let requests = w.relay.requests();
+ let peak = w.relay.peak_in_flight();
+ eprintln!("200 Spaces: {requests} relay requests in {n_passes} passes, peak {peak} in flight");
+ assert_eq!(w.rows().await.len(), N);
+ // One registration each; everything else is the directory read of a pass.
+ assert!(
+ requests <= N + 30,
+ "{requests} requests for {N} Spaces in {n_passes} passes"
+ );
+ assert!(peak <= 4, "{peak} calls at once");
+
+ // All listed: more passes ask nothing.
+ w.relay.reset_load();
+ for _ in 0..20 {
+ w.spaces.publish_to_relay().await.unwrap();
+ }
+ assert_eq!(w.relay.requests(), 0, "an idle pass called the relay");
+}
+
+/// A Space made and deleted before it settles never reaches the relay.
+#[tokio::test]
+async fn a_space_made_and_deleted_at_once_never_touches_the_relay() {
+ let w = World::new().await;
+ let _d = w.shared_driver().await;
+ w.relay.reset_load();
+ w.burst(30, "tmp").await;
+ for i in w.spaces.list().unwrap() {
+ w.spaces.delete(&i.id).await.unwrap();
+ w.spaces.publish_to_relay().await.unwrap();
+ }
+ w.spaces.publish_to_relay().await.unwrap();
+ assert_eq!(w.relay.requests(), 0);
+ assert_eq!(w.relay.register_calls(), 0);
+}
+
+/// A relay that fails stops the calls (they come back later, after a longer
+/// wait each time), never slows making Spaces, and leaks no sockets.
+#[tokio::test]
+async fn a_relay_outage_pauses_listing_and_leaks_nothing() {
+ let w = World::new().await;
+ let _d = w.shared_driver().await;
+ w.burst(10, "pre").await;
+ w.age_all();
+ w.relay.set_reads_down(true);
+ w.relay.reset_load();
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert!(r.published.is_empty(), "{r:?}");
+ let first = w.relay.requests();
+ assert!(
+ (1..=4).contains(&first),
+ "{first} calls on the first failure"
+ );
+
+ // Creating goes on at full speed while calls are paused.
+ let secs = w.burst(30, "during").await;
+ assert!(secs < 30.0, "creates slowed to {secs:.1} s");
+ w.age_all();
+ // (Each Space keeps its own connections open; the passes add none.)
+ let fds_before = open_fds();
+ for _ in 0..50 {
+ w.spaces.publish_to_relay().await.unwrap();
+ }
+ assert_eq!(w.relay.requests(), first, "calls went on during the pause");
+ assert!(
+ open_fds() <= fds_before + 3,
+ "sockets leaked: {} -> {}",
+ fds_before,
+ open_fds()
+ );
+ let fds_paused = open_fds();
+
+ // The relay is back: after the pause the Spaces are listed.
+ w.relay.set_reads_down(false);
+ let started = std::time::Instant::now();
+ loop {
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ if !r.published.is_empty() {
+ break;
+ }
+ assert!(started.elapsed() < Duration::from_secs(20), "never resumed");
+ tokio::time::sleep(Duration::from_millis(250)).await;
+ }
+ eprintln!(
+ "listing resumed {:.1} s after the relay came back",
+ started.elapsed().as_secs_f64()
+ );
+ for _ in 0..20 {
+ w.spaces.publish_to_relay().await.unwrap();
+ }
+ assert!(
+ open_fds() <= fds_paused + 6,
+ "sockets leaked after resuming"
+ );
+}
+
+/// A throttled read (429) stops the calls for a while instead of being
+/// asked again at once.
+#[tokio::test]
+async fn a_throttled_relay_is_left_alone() {
+ let w = World::new().await;
+ let _d = w.shared_driver().await;
+ w.burst(5, "t").await;
+ w.age_all();
+ w.relay.fail_reads(&[429]);
+ w.relay.reset_load();
+ let r = w.spaces.publish_to_relay().await.unwrap();
+ assert!(r.published.is_empty(), "{r:?}");
+ assert_eq!(w.relay.requests(), 1);
+ for _ in 0..20 {
+ w.spaces.publish_to_relay().await.unwrap();
+ }
+ assert_eq!(w.relay.requests(), 1, "asked again while paused");
+}
diff --git a/scripts/docs-generators/cli-specs/cua.json b/scripts/docs-generators/cli-specs/cua.json
index 858fdc6395..9d16b5f15d 100644
--- a/scripts/docs-generators/cli-specs/cua.json
+++ b/scripts/docs-generators/cli-specs/cua.json
@@ -14845,6 +14845,17 @@
"short_name": null,
"takes_value": false
},
+ {
+ "aliases": [],
+ "default_value": false,
+ "env": null,
+ "help": "Keep it off your cua.ai account. By default a Space running on a computer signed in and sharing is listed there, so your phone and your other computers see and open it (`cua config set relay.spaces off` turns that off for all of them). A child Space follows its parent. Same as `--label cua.relay=off`",
+ "hidden": false,
+ "name": "no-relay",
+ "repeatable": false,
+ "short_name": null,
+ "takes_value": false
+ },
{
"aliases": [],
"default_value": false,