Merge pull request #21 from CurtisTechSolutions/feat/match-history

feat: add match metadata and paginated history

Author: nosam1998

.sqlx/query-519b6a4759c289716712431f0ca57851ff443ee5fe4fcd6c64f60d606c2cb13d.json

@@ -87,7 +87,8 @@ fn build_router(
             "/v1/games/{game_id}/positions/validate",
             post(validate_position),
         )
-        .route("/v1/matches", post(create))
+        .route("/v1/matches", post(create).get(history))
+        .route("/v1/matches/{id}", get(metadata))
         .route("/v1/matches/{id}/info", get(info::match_info))
         .route("/v1/matches/{id}/state", get(state))
         .route("/v1/matches/{id}/legal-actions", get(legal_actions))
@@ -327,3 +328,30 @@ async fn validate_position(
         viewer,
     )?))
 }
+
+#[utoipa::path(
+    get, path = "/v1/matches", tag = "Matches",
+    params(gfa_api_types::MatchHistoryQuery),
+    responses((status = 200, description = "Bounded local history, ordered by match id. Follow next even when filters return an empty page.", body = gfa_api_types::MatchHistory),
+        (status = "default", description = "Query or service error", body = gfa_api_types::ErrorResponse))
+)]
+async fn history(
+    State(service): State<Arc<GameService>>,
+    query: Result<Query<gfa_api_types::MatchHistoryQuery>, QueryRejection>,
+) -> Result<Json<gfa_api_types::MatchHistory>, HttpError> {
+    let Query(query) = query.map_err(|error| HttpError::request(error.body_text()))?;
+    Ok(Json(service.list_matches(query).await?))
+}
+
+#[utoipa::path(
+    get, path = "/v1/matches/{id}", tag = "Matches",
+    params(("id" = String, Path, description = "Match identifier")),
+    responses((status = 200, description = "Public match metadata without hidden state or RNG", body = gfa_api_types::MatchMetadata),
+        (status = "default", description = "Match or service error", body = gfa_api_types::ErrorResponse))
+)]
+async fn metadata(
+    State(service): State<Arc<GameService>>,
+    path: Id,
+) -> Result<Json<gfa_api_types::MatchMetadata>, HttpError> {
+    Ok(Json(service.get_match(&id(path)?).await?))
+}

crates/adapters/gfa-http/src/lib.rs

@@ -6,7 +6,7 @@ use utoipa::OpenApi;
     info(title = "GamesForAI local API", description = "Single-user local play. Requests require a loopback peer and matching Host and optional Origin. Any local caller can control either seat. Bodies are limited to 64 KiB. Only implemented endpoints are listed."),
     servers((url = "/", description = "This local host")),
     paths(
-        super::health, super::games, super::game, super::create, super::state,
+        super::history, super::metadata, super::health, super::games, super::game, super::create, super::state,
         super::legal_actions, super::make_move, super::replay, super::validate_position,
         super::info::game_info, super::info::match_info, super::stream::upgrade, document
     ),

crates/adapters/gfa-http/src/openapi.rs

@@ -207,6 +207,23 @@ impl MatchStore for SqliteMatchStore {
         Box::pin(self.snapshot(id))
     }
 
+    fn list_ids<'a>(&'a self, after: &'a str, limit: u32) -> StoreFuture<'a, Vec<String>> {
+        Box::pin(async move {
+            if !(1..=101).contains(&limit) {
+                return Err(unavailable("History limit must be 1..101"));
+            }
+            let limit = i64::from(limit);
+            sqlx::query_scalar!(
+                "SELECT id FROM gfa_matches WHERE id > ? ORDER BY id LIMIT ?",
+                after,
+                limit
+            )
+            .fetch_all(&self.pool)
+            .await
+            .map_err(unavailable)
+        })
+    }
+
     fn append<'a>(
         &'a self,
         id: &'a str,

crates/adapters/gfa-store/src/lib.rs

@@ -285,3 +285,19 @@ async fn corrupt_event_sequences_fail_instead_of_returning_partial_history() ->
     store.close().await;
     Ok(())
 }
+
+#[tokio::test]
+async fn history_cursor_is_ordered_bounded_and_parameterized() -> TestResult {
+    let store = SqliteMatchStore::in_memory().await?;
+    for id in ["c", "a", "b"] {
+        store.create(new_record(id)).await?;
+    }
+    assert_eq!(store.list_ids("", 2).await?, vec!["a", "b"]);
+    assert_eq!(store.list_ids("b", 2).await?, vec!["c"]);
+    assert!(store.list_ids("c", 2).await?.is_empty());
+    assert_eq!(store.list_ids("' OR 1=1 --", 101).await?.len(), 3);
+    assert!(store.list_ids("", 0).await.is_err());
+    assert!(store.list_ids("", 102).await.is_err());
+    store.close().await;
+    Ok(())
+}

