supreme_fs/game_storage/online/

rooms.rs

//! Rooms API client for the online tournament.
//!
//! Everything here talks to the rooms actions the backend exposes at
//! `<api_url>?action=room_*` with a JSON body:
//!
//! | Method (this module)      | Action               | Response payload          |
//! |---------------------------|----------------------|---------------------------|
//! | [`GameStorage::create_room`]       | `room_create`        | `{room: RoomDto}`         |
//! | [`GameStorage::list_rooms`]        | `room_list`          | `{rooms: RoomSummaryDto[]}` |
//! | [`GameStorage::get_room`]          | `room_get`           | `{room: RoomDto}`         |
//! | [`GameStorage::join_room`]         | `room_join`          | `{room: RoomDto}`         |
//! | [`GameStorage::remove_room`]       | `room_remove`        | `{status: ...}`           |
//! | [`GameStorage::upload_room_record`]| `room_upload_record` | `{accepted, personal_best, rank, room}` |
//! | [`GameStorage::fetch_room_records`]| `room_records`       | `{records: RoomRecordDto[]}` |
//! | [`GameStorage::fetch_room_high_times`]| `room_high_times`  | `{high_times, entries}`    |
//! | [`GameStorage::fetch_room_high_times_version`]| `room_high_times_version` | `{version: sha256}` |
//!
//! # JSON casing (matched to the real server envelope)
//!
//! The backend's existing response builders are snake_case, `php/index.php`
//! emits `status`, `message`, `missing_files`, `max_upload_size`,
//! `chunk_index`, `upload_id`, `path_info`, `filename`, and the payload
//! examples are snake_case too (`ends_at`, `time_ticks`, `player_count`,
//! `record_count`, `uploaded_at`, `personal_best`). The DTO field names
//! below therefore match the wire format verbatim: **no** `rename_all`
//! attribute, plain serde field names.
//!
//! # Response handling
//!
//! Follows the fixed online-layer pattern (the client is built with
//! `http_status_as_error(false)`): an explicit `status().is_success()` check
//! turns non-2xx responses into errors carrying the server's message, and a
//! 2xx response whose body is the rooms error envelope
//! `{"status":"error","message":"..."}` is also an error.
//! `accepted: false` from `room_upload_record` is a *successful* response
//! (the server kept the player's existing personal best), never an error.
//!
//! # Record blob upload
//!
//! [`GameStorage::upload_room_record`] first pushes the raw `.dat` into the
//! server's CAS through the existing unified chunked upload
//! ([`GameStorage::upload_file_unified`], the same path
//! `supreme_snapshot` uses for replay content), and only then claims it
//! with `room_upload_record {id, player, time_ticks, hash}`, the server
//! rejects records whose hash is not already in the CAS.
//!
//! Because the backend only accepts content uploads whose hash is
//! referenced by a pending staging manifest (anti-abuse rule carried over
//! from the snapshot flow), a minimal throw-away manifest referencing the
//! blob is staged first. The manifest is deliberately **not** committed:
//! unlike a shared replay snapshot it must not appear in the public
//! replays listing, and the room JSON the server keeps is the only
//! manifest a tournament record needs.

use super::util::api_http_error;
use crate::HybridStorageError;
use crate::game_storage::GameStorage;
use serde::de::DeserializeOwned;
use sha2::{Digest, Sha256};
use std::io;
use std::path::Path;

/// One room record: the best replay `.dat` of a single player in a
/// room. `hash` is the CAS sha256 of the uploaded `.dat`.
///
/// `splits_ms` is `[checkpoint1_ms, checkpoint2_ms]` as captured at upload
/// time (whole milliseconds); `None` for records uploaded without usable
/// split data (including everything stored by older clients/servers, the
/// server renders finish-only splits for those).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RoomRecordDto {
    pub player: String,
    pub time_ticks: i64,
    pub hash: String,
    pub size: i64,
    pub uploaded_at: i64,
    #[serde(default)]
    pub splits_ms: Option<[i64; 2]>,
}

/// Lightweight room entry as returned by `room_list` (every room whose
/// `ends_at` is in the future, including not-yet-started rooms, which the
/// launcher shows as unselectable until they go live).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RoomSummaryDto {
    pub id: String,
    /// Room display name. Empty for servers/rooms predating it.
    #[serde(default)]
    pub name: String,
    pub env: String,
    pub difficulty: String,
    pub host: String,
    /// When the room opens for play, epoch seconds UTC. `0` on
    /// servers predating it, treated as "already started".
    #[serde(default)]
    pub starts_at: i64,
    pub ends_at: i64,
    pub player_count: i64,
    pub record_count: i64,
    /// The room's human-facing results page, built BY THE SERVER from its
    /// own public base URL (env `SUPREME_PUBLIC_BASE_URL`, falling back to
    /// the request origin). `None` when the server does not publish one:
    /// the launcher only renders its results icon when this is `Some`,
    /// it never assembles the URL client-side (the launcher cannot know
    /// how the backend is exposed to browsers).
    #[serde(default)]
    pub results_url: Option<String>,
    /// The creating account's user id when the server tracks room
    /// ownership (an account-created room). `None` on servers/rooms
    /// predating it: ownership then rests on the `host` name alone (the
    /// guest trust level of the rest of the API). The launcher uses it
    /// to offer removal of rooms "your account owns".
    #[serde(default)]
    pub owner_user_id: Option<i64>,
}

