hyperhive/swarm-controller/src/matrix_account.rs

//! An agent's matrix accounts, from this daemon's two sides of them.
//!
//! **The internal one** — [`agent_token`] — is the agent's own `main` account on
//! the swarm's homeserver, minted with the swarm's appservice token and stored
//! where the agent's daemon reads it. See docs/swarm/credentials.md for why
//! `main` is the one name [`put_matrix_account`] refuses to write.
//! [`hive_sender`] mints each **hive's** sender account the same way, sharing this module's helpers with [`agent_token`].
//!
//! **The external one** — [`put_matrix_account`] and everything under it — is
//! an account somewhere else that an operator hands us a credential for: put it
//! in the swarm's secret store, then tell that agent's hive it is there.
//!
//! The hive end is `hive-c0re/src/workers/credential.rs`, which reads the
//! value under its own identity and writes it into the agent's state dir. The
//! notice carries only names, so the queue never holds the secret — see
//! [`swarm_queue_client::credential_subject`] for why that is a requirement
//! rather than a preference.
//!
//! ⚠️ Store first, notify second, and the order cannot be swapped: a notice
//! that overtakes its own write reaches a hive that reads nothing, and the
//! hive deliberately does not retry.
//!
//! Two credential modes, chosen by `PutMatrixAccountRequest::mode`: `token`
//! (default, back-compat with the original blind-store shape — the caller
//! already has a bearer token) and `password` (this daemon performs
//! `m.login.password` against the caller-given homeserver itself and stores
//! the resulting token; the password is never stored, and is not sent to the
//! hive either — only the derived token is). Done here so the browser never
//! has to hold the password long enough to call an arbitrary homeserver
//! directly.

use axum::Json;
use axum::extract::State;
use axum::http::StatusCode;
use serde::{Deserialize, Serialize};
use swarm_queue_client::{CredentialNotice, credential_subject};
use swarm_secret_client::matrix;
use utoipa::ToSchema;

use super::{AppState, error_problem, swarm_hive};

pub mod agent_token;
pub mod hive_sender;

fn default_mode() -> String {
    "token".to_owned()
}

/// Env var the controller's NixOS module sets from
/// `services.hyperhive.deploy.swarm-controller.matrixHomeserverUrl` — the
/// swarm-wide default `PutMatrixAccountRequest::homeserver` falls back to
/// when a caller omits one. Read via [`configured_default_homeserver`], not
/// directly — see that fn's doc.
///
/// Also the homeserver [`agent_token`] mints agents' own accounts on. Not yet
/// consulted by [`put_matrix_account`]: `homeserver_or_configured_default`
/// below exists for a later slice of this homeserver-default rollout to call.
pub(crate) const DEFAULT_HOMESERVER_ENV: &str = "SWARM_CONTROLLER_MATRIX_HOMESERVER_URL";

/// `caller`'s own homeserver, or `default` when the caller left it unset.
/// `caller` always wins — this only fills a gap it left, never replaces a
/// value it gave.
///
/// Takes `default` as a plain parameter rather than reading
/// [`DEFAULT_HOMESERVER_ENV`] itself: a caller wants that env read done once,
/// at the edge (see [`configured_default_homeserver`]), and keeping this fn
/// pure makes it testable without mutating shared process env — three tests
/// doing exactly that raced each other under `cargo test`'s default
/// parallelism in review.
pub(crate) fn homeserver_or_configured_default(
    caller: Option<String>,
    default: Option<String>,
) -> Option<String> {
    caller.or(default)
}

/// Reads [`DEFAULT_HOMESERVER_ENV`] fresh each call — the one place this
/// crate touches that env var, so [`homeserver_or_configured_default`] above
/// can stay a pure function.
pub(crate) fn configured_default_homeserver() -> Option<String> {
    std::env::var(DEFAULT_HOMESERVER_ENV).ok()
}

