cellos_ctl/

client.rs

//! HTTP client wrapping reqwest for cellos-server.
//!
//! Per Feynman (CHATROOM Session 16): "cellctl is a thin client over cellos-server.
//! Every command = exactly one API call." This module is that contract.
//!
//! All state queries hit the projector via HTTP. There is no client-side cache.

use percent_encoding::{utf8_percent_encode, AsciiSet, NON_ALPHANUMERIC};
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION, CONTENT_TYPE};
use reqwest::StatusCode;
use serde::de::DeserializeOwned;
use serde::Serialize;

use crate::config::Config;
use crate::exit::{CtlError, CtlResult};

/// User-Agent string sent to the server — helps the projector identify CLI traffic.
const USER_AGENT: &str = concat!("cellctl/", env!("CARGO_PKG_VERSION"));

/// HIGH-CTL-002-B-1: strict percent-encoding set for path segments.
///
/// We encode EVERY non-alphanumeric byte. RFC 3986 §3.3 permits a wider
/// "unreserved" set (alphanumerics plus `-` `.` `_` `~`) inside a path
/// segment, and the small set of "sub-delims" (`!$&'()*+,;=`) plus `:`
/// and `@`. But cellctl already filters its by-name input through the
/// server's admission allow-set (`[A-Za-z0-9._-]`), so for any name
/// that round-trips the only characters this set will actually escape
/// are the ones the server rejects — and the encoding is correct for
/// those too. The conservative choice keeps the encoder future-proof
/// against an admission rule change and removes any chance of a
/// reserved-character round-trip surprise.
///
/// Critically: `b' '` (space) IS in `NON_ALPHANUMERIC` so it encodes
/// as `%20`, NOT `+`. This is the actual HIGH-CTL-002-B-1 fix —
/// `url::form_urlencoded::byte_serialize` (the previous encoder)
/// emits `+` for space because it implements `application/x-www-form-
/// urlencoded`, not path-segment encoding. axum's `Path<String>`
/// extractor decodes per RFC 3986, which does NOT recognise `+` as
/// space inside a path segment. The previous behaviour silently broke
/// `cellctl describe formation 'hello world'` with a 404. The strict
/// set fixes the asymmetry by emitting `%20` on the cellctl side.
const PATH_SEGMENT: &AsciiSet = NON_ALPHANUMERIC;

/// Build the right `/v1/formations/...` path for a user-supplied
/// identifier. CTL-002 (E2E report): the server's `/v1/formations/{id}`
/// route uses `Path<Uuid>` and rejects names with HTTP 400. We detect
/// the shape locally and route to the parallel `/v1/formations/by-name/{name}`
/// route when the input is not a UUID.
///
/// Detection is `Uuid::parse_str(input).is_ok()` — UUID-shaped strings
/// always go to the UUID route (preserves existing operator workflows),
/// everything else routes to by-name. We percent-encode the name with
/// a strict path-segment set so an operator-supplied identifier
/// containing reserved characters does not silently truncate or break
/// path parsing on the server (`/`, `?`, `#`) and so that a literal
/// space encodes as `%20` rather than `+` (HIGH-CTL-002-B-1).
pub fn formation_path(ident: &str) -> String {
    if uuid::Uuid::parse_str(ident).is_ok() {
        format!("/v1/formations/{ident}")
    } else {
        format!(
            "/v1/formations/by-name/{}",
            utf8_percent_encode(ident, PATH_SEGMENT)
        )
    }
}

#[cfg(test)]
mod path_tests {
    use super::formation_path;

    #[test]
    fn uuid_input_uses_uuid_route() {
        // Canonical hyphenated v4.
        let id = "550e8400-e29b-41d4-a716-446655440000";
        assert_eq!(formation_path(id), format!("/v1/formations/{id}"));
    }

    #[test]
    fn simple_name_uses_by_name_route() {
        assert_eq!(formation_path("demo"), "/v1/formations/by-name/demo");
    }

    #[test]
    fn name_with_reserved_chars_is_url_encoded() {
        // `/` in a name MUST NOT escape the path segment.
        let got = formation_path("ns/team");
        assert!(
            got.starts_with("/v1/formations/by-name/") && !got.contains("ns/team"),
            "expected encoded segment, got {got}"
        );
        // HIGH-CTL-002-B-1: round-trip via the percent_encoding crate's
        // decoder (RFC 3986 path-segment semantics), NOT form-urlencoded,
        // because the server uses axum's `Path<String>` which is RFC
        // 3986-shaped. Form-urlencoded decode would mistranslate `+`
        // back to space and miss the bug.
        let tail = got.trim_start_matches("/v1/formations/by-name/");
        let decoded = percent_encoding::percent_decode_str(tail)
            .decode_utf8()
            .expect("encoded segment is valid utf8")
            .into_owned();
        assert_eq!(decoded, "ns/team");
    }