/// Full room state as returned by `room_create`, `room_get` and `room_join`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RoomDto {
    pub id: String,
    /// Room display name (; server-generated snowboarding name when
    /// the creator left it empty). Empty for servers predating it.
    #[serde(default)]
    pub name: String,
    pub env: String,
    pub difficulty: String,
    pub host: String,
    /// When the room opens for play, epoch seconds UTC. `0` on
    /// servers predating it, treated as "already started".
    #[serde(default)]
    pub starts_at: i64,
    pub ends_at: i64,
    pub created_at: i64,
    pub players: Vec<String>,
    pub records: Vec<RoomRecordDto>,
}

impl RoomDto {
    /// Is the room open for business right now (started AND not ended)?
    /// `starts_at == 0` (servers predating ) counts as started.
    #[must_use]
    pub fn is_live(&self, now: i64) -> bool {
        (self.starts_at == 0 || self.starts_at <= now) && self.ends_at > now
    }
}

impl RoomSummaryDto {
    /// [`RoomDto::is_live`] for the list entry.
    #[must_use]
    pub fn is_live(&self, now: i64) -> bool {
        (self.starts_at == 0 || self.starts_at <= now) && self.ends_at > now
    }

    /// May this room still be removed by its creator: only BEFORE the
    /// room's start time and while no other player has joined (the
    /// server enforces both guards under its room lock, this is the
    /// launcher's client-side gate for showing the affordance at all).
    /// A `starts_at` of `0` (servers predating the field) counts as
    /// already started: an old-style room can never be removed.
    #[must_use]
    pub fn is_removable(&self, now: i64) -> bool {
        self.starts_at > now && self.player_count <= 1
    }
}

/// Result of `room_upload_record`. `accepted: false` means the server kept
/// the player's existing (better or equal) personal best, a successful
/// response, not an error.
#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
pub struct RoomUploadResult {
    pub accepted: bool,
    pub personal_best: Option<i64>,
    pub rank: i64,
}

/// A logged-in account's identity, attached additively to room actions
/// (`user_id` + `auth_key` body fields; `None` = guest). The server
/// verifies the pair and stamps the account on the room/record; guests
/// keep working unchanged and may not use a registered nickname.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RoomIdentity<'a> {
    pub user_id: i64,
    pub auth_key: &'a str,
}

/// The `room_remove` JSON body (pure, so the wire shape is unit-testable):
/// `{id, player}` plus the account identity fields when the caller is
/// logged in.
#[must_use]
pub fn room_remove_payload(
    id: &str,
    player: &str,
    identity: Option<RoomIdentity<'_>>,
) -> serde_json::Value {
    let mut payload = serde_json::json!({ "id": id, "player": player });
    apply_room_identity(&mut payload, identity);
    payload
}

/// Add the account identity fields to a JSON action body when the caller
/// is logged in (pure, so the wire shape is unit-testable). Absent fields
/// mean guest, exactly like an old client's body.
pub(crate) fn apply_room_identity(
    body: &mut serde_json::Value,
    identity: Option<RoomIdentity<'_>>,
) {
    if let (Some(identity), Some(obj)) = (identity, body.as_object_mut()) {
        obj.insert(
            "user_id".to_owned(),
            serde_json::Value::Number(identity.user_id.into()),
        );
        obj.insert(
            "auth_key".to_owned(),
            serde_json::Value::String(identity.auth_key.to_owned()),
        );
    }
}

/// Envelope for `room_create` / `room_get` / `room_join`: `{room: RoomDto}`.
#[derive(serde::Deserialize)]
struct RoomEnvelope {
    room: RoomDto,
}

/// Envelope for `room_list`: `{rooms: RoomSummaryDto[]}`.
#[derive(serde::Deserialize)]
struct RoomListEnvelope {
    rooms: Vec<RoomSummaryDto>,
}

/// Envelope for `room_remove`: the standard `{status: "success"}`
/// envelope (the payload is empty, the `status` check lives in
/// [`post_room_action`](GameStorage::post_room_action)).
#[derive(serde::Deserialize)]
struct RoomRemovedEnvelope {}

/// Envelope for `room_records`: `{records: RoomRecordDto[]}`.
#[derive(serde::Deserialize)]
struct RoomRecordsEnvelope {
    records: Vec<RoomRecordDto>,
}

/// Envelope for `room_high_times`: `{high_times, entries}`, the exact
/// high-times file text the server rendered for the requesting player, plus
/// the number of entries it contains (diagnostics; the full leaderboard can
/// exceed the game's five replay slots).
#[derive(serde::Deserialize)]
struct RoomHighTimesEnvelope {
    high_times: String,
    #[serde(default)]
    entries: i64,
}

/// Envelope for `room_high_times_version` : `{version}`, the sha-256
/// hex digest of the exact text `room_high_times` would currently return for
/// the same request. This is the CAS version test: the caller hashes its
/// local file and only downloads the body when the digests differ, then
/// verifies the downloaded body against the same digest before storing it
/// (content-addressed copy semantics).
#[derive(serde::Deserialize)]
struct RoomHighTimesVersionEnvelope {
    version: String,
}

/// Map a [`fetch_room_high_times`](GameStorage::fetch_room_high_times)
/// result to the optional `(file text, entry count)`: a server that predates
/// the action answers the request with a version-mismatch signature, which
/// means "generate locally" (Ok(None)), every other error stays an error so
/// the caller's own error path reports it.
fn room_high_times_from_result(
    result: Result<RoomHighTimesEnvelope, HybridStorageError>,
) -> Result<Option<(String, i64)>, HybridStorageError> {
    match result {
        Ok(envelope) => Ok(Some((envelope.high_times, envelope.entries))),
        Err(HybridStorageError::ServerVersionMismatch(_)) => Ok(None),
        Err(e) => Err(e),
    }
}