/// The credential to store for one agent's external matrix account.
///
/// No `Debug` derive: this carries a password and a token, so nothing may
/// `{:?}`-log it by accident.
#[derive(Deserialize, ToSchema)]
pub struct PutMatrixAccountRequest {
    /// `"token"` (default, back-compat) or `"password"`. Token mode stores
    /// `token` as given; password mode logs into `homeserver` with `user_id`
    /// + `password` and stores the token that comes back instead.
    #[serde(default = "default_mode")]
    #[schema(example = "token")]
    mode: String,
    /// The access token. Required (and used as given) in token mode; ignored
    /// in password mode, where the token comes from the login instead. Never
    /// logged, and never returned by this route.
    token: Option<String>,
    /// Password-mode only: the matrix user id (or bare localpart) to log in
    /// as.
    user_id: Option<String>,
    /// Password-mode only. Never logged and never stored — only the token
    /// `m.login.password` returns is.
    password: Option<String>,
    /// The account's homeserver, when it is not this swarm's own.
    ///
    /// Stored beside the token rather than sent on the notice: a notice is a
    /// queue message, so a homeserver carried there would exist only in
    /// flight, with nowhere to reconstruct it from on a re-delivery.
    ///
    /// Optional in token mode (omitted means "resolve to the agent's own
    /// `services.hyperhive.agent.matrix.url` on the hive side" — this route never needs to
    /// know it itself for a blind store). **Required** in password mode:
    /// logging in needs somewhere to log in against, and unlike token mode
    /// there is no hive-side fallback to defer to.
    #[schema(example = "https://matrix.example.org")]
    homeserver: Option<String>,
}

/// `put_matrix_account`'s success body.
#[derive(Debug, Serialize, ToSchema)]
pub struct PutMatrixAccountResponse {
    /// The account's matrix user id, recovered from the login response in
    /// password mode. `None` in token mode — the caller already knows which
    /// account their own token belongs to, and this route does not spend a
    /// `whoami` round trip validating a token it was simply handed.
    user_id: Option<String>,
}

/// Store an agent's external matrix account credential and notify its hive.
///
/// Idempotent: the store keeps versions, so repeating a call replaces the
/// value the agent will next read rather than adding a second account.
#[utoipa::path(
    put,
    path = "/api/hives/{hive}/agents/{agent}/matrix-accounts/{account}",
    params(
        ("hive" = String, Path, description = "hive whose agent receives the credential"),
        ("agent" = String, Path, description = "agent the credential is delivered to"),
        ("account" = String, Path, description = "the external account this credential authenticates as"),
    ),
    request_body = PutMatrixAccountRequest,
    responses(
        (status = 200, description = "stored, and the hive has been told", body = PutMatrixAccountResponse),
        (status = 400, description = "a name is not an identifier, the account name is not a single path segment, the account is 'main' (reserved), the mode is unrecognized, a mode's required fields are missing, or the hive is not in this swarm (problem+json)", body = String),
        (status = 503, description = "no swarm queue is wired up, or it is not connected (problem+json)", body = String),
        (status = 500, description = "the store write, the encode or the publish failed (problem+json)", body = String),
    ),
    tag = "agents"
)]
pub async fn put_matrix_account(
    State(state): State<AppState>,
    axum::extract::Path((hive, agent, account)): axum::extract::Path<(String, String, String)>,
    Json(req): Json<PutMatrixAccountRequest>,
) -> Result<Json<PutMatrixAccountResponse>, problem_details::ProblemDetails> {
    // The queue first, so a deployment that has none answers 503 whatever the
    // caller spelled — and before the store is touched, so a request that
    // could never be delivered does not leave a credential behind.
    let Some(status) = state.status.as_ref() else {
        return Err(error_problem(
            StatusCode::SERVICE_UNAVAILABLE,
            "this deployment wired up no swarm queue, so there is no hive to notify",
        ));
    };
    let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
    let agent = hive_types::Ident::parse(&agent)
        .map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
        .into_string();
    // Built before the store is reached, so a malformed account name costs a
    // parse and not a login. `account_path` is the validator: the store's
    // charset is its rule to state, not this handler's to restate.
    let secret_path = matrix::account_path(&agent, &account)
        .map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e.to_string()))?;
    // `main` is the hive-internal account `nix/agent-modules/matrix.nix`
    // declares per agent from `services.hyperhive.agent.matrix.url` — the
    // module owns that `matrixAccounts` entry, which is why this route
    // refuses to write one: an extra account literally named `main` would
    // not overwrite the real one (it lands at a different token-file suffix)
    // but would confuse anything that lists accounts by name. Checked
    // before any mode-specific work (including a network login) runs.
    if is_reserved_account(&account) {
        return Err(error_problem(
            StatusCode::BAD_REQUEST,
            "'main' is the hive-internal account, declared per agent from \
             services.hyperhive.agent.matrix.url — it cannot be set through this route.",
        ));
    }

    // Password mode's network call happens here, before the store is
    // touched, so a failed login leaves no partial state behind.
    let (token, homeserver, user_id) = resolve_credential(&req).await.map_err(|b| *b)?;

    // A queue that is configured but not yet (or no longer) connected does
    // not fail the `publish`/`flush` further down outright — it *hangs*
    // them, per `swarm_queue_client::ensure_connected`'s own doc. Checked
    // here, immediately before the store is touched, so a request that
    // cannot be delivered never leaves a credential behind — the same
    // ordering rule the module doc states for "store first, notify
    // second", extended one step earlier.
    let client = status.queue_client();
    swarm_queue_client::ensure_connected(&client).map_err(|e| {
        error_problem(
            StatusCode::SERVICE_UNAVAILABLE,
            &swarm_queue_client::chain(&e),
        )
    })?;

    let store = crate::store::connect().await.map_err(|e| {
        tracing::warn!(error = %e, "connecting to the swarm secret store failed");
        error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
    })?;
    store
        .write(
            &secret_path,
            &matrix::Credential {
                value: token,
                homeserver,
            },
        )
        .await
        .map_err(|e| {
            // The path names the agent and the account; the value is not in it.
            tracing::warn!(path = %secret_path, error = %e, "writing the credential failed");
            error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
        })?;

    let notice = CredentialNotice {
        agent: agent.clone(),
        account: account.clone(),
    };
    let payload = serde_json::to_vec(&notice).map_err(|e| {
        error_problem(
            StatusCode::INTERNAL_SERVER_ERROR,
            &format!("encoding the credential notice failed: {e}"),
        )
    })?;
    let subject = credential_subject(&hive);
    client
        .publish(subject.clone(), payload.into())
        .await
        .map_err(|e| {
            error_problem(
                StatusCode::INTERNAL_SERVER_ERROR,
                &format!("publishing to {subject} failed: {e}"),
            )
        })?;
    // Flushed for the reason `publish_deploy` flushes: `publish` hands the
    // message to the connection's write buffer and returns, so without this
    // the response can outrun the notice it reports as sent.
    client.flush().await.map_err(|e| {
        error_problem(
            StatusCode::INTERNAL_SERVER_ERROR,
            &format!("flushing the credential notice to {subject} failed: {e}"),
        )
    })?;

    tracing::info!(%subject, %hive, %agent, %account, "credential stored; hive notified");
    Ok(Json(PutMatrixAccountResponse { user_id }))
}

