117 lines
3.0 KiB
Markdown
117 lines
3.0 KiB
Markdown
# Development Guide
|
|
|
|
## Prerequisites
|
|
|
|
- Go 1.24+
|
|
- Stockfish in PATH
|
|
- Git
|
|
- curl, jq (for testing)
|
|
|
|
## Building
|
|
|
|
```bash
|
|
git clone https://git.lixen.com/lixen/chess
|
|
cd chess
|
|
go build ./cmd/chessd
|
|
```
|
|
|
|
## Running
|
|
|
|
### Flags
|
|
- `-host`: Server host (default: localhost)
|
|
- `-port`: Server port (default: 8080)
|
|
- `-dev`: Development mode with relaxed rate limits
|
|
- `-storage-path`: SQLite database file path (enables persistence)
|
|
- `-pid`: PID file path for process tracking
|
|
- `-pid-lock`: Enable exclusive locking (requires -pid)
|
|
|
|
### Modes
|
|
```bash
|
|
# In-memory only
|
|
./chessd
|
|
|
|
# With persistence
|
|
./chessd -storage-path ./db/chess.db
|
|
|
|
# Singleton enforcement (requires same PID file path across instances)
|
|
./chessd -pid /var/run/chessd.pid -pid-lock
|
|
|
|
# Development with all features
|
|
./chessd -dev -storage-path chess.db -pid /tmp/chessd.pid
|
|
```
|
|
|
|
## Database Management
|
|
|
|
### CLI Commands
|
|
```bash
|
|
# Initialize database schema
|
|
./chessd db init -path chess.db
|
|
|
|
# Query games
|
|
./chessd db query -path chess.db [-gameId ID] [-playerId ID]
|
|
|
|
# Delete database
|
|
./chessd db delete -path chess.db
|
|
```
|
|
|
|
Query parameters accept `*` for all records (default if omitted) or specific IDs for filtering.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
chess/
|
|
├── cmd/chessd/
|
|
│ ├── main.go # Entry point
|
|
│ ├── pid.go # PID file management
|
|
│ └── cli/ # Database CLI
|
|
├── internal/
|
|
│ ├── board/ # FEN/ASCII operations
|
|
│ ├── core/ # Shared types
|
|
│ ├── engine/ # Stockfish UCI wrapper
|
|
│ ├── game/ # Game state
|
|
│ ├── http/ # Fiber handlers
|
|
│ ├── processor/ # Command processing
|
|
│ ├── service/ # State management
|
|
│ └── storage/ # SQLite persistence
|
|
└── test/ # Test scripts
|
|
```
|
|
|
|
## Testing
|
|
|
|
See [test documentation](../test/README.md) for details.
|
|
|
|
## Configuration
|
|
|
|
### Fixed Values
|
|
- Engine path: `"stockfish"` (internal/engine/engine.go)
|
|
- Worker count: 2 (internal/processor/processor.go)
|
|
- Queue capacity: 100 (internal/processor/queue.go)
|
|
- Min search time: 100ms (internal/processor/processor.go)
|
|
- Write queue: 1000 operations (internal/storage/storage.go)
|
|
- DB connections: 25 max, 5 idle (internal/storage/storage.go)
|
|
|
|
### Storage Configuration
|
|
- WAL mode enabled in development for concurrency
|
|
- Foreign key constraints enforced
|
|
- Async write pattern with 2-second drain on shutdown
|
|
- Degradation to memory-only on write failures
|
|
|
|
### PID Management
|
|
- Singleton enforcement requires same PID file path - all instances must use the same -pid value
|
|
- Stale PID detection via signal 0 checking
|
|
- Exclusive file locking with LOCK_EX|LOCK_NB
|
|
- Automatic cleanup on graceful shutdown
|
|
|
|
### Validation Rules
|
|
- Player type: 1 (human) or 2 (computer)
|
|
- Skill level: 0-20
|
|
- Search time: 100-10000ms
|
|
- UCI moves: 4-5 characters ([a-h][1-8][a-h][1-8][qrbn]?)
|
|
- Undo count: 1-300
|
|
|
|
## Limitations
|
|
|
|
- No persistence (memory only)
|
|
- Hardcoded Stockfish path
|
|
- Fixed worker pool size
|
|
- No game history beyond current session |