/// Map a [`fetch_room_high_times_version`](GameStorage::fetch_room_high_times_version)
/// result to the optional content hash, with the same "server predates the
/// action" (Ok(None)) convention as [`room_high_times_from_result`].
fn room_high_times_version_from_result(
    result: Result<RoomHighTimesVersionEnvelope, HybridStorageError>,
) -> Result<Option<String>, HybridStorageError> {
    match result {
        Ok(envelope) => Ok(Some(envelope.version)),
        Err(HybridStorageError::ServerVersionMismatch(_)) => Ok(None),
        Err(e) => Err(e),
    }
}

/// Render the high-times entries for a room's records LOCALLY (local
/// fallback for servers predating `room_high_times`): every valid record
/// (positive `time_ticks`, non-empty `hash`), per-player best only,
/// ascending by `(time_ticks, player, hash)`, the same ordering as
/// [`supreme_tournament::rank_records`] and the server-side renderer, so
/// a fallback file can never disagree with a server-rendered one about
/// rank order.
///
/// Split times come straight from the stored `splits_ms`; records without
/// usable splits render finish-only (both checkpoints collapse to the
/// finish, exactly like the server does). The per-entry date column is the
/// record's upload date (UTC, game format), no padding is applied here;
/// callers that need the hot-tail dummies call
/// [`supreme_tournament::pad_with_dummies`] themselves.
pub fn high_times_entries_from_records(
    dtos: &[RoomRecordDto],
) -> Vec<supreme_tournament::HighTimesEntry> {
    use supreme_tournament::{HighTimesEntry, entry_times_ms, format_game_date};

    let mut ranked: Vec<&RoomRecordDto> = dtos
        .iter()
        .filter(|d| d.time_ticks > 0 && !d.hash.is_empty())
        .collect();
    ranked.sort_by(|a, b| {
        (a.time_ticks, &a.player, &a.hash).cmp(&(b.time_ticks, &b.player, &b.hash))
    });
    ranked.dedup_by_key(|d| d.player.as_str());

    ranked
        .into_iter()
        .map(|d| {
            let finish_ms = d.time_ticks * 10;
            let (cp1, cp2, finish) = match d.splits_ms {
                Some([cp1_ms, cp2_ms]) => entry_times_ms(finish_ms, cp1_ms, Some(cp2_ms)),
                None => entry_times_ms(finish_ms, 0, None),
            };
            HighTimesEntry {
                player: d.player.clone(),
                checkpoint1_ms: cp1,
                checkpoint2_ms: cp2,
                finish_ms: finish,
                conditions: "Day".to_owned(),
                date: format_game_date(d.uploaded_at),
            }
        })
        .collect()
}

/// Envelope for `room_upload_record`: `{accepted, personal_best, rank, room}`.
/// `rank` / `personal_best` are `#[serde(default)]` so a server that omits
/// them on a rejected upload still parses; an absent `rank` maps to `0`
/// ("unknown") in [`RoomUploadResult`].
#[derive(serde::Deserialize)]
struct RoomUploadEnvelope {
    accepted: bool,
    #[serde(default)]
    personal_best: Option<i64>,
    #[serde(default)]
    rank: Option<i64>,
}

/// Return the error message when `value` is the standard error envelope
/// `{"status":"error","message":"..."}`, `None` for success payloads.
/// Shared by the rooms actions and the auth module's actions (the same
/// envelope governs every `?action=` endpoint).
pub(super) fn room_error_message(value: &serde_json::Value) -> Option<String> {
    if value.get("status").and_then(|s| s.as_str()) == Some("error") {
        return Some(
            value
                .get("message")
                .and_then(|m| m.as_str())
                .unwrap_or("unknown room API error")
                .to_string(),
        );
    }
    None
}

fn json_parse_error(e: serde_json::Error) -> HybridStorageError {
    HybridStorageError::IoError(io::Error::new(io::ErrorKind::InvalidData, e))
}