crates/adapters/gfa-store/src/tests.rs

@@ -59,6 +59,8 @@ async fn served_openapi_matches_real_requests_responses_and_conditional_formats(
         ("/v1/games/{game_id}", "get"),
         ("/v1/games/{game_id}/info", "get"),
         ("/v1/matches", "post"),
+        ("/v1/matches", "get"),
+        ("/v1/matches/{id}", "get"),
         ("/v1/matches/{id}/info", "get"),
         ("/v1/matches/{id}/state", "get"),
         ("/v1/matches/{id}/actions", "post"),
@@ -73,7 +75,7 @@ async fn served_openapi_matches_real_requests_responses_and_conditional_formats(
             "missing {method} {path}"
         );
     }
-    assert_eq!(doc["paths"].as_object().map(serde_json::Map::len), Some(13));
+    assert_eq!(doc["paths"].as_object().map(serde_json::Map::len), Some(14));
     let game_info = &doc["paths"]["/v1/games/{game_id}/info"]["get"];
     assert!(game_info["responses"]["200"]["content"]["text/markdown"].is_object());
     assert!(game_info["responses"]["304"].get("content").is_none());
@@ -125,6 +127,17 @@ async fn served_openapi_matches_real_requests_responses_and_conditional_formats(
         &initial
     ));
     let id = initial["match_id"].as_str().ok_or("id")?;
+    for (path, template) in [
+        ("/v1/matches".to_owned(), "/v1/matches"),
+        (format!("/v1/matches/{id}"), "/v1/matches/{id}"),
+    ] {
+        let (_, value) = call(&app.router, "GET", &path, Value::Null, None).await?;
+        assert!(valid(
+            &doc,
+            response_schema(&doc, template, "get", "200"),
+            &value
+        ));
+    }
     let (_, moved) = call(
         &app.router,
         "POST",

crates/apps/gfa-server/src/openapi_tests.rs

@@ -364,3 +364,102 @@ async fn position_validation_accepts_finished_boards_and_round_trips_all_encodin
     app.store.close().await;
     Ok(())
 }
+
+#[tokio::test]
+async fn metadata_and_history_paginate_filter_and_survive_restart() -> TestResult {
+    let dir = tempfile::tempdir()?;
+    let settings = config(&dir);
+    let app = fixture(&settings).await?;
+    let mut ids = Vec::new();
+    for game_id in ["tictactoe", "connect4", "tictactoe"] {
+        let (_, created) = call(
+            &app.router,
+            "POST",
+            "/v1/matches",
+            json!({"game_id":game_id,"seed":42}),
+            None,
+        )
+        .await?;
+        ids.push(match_id(&created)?);
+    }
+    for (turn, action) in ["r1c1", "r2c1", "r1c2", "r2c2", "r1c3"].iter().enumerate() {
+        call(
+            &app.router,
+            "POST",
+            &format!("/v1/matches/{}/actions", ids[0]),
+            json!({"seat":turn%2,"turn":turn,"action":action}),
+            None,
+        )
+        .await?;
+    }
+    let (status, meta) = call(
+        &app.router,
+        "GET",
+        &format!("/v1/matches/{}", ids[0]),
+        Value::Null,
+        None,
+    )
+    .await?;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(meta["status"], "finished");
+    assert_eq!(meta["turn"], 5);
+    for private in ["seed", "start", "state", "reasoning"] {
+        assert!(meta.get(private).is_none());
+    }
+    app.store.close().await;
+    let app = fixture(&settings).await?;
+    let mut cursor = String::new();
+    let mut found = Vec::new();
+    loop {
+        let (_, page) = call(
+            &app.router,
+            "GET",
+            &format!("/v1/matches?limit=1{cursor}"),
+            Value::Null,
+            None,
+        )
+        .await?;
+        let records = page["matches"].as_array().ok_or("records")?;
+        assert_eq!(records.len(), 1);
+        found.push(records[0]["match_id"].as_str().ok_or("id")?.to_owned());
+        match page["next"].as_str() {
+            Some(next) => cursor = format!("&after={next}"),
+            None => break,
+        }
+        assert!(found.len() <= 3);
+    }
+    ids.sort();
+    assert_eq!(found, ids);
+    let (_, finished) = call(
+        &app.router,
+        "GET",
+        "/v1/matches?game_id=tictactoe&status=finished",
+        Value::Null,
+        None,
+    )
+    .await?;
+    assert_eq!(finished["matches"].as_array().ok_or("matches")?.len(), 1);
+    let (_, active) = call(
+        &app.router,
+        "GET",
+        "/v1/matches?status=active",
+        Value::Null,
+        None,
+    )
+    .await?;
+    assert_eq!(active["matches"].as_array().ok_or("matches")?.len(), 2);
+    for path in [
+        "/v1/matches?limit=0",
+        "/v1/matches?limit=101",
+        "/v1/matches?status=unknown",
+        "/v1/matches?typo=1",
+        "/v1/matches?limit=1&limit=2",
+        "/v1/matches?game_id=missing",
+    ] {
+        let (status, error) = call(&app.router, "GET", path, Value::Null, None).await?;
+        assert!(status.is_client_error(), "{path}");
+        assert!(error["error"]["code"].is_string());
+    }
+    app.store.close().await;
+    Ok(())
+}

