Merge pull request #32 from CurtisTechSolutions/feat/postgres-server-config

feat(server): support PostgreSQL-backed local matches

Author: nosam1998

.github/scripts/local-server-smoke.py

@@ -1,5 +1,6 @@
 """Exercise the actual CLI, HTTP listener, graceful shutdown, and restart."""
 import json
+import os
 from pathlib import Path
 import re
 import selectors
@@ -11,8 +12,10 @@
 
 
 def start(database):
+    variable = os.environ.get("GFA_SMOKE_POSTGRES_ENV")
+    storage = ["--postgres-env", variable] if variable else ["--sqlite", str(database)]
     process = subprocess.Popen(
-        [str(binary), "serve", "--sqlite", str(database), "--port", "0"],
+        [str(binary), "serve", *storage, "--port", "0"],
         stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
     )
     try:
@@ -68,4 +71,4 @@ def request(base, path, body=None):
         assert replay["states"][1] == moved["state"]
     finally:
         stop(process)
-print("Local CLI/HTTP/SQLite restart smoke test passed.")
+print("Local CLI/HTTP/database restart smoke test passed.")

.github/workflows/ci.yml

@@ -30,6 +30,7 @@ jobs:
       - run: cargo test --workspace --all-features --locked
         env:
           SQLX_OFFLINE: "true"
+      - run: cargo test -p gfa-cli --locked
       - run: cargo build -p gfa-cli --locked
       - run: python3 .github/scripts/local-server-smoke.py
       - name: Export generated OpenAPI

.github/workflows/postgres.yml

@@ -42,3 +42,11 @@ jobs:
         run: cargo test -p gfa-store --no-default-features --features postgres --locked -- --ignored
       - name: Verify PostgreSQL query metadata
         run: python3 .github/scripts/postgres-query-check.py
+      - name: Build PostgreSQL-enabled CLI using both backends' offline queries
+        run: cargo build -p gfa-cli --features postgres --locked
+        env:
+          SQLX_OFFLINE: "true"
+      - name: Exercise CLI and HTTP restart against PostgreSQL
+        run: python3 .github/scripts/local-server-smoke.py
+        env:
+          GFA_SMOKE_POSTGRES_ENV: GFA_TEST_POSTGRES_URL

README.md

@@ -3,3 +3,26 @@
 A game library that serves as a training and evaluation environment for AI systems. It has Rust game engines behind one standardized API (REST, WebSocket and MCP), built-in opponents such as Stockfish, persistent match history, and a React + Phaser frontend for playing games, watching live matches and viewing replays.
 
 See the [Product Requirements Document](docs/PRD.md).
+
+## Run locally
+
+```sh
+cargo run -p gfa-cli --locked -- serve --sqlite ./gfa.sqlite --port 8080
+```
+
+Open `http://127.0.0.1:8080/docs/` for the interactive API reference. Local mode
+binds to loopback and treats the local caller as the match owner.
+
+For PostgreSQL, enable the backend and put the connection URL in an environment
+variable so credentials do not appear in the command arguments:
+
+```sh
+# Set GFA_DATABASE_URL through your shell or secret manager first.
+cargo run -p gfa-cli --features postgres --locked -- serve --postgres-env GFA_DATABASE_URL
+```
+
+Use a dedicated database; startup applies embedded migrations. For remote
+PostgreSQL, require server certificate verification with `sslmode=verify-full`.
+SQLite is the default. The storage flags are mutually exclusive. Both backends
+persist moves and idempotency receipts atomically and recover replays after a
+graceful shutdown and restart.

crates/apps/gfa-cli/Cargo.toml

@@ -8,6 +8,10 @@ license.workspace = true
 name = "gfa"
 path = "src/main.rs"
 
+[features]
+default = []
+postgres = ["gfa-server/postgres"]
+
 [dependencies]
 gfa-server.workspace = true
 tokio.workspace = true

crates/apps/gfa-cli/src/main.rs

@@ -1,29 +1,61 @@
 //! GamesForAI command-line entry point for local play.
-use gfa_server::{Config, ServerError};
+use gfa_server::{Config, Database, ServerError};
 use std::path::PathBuf;
 