impl GameStorage {
    /// POST one JSON action (`?action=<name>` with a JSON body, the
    /// request shape the rooms and auth endpoints share) and decode its
    /// payload.
    ///
    /// Auth mirrors the existing multipart actions: the `X-SSBZ-Token`
    /// header when a token is configured, plus the `api_token` field inside
    /// the JSON body (the JSON equivalent of the `api_token` form field).
    ///
    /// # Errors
    ///
    /// Transport errors propagate. A response carrying the error
    /// envelope `{"status":"error","message":"..."}` is an
    /// [`HybridStorageError::UploadFailed`] with the server's message
    /// VERBATIM (the envelope is the server's per-request refusal copy:
    /// `403` not the creator, `409` players joined, a reserved nickname,
    /// ...), regardless of the HTTP status. Non-2xx responses that are
    /// NOT an error envelope are classified by the online layer's shared
    /// [`api_http_error`]: signatures of a backend that predates the
    /// requested API (legacy 413/400 catch-alls, `Unknown action`,
    /// endpoint-level 404s) become
    /// [`HybridStorageError::ServerVersionMismatch`], the end-user-facing
    /// "server version mismatch" message; genuine per-request failures
    /// stay [`HybridStorageError::UploadFailed`] carrying the server's
    /// message.
    pub(crate) fn post_room_action<T: DeserializeOwned>(
        &self,
        action: &str,
        payload: serde_json::Value,
    ) -> Result<T, HybridStorageError> {
        let client = self
            .client
            .as_ref()
            .ok_or_else(|| io::Error::other("Online storage not configured"))?;
        let api_url = self
            .api_url
            .as_ref()
            .ok_or_else(|| io::Error::other("Online storage not configured"))?;

        let mut body = payload;
        if let (Some(token), Some(obj)) = (&self.token, body.as_object_mut()) {
            obj.insert(
                "api_token".to_string(),
                serde_json::Value::String(token.clone()),
            );
        }
        let body_bytes = serde_json::to_vec(&body).map_err(json_parse_error)?;

        let url = format!("{api_url}?action={action}");
        let mut request = client.post(&url).header("Content-Type", "application/json");
        if let Some(token) = &self.token {
            request = request.header("X-SSBZ-Token", token);
        }
        let response = request.send(body_bytes)?;

        let value: serde_json::Value = if response.status().is_success() {
            response
                .into_body()
                .read_json()
                .map_err(|e| {
                    HybridStorageError::IoError(io::Error::new(
                        io::ErrorKind::InvalidData,
                        format!("rooms API returned invalid JSON: {e}"),
                    ))
                })?
        } else {
            let status = response.status().as_u16();
            let body = response.into_body().read_to_string().unwrap_or_default();
            // The rooms error envelope IS the server's refusal copy, on
            // ANY status: surface its message verbatim. Only the
            // version-mismatch signatures keep their classified error (an
            // old backend's "Unknown action" answers an update-the-server
            // message, not a per-request refusal).
            if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&body)
                && let Some(message) = room_error_message(&parsed)
                && !super::util::server_version_mismatch_signature(
                    status,
                    Some(message.as_str()),
                    true,
                )
            {
                return Err(HybridStorageError::UploadFailed(message));
            }
            return Err(api_http_error(status, &body));
        };

        if let Some(message) = room_error_message(&value) {
            return Err(HybridStorageError::UploadFailed(message));
        }

