refactor (Opus 4.5): modularize and split
This commit is contained in:
@@ -0,0 +1,198 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**LanSpread2** is a peer-to-peer (P2P) game distribution system with a Tauri desktop application frontend. It enables users to share games over local networks using mDNS discovery and QUIC protocol for peer communication.
|
||||
|
||||
## Common Development Commands
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
# Development (opens UI, needs user interaction)
|
||||
cargo tauri dev
|
||||
|
||||
# Debug build for very quick testing (without bundle)
|
||||
cargo tauri build --debug --no-bundle
|
||||
|
||||
# Relase build for testing (without bundling)
|
||||
cargo tauri build --no-bundle
|
||||
|
||||
# Production (with bundling)
|
||||
cargo tauri build -- --profile release-lto
|
||||
```
|
||||
|
||||
### Build Profiles
|
||||
|
||||
- `release`: Default release profile with debug info, assertions enabled, overflow checks on, for testing
|
||||
- `release-lto`: Optimized for distribution with LTO enabled, debug symbols stripped, smaller binary, only for production
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Lint all code
|
||||
cargo clippy
|
||||
|
||||
# Format code (nightly Rust)
|
||||
cargo +nightly fmt
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test --all
|
||||
|
||||
# Run tests for a specific crate
|
||||
cargo test -p lanspread-peer
|
||||
|
||||
# Run a specific test
|
||||
cargo test -p lanspread-peer test_name
|
||||
|
||||
# Run tests with output
|
||||
cargo test -- --nocapture
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
|
||||
```bash
|
||||
# Update frontend dependencies (Deno)
|
||||
deno outdated --update --latest
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
LanSpread follows a layered, modular architecture with clear separation of concerns:
|
||||
|
||||
### Crate Structure
|
||||
|
||||
The project is organized as a Cargo workspace with 7 crates:
|
||||
|
||||
**Foundation Layer:**
|
||||
- **lanspread-utils**: Utility macros and helpers used across all crates
|
||||
- **lanspread-db**: Core data structures (`Game`, `GameFileDescription`, game metadata)
|
||||
|
||||
**Protocol & Communication:**
|
||||
- **lanspread-proto**: P2P communication protocol definitions
|
||||
- Message types: `Request` (Ping, ListGames, GetGame, etc.), `Response`, `Message` trait
|
||||
- Serialization: JSON with `serde`
|
||||
|
||||
**Network Discovery & Compatibility:**
|
||||
- **lanspread-mdns**: mDNS service discovery and advertisement
|
||||
- Advertises and discovers "_lanspread._udp.local." services on LAN
|
||||
- Uses `mdns-sd` crate
|
||||
|
||||
- **lanspread-compat**: Compatibility layer for legacy ETI game database format
|
||||
- Reads legacy `game.db` SQLite databases
|
||||
- Converts `EtiGame` structs to modern `Game` struct
|
||||
|
||||
**Core P2P Engine:**
|
||||
- **lanspread-peer**: (~97KB) Central orchestration for all P2P functionality
|
||||
- QUIC-based networking with length-delimited frame codec (`tokio-util`)
|
||||
- Manages peer-to-peer connections and game synchronization
|
||||
- Handles file streaming with chunk transfers and path validation
|
||||
- Communicates via unbounded channels (`PeerEvent`, `PeerCommand`)
|
||||
- Implements retry logic for requesting games from peers
|
||||
- Entry point: `start_peer()` function
|
||||
|
||||
**Application Layer:**
|
||||
- **lanspread-tauri-deno-ts**: Tauri desktop application
|
||||
- Binary + Library crate for the UI layer
|
||||
- IPC commands: `request_games`, `install_game`, etc.
|
||||
- Manages `LanSpreadState` for peer controller, game DB, and downloads
|
||||
- Uses Tauri plugins: logging, shell, dialogs, persistent storage
|
||||
- Allocates MiMalloc for memory efficiency
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
User (Tauri UI)
|
||||
↓ IPC Commands (request_games, install_game)
|
||||
↓
|
||||
lanspread-tauri-deno-ts (app layer)
|
||||
↓
|
||||
lanspread-peer (P2P engine)
|
||||
├─ lanspread-mdns (discovers peers via mDNS)
|
||||
├─ lanspread-proto (constructs P2P messages)
|
||||
├─ lanspread-compat (reads legacy game databases)
|
||||
└─ QUIC Network ↔ Other Peers
|
||||
↓
|
||||
lanspread-db (game data structures)
|
||||
↓
|
||||
Result → Back to UI
|
||||
```
|
||||
|
||||
### Key Architectural Details
|
||||
|
||||
1. **Async/Await**: Tokio runtime throughout for non-blocking I/O
|
||||
2. **Message Passing**: Unbounded channels for inter-component communication (events and commands)
|
||||
3. **Protocol**: Length-delimited QUIC frames with JSON serialization
|
||||
4. **Service Discovery**: Automatic mDNS announcement and discovery of peers
|
||||
5. **File Streaming**: Chunked transfer with path validation for security
|
||||
6. **Legacy Support**: Backwards compatibility with ETI game database format
|
||||
7. **Error Handling**: Custom error types via `eyre` crate
|
||||
|
||||
## Development Practices
|
||||
|
||||
### From AGENTS.md
|
||||
|
||||
- Always check code with `cargo clippy` and fix any issues
|
||||
- Always format with `cargo +nightly fmt` after completing changes
|
||||
- Use appropriate Rust log levels when debugging:
|
||||
- `RUST_LOG=lanspread=debug` for module-specific debugging
|
||||
- `RUST_LOG=info,lanspread=debug` for general info + module debug
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
- Use `release-lto` profile for final builds to enable Link-Time Optimization
|
||||
- MiMalloc is used for the Tauri app to reduce memory overhead
|
||||
- QUIC protocol chosen for efficient P2P communication
|
||||
- Length-delimited framing reduces message parsing overhead
|
||||
|
||||
## Important Implementation Notes
|
||||
|
||||
### Logging
|
||||
|
||||
The codebase uses `tracing` and `log` crates. Note: There's documented uncertainty about their exact relationship (see LESSONS_LEARNED.md). The client app uses `log` crate; be consistent with whichever is used in the component you're modifying.
|
||||
|
||||
### Legacy Database Support
|
||||
|
||||
Some users may have old ETI format game databases. The `lanspread-compat` crate handles reading these. When querying games, both modern and legacy formats are considered.
|
||||
|
||||
### Path Validation
|
||||
|
||||
File transfers validate paths to prevent directory traversal attacks. All file operations use validated paths from `lanspread-peer`.
|
||||
|
||||
### Retry Logic
|
||||
|
||||
`lanspread-peer` includes retry logic for requesting games from peers. This handles transient network failures in P2P discovery.
|
||||
|
||||
## Known Design Decisions
|
||||
|
||||
**Why not Tauri + Leptos?** Leptos adds unnecessary complexity. Tauri is designed to transfer backend Rust to frontend JavaScript world, but with Leptos the frontend becomes Rust, creating a double translation. The current Tauri + Deno/TypeScript approach is cleaner.
|
||||
|
||||
**Why Tauri?** Simple setup, easy development with `cargo tauri dev`, easy testing and bundling with installers, small final binary (~13MB).
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
crates/
|
||||
├── lanspread-db/ # Core data models
|
||||
├── lanspread-utils/ # Macros & utilities
|
||||
├── lanspread-proto/ # Protocol definitions
|
||||
├── lanspread-compat/ # Legacy ETI compatibility
|
||||
├── lanspread-mdns/ # mDNS discovery
|
||||
├── lanspread-peer/ # P2P engine (largest, most complex)
|
||||
└── lanspread-tauri-deno-ts/
|
||||
├── src-tauri/ # Rust Tauri backend
|
||||
└── (sibling dirs) # Deno/TypeScript frontend code
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **README.md**: Build and development prerequisites
|
||||
- **LESSONS_LEARNED.md**: Architectural decisions and trade-offs
|
||||
- **AGENTS.md**: Code quality guidelines
|
||||
- **TODO.md**: Tracked work items
|
||||
Reference in New Issue
Block a user