v0.6.0 multi-user game support with longpoll, tests and doc updated

doc/api.md

@@ -154,6 +154,23 @@ Note: When authenticated, human player IDs match the user's ID. Anonymous player
 
 Returns current game state.
 
+**Long-polling support:**
+Add query parameters for real-time updates:
+- `wait=true` - Enable long-polling (waits up to 25 seconds)
+- `moveCount=N` - Last known move count
+
+Returns immediately if game state changed, otherwise waits for updates:
+```
+GET /games/{gameId}?wait=true&moveCount=5
+```
+
+Response includes all game data. Compare `moves` array length to detect changes.
+
+**Timeout behavior:**
+- Returns current state after 25 seconds even if no changes
+- Client disconnection cancels wait immediately
+- Game deletion notifies all waiting clients
+
 ### Make Move
 `POST /games/{gameId}/moves`
 

doc/architecture.md

@@ -11,15 +11,18 @@ Central command handler containing business logic. Single `Execute(Command)` ent
 ### Service Layer (`internal/service`)
 In-memory state storage with authentication support. Thread-safe game map protected by RWMutex. Manages game lifecycle, snapshots, player configuration, user accounts, and JWT token generation. Coordinates with storage layer for persistence of both games and users.
 
-### Storage Layer (`internal/storage`)
-SQLite persistence with async writes for games, synchronous writes for authentication operations. Buffered channel (1000 ops) processes game writes sequentially in background. User operations use direct database access for consistency. Graceful degradation on write failures. WAL mode for development environments.
+#### Long-Polling Registry (`internal/service/waiter.go`)
+Manages clients waiting for game state changes via HTTP long-polling. Tracks move counts per client, sends notifications on state changes, enforces 25-second timeout. Non-blocking notification pattern handles slow clients gracefully. Coordinates with service layer for game updates and deletion events.
 
-### Authentication Module (`internal/service/user.go`, `internal/http/auth.go`)
+#### Authentication Module (`internal/service/user.go`, `internal/http/auth.go`)
 - **Password Hashing**: Argon2id for secure password storage
 - **JWT Management**: HS256 tokens with 7-day expiration
 - **User Operations**: Registration, login, profile management
 - **Session Tracking**: Last login timestamps
 
+### Storage Layer (`internal/storage`)
+SQLite persistence with async writes for games, synchronous writes for authentication operations. Buffered channel (1000 ops) processes game writes sequentially in background. User operations use direct database access for consistency. Graceful degradation on write failures. WAL mode for development environments.
+
 ### Supporting Modules
 - **Engine** (`internal/engine`): UCI protocol wrapper for Stockfish process communication
 - **Game** (`internal/game`): Game state with snapshot history and player associations
@@ -62,6 +65,17 @@ SQLite persistence with async writes for games, synchronous writes for authentic
 4. Worker goroutine calculates move with dedicated Stockfish instance
 5. Callback updates game state via service
 6. Client polls for completion
+7. Returns GameResponse
+
+### Long-Polling Flow
+1. Client sends `GET /games/{id}?wait=true&moveCount=N`
+2. Handler creates context from HTTP connection
+3. Registers wait with WaitRegistry using game ID and move count
+4. If game state unchanged, blocks up to 25 seconds
+5. On any game update, NotifyGame sends to all waiters
+6. Returns immediately with current state
+7. Client disconnection cancels wait via context
+8. Game deletion notifies and removes all waiters
 
 ## Persistence Flow
 

doc/development.md

@@ -158,6 +158,9 @@ See [test documentation](../test/README.md) for comprehensive test suites coveri
 
 # Run test server with sample users
 ./test/test-db-server.sh
+
+# Test real-time game updates via long-polling
+./test/test-longpoll.sh
 ```
 
 ## Configuration
@@ -170,6 +173,8 @@ See [test documentation](../test/README.md) for comprehensive test suites coveri
 - Write queue: 1000 operations (internal/storage/storage.go)
 - DB connections: 25 max, 5 idle (internal/storage/storage.go)
 - JWT expiration: 7 days (internal/service/user.go)
+- Long-poll timeout: 25 seconds (internal/service/waiter.go)
+- Long-poll channel buffer: 1 (internal/service/waiter.go)
 
 ### Authentication Configuration
 - Password minimum: 8 characters with letter and number
@@ -234,4 +239,6 @@ See [test documentation](../test/README.md) for comprehensive test suites coveri
 - No password recovery mechanism
 - No email verification for registration
 - Fixed worker pool size for engine calculations
-- No real-time game updates (polling required)
+- No real-time game updates (polling required)
+- Long-polling limited to 25 seconds per request
+- REST API only