/// Whether `account` is the agent's own account, which [`agent_token`] mints
/// and `nix/agent-modules/matrix.nix` declares per agent — see the call site's
/// own comment for why this route must never write one.
fn is_reserved_account(account: &str) -> bool {
    account == agent_token::ACCOUNT
}

/// Token-mode's only requirement: a token was actually given. Split out of
/// `resolve_credential` (with `password_fields` below) so each mode's
/// validation is unit-testable directly — only the actual network login in
/// `resolve_credential` itself needs an async runtime to exercise. Returns a
/// plain `&'static str` rather than a `ProblemDetails` — `clippy::result_large_err`
/// (this workspace runs `pedantic = deny`) flags a private fn returning one of
/// those directly; `put_matrix_account` itself is exempt only because it is
/// `pub` (clippy's `avoid-breaking-exported-api` default), which these
/// helpers are not.
fn token_credential(
    req: &PutMatrixAccountRequest,
) -> Result<(String, Option<String>), &'static str> {
    let Some(token) = req.token.clone() else {
        return Err("token mode needs a token");
    };
    Ok((token, req.homeserver.clone()))
}

/// Password mode's required fields, validated present, with the
/// homeserver's trailing slash already trimmed — this is what actually
/// reaches `matrix_password_login`, not the caller's raw string, so the
/// login URL below never ends up with a doubled `//`.
struct PasswordFields<'a> {
    homeserver: String,
    user_id: &'a str,
    password: &'a str,
}

fn password_fields(req: &PutMatrixAccountRequest) -> Result<PasswordFields<'_>, &'static str> {
    let (Some(homeserver), Some(user_id), Some(password)) = (
        req.homeserver.as_deref(),
        req.user_id.as_deref(),
        req.password.as_deref(),
    ) else {
        return Err("password mode needs homeserver, user_id, and password");
    };
    Ok(PasswordFields {
        homeserver: homeserver.trim_end_matches('/').to_owned(),
        user_id,
        password,
    })
}