crates/apps/gfa-server/src/tests.rs

@@ -0,0 +1,82 @@
+//! Public match metadata and bounded history queries.
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// Current lifecycle status derived from the event log.
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum MatchStatus {
+    /// The engine is waiting for another move.
+    Active,
+    /// The game reached a terminal result or a length cap.
+    Finished,
+}
+
+/// Public metadata, excluding private state, seeds and player reasoning.
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct MatchMetadata {
+    /// Match identifier.
+    pub match_id: String,
+    /// Registered game identifier.
+    pub game_id: String,
+    /// Engine version used for reconstruction.
+    pub engine_version: String,
+    /// Current lifecycle status.
+    pub status: MatchStatus,
+    /// Accepted action count.
+    pub turn: u64,
+    /// Seats currently required to act.
+    pub to_act: Vec<u8>,
+    /// Per-seat returns.
+    pub returns: Vec<f64>,
+    /// Rules ended play.
+    pub terminated: bool,
+    /// A length or external cap ended play.
+    pub truncated: bool,
+    /// Creation timestamp in Unix milliseconds.
+    pub created_at_ms: u64,
+}
+
+fn default_limit() -> u32 {
+    50
+}
+
+/// Cursor query for local match history.
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema, utoipa::IntoParams))]
+#[cfg_attr(feature = "openapi", into_params(parameter_in = Query))]
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct MatchHistoryQuery {
+    /// Exclusive match-id cursor; omit for the first page.
+    pub after: Option<String>,
+    /// Restrict results to one registered game.
+    pub game_id: Option<String>,
+    /// Restrict results to active or finished games.
+    pub status: Option<MatchStatus>,
+    /// Maximum records scanned before filtering, from 1 to 100.
+    #[serde(default = "default_limit")]
+    pub limit: u32,
+}
+
+impl Default for MatchHistoryQuery {
+    fn default() -> Self {
+        Self {
+            after: None,
+            game_id: None,
+            status: None,
+            limit: default_limit(),
+        }
+    }
+}
+
+/// One bounded page; filters can produce an empty page with a continuation cursor.
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct MatchHistory {
+    /// Matching records from this page, in ascending match-id order.
+    pub matches: Vec<MatchMetadata>,
+    /// Exclusive cursor for the next page; null means the scan is exhausted.
+    pub next: Option<String>,
+}

crates/domain/gfa-api-types/src/history.rs

@@ -252,3 +252,6 @@ pub enum StreamMessage {
         error: ApiError,
     },
 }
+
+mod history;
+pub use history::{MatchHistory, MatchHistoryQuery, MatchMetadata, MatchStatus};

crates/domain/gfa-api-types/src/lib.rs

@@ -32,6 +32,17 @@ pub trait MatchStore: Send + Sync {
     /// Read one consistent event/command snapshot.
     fn load<'a>(&'a self, id: &'a str) -> StoreFuture<'a, Option<MatchRecord>>;
 
+    /// List up to limit identifiers in ascending order, strictly after the cursor.
+    ///
+    /// Limit is 1..101. Hosts must authorize access to this local history index.
+    fn list_ids<'a>(&'a self, _after: &'a str, _limit: u32) -> StoreFuture<'a, Vec<String>> {
+        Box::pin(async {
+            Err(StoreError::Unavailable(
+                "History is unsupported by this store".into(),
+            ))
+        })
+    }
+
     /// Compare-and-append using the current event count as the revision.
     ///
     /// Check idempotency before the revision: an identical command returns its