Wizard Server

Overview

wizard-server is a lightweight, fast WebSocket‑based backend that powers the Lazarus Games ecosystem. It provides a set of REST and WebSocket APIs for managing game sessions, player actions, and real‑time synchronization between clients. The server is written in Python using FastAPI and uvicorn, making it easy to extend and deploy.

---

Features

• Real‑time game state synchronization via WebSockets.
• RESTful endpoints for CRUD operations on games, players, and puzzles.
• Pluggable authentication (JWT, OAuth2) ready for integration with Neon Auth.
• Automatic puzzle loading from Vercel Blob (fallback to local JSON).
• Extensible router architecture – each domain (game, player, admin) lives in its own module.
• Comprehensive OpenAPI documentation automatically generated by FastAPI.
• Docker‑ready configuration for simple container deployment.
• Unit‑tested core logic with pytest coverage > 85%.

---

Installation

# Clone the repository
git clone https://github.com/your-org/lazarus-games.git
cd lazarus-games/wizard-server

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

# Install dependencies
pip install -r requirements.txt

Docker (optional)

# Build the image
docker build -t wizard-server:latest .

# Run the container
docker run -p 8000:8000 wizard-server:latest

---

Quick Start

1. Run the development server

   uvicorn app.main:app --reload

   The API will be available at http://127.0.0.1:8000.

2. Explore the interactive docs Open http://127.0.0.1:8000/docs in your browser to view the automatically generated Swagger UI.

3. Connect via WebSocket

   const ws = new WebSocket('ws://127.0.0.1:8000/ws/game/{game_id}');
   ws.onmessage = (event) => console.log('Update:', event.data);

---

API Reference

REST Endpoints

Method	Path	Description
GET	/games/	List all active games
POST	/games/	Create a new game session
GET	/games/{game_id}	Retrieve a specific game
PUT	/games/{game_id}	Update game state
DELETE	/games/{game_id}	End a game session
GET	/players/{player_id}	Get player profile
POST	/players/	Register a new player

WebSocket Endpoints

• /ws/game/{game_id} – Bi‑directional channel for real‑time game updates. Clients send actions ({"type": "move", "payload": {...}}) and receive broadcasted state changes.

---

Configuration

The server reads configuration from environment variables or a .env file (loaded via python-dotenv). Key variables include:

• HOST – Host address (default 0.0.0.0).
• PORT – Port number (default 8000).
• JWT_SECRET – Secret key for JWT signing.
• VERCEL_BLOB_URL – URL to the Vercel Blob containing puzzle data.

---

Testing

# Run the test suite
pytest -vv

Coverage report:

pytest --cov=app

---

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feat/awesome-feature).
3. Write tests for your changes.
4. Ensure all existing tests pass (pytest).
5. Open a Pull Request with a clear description of the change.

---

License

This project is licensed under the MIT License – see the LICENSE file for details.

---

Contact

For questions or support, open an issue on the repository or contact the maintainer at dev@lazarusgames.com.