/// Resolve a request's credential mode to a concrete `(token, homeserver,
/// resolved user id)`. Extracted out of `put_matrix_account` to keep that
/// function under `clippy::too_many_lines`, and so the mode branching has
/// something to unit-test directly (via `token_credential`/`password_fields`
/// above) instead of only through the full route.
///
/// `Box`ed error for the same `result_large_err` reason `token_credential`'s
/// doc explains — this fn is private too, so it does not get `put_matrix_account`'s
/// exported-API exemption. Unboxed at the one call site instead of changing
/// `put_matrix_account`'s own (exempt, and part of the route's documented
/// contract) return type.
async fn resolve_credential(
    req: &PutMatrixAccountRequest,
) -> Result<(String, Option<String>, Option<String>), Box<problem_details::ProblemDetails>> {
    match req.mode.as_str() {
        "token" => {
            let (token, homeserver) = token_credential(req)
                .map_err(|e| Box::new(error_problem(StatusCode::BAD_REQUEST, e)))?;
            Ok((token, homeserver, None))
        }
        "password" => {
            let fields = password_fields(req)
                .map_err(|e| Box::new(error_problem(StatusCode::BAD_REQUEST, e)))?;
            let (token, resolved_user_id) =
                matrix_password_login(&fields.homeserver, fields.user_id, fields.password)
                    .await
                    .map_err(|e| Box::new(error_problem(StatusCode::BAD_REQUEST, &e)))?;
            Ok((token, Some(fields.homeserver), Some(resolved_user_id)))
        }
        other => Err(Box::new(error_problem(
            StatusCode::BAD_REQUEST,
            &format!("unknown mode {other:?} (want token|password)"),
        ))),
    }
}

/// Bound on reaching the homeserver.
const HTTP_CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
/// Bound on one whole homeserver round trip, body included. A password
/// login makes the homeserver hash the password before it answers, so this
/// is looser than a plain API call needs.
const HTTP_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);

/// A client with both homeserver bounds applied.
fn http_client() -> Result<reqwest::Client, String> {
    reqwest::Client::builder()
        .connect_timeout(HTTP_CONNECT_TIMEOUT)
        .timeout(HTTP_TIMEOUT)
        .build()
        .map_err(|e| format!("build HTTP client: {e}"))
}

/// `what` failed with `e`; a timeout names the bound that fired.
fn http_error(what: &str, e: &reqwest::Error) -> String {
    if e.is_connect() && e.is_timeout() {
        format!("{what}: connect timed out after {HTTP_CONNECT_TIMEOUT:?}")
    } else if e.is_timeout() {
        format!("{what}: timed out after {HTTP_TIMEOUT:?}")
    } else {
        format!("{what}: {e}")
    }
}

/// POST `m.login.password` to `<homeserver>/_matrix/client/v3/login`.
/// Returns `(access_token, user_id)`.
///
/// Deliberately its own copy rather than a shared crate with
/// `hive-c0re::dashboard::matrix_accounts`'s near-identical helper: the two
/// log in on behalf of different callers (a hive's own dashboard vs. this
/// swarm-wide provisioning route) and share no other code — four lines of
/// JSON construction do not justify a dependency edge between them.
async fn matrix_password_login(
    homeserver: &str,
    user_id: &str,
    password: &str,
) -> Result<(String, String), String> {
    let url = format!("{homeserver}/_matrix/client/v3/login");
    let body = serde_json::json!({
        "type": "m.login.password",
        "identifier": { "type": "m.id.user", "user": user_id },
        "password": password,
        "initial_device_display_name": "hyperhive",
    });
    let resp = http_client()?
        .post(&url)
        .json(&body)
        .send()
        .await
        .map_err(|e| http_error("POST /login", &e))?;
    let status = resp.status();
    let json: serde_json::Value = resp
        .json()
        .await
        .map_err(|e| http_error("parse /login response", &e))?;
    if !status.is_success() {
        let err = json
            .get("error")
            .and_then(serde_json::Value::as_str)
            .unwrap_or("login failed");
        return Err(format!("/login HTTP {status}: {err}"));
    }
    let token = json
        .get("access_token")
        .and_then(serde_json::Value::as_str)
        .ok_or_else(|| "login response missing access_token".to_owned())?;
    let uid = json
        .get("user_id")
        .and_then(serde_json::Value::as_str)
        .ok_or_else(|| "login response missing user_id".to_owned())?;
    Ok((token.to_owned(), uid.to_owned()))
}

#[cfg(test)]
mod tests {
    use super::{
        PutMatrixAccountRequest, homeserver_or_configured_default, is_reserved_account,
        password_fields, resolve_credential, token_credential,
    };

    fn request(mode: &str) -> PutMatrixAccountRequest {
        PutMatrixAccountRequest {
            mode: mode.to_owned(),
            token: None,
            user_id: None,
            password: None,
            homeserver: None,
        }
    }

