Upload files to "/"
This commit is contained in:
435
README.md
Normal file
435
README.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# RCC (Rust Cloud Coordinator)
|
||||
|
||||
> **A clean-room, Linux-first reimplementation of a cloud-based game engine backend with sandboxed WASM execution.**
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.rust-lang.org/)
|
||||
[](https://www.linux.org/)
|
||||
|
||||
---
|
||||
|
||||
## Project Vision
|
||||
|
||||
RCC is built on a **clean-room philosophy**: a high-performance, production-grade game backend designed from the ground up without reference to proprietary systems, assets, or codebases. This project demonstrates:
|
||||
|
||||
- **Architectural Independence**: All design decisions are made in isolation, prioritizing modern cloud-native patterns over legacy compatibility.
|
||||
- **Sandboxed Execution**: Game logic runs in WebAssembly modules with strict memory isolation and CPU metering, ensuring deterministic and auditable behavior.
|
||||
- **Scalability-First**: Async Rust (Tokio) + gRPC enable horizontal scaling across distributed nodes with minimal overhead.
|
||||
- **Security by Default**: JWT authentication, zero-trust WASM sandboxing, and no outbound network access from game logic layers.
|
||||
|
||||
This is **not a port, fork, or derivative**—it is a standalone system for building multiplayer game backends with deterministic, auditable logic execution.
|
||||
|
||||
### Design Goals
|
||||
|
||||
- **Performance**: Sub-millisecond tick rates for real-time multiplayer sessions
|
||||
- **Isolation**: Complete sandboxing of untrusted game logic from infrastructure
|
||||
- **Observability**: Full tracing and metrics for debugging distributed game state
|
||||
- **Modularity**: Hot-swappable WASM modules without service restarts
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
RCC is a **three-tier distributed system** with clear separation of concerns:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Bevy Client │ ← 3D Visualization Layer
|
||||
│ (Rust/ECS + Rendering) │ • Player input handling
|
||||
└────────────┬────────────────────┘ • State interpolation
|
||||
│ WebSocket (WSS) • Asset rendering
|
||||
↓
|
||||
┌─────────────────────────────────┐
|
||||
│ RCCSoap │ ← Executor Node
|
||||
│ (WASM Runtime + WebSocket) │ • Runs sandboxed modules
|
||||
│ │ • Manages player sessions
|
||||
│ ┌─────────────────────┐ │ • CPU tick enforcement
|
||||
│ │ Wasmtime Instance │ │ • Memory isolation
|
||||
│ │ (Game Logic WASM) │ │
|
||||
│ └─────────────────────┘ │
|
||||
└────────────┬────────────────────┘
|
||||
│ gRPC (Protobuf)
|
||||
↓
|
||||
┌─────────────────────────────────┐
|
||||
│ RCCService │ ← Coordinator
|
||||
│ (gRPC API + State Manager) │ • Session lifecycle
|
||||
│ │ • Authentication (JWT)
|
||||
│ ┌─────────────────────┐ │ • Module registry
|
||||
│ │ PostgreSQL DB │ │ • State persistence
|
||||
│ └─────────────────────┘ │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Component Responsibilities
|
||||
|
||||
| Component | Technology Stack | Primary Role | Secondary Functions |
|
||||
|-----------|-----------------|--------------|---------------------|
|
||||
| **RCCService** | Tokio, Tonic, SQLx, PostgreSQL | Central coordinator handling session lifecycle and authentication | Module validation, metrics aggregation, admin API |
|
||||
| **RCCSoap** | Wasmtime, WASI, Tokio-tungstenite | Executor node that loads WASM modules and manages real-time connections | Game state broadcasting, tick scheduling, client session management |
|
||||
| **Bevy Client** | Bevy Engine (ECS), WebSockets | 3D game client that visualizes game state and handles player input | Asset management, UI rendering, input prediction |
|
||||
| **PostgreSQL** | Database | Persistent storage for sessions, user accounts, and state snapshots | Audit logs, leaderboard data, module metadata |
|
||||
|
||||
---
|
||||
|
||||
## WASM Sandbox Specifications
|
||||
|
||||
Game logic modules are compiled to `wasm32-wasi` and executed with strict isolation guarantees enforced at multiple levels.
|
||||
|
||||
### Security Model
|
||||
|
||||
| Feature | Implementation | Enforcement Mechanism |
|
||||
|---------|---------------|----------------------|
|
||||
| **Memory Isolation** | Each module runs in a separate Wasmtime instance | OS-level process boundaries + WASM linear memory sandboxing |
|
||||
| **Network Restrictions** | WASM modules have **zero** outbound network capability | WASI configuration denies all network syscalls at runtime |
|
||||
| **CPU Metering** | Tick-based execution limits prevent infinite loops | Wasmtime fuel metering (configurable per module, default: 10M instructions/tick) |
|
||||
| **Filesystem Access** | Read-only access to approved asset directories only | WASI preopened directories (no write permissions, allowlist-based) |
|
||||
| **Determinism** | Pure functions with controlled entropy sources | RNG seeded by coordinator, no system clock access, no thread spawning |
|
||||
|
||||
### Runtime Guarantees
|
||||
|
||||
- **No FFI**: WASM modules cannot invoke native code outside the WASI interface contract.
|
||||
- **No Shared Memory**: Modules communicate only via serialized messages (Protobuf over WASI stdio).
|
||||
- **Rollback Safety**: All state mutations are transactional and can be replayed from coordinator logs.
|
||||
- **Resource Limits**: Configurable memory caps (default: 64MB heap per instance), stack depth limits (default: 1024 frames).
|
||||
|
||||
### Execution Model
|
||||
|
||||
Each game tick follows this deterministic pipeline:
|
||||
|
||||
1. **State Snapshot**: Coordinator serializes current game state
|
||||
2. **Module Invocation**: RCCSoap loads state into WASM linear memory
|
||||
3. **Logic Execution**: Module processes player actions within fuel budget
|
||||
4. **State Delta**: Module returns only changed state (diff-based)
|
||||
5. **Validation**: Coordinator validates output against game rules schema
|
||||
6. **Broadcast**: New state pushed to connected clients via WebSocket
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Ensure the following tools are installed on your Linux system:
|
||||
|
||||
- **Rust** 1.75+ with `wasm32-wasi` target
|
||||
- **Docker** 24.0+ with Compose V2
|
||||
- **PostgreSQL Client** 15+ (for manual DB operations)
|
||||
- **Git** 2.40+
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-org/rcc.git
|
||||
cd rcc
|
||||
|
||||
# Install WASM target
|
||||
rustup target add wasm32-wasi
|
||||
|
||||
# Build all components (services + example WASM modules)
|
||||
./scripts/build_all.sh
|
||||
|
||||
# Start infrastructure (PostgreSQL, metrics collectors)
|
||||
docker-compose up -d
|
||||
|
||||
# Run database migrations
|
||||
./scripts/migrate.sh
|
||||
|
||||
# Initialize default admin user and example game module
|
||||
./scripts/init_dev_data.sh
|
||||
```
|
||||
|
||||
### Running the System
|
||||
|
||||
Open three terminal windows:
|
||||
|
||||
**Terminal 1 - Coordinator**
|
||||
```bash
|
||||
cargo run --release --bin rcc-service
|
||||
# Starts on 0.0.0.0:50051 (gRPC)
|
||||
```
|
||||
|
||||
**Terminal 2 - Executor**
|
||||
```bash
|
||||
cargo run --release --bin rcc-soap
|
||||
# Starts on 0.0.0.0:8080 (WebSocket)
|
||||
```
|
||||
|
||||
**Terminal 3 - Client**
|
||||
```bash
|
||||
cargo run --release --bin bevy-client -- --server ws://localhost:8080
|
||||
# Connects to RCCSoap and renders game state
|
||||
```
|
||||
|
||||
### Port Allocation
|
||||
|
||||
| Service | Port | Protocol | Purpose | TLS Required |
|
||||
|---------|------|----------|---------|--------------|
|
||||
| RCCService | 50051 | gRPC/HTTP2 | Coordinator API (internal) | Yes (production) |
|
||||
| RCCSoap | 8080 | WebSocket | Real-time client connections | Yes (production) |
|
||||
| PostgreSQL | 5432 | TCP | Database connections | TLS recommended |
|
||||
| Prometheus | 9090 | HTTP | Metrics scraping | No |
|
||||
| Grafana | 3000 | HTTP | Monitoring dashboard | Optional |
|
||||
|
||||
### Verifying the Installation
|
||||
|
||||
```bash
|
||||
# Check service health
|
||||
curl -X POST http://localhost:50051/health
|
||||
|
||||
# List available game modules
|
||||
grpcurl -plaintext localhost:50051 rcc.ModuleService/ListModules
|
||||
|
||||
# Monitor active sessions
|
||||
grpcurl -plaintext localhost:50051 rcc.SessionService/ListSessions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Developer Guide
|
||||
|
||||
### Writing a Game Module
|
||||
|
||||
Game modules are Rust libraries compiled to WASM with a specific interface contract.
|
||||
|
||||
#### Project Structure
|
||||
|
||||
```
|
||||
my_game_module/
|
||||
├── Cargo.toml
|
||||
├── src/
|
||||
│ └── lib.rs
|
||||
├── assets/ # Optional: read-only game assets
|
||||
│ └── config.json
|
||||
└── build.sh # Compilation script
|
||||
```
|
||||
|
||||
#### Cargo.toml Configuration
|
||||
|
||||
Your module must be a `cdylib` crate targeting `wasm32-wasi`:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "my_game_module"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
# RCC SDK provides WASI bindings + game state types
|
||||
rcc-sdk = { git = "https://github.com/your-org/rcc-sdk", tag = "v0.3.0" }
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
```
|
||||
|
||||
#### Module Interface
|
||||
|
||||
Your module must export two functions:
|
||||
|
||||
- `game_init()`: Called once when module loads (setup phase)
|
||||
- `game_tick(state, actions)`: Called every game tick (16ms default)
|
||||
|
||||
#### Compilation
|
||||
|
||||
```bash
|
||||
# Compile to WASM with optimizations
|
||||
cargo build --target wasm32-wasi --release
|
||||
|
||||
# Strip debug symbols (reduces binary size by ~40%)
|
||||
wasm-strip target/wasm32-wasi/release/my_game_module.wasm
|
||||
|
||||
# Optimize with wasm-opt (optional but recommended)
|
||||
wasm-opt -Oz -o optimized.wasm target/wasm32-wasi/release/my_game_module.wasm
|
||||
```
|
||||
|
||||
### Module Lifecycle
|
||||
|
||||
1. **Development**: Write and test module locally using RCC SDK test harness
|
||||
2. **Upload**: POST WASM binary to RCCService `/api/v1/modules` endpoint with JWT auth
|
||||
3. **Validation**: Coordinator verifies module signature, resource limits, and interface compliance
|
||||
4. **Distribution**: Module hash distributed to all RCCSoap executors via gRPC
|
||||
5. **Instantiation**: Wasmtime preloads module when first session requests it
|
||||
6. **Execution**: Game ticks invoke module exports with fuel limits and memory boundaries
|
||||
7. **Monitoring**: Metrics collected on execution time, memory usage, and error rates
|
||||
|
||||
### Testing Your Module
|
||||
|
||||
```bash
|
||||
# Run RCC SDK test suite against your module
|
||||
cargo test --target wasm32-wasi
|
||||
|
||||
# Benchmark tick performance
|
||||
./scripts/benchmark_module.sh my_game_module.wasm
|
||||
|
||||
# Validate WASM interface compliance
|
||||
./scripts/validate_module.sh my_game_module.wasm
|
||||
```
|
||||
|
||||
### Module Best Practices
|
||||
|
||||
- **Keep ticks fast**: Target <5ms execution time per tick
|
||||
- **Minimize allocations**: Reuse buffers, avoid Vec growth in hot paths
|
||||
- **Use delta encoding**: Only return changed state, not full snapshots
|
||||
- **Handle errors gracefully**: Return error codes instead of panicking
|
||||
- **Version your protocol**: Use semantic versioning for state schema changes
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
RCC uses JWT-based authentication with short-lived tokens and refresh mechanisms:
|
||||
|
||||
```
|
||||
1. Client → RCCService (POST /auth/login)
|
||||
↓ Credentials (username/password or OAuth token)
|
||||
|
||||
2. RCCService validates credentials
|
||||
↓ Queries PostgreSQL user table
|
||||
|
||||
3. RCCService ← JWT signed with RS256
|
||||
↑ Claims: {sub, session_id, roles, exp}
|
||||
|
||||
4. Client → RCCSoap (WebSocket upgrade + JWT in header)
|
||||
↓ Authorization: Bearer <token>
|
||||
|
||||
5. RCCSoap → RCCService (gRPC ValidateToken)
|
||||
↓ Token validation request
|
||||
|
||||
6. RCCSoap ← Token valid + user metadata
|
||||
↑ WebSocket connection established
|
||||
```
|
||||
|
||||
### JWT Claims Structure
|
||||
|
||||
| Claim | Type | Description | Example |
|
||||
|-------|------|-------------|---------|
|
||||
| `sub` | string | User ID (UUID) | `"550e8400-e29b-41d4-a716-446655440000"` |
|
||||
| `session_id` | string | Active game session identifier | `"match-2024-01-15-7f3a"` |
|
||||
| `exp` | integer | Token expiration timestamp | `1705334400` (Unix epoch) |
|
||||
| `iat` | integer | Token issued at timestamp | `1705330800` |
|
||||
| `roles` | array | Permission scopes | `["player", "observer"]` |
|
||||
| `module_access` | array | Whitelisted game modules | `["chess_v1", "demo_v2"]` |
|
||||
|
||||
**Token Lifetime**: Default 1 hour, configurable via environment variable `RCC_JWT_EXPIRY_SECONDS`.
|
||||
|
||||
### WASM Isolation Layers
|
||||
|
||||
Security is enforced through defense-in-depth:
|
||||
|
||||
1. **Wasmtime Sandbox**: Hardware-assisted memory virtualization (Intel MPK on x86_64, PAC on ARM64)
|
||||
2. **WASI Capability Model**: Explicit grants for filesystem/clock access (capabilities cannot be forged)
|
||||
3. **CPU Fuel Limits**: Configurable per-module instruction budgets prevent DoS (default: 10M instructions/tick)
|
||||
4. **Network Isolation**: WASM modules run in network namespaces with no routes (verified via seccomp-bpf)
|
||||
5. **Audit Logging**: All WASI calls logged to immutable append-only store (PostgreSQL + write-ahead log)
|
||||
|
||||
### Threat Model
|
||||
|
||||
**Protected Against**:
|
||||
- Malicious game modules executing arbitrary code on host
|
||||
- Resource exhaustion attacks (CPU, memory, disk)
|
||||
- Network exfiltration of game state or player data
|
||||
- Time-of-check-to-time-of-use race conditions
|
||||
- SQL injection via game state serialization
|
||||
|
||||
**Out of Scope**:
|
||||
- DDoS attacks at network layer (use Cloudflare or AWS Shield)
|
||||
- Client-side cheating (implement server-authoritative validation)
|
||||
- Side-channel attacks (e.g., Spectre) on shared hardware
|
||||
|
||||
---
|
||||
|
||||
## Non-Negotiable Rules
|
||||
|
||||
This section clarifies the project's boundaries and principles:
|
||||
|
||||
### Architectural Independence
|
||||
|
||||
- ✅ **YES**: This is a clean-room implementation designed from first principles.
|
||||
- ✅ **YES**: All architecture decisions are documented with rationale in ADRs (Architecture Decision Records).
|
||||
- ❌ **NO**: This project does not reverse-engineer, reference, or derive from any proprietary systems.
|
||||
- ❌ **NO**: No proprietary assets, protocols, or algorithms are used or referenced.
|
||||
|
||||
### Code Contributions
|
||||
|
||||
- ✅ **YES**: Contributors must certify that all submitted code is original work or properly licensed.
|
||||
- ✅ **YES**: All dependencies must be MIT, Apache-2.0, or BSD-licensed (no copyleft licenses).
|
||||
- ❌ **NO**: Code derived from proprietary sources, even if reverse-engineered, will be rejected.
|
||||
- ❌ **NO**: Pull requests referencing proprietary systems or protocols will be closed without review.
|
||||
|
||||
### Legal Compliance
|
||||
|
||||
- This project is developed under the principle of independent implementation.
|
||||
- Contributors are expected to understand and respect intellectual property laws.
|
||||
- If you have previously worked on similar proprietary systems, consult legal counsel before contributing.
|
||||
- All contributions are subject to the project's Contributor License Agreement (CLA).
|
||||
|
||||
### Technical Philosophy
|
||||
|
||||
- **Performance over compatibility**: We optimize for modern hardware, not legacy constraints.
|
||||
- **Security over convenience**: Sandboxing cannot be disabled or bypassed.
|
||||
- **Explicitness over magic**: All behavior is documented and configurable.
|
||||
- **Linux-first**: Primary platform is Linux x86_64; other platforms are best-effort.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Current Status (v0.3.0)
|
||||
|
||||
- ✅ Core coordinator and executor services
|
||||
- ✅ WASM module loading and execution
|
||||
- ✅ JWT authentication and session management
|
||||
- ✅ Basic Bevy client with 3D rendering
|
||||
- ✅ PostgreSQL state persistence
|
||||
|
||||
### Planned Features (v0.4.0 - Q2 2026)
|
||||
|
||||
- 🔄 Hot-reloading of WASM modules without session interruption
|
||||
- 🔄 Multi-region deployment with state replication
|
||||
- 🔄 Enhanced observability (distributed tracing with OpenTelemetry)
|
||||
- 🔄 Client-side prediction and interpolation improvements
|
||||
- 🔄 Admin dashboard for session monitoring
|
||||
|
||||
### Future Considerations (v1.0+)
|
||||
|
||||
- AI-powered anomaly detection for cheating prevention
|
||||
- Support for mobile clients (iOS/Android via Bevy)
|
||||
- Kubernetes operator for automated scaling
|
||||
- Plugin system for custom authentication providers
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
**Before submitting a PR**:
|
||||
1. Review the [Non-Negotiable Rules](#non-negotiable-rules) section
|
||||
2. Sign the Contributor License Agreement (CLA)
|
||||
3. Ensure all tests pass: `./scripts/run_tests.sh`
|
||||
4. Run linters: `cargo clippy -- -D warnings`
|
||||
5. Format code: `cargo fmt --all`
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
**Third-Party Dependencies**: All dependencies are listed in `Cargo.lock` with their respective licenses. Use `cargo license` to generate a full report.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation**: [https://docs.rcc-engine.io](https://docs.rcc-engine.io)
|
||||
- **Discord**: [https://discord.gg/rcc-dev](https://discord.gg/rcc-dev)
|
||||
- **Issue Tracker**: [GitHub Issues](https://github.com/your-org/rcc/issues)
|
||||
- **Security Reports**: security@rcc-engine.io (PGP key in repository)
|
||||
|
||||
---
|
||||
|
||||
**Built with 🦀 Rust • Designed for the cloud • Sandboxed by default**
|
||||
Reference in New Issue
Block a user