-const USAGE: &str = "Usage: gfa serve [--sqlite PATH] [--port PORT]\n\nStarts a local API on 127.0.0.1 (default port 8080).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.";
+const USAGE: &str = "Usage: gfa serve [--sqlite PATH | --postgres-env VARIABLE] [--port PORT]\n\nStarts a local API on 127.0.0.1 (default port 8080).\nSQLite defaults to ./gfa.sqlite. Port 0 selects an available port.\nPostgreSQL requires the postgres build feature and reads its URL from VARIABLE.";
 
 fn parse(args: impl IntoIterator<Item = String>) -> Result<Option<Config>, String> {
+    parse_with_env(args, |name| std::env::var(name).ok())
+}
+
+fn parse_with_env(
+    args: impl IntoIterator<Item = String>,
+    env: impl Fn(&str) -> Option<String>,
+) -> Result<Option<Config>, String> {
+    // Keep the same parser signature in SQLite-only builds.
+    let _ = &env;
     let mut args = args.into_iter();
     match args.next().as_deref() {
         None | Some("--help" | "-h") => return Ok(None),
         Some("serve") => {}
         Some(command) => return Err(format!("Unknown command: {command}")),
     }
     let mut config = Config::default();
-    let mut sqlite_seen = false;
+    let mut database_seen = false;
     let mut port_seen = false;
     while let Some(option) = args.next() {
         match option.as_str() {
             "--help" | "-h" => return Ok(None),
-            "--sqlite" if !sqlite_seen => {
+            "--sqlite" if !database_seen => {
                 let path = args.next().ok_or("--sqlite requires a path")?;
                 if path.is_empty() || path.starts_with("--") {
                     return Err("--sqlite requires a path".into());
                 }
-                config.sqlite = PathBuf::from(path);
-                sqlite_seen = true;
+                config.database = Database::Sqlite(PathBuf::from(path));
+                database_seen = true;
+            }
+            #[cfg(feature = "postgres")]
+            "--postgres-env" if !database_seen => {
+                let name = args
+                    .next()
+                    .ok_or("--postgres-env requires an environment variable name")?;
+                if name.is_empty() || !name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
+                {
+                    return Err("--postgres-env requires an environment variable name".into());
+                }
+                let url = env(&name)
+                    .ok_or("PostgreSQL environment variable is missing or not Unicode")?;
+                if !(url.starts_with("postgres://") || url.starts_with("postgresql://")) {
+                    return Err(
+                        "PostgreSQL environment variable must contain a PostgreSQL URL".into(),
+                    );
+                }
+                config.database = Database::Postgres(url);
+                database_seen = true;
+            }
+            #[cfg(not(feature = "postgres"))]
+            "--postgres-env" => {
+                return Err("PostgreSQL requires a build with --features postgres".into())
             }
             "--port" if !port_seen => {
                 config.port = args
@@ -90,7 +122,7 @@ mod tests {
         assert_eq!(
             options(&["serve", "--sqlite", "matches.sqlite", "--port", "0"])?,
             Some(Config {
-                sqlite: "matches.sqlite".into(),
+                database: Database::Sqlite("matches.sqlite".into()),
                 port: 0
             })
         );
@@ -99,6 +131,66 @@ mod tests {
         Ok(())
     }
 
+    #[cfg(feature = "postgres")]
+    #[test]
+    fn reads_postgres_from_environment_without_exposing_the_url() -> Result<(), String> {
+        let url = "postgres://alice:secret@localhost/gfa?sslmode=verify-full";
+        let parsed = parse_with_env(
+            ["serve", "--postgres-env", "GFA_DATABASE_URL"].map(str::to_owned),
+            |name| (name == "GFA_DATABASE_URL").then(|| url.to_owned()),
+        )?
+        .ok_or("missing config")?;
+        assert_eq!(parsed.database, Database::Postgres(url.to_owned()));
+        assert!(!format!("{parsed:?}").contains("secret"));
+        for options in [
+            vec!["serve", "--postgres-env"],
+            vec!["serve", "--postgres-env", "missing"],
+            vec!["serve", "--postgres-env", "--port"],
+            vec![
+                "serve",
+                "--sqlite",
+                "x.sqlite",
+                "--postgres-env",
+                "GFA_DATABASE_URL",
+            ],
+            vec![
+                "serve",
+                "--postgres-env",
+                "GFA_DATABASE_URL",
+                "--sqlite",
+                "x.sqlite",
+            ],
+            vec![
+                "serve",
+                "--postgres-env",
+                "GFA_DATABASE_URL",
+                "--postgres-env",
+                "GFA_DATABASE_URL",
+            ],
+        ] {
+            let result = parse_with_env(options.iter().map(|s| (*s).to_owned()), |name| {
+                (name == "GFA_DATABASE_URL").then(|| url.to_owned())
+            });
+            assert!(result.is_err(), "{options:?}");
+        }
+        let error = parse_with_env(
+            ["serve", "--postgres-env", "GFA_DATABASE_URL"].map(str::to_owned),
+            |_| Some("invalid-secret-url".into()),
+        )
+        .err()
+        .ok_or("invalid URL accepted")?;
+        assert!(!error.contains("invalid-secret-url"));
+        Ok(())
+    }
+
+    #[cfg(not(feature = "postgres"))]
+    #[test]
+    fn explains_missing_postgres_feature() {
+        assert!(options(&["serve", "--postgres-env", "GFA_DATABASE_URL"])
+            .err()
+            .is_some_and(|error| error.contains("--features postgres")));
+    }
+
     #[test]
     fn rejects_invalid_or_ambiguous_options() {
         for args in [

crates/apps/gfa-server/Cargo.toml

@@ -4,6 +4,10 @@ version.workspace = true
 edition.workspace = true
 license.workspace = true
 
+[features]
+default = []
+postgres = ["gfa-store/postgres"]
+
 [dependencies]
 gfa-games.workspace = true
 gfa-service.workspace = true

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

@@ -1,5 +1,5 @@
-//! Local server composition: registry, lifecycle service, SQLite, and HTTP.
-use gfa_service::{Clock, GameService, MatchIds};
+//! Local server composition: registry, lifecycle service, persistence, and HTTP.
+use gfa_service::{Clock, GameService, MatchIds, MatchStore};
 use gfa_store::SqliteMatchStore;
 use std::{
     error::Error,
@@ -18,21 +18,77 @@ pub type ServerError = Box<dyn Error + Send + Sync>;
 /// Configuration for auth-disabled, single-user local play.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Config {
-    /// Database file; its parent directory must already exist.
-    pub sqlite: PathBuf,
+    /// Persistent storage backend.
+    pub database: Database,
     /// Loopback port. Zero lets the OS select an available port.
     pub port: u16,
 }
 
 impl Default for Config {
     fn default() -> Self {
         Self {
-            sqlite: "gfa.sqlite".into(),
+            database: Database::Sqlite("gfa.sqlite".into()),
             port: 8080,
         }
     }
 }
 
+/// Storage backend selected at startup.
+#[derive(Clone, PartialEq, Eq)]
+pub enum Database {
+    /// SQLite file; its parent directory must already exist.
+    Sqlite(PathBuf),
+    /// PostgreSQL URL. Debug output redacts credentials and connection details.
+    #[cfg(feature = "postgres")]
+    Postgres(String),
+}
+
+impl std::fmt::Debug for Database {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Sqlite(path) => formatter.debug_tuple("Sqlite").field(path).finish(),
+            #[cfg(feature = "postgres")]
+            Self::Postgres(_) => formatter.write_str("Postgres([redacted])"),
+        }
+    }
+}
+
+enum Store {
+    Sqlite(Arc<SqliteMatchStore>),
+    #[cfg(feature = "postgres")]
+    Postgres(Arc<gfa_store::PostgresMatchStore>),
+}
+
+impl Store {
+    async fn open(database: &Database) -> Result<Self, ServerError> {
+        match database {
+            Database::Sqlite(path) => {
+                Ok(Self::Sqlite(Arc::new(SqliteMatchStore::open(path).await?)))
+            }
+            #[cfg(feature = "postgres")]
+            Database::Postgres(url) => Ok(Self::Postgres(Arc::new(
+                gfa_store::PostgresMatchStore::connect(url).await?,
+            ))),
+        }
+    }
+
+    fn port(&self) -> Arc<dyn MatchStore> {
+        match self {
+            Self::Sqlite(store) => store.clone(),
+            #[cfg(feature = "postgres")]
+            Self::Postgres(store) => store.clone(),
+        }
+    }
+
+    async fn close(&self) {
+        match self {
+            Self::Sqlite(store) => store.close().await,
+            #[cfg(feature = "postgres")]
+            Self::Postgres(store) => store.close().await,
+        }
+    }
+}
+
 struct Host;
 impl Clock for Host {
     fn now_ms(&self) -> u64 {
@@ -56,20 +112,19 @@ impl MatchIds for Host {
 
 struct Application {
     router: axum::Router,
-    store: Arc<SqliteMatchStore>,
+    store: Store,
     updates: Arc<gfa_http::LiveUpdates>,
     #[cfg(test)]
     service: Arc<GameService>,
 }
 
 async fn application(config: &Config, address: SocketAddr) -> Result<Application, ServerError> {
     let registry = gfa_games::registry()?;
-    let store = Arc::new(SqliteMatchStore::open(&config.sqlite).await?);
+    let store = Store::open(&config.database).await?;
     let host = Arc::new(Host);
     let updates = Arc::new(gfa_http::LiveUpdates::default());
     let service = Arc::new(
-        GameService::new(registry, store.clone(), host.clone(), host)
-            .with_observer(updates.clone()),
+        GameService::new(registry, store.port(), host.clone(), host).with_observer(updates.clone()),
     );
     let router = gfa_http::local_router_with_updates(service.clone(), address, updates.clone())?;
     Ok(Application {
@@ -84,7 +139,7 @@ async fn application(config: &Config, address: SocketAddr) -> Result<Application
 /// Bind loopback, migrate the database, and serve until shutdown completes.
 ///
 /// The address is printed after startup succeeds. A graceful shutdown drains HTTP
-/// requests before closing SQLite. This local mode has no agent authentication.
+/// requests before closing the database pool. This local mode has no agent authentication.
 pub async fn serve(
     config: Config,
     shutdown: impl Future<Output = ()> + Send + 'static,