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.

fix(spaces-macos): sign in inline and retry transient failures in host setup (#4490)

dduponta129ab6a5a2e
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppEnvironment.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppEnvironment.swift
index ea8724c011..f58528a8a5 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppEnvironment.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppEnvironment.swift
@@ -117,7 +117,16 @@ public enum AppEnvironment {
loginItem: fixtures ? fixtureLoginItem(env["CUA_SPACES_LOGIN_ITEM"]) : MainAppLoginItem())
if let live {
let auth = live.cua.auth()
- let token: () async -> String? = { try? await auth.accessToken(force: false) }
+ // Signed out is nil (setup signs in first); anything else (no
+ // network, the credential vault) is the error itself, never a
+ // silent nil that reads as "not signed in".
+ let token: (Bool) async throws -> String? = { force in
+ do {
+ return try await auth.accessToken(force: force)
+ } catch CuaError.Unauthenticated {
+ return nil
+ }
+ }
onboarding.accountToken = token
model.host.accountToken = token
}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
index 5afe3a297c..e1f63515f5 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
@@ -194,6 +194,14 @@ public final class AppModel {
if case .failed = self.signIn { return false }
return self.identity != nil
}
+ // "Set up for access" signs in inline when relay setup has no
+ // account, then carries on.
+ self.host.signIn = { [weak self] in
+ guard let self else { return false }
+ await self.beginSignIn()
+ if case .failed = self.signIn { return false }
+ return self.identity != nil
+ }
// A row takes a window drop by the core's rule (the notch tiles' too).
dropTargets.isDropTarget = { [weak self] id in
self?.spaces.first { $0.id == id }.map { appSpaceAcceptsDrop(space: $0) } ?? false
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostModel.swift
index e6014ba26f..7d46ce9558 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostModel.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostModel.swift
@@ -112,8 +112,23 @@ public final class HostModel {
public var settingUp: Bool { formView?.busy == true }
/// The signed-in account (relay mode joins as it).
public var identity: String?
- /// The account's token for relay setup.
- public var accountToken: (() async -> String?)?
+ /// The account's token for relay setup (`true`: refresh it even if it
+ /// looks valid). nil when no one is signed in; throws when it could not
+ /// be read or refreshed (offline, the vault), which is not "signed out".
+ public var accountToken: ((_ forceRefresh: Bool) async throws -> String?)?
+ /// Signs in to Cua (opens the browser and waits): true once signed in.
+ /// "Set up for access" runs it inline when relay setup has no account,
+ /// then carries on by itself.
+ public var signIn: (() async -> Bool)?
+ /// What a running "Set up for access" is waiting for, under the form
+ /// (finishing the sign-in in the browser); nil otherwise.
+ public private(set) var progress: String?
+ /// Waits before trying the account token again after a network error
+ /// (tests set them to zero).
+ var tokenRetryDelays: [Duration] = [.seconds(1), .seconds(3)]
+
+ static let signInProgress =
+ "Sign in to Cua in your browser to continue. Setup finishes on its own after that."
/// Called whenever the state changes (the roster's entry follows it).
public var onChange: (() -> Void)?
@@ -163,19 +178,82 @@ public final class HostModel {
public func submit() async {
guard let host, let view = formView, view.canSubmit, let request = view.request else { return }
send(.submit)
+ defer { progress = nil }
do {
- let token: String? = request.mode == "relay" ? await accountToken?() : nil
- let status = try await host.setupRequest(request: request, accountToken: token)
+ let status = request.mode == "relay"
+ ? try await setUpRelay(host, request)
+ : try await host.setupRequest(request: request, accountToken: nil)
form = nil
setupFailure = nil
apply(status)
} catch {
let raw = LiveSpacesBackend.words(error)
- setupFailure = HostSetupFailure.presenting(raw)
+ setupFailure = Self.isUnauthenticated(error)
+ ? HostSetupFailure.presenting(raw, as: .signedOut)
+ : HostSetupFailure.presenting(raw)
send(.failed(error: raw))
}
}
+ /// Relay setup always runs with a valid account token: signed out (or a
+ /// session that can no longer refresh) signs in first, inline; a token
+ /// the relay refuses is refreshed once, then signed in again.
+ private func setUpRelay(_ host: HostRunning, _ request: AppHostSetupRequest) async throws -> HostStatus {
+ // No account wired (fixtures, captures): the host decides.
+ guard accountToken != nil else { return try await host.setupRequest(request: request, accountToken: nil) }
+ let token = try await validToken(forceRefresh: false)
+ do {
+ return try await host.setupRequest(request: request, accountToken: token)
+ } catch let error where Self.isUnauthenticated(error) {
+ // The relay refused it (expired early, revoked, clock skew):
+ // refresh it, then sign in again if that fails too.
+ let fresh = try await validToken(forceRefresh: true)
+ return try await host.setupRequest(request: request, accountToken: fresh)
+ }
+ }
+
+ /// The account's token, signing in first when there is none.
+ private func validToken(forceRefresh: Bool) async throws -> String {
+ if let token = try await readToken(forceRefresh: forceRefresh) { return token }
+ guard let signIn else { throw HostSetupAuthError.signedOut }
+ progress = Self.signInProgress
+ let signedIn = await signIn()
+ progress = nil
+ guard signedIn else { throw HostSetupAuthError.signInNotFinished }
+ if let token = try await readToken(forceRefresh: false) { return token }
+ throw HostSetupAuthError.signedOut
+ }
+
+ /// One token read: nil when signed out (or refused for good), a network
+ /// error tried again with backoff before it is reported as one.
+ private func readToken(forceRefresh: Bool) async throws -> String? {
+ guard let accountToken else { return nil }
+ var waits = tokenRetryDelays[...]
+ while true {
+ do {
+ let token = try await accountToken(forceRefresh)
+ return token?.isEmpty == false ? token : nil
+ } catch let error where Self.isUnauthenticated(error) {
+ return nil
+ } catch let error where Self.isTransient(error) && !waits.isEmpty {
+ try? await Task.sleep(for: waits.removeFirst())
+ }
+ }
+ }
+
+ static func isUnauthenticated(_ error: Error) -> Bool {
+ if case CuaError.Unauthenticated = error { return true }
+ if let e = error as? HostSetupAuthError { return e == .signedOut }
+ return false
+ }
+
+ static func isTransient(_ error: Error) -> Bool {
+ switch error {
+ case CuaError.Http, CuaError.Timeout, CuaError.Transport: return true
+ default: return false
+ }
+ }
+
// MARK: - Page buttons
public func run(_ id: AppHostActionId) async {
@@ -207,3 +285,21 @@ public final class HostModel {
}
}
}
+
+/// Why relay host setup could not get an account token. The words are what
+/// `HostSetupFailure` shows (as "Sign in to Cua").
+public enum HostSetupAuthError: Error, Equatable, LocalizedError, CustomStringConvertible {
+ /// No one is signed in to Cua on this Mac.
+ case signedOut
+ /// The inline sign-in was cancelled or did not finish.
+ case signInNotFinished
+
+ public var description: String {
+ switch self {
+ case .signedOut: return "Not signed in to Cua: sign in to set up this Mac for access."
+ case .signInNotFinished: return "Not signed in to Cua: the sign-in did not finish."
+ }
+ }
+
+ public var errorDescription: String? { description }
+}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostSetupFailure.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostSetupFailure.swift
index be5cf34a08..66142ad6c8 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostSetupFailure.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/HostSetupFailure.swift
@@ -29,6 +29,18 @@ public struct HostSetupFailure: Equatable, Sendable {
public static let retryingLabel = "Retrying\u{2026}"
public static let detailsLabel = "Details"
public static let copyLabel = "Copy"
+ public static let signInLabel = "Sign In"
+
+ /// A failure whose kind the error itself says (the account refused,
+ /// whatever its words), with the raw error as details.
+ public static func presenting(_ raw: String, as kind: Kind) -> HostSetupFailure {
+ let (title, message) = words(kind)
+ return HostSetupFailure(kind: kind, title: title, message: message, details: raw)
+ }
+
+ /// The failure's button: Sign In when the account is what is missing
+ /// (it signs in inline, then sets up), Retry otherwise.
+ public var actionLabel: String { kind == .signedOut ? Self.signInLabel : Self.retryLabel }
/// Maps the raw setup error to what the sheet shows.
public static func presenting(_ raw: String) -> HostSetupFailure {
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/OnboardingModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/OnboardingModel.swift
index 46ea76c5b0..1ed6db8437 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/OnboardingModel.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/OnboardingModel.swift
@@ -30,7 +30,7 @@ public final class OnboardingModel {
/// This machine's host setup (the same form and host as the main window).
public let host: HostModel
/// The signed-in account's token, for relay host setup.
- public var accountToken: (() async -> String?)? {
+ public var accountToken: ((_ forceRefresh: Bool) async throws -> String?)? {
get { host.accountToken }
set { host.accountToken = newValue }
}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/OnboardingView.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/OnboardingView.swift
index c32bc366c7..41398634f8 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/OnboardingView.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/OnboardingView.swift
@@ -226,6 +226,10 @@ public struct OnboardingView: View {
}
.padding(.horizontal, 20)
}
+ if let progress = onboarding.host.progress {
+ HostSetupProgressView(text: progress)
+ .padding(.horizontal, 20)
+ }
}
} else {
VStack(alignment: .leading, spacing: 10) {
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/ThisMachineView.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/ThisMachineView.swift
index e89bb5c012..1ad8a33c5a 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/ThisMachineView.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/ThisMachineView.swift
@@ -241,6 +241,9 @@ struct HostFormView: View {
Task { await host.submit() }
}
}
+ if showsFailure, let progress = host.progress {
+ HostSetupProgressView(text: progress)
+ }
}
if buttons {
Section {
@@ -291,6 +294,22 @@ struct HostFormView: View {
/// A failed "Set up for access": a small warning symbol and a short title,
/// one secondary line saying what to do, Retry, and the raw error under a
/// collapsed Details (selectable, with Copy).
+/// What a running "Set up for access" waits for (the inline sign-in).
+struct HostSetupProgressView: View {
+ let text: String
+
+ var body: some View {
+ HStack(alignment: .firstTextBaseline, spacing: 6) {
+ ProgressView().controlSize(.small)
+ Text(text)
+ .font(.callout)
+ .foregroundStyle(.secondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
+ .accessibilityIdentifier("host-setup-progress")
+ }
+}
+
struct HostSetupFailureView: View {
let failure: HostSetupFailure
/// The retry is running: Retry shows progress and is disabled.
@@ -310,7 +329,7 @@ struct HostSetupFailureView: View {
Button(action: retry) {
HStack(spacing: 6) {
if retrying { ProgressView().controlSize(.small) }
- Text(retrying ? HostSetupFailure.retryingLabel : HostSetupFailure.retryLabel)
+ Text(retrying ? HostSetupFailure.retryingLabel : failure.actionLabel)
}
}
.controlSize(.small)
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/HostSetupAuthTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/HostSetupAuthTests.swift
new file mode 100644
index 0000000000..ee5645ba55
--- /dev/null
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/HostSetupAuthTests.swift
@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import CuaSDK
+import CuaSpacesFFI
+@testable import CuaSpacesMacKit
+import Foundation
+import Testing
+
+/// A host whose setups answer from a script (then succeed), recording the
+/// token each one got. No service, no network.
+final class ScriptedHost: HostRunning, @unchecked Sendable {
+ let inner = FixtureHost()
+ var script: [Error] = []
+ private(set) var tokens: [String?] = []
+
+ func setupRequest(request: AppHostSetupRequest, accountToken: String?) async throws -> HostStatus {
+ tokens.append(accountToken)
+ if !script.isEmpty { throw script.removeFirst() }
+ return try await inner.setupRequest(request: request, accountToken: accountToken)
+ }
+
+ func status() async throws -> HostStatus { try await inner.status() }
+ func stopSharing() async throws -> HostStatus { try await inner.stopSharing() }
+ func startSharing() async throws -> HostStatus { try await inner.startSharing() }
+ func remove() async throws { try await inner.remove() }
+ func configure(change: HostSettingsChange) async throws -> HostStatus { try await inner.configure(change: change) }
+}
+
+/// The account as host setup sees it: a token store that can be signed
+/// out, offline, or refuse to refresh, and a sign-in that can finish or not.
+@MainActor
+final class FakeAccountTokens {
+ /// The session's token; nil is signed out.
+ var token: String?
+ /// What a forced refresh yields (nil: the refresh was refused).
+ var refreshed: String?
+ /// The next reads fail with these first.
+ var failures: [Error] = []
+ /// What a sign-in leaves signed in as (nil: cancelled).
+ var signInGives: String?
+ private(set) var reads: [Bool] = []
+ private(set) var signIns = 0
+ /// The progress the form showed while the sign-in ran.
+ private(set) var progressDuringSignIn: String?
+
+ func wire(_ model: HostModel) {
+ model.tokenRetryDelays = [.zero, .zero]
+ model.accountToken = { [unowned self] force in
+ self.reads.append(force)
+ if !self.failures.isEmpty { throw self.failures.removeFirst() }
+ if force {
+ self.token = self.refreshed
+ }
+ return self.token
+ }
+ model.signIn = { [unowned self, unowned model] in
+ self.signIns += 1
+ self.progressDuringSignIn = model.progress
+ self.token = self.signInGives
+ return self.signInGives != nil
+ }
+ }
+}
+
+@MainActor
+@Suite("Host setup account")
+struct HostSetupAuthTests {
+ func model(_ host: ScriptedHost, _ account: FakeAccountTokens) -> HostModel {
+ let m = HostModel(host: host)
+ account.wire(m)
+ m.openForm()
+ return m
+ }
+
+ @Test func signedInRunsSetupWithTheToken() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens == ["tok-1"])
+ #expect(account.signIns == 0)
+ #expect(m.form == nil && m.setupFailure == nil)
+ #expect(m.state?.configured == true)
+ }
+
+ /// The launch bug: onboarding allows skipping sign-in, and 0.3.0/0.3.1
+ /// then ran relay setup with no token, failing `unauthenticated`. Now
+ /// "Set up for access" signs in inline and carries on.
+ @Test func signedOutSignsInInlineThenFinishesSetup() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.signInGives = "tok-new"
+ let m = model(host, account)
+ await m.submit()
+ #expect(account.signIns == 1)
+ #expect(account.progressDuringSignIn == HostModel.signInProgress)
+ #expect(host.tokens == ["tok-new"], "setup never runs without a token")
+ #expect(m.form == nil && m.setupFailure == nil)
+ #expect(m.progress == nil)
+ #expect(m.state?.configured == true)
+ }
+
+ @Test func aCancelledSignInIsASignInFailureWithSignInAsItsButton() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens.isEmpty, "the relay is never asked without an account")
+ let f = try? #require(m.setupFailure)
+ #expect(f?.kind == .signedOut)
+ #expect(f?.actionLabel == "Sign In")
+ #expect(m.form != nil && m.progress == nil)
+
+ // Sign In (the failure's button) runs the same flow again.
+ account.signInGives = "tok-2"
+ await m.submit()
+ #expect(host.tokens == ["tok-2"])
+ #expect(m.setupFailure == nil && m.form == nil)
+ }
+
+ @Test func aNetworkErrorReadingTheTokenIsRetriedNotTakenAsSignedOut() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ account.failures = [CuaError.Http(message: "auth.cua.ai: connection reset"),
+ CuaError.Timeout(message: "refresh timed out")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(account.reads.count == 3)
+ #expect(account.signIns == 0)
+ #expect(host.tokens == ["tok-1"])
+ #expect(m.setupFailure == nil)
+ }
+
+ @Test func offlineStaysANetworkFailureWithRetry() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ account.failures = Array(repeating: CuaError.Http(
+ message: "error sending request for url (https://auth.cua.ai/token): connection refused"), count: 5)
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens.isEmpty)
+ #expect(account.signIns == 0, "offline is not signed out")
+ #expect(m.setupFailure?.kind == .network)
+ #expect(m.setupFailure?.actionLabel == "Retry")
+ }
+
+ /// The old closure turned any token error (vault, network) into nil,
+ /// which reached the relay as "not signed in". Now the error is shown.
+ @Test func aVaultErrorIsShownNotSentAsNoToken() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ account.failures = [CuaError.Internal(message: "credential store: keychain is locked")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens.isEmpty)
+ #expect(m.setupFailure?.details.contains("keychain is locked") == true)
+ #expect(m.setupFailure?.kind != .signedOut)
+ }
+
+ @Test func aTokenTheRelayRefusesIsRefreshedOnceThenSetupFinishes() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-stale"
+ account.refreshed = "tok-fresh"
+ host.script = [CuaError.Unauthenticated(message: "relay: invalid account token: ExpiredSignature")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(account.reads == [false, true])
+ #expect(host.tokens == ["tok-stale", "tok-fresh"])
+ #expect(account.signIns == 0)
+ #expect(m.setupFailure == nil && m.form == nil)
+ }
+
+ @Test func aRefreshTheAccountRefusesSignsInAgainThenFinishes() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-stale"
+ account.refreshed = nil
+ account.signInGives = "tok-new"
+ host.script = [CuaError.Unauthenticated(message: "relay: invalid account token")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(account.signIns == 1)
+ #expect(host.tokens == ["tok-stale", "tok-new"])
+ #expect(m.setupFailure == nil)
+ }
+
+ @Test func aRelayThatKeepsRefusingIsASignInFailure() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ account.refreshed = "tok-2"
+ host.script = [CuaError.Unauthenticated(message: "relay: invalid account token"),
+ CuaError.Unauthenticated(message: "relay: invalid account token")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens == ["tok-1", "tok-2"], "one refresh, not a loop")
+ #expect(m.setupFailure?.kind == .signedOut)
+ }
+
+ @Test func otherSetupFailuresAreNotRetriedWithANewToken() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ account.token = "tok-1"
+ host.script = [CuaError.Http(message: "download: https://x/cua-spacesd.tar.gz: HTTP 404 Not Found")]
+ let m = model(host, account)
+ await m.submit()
+ #expect(host.tokens == ["tok-1"])
+ #expect(account.reads == [false])
+ #expect(m.setupFailure?.kind == .download)
+ #expect(m.setupFailure?.actionLabel == "Retry")
+ }
+
+ @Test func directSetupNeedsNoAccount() async {
+ let host = ScriptedHost(), account = FakeAccountTokens()
+ let m = model(host, account)
+ m.send(.setDirect(on: true))
+ m.send(.setListen(listen: "10.0.0.2:3211"))
+ await m.submit()
+ #expect(account.reads.isEmpty && account.signIns == 0)
+ #expect(host.tokens == [nil])
+ }
+
+ @Test func withoutAnAccountWiredTheHostDecides() async {
+ let host = ScriptedHost()
+ let m = HostModel(host: host)
+ m.openForm()
+ await m.submit()
+ #expect(host.tokens == [nil])
+ }
+}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/OnboardingTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/OnboardingTests.swift
index 5f51b2edc0..fcd668c478 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/OnboardingTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/OnboardingTests.swift
@@ -183,7 +183,7 @@ struct OnboardingTests {
@Test func hostSetupRunsWithTheAccountTokenThenFinishes() async {
let host = FakeHost()
let o = model(host: host)
- o.accountToken = { "tok-1" }
+ o.accountToken = { _ in "tok-1" }
toMode(o)
#expect(o.view.step == .mode)
#expect(o.view.choices.map(\.mode) == [.client, .host])
@@ -211,7 +211,7 @@ struct OnboardingTests {
@Test func directSetupNeedsAnAddressAndSendsNoToken() async {
let host = FakeHost()
let o = model(host: host)
- o.accountToken = { "tok-1" }
+ o.accountToken = { _ in "tok-1" }
toMode(o)
o.host.openForm()
o.host.send(.toggleAdvanced)
diff --git a/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx b/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
index 6790596a94..767e755e24 100644
--- a/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
+++ b/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
@@ -40,7 +40,7 @@ Every event carries: `telemetry_schema_version`, `event_version`, `product`
| `cua_space_create` | `location`, `guest_os`, `kind`, `outcome` (`ok`, `error`, or `cancelled` when Cancel was pressed while it was being created), `failed_phase` (the phase it failed or was cancelled in, or `none`), `stalled`, `time_bucket` (to ready, the failure, or the cancel finishing), `gpu` | Space create success, failure and cancel rates, time to ready, and which phase fails. |
| `cua_volume_setup` | `surface` (`onboarding` or `settings`), `storage` (`this_mac`, `s3`, `later`), `add_to_finder`, `mount_method` (`fskit`, `nfs`, `fuse`, `none`, `unknown`), `outcome` | Cua Volume adoption. |
| `cua_persistent_agent` | `action` (`create`, `pause`, `resume`, `routine_add`, ...), `harness`, `outcome`, `error_kind` | Persistent agents and routines adoption. |
-| `cua_host_setup` | `mode` (`relay` or `direct`), `profile` (`desktop`, `spare`, `both`), `outcome`, `error_kind` | Machines set up for access. |
+| `cua_host_setup` | `mode` (`relay` or `direct`), `profile` (`desktop`, `spare`, `both`), `outcome`, `error_kind`, `signed_in`, `token_state` (`provided`, `expired`, `missing`, `not_needed`; never the token), `failed_stage` (`none`, `preflight`, `token`, `register`, `download`, `service`), `http_status` (the status a server answered a failure with, `0` when none) | Machines set up for access, and where a failed setup stopped. |
| `cua_host_space_provided` | `kind`, `guest_os`, `outcome`, `error_kind` | Spaces a host machine created for your other devices. |
| `cua_keyvault_action` | `action` (`setup`, `unlock`, `lock`, `import`, `site_login`), `method` (`os_key_store`, which is Touch ID on a Mac, `passphrase`, `recovery_key`, `none`), `outcome` | Keyvault adoption and how it is unlocked. Nothing about what is stored. |
| `cua_share` | `action` (`share`, `unshare`, `change_role`), `role` (`viewer`, `editor`, `none`), `outcome` | Sharing, and how often it is view-only. Never who. |
diff --git a/libs/cua/crates/cua-host/src/driver.rs b/libs/cua/crates/cua-host/src/driver.rs
index b002dc440a..fdcf74a163 100644
--- a/libs/cua/crates/cua-host/src/driver.rs
+++ b/libs/cua/crates/cua-host/src/driver.rs
@@ -250,6 +250,9 @@ fn allowed_download_url(url: &url::Url) -> bool {
#[derive(Debug)]
struct FetchError {
missing: bool,
+ /// Worth trying again: no connection, a timeout, a dropped transfer,
+ /// or a 5xx / 429 from the server or its CDN.
+ transient: bool,
message: String,
}
@@ -257,11 +260,36 @@ impl FetchError {
fn other(message: String) -> Self {
Self {
missing: false,
+ transient: false,
+ message,
+ }
+ }
+
+ fn network(message: String, e: &reqwest::Error) -> Self {
+ Self {
+ missing: false,
+ transient: e.is_connect() || e.is_timeout() || e.is_body() || e.is_request(),
+ message,
+ }
+ }
+
+ fn status(message: String, status: reqwest::StatusCode) -> Self {
+ Self {
+ missing: is_missing(status),
+ transient: status.is_server_error() || status == reqwest::StatusCode::TOO_MANY_REQUESTS,
message,
}
}
}
+/// Times a download is tried again after a transient failure.
+const FETCH_RETRIES: u32 = 3;
+/// The first wait before trying again (doubling each time).
+#[cfg(not(test))]
+const FETCH_RETRY_BASE: std::time::Duration = std::time::Duration::from_secs(1);
+#[cfg(test)]
+const FETCH_RETRY_BASE: std::time::Duration = std::time::Duration::from_millis(5);
+
impl From<FetchError> for Error {
fn from(e: FetchError) -> Self {
Error::Download(e.message)
@@ -298,6 +326,22 @@ pub async fn download_verified(url: &str) -> Result<Vec<u8>> {
}
async fn fetch_verified(url: &str) -> std::result::Result<Vec<u8>, FetchError> {
+ let mut delay = FETCH_RETRY_BASE;
+ let mut attempt = 0;
+ loop {
+ match fetch_verified_once(url).await {
+ Err(e) if e.transient && attempt < FETCH_RETRIES => {
+ attempt += 1;
+ tracing::warn!(attempt, "download failed, retrying: {}", e.message);
+ tokio::time::sleep(delay).await;
+ delay *= 2;
+ }
+ r => return r,
+ }
+ }
+}
+
+async fn fetch_verified_once(url: &str) -> std::result::Result<Vec<u8>, FetchError> {
let parsed = url::Url::parse(url).map_err(|e| FetchError::other(format!("{url}: {e}")))?;
if !allowed_download_url(&parsed) {
return Err(FetchError::other(format!(
@@ -310,12 +354,12 @@ async fn fetch_verified(url: &str) -> std::result::Result<Vec<u8>, FetchError> {
.get(url)
.send()
.await
- .map_err(|e| FetchError::other(format!("{url}: {e}")))?;
+ .map_err(|e| FetchError::network(format!("{url}: {e}"), &e))?;
if !resp.status().is_success() {
- return Err(FetchError {
- missing: is_missing(resp.status()),
- message: format!("{url}: HTTP {}", resp.status()),
- });
+ return Err(FetchError::status(
+ format!("{url}: HTTP {}", resp.status()),
+ resp.status(),
+ ));
}
if resp
.content_length()
@@ -326,7 +370,7 @@ async fn fetch_verified(url: &str) -> std::result::Result<Vec<u8>, FetchError> {
let bytes = resp
.bytes()
.await
- .map_err(|e| FetchError::other(format!("{url}: {e}")))?;
+ .map_err(|e| FetchError::network(format!("{url}: {e}"), &e))?;
if bytes.len() > MAX_ARCHIVE_BYTES {
return Err(FetchError::other(format!("{url}: archive too large")));
}
@@ -335,20 +379,20 @@ async fn fetch_verified(url: &str) -> std::result::Result<Vec<u8>, FetchError> {
.get(&sum_url)
.send()
.await
- .map_err(|e| FetchError::other(format!("{sum_url}: {e}")))?;
+ .map_err(|e| FetchError::network(format!("{sum_url}: {e}"), &e))?;
if !r.status().is_success() {
- return Err(FetchError {
- missing: is_missing(r.status()),
- message: format!(
+ return Err(FetchError::status(
+ format!(
"{sum_url}: HTTP {} (a published checksum is required)",
r.status()
),
- });
+ r.status(),
+ ));
}
let text = r
.text()
.await
- .map_err(|e| FetchError::other(format!("{sum_url}: {e}")))?;
+ .map_err(|e| FetchError::network(format!("{sum_url}: {e}"), &e))?;
let expected = text
.split_whitespace()
.next()
@@ -938,4 +982,91 @@ mod tests {
assert_eq!(parse_version("v0.2.0"), Some((0, 2, 0)));
assert_eq!(parse_version("0.2.0-rc.1"), None);
}
+
+ /// A CDN that answers 503 (or drops the connection) a couple of times
+ /// is tried again; a 404 is not (the release fallback handles it), and
+ /// a server that keeps failing gives up after the retries.
+ #[tokio::test]
+ async fn downloads_retry_transient_failures_but_not_missing_files() {
+ use axum::{Router, http::StatusCode, routing::get};
+ use std::sync::Arc;
+ use std::sync::atomic::{AtomicUsize, Ordering};
+ let archive = tar_gz(binary_name(), b"driver-bytes");
+ let sum = format!(
+ "{} a.tar.gz\n",
+ hex::encode(sha2::Sha256::digest(&archive))
+ );
+ let (flaky, down, gone) = (
+ Arc::new(AtomicUsize::new(0)),
+ Arc::new(AtomicUsize::new(0)),
+ Arc::new(AtomicUsize::new(0)),
+ );
+ let app = Router::new()
+ .route(
+ "/flaky/a.tar.gz",
+ get({
+ let (n, body) = (flaky.clone(), archive.clone());
+ move || async move {
+ if n.fetch_add(1, Ordering::SeqCst) < 2 {
+ (StatusCode::SERVICE_UNAVAILABLE, Vec::new())
+ } else {
+ (StatusCode::OK, body)
+ }
+ }
+ }),
+ )
+ .route("/flaky/a.tar.gz.sha256", get(move || async move { sum }))
+ .route(
+ "/down/a.tar.gz",
+ get({
+ let n = down.clone();
+ move || async move {
+ n.fetch_add(1, Ordering::SeqCst);
+ StatusCode::BAD_GATEWAY
+ }
+ }),
+ )
+ .route(
+ "/gone/a.tar.gz",
+ get({
+ let n = gone.clone();
+ move || async move {
+ n.fetch_add(1, Ordering::SeqCst);
+ StatusCode::NOT_FOUND
+ }
+ }),
+ );
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let base = format!("http://{}", listener.local_addr().unwrap());
+ tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+
+ assert_eq!(
+ download_verified(&format!("{base}/flaky/a.tar.gz"))
+ .await
+ .unwrap(),
+ archive
+ );
+ assert_eq!(flaky.load(Ordering::SeqCst), 3);
+
+ let err = download_verified(&format!("{base}/down/a.tar.gz"))
+ .await
+ .unwrap_err();
+ assert_eq!(down.load(Ordering::SeqCst), 1 + FETCH_RETRIES as usize);
+ assert_eq!(err.http_status(), Some(502), "{err}");
+
+ let err = download_verified(&format!("{base}/gone/a.tar.gz"))
+ .await
+ .unwrap_err();
+ assert_eq!(gone.load(Ordering::SeqCst), 1);
+ assert_eq!(err.http_status(), Some(404), "{err}");
+
+ // Nothing listening: refused at once, tried again, then given up.
+ let closed = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = closed.local_addr().unwrap();
+ drop(closed);
+ let err = download_verified(&format!("http://{addr}/a.tar.gz"))
+ .await
+ .unwrap_err();
+ assert_eq!(err.http_status(), None, "{err}");
+ }
}
diff --git a/libs/cua/crates/cua-host/src/host.rs b/libs/cua/crates/cua-host/src/host.rs
index 7f8dbd98ed..d790a9a166 100644
--- a/libs/cua/crates/cua-host/src/host.rs
+++ b/libs/cua/crates/cua-host/src/host.rs
@@ -10,6 +10,34 @@ use std::net::SocketAddr;
use std::path::{Path, PathBuf};
use std::sync::Arc;
+/// Where a host setup stopped (see [`Host::setup_staged`]).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SetupStage {
+ /// Checking the request and this machine (GUI session, address).
+ Preflight,
+ /// Getting the account's token (relay mode).
+ Token,
+ /// Registering with the relay.
+ Register,
+ /// Getting cua-spacesd (download or local copy).
+ Download,
+ /// Installing and starting the host service.
+ Service,
+}
+
+impl SetupStage {
+ /// The stage as usage data and logs spell it.
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::Preflight => "preflight",
+ Self::Token => "token",
+ Self::Register => "register",
+ Self::Download => "download",
+ Self::Service => "service",
+ }
+ }
+}
+
/// How clients reach this machine.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum HostMode {
@@ -751,6 +779,29 @@ impl Host {
&self,
opts: SetupOptions,
tokens: &dyn AccountTokens,
+ ) -> Result<HostStatus> {
+ self.setup_staged(opts, tokens).await.map_err(|(_, e)| e)
+ }
+
+ /// [`Host::setup`], saying on failure which stage stopped it (usage
+ /// data and the apps' messages tell "not signed in" from "the relay
+ /// refused the account" from "the download failed").
+ pub async fn setup_staged(
+ &self,
+ opts: SetupOptions,
+ tokens: &dyn AccountTokens,
+ ) -> std::result::Result<HostStatus, (SetupStage, Error)> {
+ let mut stage = SetupStage::Preflight;
+ self.setup_inner(opts, tokens, &mut stage)
+ .await
+ .map_err(|e| (stage, e))
+ }
+
+ async fn setup_inner(
+ &self,
+ opts: SetupOptions,
+ tokens: &dyn AccountTokens,
+ stage: &mut SetupStage,
) -> Result<HostStatus> {
let runner = match &self.manager {
Some(m) => m.kind(),
@@ -801,7 +852,9 @@ impl Host {
match &opts.mode {
HostMode::Relay { url } => {
let relay = RelayClient::new(url)?;
+ *stage = SetupStage::Token;
let token = tokens.access_token().await?;
+ *stage = SetupStage::Register;
let id = load_or_create_machine_id(&self.paths.machine_id)?;
// Re-running setup proves it is this machine with its current
// machine token; the account session is used only for this
@@ -868,6 +921,7 @@ impl Host {
write_json(&self.paths.policy(), &policy)?;
}
}
+ *stage = SetupStage::Download;
let source = driver::locate(opts.driver_bin.as_deref())?;
match &source {
DriverSource::Download(url) => tracing::info!(%url, "downloading cua-spacesd"),
@@ -877,6 +931,7 @@ impl Host {
DriverSource::Local(_) => {}
}
driver::install_to(&source, &config.driver_bin).await?;
+ *stage = SetupStage::Service;
write_json(&self.paths.config(), &config)?;
let manager = self.manager(runner);
manager.install(&self.service_spec(&config))?;
diff --git a/libs/cua/crates/cua-host/src/lib.rs b/libs/cua/crates/cua-host/src/lib.rs
index c8ea5bae1c..87e24db44d 100644
--- a/libs/cua/crates/cua-host/src/lib.rs
+++ b/libs/cua/crates/cua-host/src/lib.rs
@@ -41,12 +41,15 @@ pub mod preflight;
pub mod provided;
pub mod relay;
pub mod service;
+#[cfg(test)]
+mod setup_tests;
#[cfg(any(test, feature = "testing"))]
pub mod testing;
#[cfg(test)]
mod tests;
pub use device::{DeviceAuth, DeviceKey, FileKeySlot, KeySlot, MemoryKeySlot};
+pub use host::SetupStage;
pub use host::{
DirectHosting, Host, HostConfig, HostMode, HostPaths, HostPolicy, HostSettingsChange,
HostStatus, PermissionHint, SetupOptions, SpacesDaemon, permission_hints,
@@ -108,5 +111,31 @@ pub enum Error {
Internal(String),
}
+impl Error {
+ /// The HTTP status the relay or the download server answered with,
+ /// when one did. None: the server was not reached (offline, DNS, TLS,
+ /// timeout) or the error is not about HTTP at all.
+ pub fn http_status(&self) -> Option<u16> {
+ match self {
+ // `relay::http_error` maps these statuses to these variants.
+ Error::Unauthenticated(m) if m.starts_with("relay: ") => Some(401),
+ Error::PermissionDenied(m) if m.starts_with("relay: ") => Some(403),
+ Error::NotFound(m) if m.starts_with("relay: ") => Some(404),
+ Error::Conflict(m) if m.starts_with("relay: ") => Some(409),
+ Error::Relay(m) | Error::Download(m) => status_in(m),
+ _ => None,
+ }
+ }
+}
+
+/// The status in an "HTTP 503: ..." / "<url>: HTTP 404 Not Found" message.
+fn status_in(message: &str) -> Option<u16> {
+ message.match_indices("HTTP ").find_map(|(i, _)| {
+ let digits = message.get(i + 5..i + 8)?;
+ let code: u16 = digits.parse().ok()?;
+ (100..600).contains(&code).then_some(code)
+ })
+}
+
/// Result alias.
pub type Result<T> = std::result::Result<T, Error>;
diff --git a/libs/cua/crates/cua-host/src/relay.rs b/libs/cua/crates/cua-host/src/relay.rs
index 4d699fd163..70dfdd51e6 100644
--- a/libs/cua/crates/cua-host/src/relay.rs
+++ b/libs/cua/crates/cua-host/src/relay.rs
@@ -377,6 +377,14 @@ pub struct DeviceSession {
pub expires_at: u64,
}
+/// Times a machine registration is tried again after a transient failure.
+const REGISTER_RETRIES: u32 = 3;
+/// The first wait before trying again (doubling each time).
+#[cfg(not(test))]
+const REGISTER_RETRY_BASE: Duration = Duration::from_secs(1);
+#[cfg(test)]
+const REGISTER_RETRY_BASE: Duration = Duration::from_millis(5);
+
/// HTTP client for one relay.
#[derive(Clone, Debug)]
pub struct RelayClient {
@@ -427,6 +435,17 @@ impl RelayClient {
req: reqwest::RequestBuilder,
bearer: &str,
) -> Result<T> {
+ self.send_once(req, bearer).await.map_err(|(e, _)| e)
+ }
+
+ /// One request. On failure, also whether the relay certainly did not
+ /// act on it and it may be sent again: the connection never opened, or
+ /// the relay (or the proxy in front of it) answered 429, 502 or 503.
+ async fn send_once<T: serde::de::DeserializeOwned>(
+ &self,
+ req: reqwest::RequestBuilder,
+ bearer: &str,
+ ) -> std::result::Result<T, (Error, bool)> {
let mut req = req.bearer_auth(bearer);
if let Some(session) = &self.device_session {
req = req.header(DEVICE_SESSION_HEADER, session);
@@ -434,18 +453,23 @@ impl RelayClient {
let resp = req
.send()
.await
- .map_err(|e| Error::Relay(format!("{}: {e}", self.base)))?;
+ .map_err(|e| (Error::Relay(format!("{}: {e}", self.base)), e.is_connect()))?;
let status = resp.status();
- let body = resp.text().await.map_err(|e| Error::Relay(e.to_string()))?;
+ let body = resp
+ .text()
+ .await
+ .map_err(|e| (Error::Relay(e.to_string()), false))?;
if !status.is_success() {
- return Err(http_error(status.as_u16(), &body));
+ let retry = matches!(status.as_u16(), 429 | 502 | 503);
+ return Err((http_error(status.as_u16(), &body), retry));
}
let body = if body.trim().is_empty() {
"null"
} else {
&body
};
- serde_json::from_str(body).map_err(|e| Error::Relay(format!("bad relay response: {e}")))
+ serde_json::from_str(body)
+ .map_err(|e| (Error::Relay(format!("bad relay response: {e}")), false))
}
/// `GET /v1/info` (no auth).
@@ -504,11 +528,28 @@ impl RelayClient {
machine_token: Option<&str>,
req: &RegisterRequest,
) -> Result<Registration> {
- let mut builder = self.http.post(self.url("/v1/machines")).json(req);
- if let Some(t) = machine_token.filter(|t| !t.is_empty()) {
- builder = builder.header(MACHINE_AUTHORIZATION_HEADER, format!("Bearer {t}"));
+ // A relay that is briefly unreachable or overloaded (a deploy, a
+ // flaky Wi-Fi) is tried again with backoff. Only failures where the
+ // relay certainly did not register the machine are retried: a
+ // second registration of one it did register would need the new
+ // machine token, which the lost answer carried.
+ let mut delay = REGISTER_RETRY_BASE;
+ let mut attempt = 0;
+ loop {
+ let mut builder = self.http.post(self.url("/v1/machines")).json(req);
+ if let Some(t) = machine_token.filter(|t| !t.is_empty()) {
+ builder = builder.header(MACHINE_AUTHORIZATION_HEADER, format!("Bearer {t}"));
+ }
+ match self.send_once(builder, account_token).await {
+ Err((e, true)) if attempt < REGISTER_RETRIES => {
+ attempt += 1;
+ tracing::warn!(attempt, "relay registration failed, retrying: {e}");
+ tokio::time::sleep(delay).await;
+ delay *= 2;
+ }
+ r => return r.map_err(|(e, _)| e),
+ }
}
- self.send(builder, account_token).await
}
/// Registers the client device with `public_key` (see
diff --git a/libs/cua/crates/cua-host/src/setup_tests.rs b/libs/cua/crates/cua-host/src/setup_tests.rs
new file mode 100644
index 0000000000..c10e909de4
--- /dev/null
+++ b/libs/cua/crates/cua-host/src/setup_tests.rs
@@ -0,0 +1,186 @@
+//! Host setup's auth and network failures: which stage stopped it, the
+//! HTTP status behind it, and the transient relay failures it rides out.
+
+use crate::service::FakeServiceManager;
+use crate::testing::FakeRelay;
+use crate::*;
+use std::sync::Arc;
+
+struct Fixture {
+ _dir: tempfile::TempDir,
+ home: std::path::PathBuf,
+ driver: std::path::PathBuf,
+ manager: Arc<FakeServiceManager>,
+}
+
+fn fixture() -> Fixture {
+ let dir = tempfile::tempdir().unwrap();
+ let driver = dir.path().join("bundled-cua-spacesd");
+ std::fs::write(&driver, b"#!/bin/sh\n").unwrap();
+ Fixture {
+ home: dir.path().join(".cua"),
+ driver,
+ manager: Arc::new(FakeServiceManager::default()),
+ _dir: dir,
+ }
+}
+
+impl Fixture {
+ fn host(&self) -> Host {
+ Host::new(&self.home).with_service_manager(self.manager.clone())
+ }
+ fn opts(&self, url: &str) -> SetupOptions {
+ let mut o = SetupOptions::relay(url);
+ o.name = Some("mini".into());
+ o.driver_bin = Some(self.driver.clone());
+ o
+ }
+}
+
+#[tokio::test]
+async fn no_account_stops_at_the_token_stage_before_the_relay_is_called() {
+ let relay = FakeRelay::start().await;
+ let f = fixture();
+ let (stage, e) = f
+ .host()
+ .setup_staged(f.opts(&relay.url), &NoAccount)
+ .await
+ .unwrap_err();
+ assert_eq!(stage, SetupStage::Token);
+ assert!(matches!(e, Error::Unauthenticated(_)), "{e}");
+ assert_eq!(e.http_status(), None);
+ assert_eq!(relay.register_calls(), 0);
+ assert!(!f.host().status().await.unwrap().configured);
+}
+
+#[tokio::test]
+async fn a_refused_account_token_is_a_401_at_the_register_stage() {
+ let relay = FakeRelay::start().await;
+ relay.add_account("good", "user-1", None);
+ let f = fixture();
+ let (stage, e) = f
+ .host()
+ .setup_staged(f.opts(&relay.url), &StaticToken("expired".into()))
+ .await
+ .unwrap_err();
+ assert_eq!(stage, SetupStage::Register);
+ assert!(matches!(e, Error::Unauthenticated(_)), "{e}");
+ assert_eq!(e.http_status(), Some(401));
+ // Not retried: the relay answered, and a new token is the fix.
+ assert_eq!(relay.register_calls(), 1);
+ // With a valid token the same setup goes through.
+ assert!(
+ f.host()
+ .setup(f.opts(&relay.url), &StaticToken("good".into()))
+ .await
+ .unwrap()
+ .configured
+ );
+}
+
+#[tokio::test]
+async fn a_relay_briefly_unavailable_is_retried_until_it_registers() {
+ let relay = FakeRelay::start().await;
+ relay.add_account("good", "user-1", None);
+ relay.fail_registrations(&[503, 502, 429]);
+ let f = fixture();
+ let status = f
+ .host()
+ .setup(f.opts(&relay.url), &StaticToken("good".into()))
+ .await
+ .unwrap();
+ assert!(status.configured && status.service.running);
+ assert_eq!(relay.register_calls(), 4);
+}
+
+#[tokio::test]
+async fn a_relay_that_stays_down_fails_at_register_with_its_status() {
+ let relay = FakeRelay::start().await;
+ relay.add_account("good", "user-1", None);
+ relay.fail_registrations(&[503; 10]);
+ let f = fixture();
+ let (stage, e) = f
+ .host()
+ .setup_staged(f.opts(&relay.url), &StaticToken("good".into()))
+ .await
+ .unwrap_err();
+ assert_eq!(stage, SetupStage::Register);
+ assert!(matches!(e, Error::Relay(_)), "{e}");
+ assert_eq!(e.http_status(), Some(503));
+ assert_eq!(relay.register_calls(), 4);
+}
+
+#[tokio::test]
+async fn a_500_may_have_registered_so_it_is_not_sent_again() {
+ let relay = FakeRelay::start().await;
+ relay.add_account("good", "user-1", None);
+ relay.fail_registrations(&[500]);
+ let f = fixture();
+ let (stage, e) = f
+ .host()
+ .setup_staged(f.opts(&relay.url), &StaticToken("good".into()))
+ .await
+ .unwrap_err();
+ assert_eq!((stage, e.http_status()), (SetupStage::Register, Some(500)));
+ assert_eq!(relay.register_calls(), 1);
+}
+
+#[tokio::test]
+async fn an_unreachable_relay_is_retried_then_fails_with_no_status() {
+ let closed = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let url = format!("http://{}", closed.local_addr().unwrap());
+ drop(closed);
+ let f = fixture();
+ let (stage, e) = f
+ .host()
+ .setup_staged(f.opts(&url), &StaticToken("good".into()))
+ .await
+ .unwrap_err();
+ assert_eq!(stage, SetupStage::Register);
+ assert!(matches!(e, Error::Relay(_)), "{e}");
+ assert_eq!(e.http_status(), None);
+}
+
+#[tokio::test]
+async fn a_missing_driver_fails_at_the_download_stage() {
+ let relay = FakeRelay::start().await;
+ relay.add_account("good", "user-1", None);
+ let f = fixture();
+ let mut o = f.opts(&relay.url);
+ o.driver_bin = Some(f.home.join("no-such-cua-spacesd"));
+ let (stage, _) = f
+ .host()
+ .setup_staged(o, &StaticToken("good".into()))
+ .await
+ .unwrap_err();
+ assert_eq!(stage, SetupStage::Download);
+}
+
+#[test]
+fn http_status_reads_relay_and_download_errors() {
+ for (e, want) in [
+ (Error::Relay("HTTP 503: busy".into()), Some(503)),
+ (
+ Error::Download("https://x/a.tar.gz: HTTP 404 Not Found".into()),
+ Some(404),
+ ),
+ (
+ Error::Relay("http://127.0.0.1:9: error sending request".into()),
+ None,
+ ),
+ (
+ Error::Unauthenticated("relay: invalid account token".into()),
+ Some(401),
+ ),
+ (
+ Error::Unauthenticated("not signed in to cua.ai".into()),
+ None,
+ ),
+ (Error::PermissionDenied("relay: no".into()), Some(403)),
+ (Error::Download("archive: HTTP 9".into()), None),
+ (Error::Service("launchctl bootstrap failed".into()), None),
+ ] {
+ assert_eq!(e.http_status(), want, "{e}");
+ }
+ assert_eq!(SetupStage::Register.as_str(), "register");
+}
diff --git a/libs/cua/crates/cua-host/src/testing.rs b/libs/cua/crates/cua-host/src/testing.rs
index 523376c937..d197ab1ea7 100644
--- a/libs/cua/crates/cua-host/src/testing.rs
+++ b/libs/cua/crates/cua-host/src/testing.rs
@@ -67,6 +67,11 @@ struct State_ {
/// Enrollment rules of a relay before sign-in enrollment for every
/// device and re-keying.
legacy: bool,
+ /// Statuses the next machine registrations answer with, in order
+ /// (a relay mid-deploy, a proxy in front of it).
+ fail_register: std::collections::VecDeque<u16>,
+ /// Machine registrations received (including refused ones).
+ register_calls: usize,
}
impl State_ {
@@ -233,6 +238,11 @@ async fn register(
Json(body): Json<serde_json::Value>,
) -> Response {
let mut st = s.lock().unwrap();
+ st.register_calls += 1;
+ if let Some(code) = st.fail_register.pop_front() {
+ let status = StatusCode::from_u16(code).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
+ return err(status, "the fake relay failed this registration");
+ }
let Some(Caller::Account(who)) = caller(&st, &headers) else {
return err(StatusCode::UNAUTHORIZED, "account token required");
};
@@ -882,6 +892,21 @@ impl FakeRelay {
.map(|r| r.machine.clone())
}
+ /// The next machine registrations answer with `statuses`, in order,
+ /// before the relay registers normally again.
+ pub fn fail_registrations(&self, statuses: &[u16]) {
+ self.state
+ .lock()
+ .unwrap()
+ .fail_register
+ .extend(statuses.iter().copied());
+ }
+
+ /// Machine registrations received so far (refused ones too).
+ pub fn register_calls(&self) -> usize {
+ self.state.lock().unwrap().register_calls
+ }
+
/// Refuses account calls to the machine API without an enrolled
/// device's session (the real relay after its grace period).
pub fn require_devices(&self, on: bool) {
diff --git a/libs/cua/crates/cua-sdk/src/native/host.rs b/libs/cua/crates/cua-sdk/src/native/host.rs
index 22d6d10b8b..e28043ea90 100644
--- a/libs/cua/crates/cua-sdk/src/native/host.rs
+++ b/libs/cua/crates/cua-sdk/src/native/host.rs
@@ -431,6 +431,25 @@ impl From<cua_host::HostStatus> for HostStatus {
}
}
+/// What host setup's usage data says about the account token: `provided`,
+/// `expired` (its `exp` is past: the app passed a stale token), `missing`
+/// (relay mode with none), `not_needed` (direct mode). Never the token.
+pub(crate) fn setup_token_state(mode: &str, token: Option<&str>) -> &'static str {
+ if mode.trim().eq_ignore_ascii_case("direct") {
+ return "not_needed";
+ }
+ let Some(token) = token.filter(|t| !t.trim().is_empty()) else {
+ return "missing";
+ };
+ let now = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0, |d| d.as_secs());
+ match cua_auth::jwt_claims(token).and_then(|c| c["exp"].as_u64()) {
+ Some(exp) if exp <= now => "expired",
+ _ => "provided",
+ }
+}
+
/// Converts binding options to cua-host options.
pub(crate) fn setup_options(o: HostSetupOptions) -> Result<cua_host::SetupOptions> {
let mut opts = match o.mode.as_deref().unwrap_or("relay") {
@@ -505,22 +524,34 @@ impl Host {
.as_ref()
.map(|o| (o.share_desktop, o.provide_spaces))
.unwrap_or((true, false));
- let r = match opts {
+ let account_token = account_token.filter(|t| !t.trim().is_empty());
+ let token_state = setup_token_state(&mode, account_token.as_deref());
+ let (r, failed_stage, http_status) = match opts {
Ok(opts) => {
- run(async move {
+ let staged = run(async move {
let host = cua_host::Host::new(home);
- let status = match account_token.filter(|t| !t.is_empty()) {
- Some(t) => host.setup(opts, &cua_host::StaticToken(t)).await?,
- None => host.setup(opts, &cua_host::NoAccount).await?,
+ let staged = match account_token {
+ Some(t) => host.setup_staged(opts, &cua_host::StaticToken(t)).await,
+ None => host.setup_staged(opts, &cua_host::NoAccount).await,
};
- Ok(status.into())
+ Ok(staged)
})
- .await
+ .await;
+ match staged {
+ Ok(Ok(status)) => (Ok(status.into()), None, None),
+ Ok(Err((stage, e))) => {
+ let status = e.http_status();
+ (Err(e.into()), Some(stage.as_str()), status)
+ }
+ Err(e) => (Err(e), Some("preflight"), None),
+ }
}
- Err(e) => Err(e),
+ Err(e) => (Err(e), Some("preflight"), None),
};
// Host Spaces adoption: the mode and what the machine is for,
- // never its name, address or who it is shared with.
+ // never its name, address or who it is shared with. A failure says
+ // where it stopped, whether an account token was there (never the
+ // token) and the HTTP status a server answered with.
cua_telemetry::capture(cua_telemetry::events::host_setup(
&mode,
desktop,
@@ -531,6 +562,13 @@ impl Host {
cua_telemetry::Outcome::Error
},
super::telemetry::variant(&r),
+ &cua_telemetry::events::HostSetupDetail {
+ signed_in: token_state != "missing" && token_state != "not_needed"
+ || cua_auth::may_have_session(),
+ token_state,
+ failed_stage,
+ http_status,
+ },
));
r
}
@@ -859,6 +897,51 @@ impl Devices {
mod tests {
use super::*;
+ #[test]
+ fn setup_reports_whether_it_had_a_token_never_the_token() {
+ use base64::Engine;
+ let jwt = |exp: u64| {
+ let claims = base64::engine::general_purpose::URL_SAFE_NO_PAD
+ .encode(format!(r#"{{"sub":"u","exp":{exp}}}"#));
+ format!("h.{claims}.s")
+ };
+ assert_eq!(setup_token_state("relay", None), "missing");
+ assert_eq!(setup_token_state("relay", Some(" ")), "missing");
+ assert_eq!(setup_token_state("relay", Some(&jwt(1))), "expired");
+ assert_eq!(
+ setup_token_state("relay", Some(&jwt(u64::MAX / 2))),
+ "provided"
+ );
+ // Opaque tokens are taken as given.
+ assert_eq!(setup_token_state("relay", Some("opaque")), "provided");
+ assert_eq!(setup_token_state("Direct", None), "not_needed");
+ }
+
+ /// A relay setup with no account token stops before the relay with
+ /// `Unauthenticated` (what 0.3.0/0.3.1 sent when the app's token read
+ /// failed): the app must sign in first, never call this without one.
+ #[tokio::test]
+ async fn relay_setup_without_a_token_is_unauthenticated() {
+ let relay = cua_host::testing::FakeRelay::start().await;
+ let dir = tempfile::tempdir().unwrap();
+ let host = Host::new(Some(dir.path().join(".cua").to_string_lossy().into()));
+ let err = host
+ .setup(
+ HostSetupOptions {
+ mode: Some("relay".into()),
+ relay_url: Some(relay.url.clone()),
+ driver_bin: Some(dir.path().join("x").to_string_lossy().into()),
+ runner: Some("process".into()),
+ ..Default::default()
+ },
+ None,
+ )
+ .await
+ .unwrap_err();
+ assert!(matches!(err, CuaError::Unauthenticated(_)), "{err}");
+ assert_eq!(relay.register_calls(), 0);
+ }
+
#[tokio::test]
async fn devices_enroll_approve_rename_and_revoke_through_the_relay() {
let relay = cua_host::testing::FakeRelay::start().await;
diff --git a/libs/cua/crates/cua-telemetry/src/events.rs b/libs/cua/crates/cua-telemetry/src/events.rs
index 73353e681f..27ead5f092 100644
--- a/libs/cua/crates/cua-telemetry/src/events.rs
+++ b/libs/cua/crates/cua-telemetry/src/events.rs
@@ -884,6 +884,19 @@ pub fn persistent_agent(
})
}
+/// What a host setup knew about its account and where it stopped.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct HostSetupDetail<'a> {
+ /// A Cua account session is stored on this machine.
+ pub signed_in: bool,
+ /// `provided`, `expired`, `missing` or `not_needed`.
+ pub token_state: &'a str,
+ /// The stage a failure stopped at (`token`, `register`, ...).
+ pub failed_stage: Option<&'a str>,
+ /// The HTTP status behind the failure, if a server answered.
+ pub http_status: Option<u16>,
+}
+
/// `cua_host_setup`. `profile` is the request's (`desktop`, `spare`);
/// `share_desktop` and `provide_spaces` both on is `both`.
pub fn host_setup(
@@ -892,6 +905,7 @@ pub fn host_setup(
provide_spaces: bool,
outcome: Outcome,
error_variant: Option<&str>,
+ detail: &HostSetupDetail<'_>,
) -> Event {
let profile = match (share_desktop, provide_spaces) {
(true, true) => "both",
@@ -910,6 +924,25 @@ pub fn host_setup(
"error_kind",
error_variant.map(error_kind).unwrap_or("none"),
)
+ .b("signed_in", detail.signed_in)
+ .s(
+ "token_state",
+ pick(schema::HOST_TOKEN_STATES, detail.token_state, "missing"),
+ )
+ .s(
+ "failed_stage",
+ detail
+ .failed_stage
+ .map(|st| pick(schema::HOST_SETUP_STAGES, st, "none"))
+ .unwrap_or("none"),
+ )
+ .n(
+ "http_status",
+ detail
+ .http_status
+ .filter(|c| (100..600).contains(c))
+ .map_or(0, u64::from),
+ )
}
/// `cua_host_space_provided`.
diff --git a/libs/cua/crates/cua-telemetry/src/schema.rs b/libs/cua/crates/cua-telemetry/src/schema.rs
index 5f28e9a5b8..bc049d5dec 100644
--- a/libs/cua/crates/cua-telemetry/src/schema.rs
+++ b/libs/cua/crates/cua-telemetry/src/schema.rs
@@ -344,6 +344,19 @@ pub const HOST_MODES: &[&str] = &["relay", "direct", "unknown"];
/// What a host machine is for: share its desktop, or only run Spaces for
/// the account's other devices.
pub const HOST_PROFILES: &[&str] = &["desktop", "spare", "both", "unknown"];
+/// The account token a relay host setup was given: one that looked valid,
+/// one already past its expiry, none (signed out, or the app could not get
+/// one), or none needed (direct mode).
+pub const HOST_TOKEN_STATES: &[&str] = &["provided", "expired", "missing", "not_needed"];
+/// Where a failed host setup stopped; `none` when it succeeded.
+pub const HOST_SETUP_STAGES: &[&str] = &[
+ "none",
+ "preflight",
+ "token",
+ "register",
+ "download",
+ "service",
+];
/// Keyvault actions (the Keyvault broker in `cua daemon`).
pub const KEYVAULT_ACTIONS: &[&str] = &["setup", "unlock", "lock", "import", "site_login"];
/// How the Keyvault was set up or unlocked.
@@ -1030,7 +1043,7 @@ pub const EVENTS: &[EventSpec] = &[
},
EventSpec {
name: event::HOST_SETUP,
- version: 1,
+ version: 2,
tier: Tier::Usage,
sample_rate: 1.0,
products: CLIENTS,
@@ -1043,6 +1056,26 @@ pub const EVENTS: &[EventSpec] = &[
),
OUTCOME,
ERROR_KIND,
+ p(
+ "signed_in",
+ Kind::Bool,
+ "A Cua account session is stored on this machine (no network, no keychain read).",
+ ),
+ p(
+ "token_state",
+ Kind::Enum(HOST_TOKEN_STATES),
+ "Whether the setup got an account token and whether it had expired. Never the token.",
+ ),
+ p(
+ "failed_stage",
+ Kind::Enum(HOST_SETUP_STAGES),
+ "Where a failed setup stopped (token, relay registration, download, service).",
+ ),
+ p(
+ "http_status",
+ Kind::Count { max: 599 },
+ "The HTTP status the relay or download answered a failure with; 0 when none.",
+ ),
],
purpose: "Host Spaces adoption: machines set up for access, and by which profile.",
},
diff --git a/libs/cua/crates/cua-telemetry/tests/privacy.rs b/libs/cua/crates/cua-telemetry/tests/privacy.rs
index 9d9b850845..fc5bc6c664 100644
--- a/libs/cua/crates/cua-telemetry/tests/privacy.rs
+++ b/libs/cua/crates/cua-telemetry/tests/privacy.rs
@@ -162,7 +162,19 @@ fn all_builders(s: &str) -> Vec<Event> {
},
Outcome::Ok,
),
- events::host_setup(s, true, true, Outcome::Error, Some(s)),
+ events::host_setup(
+ s,
+ true,
+ true,
+ Outcome::Error,
+ Some(s),
+ &events::HostSetupDetail {
+ signed_in: true,
+ token_state: s,
+ failed_stage: Some(s),
+ http_status: Some(65535),
+ },
+ ),
events::host_space_provided(s, s, Outcome::Error, Some(s)),
events::keyvault_action(
events::KeyvaultAction::Unlock,
@@ -987,9 +999,29 @@ fn activation_builders_keep_vocabulary_and_coarsen_the_rest() {
assert_eq!(v.props["mount_method"], "fskit");
assert_eq!(v.props["storage"], "s3");
assert_eq!(
- events::host_setup("RELAY", false, true, Outcome::Ok, None).props["profile"],
+ events::host_setup("RELAY", false, true, Outcome::Ok, None, &Default::default()).props["profile"],
"spare"
);
+ // A failure says where it stopped and what the server answered; the
+ // token itself never appears (only whether there was one).
+ let failed = events::host_setup(
+ "relay",
+ true,
+ false,
+ Outcome::Error,
+ Some("Unauthenticated"),
+ &events::HostSetupDetail {
+ signed_in: true,
+ token_state: "expired",
+ failed_stage: Some("register"),
+ http_status: Some(401),
+ },
+ );
+ assert_eq!(failed.props["signed_in"], true);
+ assert_eq!(failed.props["token_state"], "expired");
+ assert_eq!(failed.props["failed_stage"], "register");
+ assert_eq!(failed.props["http_status"], 401);
+ assert_eq!(failed.props["error_kind"], "unauthenticated");
assert_eq!(
events::share("unshare", "editor", Outcome::Ok)
.unwrap()