        serde_json::from_value(value).map_err(json_parse_error)
    }

    /// Create a tournament room (`room_create`). The server generates
    /// the room id (`r_` + 12 hex chars) and `created_at`.
    ///
    /// the room has a planning window, `starts_at` (epoch seconds;
    /// may reach 13 h into the past, 7 days into the future) and `ends_at`
    /// (after `starts_at`, at most 7 days out; a host may not have two
    /// rooms sharing a UTC calendar day), and an optional display `name`
    /// (empty = the server picks a snowboarding word pair; a supplied name
    /// must pass the server's blocklist).
    ///
    /// `identity` attaches the logged-in account when present (the room
    /// becomes account-owned and verified); `None` creates as a guest.
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`].
    pub fn create_room(
        &self,
        env: &str,
        difficulty: &str,
        host: &str,
        name: &str,
        starts_at: i64,
        ends_at: i64,
        identity: Option<RoomIdentity<'_>>,
    ) -> Result<RoomDto, HybridStorageError> {
        let mut payload = serde_json::json!({
            "env": env,
            "difficulty": difficulty,
            "host": host,
            "name": name,
            "starts_at": starts_at,
            "ends_at": ends_at,
        });
        apply_room_identity(&mut payload, identity);
        Ok(self
            .post_room_action::<RoomEnvelope>("room_create", payload)?
            .room)
    }

    /// List open rooms (`room_list`; the server only returns rooms whose
    /// `ends_at` is in the future).
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`].
    pub fn list_rooms(&self) -> Result<Vec<RoomSummaryDto>, HybridStorageError> {
        Ok(self
            .post_room_action::<RoomListEnvelope>("room_list", serde_json::json!({}))?
            .rooms)
    }

    /// Fetch full room state (`room_get`).
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`].
    pub fn get_room(&self, id: &str) -> Result<RoomDto, HybridStorageError> {
        Ok(self
            .post_room_action::<RoomEnvelope>("room_get", serde_json::json!({ "id": id }))?
            .room)
    }

    /// Join a room as `player` (`room_join`), with the logged-in
    /// account's `identity` attached when present (a guest join stays
    /// `None`; the server refuses a guest whose name matches a
    /// registered nickname, that refusal arrives verbatim).
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`].
    pub fn join_room(
        &self,
        id: &str,
        player: &str,
        identity: Option<RoomIdentity<'_>>,
    ) -> Result<RoomDto, HybridStorageError> {
        let mut payload = serde_json::json!({ "id": id, "player": player });
        apply_room_identity(&mut payload, identity);
        Ok(self
            .post_room_action::<RoomEnvelope>("room_join", payload)?
            .room)
    }

    /// Remove a room you created (`room_remove`). The server only
    /// accepts the request from the room's creator, only while no other
    /// player has joined, and only BEFORE the room's start time; the
    /// player identifies as the creator by `player` name (guest rooms)
    /// and/or the account `identity` when logged in. The room's files are
    /// deleted server-side; the content-addressed blobs are shared and
    /// stay.
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`]; the server's refusal
    /// messages (`not the creator`, `players have joined`, `room already
    /// started`, `unknown room`) arrive verbatim. A backend predating
    /// the action answers a version-mismatch signature.
    pub fn remove_room(
        &self,
        id: &str,
        player: &str,
        identity: Option<RoomIdentity<'_>>,
    ) -> Result<(), HybridStorageError> {
        let payload = room_remove_payload(id, player, identity);
        self.post_room_action::<RoomRemovedEnvelope>("room_remove", payload)
            .map(|_| ())
    }

    /// Fetch the best record per player (`room_records`, the DLL's
    /// polling endpoint).
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`].
    pub fn fetch_room_records(
        &self,
        room_id: &str,
    ) -> Result<Vec<RoomRecordDto>, HybridStorageError> {
        Ok(self
            .post_room_action::<RoomRecordsEnvelope>(
                "room_records",
                serde_json::json!({ "id": room_id }),
            )?
            .records)
    }

    /// Fetch the server-rendered high-times file for the selected track's
    /// room and `player` (`room_high_times`): the exact text the game's
    /// `Saved_Data/<env>_<diff>_high_times.txt` should contain, the
    /// FULL room leaderboard (every record the server has, ascending, plus
    /// dummy padding only when fewer than five), so the game's high-score
    /// screen shows everyone. Entry rank N pairs with `Replay_N.dat` for the
    /// game's five replay slots.
    ///
    /// Returns `Ok(Some((text, entries)))` on success (`entries` = the
    /// rendered entry count, diagnostics), and `Ok(None)` when the server
    /// predates the action (version mismatch signature), the caller falls
    /// back to local generation ([`high_times_entries_from_records`]).
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`]; all non-version-mismatch
    /// errors propagate.
    pub fn fetch_room_high_times(
        &self,
        room_id: &str,
        player: &str,
    ) -> Result<Option<(String, i64)>, HybridStorageError> {
        let result = self.post_room_action::<RoomHighTimesEnvelope>(
            "room_high_times",
            serde_json::json!({ "id": room_id, "player": player }),
        );
        room_high_times_from_result(result)
    }

    /// Ask the server for the CONTENT HASH of the current high-times file
    /// for the selected track's room and `player`
    /// (`room_high_times_version`): the sha-256 hex digest of the exact
    /// text [`GameStorage::fetch_room_high_times`] would return right now.
    /// The cheap half of the CAS copy rule, hash the local file, and only
    /// download the body when the digests differ.
    ///
    /// Returns `Ok(Some(version))` on success and `Ok(None)` when the server
    /// predates the action (version-mismatch signature), the caller then
    /// degrades to fetching the body and byte-comparing it against the local
    /// file, which avoids spurious writes on old servers too.
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`]; all non-version-mismatch
    /// errors propagate.
    pub fn fetch_room_high_times_version(
        &self,
        room_id: &str,
        player: &str,
    ) -> Result<Option<String>, HybridStorageError> {
        let result = self.post_room_action::<RoomHighTimesVersionEnvelope>(
            "room_high_times_version",
            serde_json::json!({ "id": room_id, "player": player }),
        );
        room_high_times_version_from_result(result)
    }

    /// Upload a tournament record for `player` (`room_upload_record`).
    ///
    /// `time_ticks` is the race time in the game's 10 ms replay ticks. The
    /// `.dat` at `dat_path` is first pushed into the server CAS through the
    /// existing unified chunked upload, then claimed with
    /// `room_upload_record {id, player, time_ticks, hash, splits_ms?}`.
    /// `splits_ms` (whole-millisecond `[checkpoint1_ms, checkpoint2_ms]`)
    /// lets the server render the room's high-times entries with real
    /// split times; `None` uploads the record without them (the server
    /// then falls back to finish-only splits).
    ///
    /// `accepted: false` (worse or equal than the player's existing
    /// personal best) is a successful [`RoomUploadResult`], not an error.
    ///
    /// # Errors
    ///
    /// See [`GameStorage::post_room_action`]; also fails when `time_ticks`
    /// is 0 (the server would reject it and the blob upload would be
    /// wasted) or when reading `dat_path` fails.
    pub fn upload_room_record(
        &self,
        room_id: &str,
        player: &str,
        time_ticks: u32,
        dat_path: &Path,
        splits_ms: Option<[i64; 2]>,
    ) -> Result<RoomUploadResult, HybridStorageError> {
        if time_ticks == 0 {
            return Err(HybridStorageError::UploadFailed(
                "time_ticks must be > 0".to_string(),
            ));
        }

        let data = std::fs::read(dat_path)?;
        let hash = {
            let mut hasher = Sha256::new();
            hasher.update(&data);
            hex::encode(hasher.finalize())
        };

        self.upload_record_blob(&hash, &data)?;

        let mut payload = serde_json::json!({
            "id": room_id,
            "player": player,
            "time_ticks": time_ticks,
            "hash": hash,
        });
        if let Some(splits) = splits_ms {
            payload["splits_ms"] = serde_json::json!(splits);
        }
        let envelope: RoomUploadEnvelope = self.post_room_action("room_upload_record", payload)?;

        Ok(RoomUploadResult {
            accepted: envelope.accepted,
            personal_best: envelope.personal_best,
            rank: envelope.rank.unwrap_or(0),
        })
    }

    /// Push the raw record `.dat` into the server CAS via the existing
    /// upload path.
    ///
    /// Stages a minimal manifest referencing the blob (the backend only
    /// accepts content uploads referenced by a pending staging manifest),
    /// then reuses [`GameStorage::upload_file_unified`] with
    /// `file_type = "content"`, the exact call
    /// [`crate::game_storage::GameStorage::upload_content_file`] makes, so
    /// chunking, hashing and error handling are identical to every other
    /// CAS upload. The staged manifest is never committed (see module docs).
    ///
    /// # Errors
    ///
    /// Staging or content upload failures surface as
    /// [`HybridStorageError::UploadFailed`].
    fn upload_record_blob(&self, hash: &str, data: &[u8]) -> Result<(), HybridStorageError> {
        use super::multipart::{MultipartForm, SendMultipart};

        let client = self
            .client
            .as_ref()
            .ok_or_else(|| io::Error::other("Online storage not configured"))?;
        let api_url = self
            .api_url
            .as_ref()
            .ok_or_else(|| io::Error::other("Online storage not configured"))?;

        let manifest = serde_json::json!({
            "name": format!("room_record_{hash}"),
            "files": { "record.dat": hash },
        });
        let manifest_bytes = serde_json::to_vec(&manifest).map_err(json_parse_error)?;
        let manifest_hash = {
            let mut hasher = Sha256::new();
            hasher.update(&manifest_bytes);
            hex::encode(hasher.finalize())
        };
        let manifest_filename = format!("{manifest_hash}.json");

        // Single-shot staging upload (no commit): identical to the
        // non-chunked snapshot_file path the test harness exercises.
        let mut form = MultipartForm::new().bytes(
            "snapshot_file",
            &manifest_filename,
            "application/json",
            &manifest_bytes,
        );
        if let Some(token) = &self.token {
            form = form.text("api_token", token.clone());
        }

        let mut request = client.post(api_url);
        if let Some(ref token) = self.token {
            request = request.header("X-SSBZ-Token", token);
        }
        let response = request.send_multipart(form)?;
        if !response.status().is_success() {
            return Err(HybridStorageError::UploadFailed(
                self.extract_error_message(response),
            ));
        }

        // Existing unified chunked CAS upload (re-uploads are idempotent).
        self.upload_file_unified("contents", data, "content", Some(hash), None)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Rooms-API example JSON (snake_case wire format).
    const ROOM_JSON: &str = r#"{
        "id": "r_0123456789ab",
        "env": "alpine",
        "difficulty": "easy",
        "host": "psycho sam",
        "ends_at": 1760000000,
        "created_at": 1759000000,
        "players": ["psycho sam", "racer_x"],
        "records": [
            {"player": "racer_x", "time_ticks": 61230, "hash": "deadbeef01",
             "size": 4096, "uploaded_at": 1759000100}
        ]
    }"#;

    #[test]
    fn room_dto_parses_snake_case_wire_format() {
        let room: RoomDto = serde_json::from_str(ROOM_JSON).expect("parse RoomDto");
        assert_eq!(room.id, "r_0123456789ab");
        assert_eq!(room.env, "alpine");
        assert_eq!(room.difficulty, "easy");
        assert_eq!(room.host, "psycho sam");
        assert_eq!(room.ends_at, 1_760_000_000);
        assert_eq!(room.created_at, 1_759_000_000);
        assert_eq!(room.players, vec!["psycho sam", "racer_x"]);
        assert_eq!(room.records.len(), 1);
        assert_eq!(room.records[0].player, "racer_x");
        assert_eq!(room.records[0].time_ticks, 61_230);
        assert_eq!(room.records[0].hash, "deadbeef01");
        assert_eq!(room.records[0].size, 4_096);
        assert_eq!(room.records[0].uploaded_at, 1_759_000_100);
    }

    #[test]
    fn room_dto_serializes_snake_case_field_names() {
        let room: RoomDto = serde_json::from_str(ROOM_JSON).expect("parse RoomDto");
        let value = serde_json::to_value(&room).expect("serialize RoomDto");
        let obj = value.as_object().expect("object");
        for key in ["id", "env", "difficulty", "host", "ends_at", "created_at"] {
            assert!(obj.contains_key(key), "missing wire field {key}");
        }
        assert!(!obj.contains_key("endsAt"), "no camelCase on the wire");
        let record = &obj["records"][0];
        for key in ["player", "time_ticks", "hash", "size", "uploaded_at"] {
            assert!(record.get(key).is_some(), "record missing wire field {key}");
        }
        assert!(record.get("timeTicks").is_none());
    }

    #[test]
    fn room_summary_parses_list_entry() {
        let summary: RoomSummaryDto = serde_json::from_str(
            r#"{"id":"r_aa11bb22cc33","env":"forest","difficulty":"hard",
                "host":"host_dude","ends_at":1760000000,
                "player_count":3,"record_count":5}"#,
        )
        .expect("parse RoomSummaryDto");
        assert_eq!(summary.id, "r_aa11bb22cc33");
        assert_eq!(summary.player_count, 3);
        assert_eq!(summary.record_count, 5);
        // Servers predating the field (no results_url on the wire) still
        // parse; the launcher hides its results icon for them.
        assert_eq!(summary.results_url, None);
    }

    #[test]
    fn room_summary_parses_results_url_when_the_server_publishes_one() {
        let summary: RoomSummaryDto = serde_json::from_str(
            r#"{"id":"r_aa11bb22cc33","env":"forest","difficulty":"hard",
                "host":"host_dude","ends_at":1760000000,
                "player_count":3,"record_count":5,
                "results_url":"https://ssbz.example/leaderboard.html?id=r_aa11bb22cc33"}"#,
        )
        .expect("parse RoomSummaryDto");
        assert_eq!(
            summary.results_url.as_deref(),
            Some("https://ssbz.example/leaderboard.html?id=r_aa11bb22cc33")
        );
        // owner_user_id rides along when the server tracks ownership;
        // servers predating it keep parsing as guest-hosted rooms.
        let summary: RoomSummaryDto = serde_json::from_str(
            r#"{"id":"r_aa11bb22cc33","env":"forest","difficulty":"hard",
                "host":"host_dude","ends_at":1760000000,
                "player_count":1,"record_count":0,"owner_user_id":7}"#,
        )
        .expect("parse RoomSummaryDto with owner");
        assert_eq!(summary.owner_user_id, Some(7));
    }

    #[test]
    fn room_remove_is_gated_on_start_time_and_other_players() {
        let mut room = RoomSummaryDto {
            id: "r_x".to_owned(),
            name: "Fresh Powder".to_owned(),
            env: "alpine".to_owned(),
            difficulty: "easy".to_owned(),
            host: "Xinfe".to_owned(),
            starts_at: 1_000,
            ends_at: 2_000,
            player_count: 1,
            record_count: 0,
            results_url: None,
            owner_user_id: None,
        };
        // Un-started, only the creator inside: removable.
        assert!(room.is_removable(999));
        // The boundary mirrors `is_live`: the second the room starts it
        // is live, so that is exactly when it stops being removable.
        assert!(!room.is_removable(1_000), "the start second is live");
        assert!(!room.is_removable(1_001), "a started room is not removable");
        // Someone joined: not removable even before the start.
        room.player_count = 2;
        assert!(!room.is_removable(999));
        // starts_at == 0 (servers predating the field) counts as started.
        room.starts_at = 0;
        room.player_count = 1;
        assert!(!room.is_removable(0), "an old-style room is never removable");
    }

    #[test]
    fn room_remove_payload_carries_id_player_and_identity_fields() {
        // Guest: exactly {id, player}, no identity keys (an old client's
        // body shape).
        let guest = room_remove_payload("r_ab12", "Xinfe", None);
        assert_eq!(
            guest,
            serde_json::json!({"id": "r_ab12", "player": "Xinfe"})
        );

        // Logged in: the account identity rides along additively.
        let identity = RoomIdentity {
            user_id: 7,
            auth_key: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        };
        let owned = room_remove_payload("r_ab12", "Xinfe", Some(identity));
        assert_eq!(
            owned,
            serde_json::json!({
                "id": "r_ab12",
                "player": "Xinfe",
                "user_id": 7,
                "auth_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
            })
        );
    }

    #[test]
    fn room_upload_envelope_parses_full_and_minimal_payloads() {
        let full: RoomUploadEnvelope = serde_json::from_value(serde_json::json!({
            "accepted": true, "personal_best": 61230, "rank": 1,
            "room": serde_json::from_str::<serde_json::Value>(ROOM_JSON).unwrap()
        }))
        .expect("parse full upload envelope");
        assert!(full.accepted);
        assert_eq!(full.personal_best, Some(61_230));
        assert_eq!(full.rank, Some(1));

        // Server may omit rank/personal_best on a rejected upload; the
        // trailing `room` payload is not part of RoomUploadResult.
        let minimal: RoomUploadEnvelope = serde_json::from_value(serde_json::json!({
            "accepted": false, "personal_best": 61000, "rank": 1, "room": null
        }))
        .expect("parse minimal upload envelope");
        assert!(!minimal.accepted);
        assert_eq!(minimal.personal_best, Some(61_000));

        let bare: RoomUploadEnvelope =
            serde_json::from_value(serde_json::json!({ "accepted": true }))
                .expect("parse bare upload envelope");
        assert_eq!(bare.rank, None);
    }

    #[test]
    fn room_error_message_detects_d4_error_envelope() {
        let value: serde_json::Value =
            serde_json::from_str(r#"{"status":"error","message":"unknown action"}"#)
                .expect("parse error envelope");
        assert_eq!(
            room_error_message(&value).as_deref(),
            Some("unknown action")
        );
    }

    #[test]
    fn room_error_message_ignores_success_payloads() {
        let success: serde_json::Value =
            serde_json::from_str(r#"{"status":"success","rooms":[]}"#).expect("parse");
        assert_eq!(room_error_message(&success), None);

        let legacy: serde_json::Value =
            serde_json::from_str(r#"{"error":"legacy error shape"}"#).expect("parse");
        // Legacy envelope has no "status", non-2xx handling owns it.
        assert_eq!(room_error_message(&legacy), None);

        assert_eq!(room_error_message(&serde_json::json!({})), None);
    }

    #[test]
    fn room_upload_result_maps_absent_rank_to_zero() {
        let envelope: RoomUploadEnvelope =
            serde_json::from_value(serde_json::json!({ "accepted": true }))
                .expect("parse bare envelope");
        let result = RoomUploadResult {
            accepted: envelope.accepted,
            personal_best: envelope.personal_best,
            rank: envelope.rank.unwrap_or(0),
        };
        assert!(result.accepted);
        assert_eq!(result.personal_best, None);
        assert_eq!(result.rank, 0);
    }

    #[test]
    fn room_record_dto_parses_with_and_without_splits_ms() {
        let with: RoomRecordDto = serde_json::from_str(
            r#"{"player":"racer_x","time_ticks":61230,"hash":"deadbeef01",
                "size":4096,"uploaded_at":1759000100,
                "splits_ms":[20140,41500]}"#,
        )
        .expect("parse record with splits_ms");
        assert_eq!(with.splits_ms, Some([20_140, 41_500]));

        // Older servers (and uploads without usable splits) omit the field.
        let without: RoomRecordDto = serde_json::from_str(
            r#"{"player":"racer_x","time_ticks":61230,"hash":"deadbeef01",
                "size":4096,"uploaded_at":1759000100}"#,
        )
        .expect("parse record without splits_ms");
        assert_eq!(without.splits_ms, None);

        // The server may also store an explicit null.
        let null: RoomRecordDto = serde_json::from_str(
            r#"{"player":"r","time_ticks":1,"hash":"h","size":1,"uploaded_at":1,
                "splits_ms":null}"#,
        )
        .expect("parse record with null splits_ms");
        assert_eq!(null.splits_ms, None);
    }

    #[test]
    fn room_high_times_version_mismatch_maps_to_none() {
        // A backend predating room_high_times answers "Unknown action" (400)
        // → ServerVersionMismatch → Ok(None) = "generate locally".
        let mismatch = HybridStorageError::ServerVersionMismatch(
            "Unknown action: room_high_times. (HTTP 400)".to_string(),
        );
        assert_eq!(
            room_high_times_from_result(Err(mismatch)).unwrap(),
            None,
            "version mismatch must degrade to local generation, not an error"
        );

        // Real failures keep propagating.
        let failed = HybridStorageError::UploadFailed("Room not found: r_x (HTTP 404)".to_string());
        assert!(room_high_times_from_result(Err(failed)).is_err());

        let envelope = RoomHighTimesEnvelope {
            high_times: "{\n}\n".to_string(),
            entries: 0,
        };
        assert_eq!(
            room_high_times_from_result(Ok(envelope)).unwrap(),
            Some(("{\n}\n".to_string(), 0))
        );
    }

    #[test]
    fn room_high_times_version_probe_maps_all_three_outcomes() {
        // Success: the wire's sha-256 hex digest passes through untouched.
        let envelope = RoomHighTimesVersionEnvelope {
            version: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855".to_string(),
        };
        assert_eq!(
            room_high_times_version_from_result(Ok(envelope))
                .unwrap()
                .as_deref(),
            Some("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
        );

        // A backend predating room_high_times_version answers "Unknown
        // action" (400) → ServerVersionMismatch → Ok(None) = "fetch the
        // body and byte-compare instead".
        let mismatch = HybridStorageError::ServerVersionMismatch(
            "Unknown action: room_high_times_version. (HTTP 400)".to_string(),
        );
        assert_eq!(
            room_high_times_version_from_result(Err(mismatch)).unwrap(),
            None,
            "version mismatch must degrade to the body-compare path, not an error"
        );

        // Real failures keep propagating (room gone, server broken, …).
        let failed = HybridStorageError::UploadFailed("Room not found: r_x (HTTP 404)".to_string());
        assert!(room_high_times_version_from_result(Err(failed)).is_err());
    }

    // --- local fallback: DTOs → high-times entries -------------------

    fn dto(
        player: &str,
        ticks: i64,
        hash: &str,
        uploaded_at: i64,
        splits: Option<[i64; 2]>,
    ) -> RoomRecordDto {
        RoomRecordDto {
            player: player.to_owned(),
            time_ticks: ticks,
            hash: hash.to_owned(),
            size: 4096,
            uploaded_at,
            splits_ms: splits,
        }
    }

    #[test]
    fn high_times_entries_render_every_record_ascending_with_splits() {
        let dtos = vec![
            dto("slow", 90_000, "h3", 1_792_454_400, Some([30_000, 60_000])),
            dto("fast", 61_230, "h1", 1_792_454_400, Some([20_140, 41_500])),
            dto("mid", 75_000, "h2", 1_792_454_400, None),
        ];
        let entries = high_times_entries_from_records(&dtos);
        // ALL records, fastest first; nothing truncated.
        assert_eq!(entries.len(), 3);
        assert_eq!(entries[0].player, "fast");
        assert_eq!(entries[1].player, "mid");
        assert_eq!(entries[2].player, "slow");
        // Splits flow straight into the entry (whole milliseconds).
        // ticks are 10 ms units: 61230 ticks = 612300 ms finish.
        assert_eq!(entries[0].checkpoint1_ms, 20_140);
        assert_eq!(entries[0].checkpoint2_ms, 41_500);
        assert_eq!(entries[0].finish_ms, 612_300);
        // The per-entry date column is the record's upload date (UTC).
        assert_eq!(entries[0].date, "2026/10/20");
        // finish-only record, the fallbacks space 10 ms below the
        // finish (75000 ticks = 750000 ms → cp2 = 749990, cp1 = 749980);
        // the old collapse emitted cp1 == cp2, which the game refuses.
        assert_eq!(entries[1].checkpoint1_ms, 749_980);
        assert_eq!(entries[1].checkpoint2_ms, 749_990);
        assert_eq!(entries[1].finish_ms, 750_000);
    }

    #[test]
    fn high_times_entries_dedup_per_player_best_and_skip_invalid() {
        let dtos = vec![
            dto("racer", 90_000, "h-old", 1, None),
            dto("racer", 60_000, "h-new", 2, Some([20_000, 40_000])),
            dto("broken", 0, "h-bad", 3, None), // time_ticks <= 0: skipped
            dto("noname", 50_000, "", 4, None), // empty hash: skipped
        ];
        let entries = high_times_entries_from_records(&dtos);
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].player, "racer");
        // Best (lowest ticks) wins: 60000 ticks = 600000 ms, real splits kept.
        assert_eq!(entries[0].finish_ms, 600_000);
        assert_eq!(entries[0].checkpoint1_ms, 20_000);
        assert_eq!(entries[0].checkpoint2_ms, 40_000);
    }

    #[test]
    fn high_times_entries_empty_room_is_empty_vec() {
        let entries = high_times_entries_from_records(&[]);
        assert!(entries.is_empty());
    }

    // --- non-2xx classification lives in super::util::api_http_error
    // (shared across API action clients; pure tests there) -------------------
}