    // `homeserver_or_configured_default` takes its default as a plain
    // parameter rather than reading the env var itself, so these are pure
    // — no process env mutation, and so no risk of racing each other (or
    // any other test in the crate) under `cargo test`'s default parallelism.

    #[test]
    fn caller_supplied_homeserver_wins_even_with_a_default_configured() {
        let result = homeserver_or_configured_default(
            Some("https://caller.example.org".to_owned()),
            Some("https://default.example.org".to_owned()),
        );
        assert_eq!(result.as_deref(), Some("https://caller.example.org"));
    }

    #[test]
    fn falls_back_to_the_configured_default_when_the_caller_omits_one() {
        let result =
            homeserver_or_configured_default(None, Some("https://default.example.org".to_owned()));
        assert_eq!(result.as_deref(), Some("https://default.example.org"));
    }

    #[test]
    fn none_when_neither_caller_nor_default_is_set() {
        assert_eq!(homeserver_or_configured_default(None, None), None);
    }

    #[test]
    fn main_is_reserved_but_nothing_else_is() {
        assert!(is_reserved_account("main"));
        assert!(!is_reserved_account("ops-relay"));
        // Case-sensitive on purpose: `matrixAccounts` is a nix attrset, so
        // `Main` is a distinct, legal key from the reserved `main`.
        assert!(!is_reserved_account("Main"));
    }

    #[test]
    fn token_mode_needs_a_token() {
        assert!(token_credential(&request("token")).is_err());
    }

    #[test]
    fn token_mode_passes_through_token_and_homeserver_unchanged() {
        let mut req = request("token");
        req.token = Some("t0k3n".to_owned());
        req.homeserver = Some("https://matrix.example.org".to_owned());
        let (token, homeserver) = token_credential(&req).expect("token + homeserver both given");
        assert_eq!(token, "t0k3n");
        assert_eq!(homeserver.as_deref(), Some("https://matrix.example.org"));
    }

    #[test]
    fn password_mode_needs_all_three_fields() {
        let mut req = request("password");
        assert!(password_fields(&req).is_err(), "none given");
        req.homeserver = Some("https://matrix.example.org".to_owned());
        assert!(
            password_fields(&req).is_err(),
            "still missing user_id + password"
        );
        req.user_id = Some("@a:matrix.example.org".to_owned());
        assert!(password_fields(&req).is_err(), "still missing password");
        req.password = Some("hunter2".to_owned());
        assert!(password_fields(&req).is_ok(), "now all three given");
    }

    #[test]
    fn password_mode_trims_a_trailing_slash_off_the_homeserver() {
        let mut req = request("password");
        req.homeserver = Some("https://matrix.example.org/".to_owned());
        req.user_id = Some("@a:matrix.example.org".to_owned());
        req.password = Some("hunter2".to_owned());
        let fields = password_fields(&req).expect("all three fields given");
        assert_eq!(fields.homeserver, "https://matrix.example.org");
    }

    #[test]
    fn password_mode_leaves_a_homeserver_with_no_trailing_slash_unchanged() {
        let mut req = request("password");
        req.homeserver = Some("https://matrix.example.org".to_owned());
        req.user_id = Some("@a:matrix.example.org".to_owned());
        req.password = Some("hunter2".to_owned());
        let fields = password_fields(&req).expect("all three fields given");
        assert_eq!(fields.homeserver, "https://matrix.example.org");
    }

    #[tokio::test]
    async fn resolve_credential_token_mode_end_to_end() {
        let mut req = request("token");
        req.token = Some("t0k3n".to_owned());
        let (token, homeserver, user_id) = resolve_credential(&req)
            .await
            .expect("token mode with a token given");
        assert_eq!(token, "t0k3n");
        assert_eq!(homeserver, None);
        assert_eq!(user_id, None);
    }

    #[tokio::test]
    async fn resolve_credential_rejects_an_unknown_mode() {
        assert!(
            resolve_credential(&request("carrier-pigeon"))
                .await
                .is_err()
        );
    }

    // ── the connected-but-not-yet-connected queue ───────────────────────

    /// A client that exists but has never connected — the `Pending` state
    /// `ensure_connected`'s own doc says a `Disconnected` check would miss.
    /// `retry_on_initial_connect` is what makes `.connect()` return
    /// immediately instead of blocking on a handshake that will never
    /// succeed against a loopback port nothing listens on.
    async fn disconnected_client() -> async_nats::Client {
        async_nats::ConnectOptions::new()
            .retry_on_initial_connect()
            .connect("127.0.0.1:1")
            .await
            .expect("retry_on_initial_connect returns without waiting for a real connection")
    }