    /// HIGH-CTL-002-B-1 regression: space MUST encode as `%20`, NOT
    /// `+`. The pre-fix encoder (`form_urlencoded::byte_serialize`)
    /// emitted `+` for space, and axum's `Path<String>` extractor —
    /// which uses RFC 3986 path-segment decoding — does NOT translate
    /// `+` back to space inside a path. Result: a formation named
    /// `hello world` was unreachable via cellctl's by-name path.
    ///
    /// This is the single most important behavioural pin in this
    /// file. If a future encoder change re-introduces `+` for space,
    /// this test fails immediately and points the reader at the bug.
    #[test]
    fn space_encodes_as_percent20_not_plus() {
        let got = formation_path("hello world");
        assert!(got.contains("%20"), "space must encode as %20; got {got}",);
        assert!(
            !got.contains('+'),
            "space must NOT encode as `+` (axum Path<String> would not decode it); got {got}",
        );
        // Full expected encoding so future readers see the contract.
        assert_eq!(got, "/v1/formations/by-name/hello%20world");
    }

    /// HIGH-CTL-002-B-1 round-trip: every byte the strict encoder
    /// produces must round-trip through `percent_decode_str` back to
    /// the operator-typed name. This proves the encode/decode pair is
    /// symmetric across the URL-reserved character classes the server
    /// might one day accept (`/`, `?`, `#`, `%`, non-ASCII).
    #[test]
    fn percent_encoder_round_trips_reserved_chars() {
        for (input, label) in [
            ("ns/team", "slash"),
            ("100%-clean", "percent"),
            ("why?-team", "question"),
            ("v1#main", "hash"),
            ("hello world", "space"),
            ("café-team", "non-ascii"),
        ] {
            let got = formation_path(input);
            let tail = got.trim_start_matches("/v1/formations/by-name/");
            // Plus is form-urlencoded space — it MUST NOT appear in
            // path-segment encoding. We assert at the tail level so a
            // future encoder regression on any character class is
            // caught.
            assert!(
                !tail.contains('+'),
                "[{label}] encoded segment must not contain `+`; got {tail}",
            );
            let decoded = percent_encoding::percent_decode_str(tail)
                .decode_utf8()
                .unwrap_or_else(|e| panic!("[{label}] decode utf8: {e}"))
                .into_owned();
            assert_eq!(
                decoded, input,
                "[{label}] encode-then-decode must be the identity",
            );
        }
    }

    #[test]
    fn empty_string_routes_to_by_name() {
        // Empty is not a UUID; the server will surface a 404 (or a
        // route-level miss). Either way, cellctl does not silently
        // mis-route to the UUID path.
        assert_eq!(formation_path(""), "/v1/formations/by-name/");
    }

    #[test]
    fn uppercase_uuid_input_uses_uuid_route() {
        // RFC 4122 §3 explicitly allows uppercase hex; `Uuid::parse_str`
        // accepts it. The server's `Path<Uuid>` extractor does too.
        let id = "550E8400-E29B-41D4-A716-446655440000";
        assert_eq!(formation_path(id), format!("/v1/formations/{id}"));
    }

    #[test]
    fn near_uuid_shaped_name_does_not_collide() {
        // A 32-char hex string without hyphens parses as a UUID per
        // RFC 4122 §3 "simple" form — that is intentional and the
        // server's Uuid extractor accepts it. This pin documents the
        // boundary: if an operator ever names a formation as 32 hex
        // chars, cellctl WILL route it to the UUID path. That is the
        // known ambiguity Option B accepts (Option C would have made
        // it worse). The test exists so the choice is auditable.
        let s = "550e8400e29b41d4a716446655440000";
        assert_eq!(formation_path(s), format!("/v1/formations/{s}"));
    }
}

#[derive(Clone)]
pub struct CellosClient {
    base: String,
    http: reqwest::Client,
    /// Raw bearer token if configured. Held separately so paths that
    /// don't go through reqwest (the WebSocket upgrade in
    /// `cmd::events`) can still authenticate without parsing it back
    /// out of `default_headers`. EVT-002 (E2E report): cellctl's WS
    /// upgrade needs to set `Authorization: Bearer <token>` on the
    /// `http::Request`; before this field it had no clean way to
    /// reach the configured token.
    bearer: Option<String>,
}