    /// Bare-minimum `AppState` for a handler test: one hive, no queue-backed
    /// helpers beyond `status` (the field this handler actually reads), and
    /// an empty in-memory job graph the endpoint under test never touches.
    fn state_with_status(status: super::super::status::StatusReader) -> super::super::AppState {
        super::super::AppState {
            hives: std::sync::Arc::new(vec![super::super::HiveEntry {
                name: "pr1ma".to_owned(),
                domain: "pr1ma.example".to_owned(),
            }]),
            links: std::sync::Arc::new(Vec::new()),
            status: Some(std::sync::Arc::new(status)),
            wanted: None,
            agent_status: None,
            agent_icons: None,
            jobq: std::sync::Arc::new(std::sync::Mutex::new(hive_jobq::scheduler::Scheduler::new(
                hive_jobq::Graph::new(),
                hive_jobq::resources::ResourceTable::new(),
            ))),
            webhook_secret: None,
            config_prs: None,
            swarm_name: None,
            auth: None,
            forge: None,
            create_gate: std::sync::Arc::default(),
        }
    }

    /// The defect this whole PR exists to close: a queue that is
    /// configured but not connected must not let this handler reach the
    /// store write at all.
    ///
    /// `BAO_ADDR`/`BAO_CLIENT_CERT`/`BAO_CLIENT_KEY` are asserted unset
    /// first — not incidental setup, but the control that makes the 503
    /// meaningful. If `put_matrix_account` reached `crate::store::connect()`
    /// with those unset, *that* call fails too, and would also answer with
    /// a `problem+json` body (500, "connecting to the swarm secret store
    /// failed"). A 503 here is therefore proof execution never got past
    /// `ensure_connected`, not a coincidence of two paths landing on the
    /// same status family.
    #[tokio::test]
    async fn a_disconnected_queue_answers_503_and_never_reaches_the_store() {
        for var in ["BAO_ADDR", "BAO_CLIENT_CERT", "BAO_CLIENT_KEY"] {
            assert!(
                std::env::var(var).is_err(),
                "{var} must be unset for this test to prove anything"
            );
        }

        let reader = super::super::status::StatusReader::new(
            disconnected_client().await,
            std::time::Duration::from_mins(1),
        );
        let state = state_with_status(reader);

        let result = super::put_matrix_account(
            axum::extract::State(state),
            axum::extract::Path((
                "pr1ma".to_owned(),
                "atlas".to_owned(),
                "workaccount".to_owned(),
            )),
            axum::Json(PutMatrixAccountRequest {
                mode: "token".to_owned(),
                token: Some("t0k3n".to_owned()),
                user_id: None,
                password: None,
                homeserver: None,
            }),
        )
        .await;

        let problem = result.expect_err("a disconnected queue must refuse, not hang or 500");
        assert_eq!(
            problem.status,
            Some(axum::http::StatusCode::SERVICE_UNAVAILABLE),
            "{problem:?}"
        );
    }

    /// The control for the test above: a client that starts in `Pending`
    /// but genuinely never connects is exactly what `ensure_connected` is
    /// specified to reject — proving the 503 above tracks the connection
    /// state and is not simply what every call through this handler
    /// returns. Same client shape, mode rejected before either queue or
    /// store is touched, so it exercises a different early return
    /// (`is_reserved_account`) and confirms the handler still validates
    /// normally on a path that never reaches `ensure_connected`'s sibling
    /// checks.
    #[tokio::test]
    async fn a_reserved_account_name_is_still_refused_before_any_queue_check_matters() {
        let reader = super::super::status::StatusReader::new(
            disconnected_client().await,
            std::time::Duration::from_mins(1),
        );
        let state = state_with_status(reader);

        let result = super::put_matrix_account(
            axum::extract::State(state),
            axum::extract::Path(("pr1ma".to_owned(), "atlas".to_owned(), "main".to_owned())),
            axum::Json(PutMatrixAccountRequest {
                mode: "token".to_owned(),
                token: Some("t0k3n".to_owned()),
                user_id: None,
                password: None,
                homeserver: None,
            }),
        )
        .await;

        let problem = result.expect_err("'main' is reserved regardless of queue state");
        assert_eq!(
            problem.status,
            Some(axum::http::StatusCode::BAD_REQUEST),
            "{problem:?}"
        );
    }
}