impl CellosClient {
    pub fn new(cfg: &Config) -> CtlResult<Self> {
        let base = cfg.effective_server();
        // Normalize: strip trailing slash so we can confidently concatenate paths.
        let base = base.trim_end_matches('/').to_string();

        let bearer = cfg.effective_token();
        let mut headers = HeaderMap::new();
        headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
        if let Some(tok) = bearer.as_deref() {
            let v = HeaderValue::from_str(&format!("Bearer {tok}"))
                .map_err(|e| CtlError::usage(format!("bad token: {e}")))?;
            headers.insert(AUTHORIZATION, v);
        }

        let http = reqwest::Client::builder()
            .user_agent(USER_AGENT)
            .default_headers(headers)
            .build()
            .map_err(|e| CtlError::api(format!("init http client: {e}")))?;

        Ok(Self { base, http, bearer })
    }

    pub fn base_url(&self) -> &str {
        &self.base
    }

    /// Raw bearer token, if one is configured. Used by the WebSocket
    /// upgrade path (`cmd::events::follow_ws`) where the auth header
    /// has to be installed on a `tokio_tungstenite` `http::Request`
    /// rather than a reqwest call.
    pub fn bearer_token(&self) -> Option<&str> {
        self.bearer.as_deref()
    }

    fn url(&self, path: &str) -> String {
        if path.starts_with('/') {
            format!("{}{}", self.base, path)
        } else {
            format!("{}/{}", self.base, path)
        }
    }

    /// GET <path> → T
    pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> CtlResult<T> {
        let resp = self.http.get(self.url(path)).send().await?;
        decode_json(resp).await
    }

    /// POST <path> with JSON body → T
    pub async fn post_json<B: Serialize, T: DeserializeOwned>(
        &self,
        path: &str,
        body: &B,
    ) -> CtlResult<T> {
        let resp = self.http.post(self.url(path)).json(body).send().await?;
        decode_json(resp).await
    }

    /// DELETE <path> — body ignored, only status checked.
    pub async fn delete(&self, path: &str) -> CtlResult<()> {
        let resp = self.http.delete(self.url(path)).send().await?;
        check_status(resp).await.map(|_| ())
    }

    /// Stream Server-Sent-Events-ish JSON lines (newline-delimited) from a GET endpoint.
    /// Used by `logs --follow` over HTTP chunked transfer.
    pub async fn get_stream(&self, path: &str) -> CtlResult<reqwest::Response> {
        let resp = self.http.get(self.url(path)).send().await?;
        check_status(resp).await
    }

    /// Build a WebSocket URL aligned to the same base. http→ws, https→wss.
    pub fn ws_url(&self, path: &str) -> CtlResult<String> {
        let mut u = url::Url::parse(&self.url(path))
            .map_err(|e| CtlError::usage(format!("bad url: {e}")))?;
        match u.scheme() {
            "http" => u
                .set_scheme("ws")
                .map_err(|_| CtlError::usage("set ws scheme"))?,
            "https" => u
                .set_scheme("wss")
                .map_err(|_| CtlError::usage("set wss scheme"))?,
            "ws" | "wss" => {}
            other => return Err(CtlError::usage(format!("unsupported scheme: {other}"))),
        }
        Ok(u.to_string())
    }
}

async fn check_status(resp: reqwest::Response) -> CtlResult<reqwest::Response> {
    let status = resp.status();
    if status.is_success() {
        return Ok(resp);
    }
    // Best-effort: include server-provided body in the error message.
    let body = resp.text().await.unwrap_or_default();
    let body_trim = body.trim();
    let detail = if body_trim.is_empty() {
        format!("server returned {status}")
    } else {
        format!("server returned {status}: {body_trim}")
    };
    let code = status.as_u16();
    Err(match status {
        StatusCode::BAD_REQUEST | StatusCode::UNPROCESSABLE_ENTITY => {
            CtlError::validation(detail).with_status(code)
        }
        _ => CtlError::api(detail).with_status(code),
    })
}

async fn decode_json<T: DeserializeOwned>(resp: reqwest::Response) -> CtlResult<T> {
    let resp = check_status(resp).await?;
    let bytes = resp.bytes().await?;
    serde_json::from_slice(&bytes).map_err(|e| CtlError::api(format!("decode json: {e}")))
}