From 2418bef1a211e93b955ea4cfd58e9a219225386a Mon Sep 17 00:00:00 2001 From: "Marcel R." Date: Thu, 15 Jan 2026 00:51:46 +0100 Subject: [PATCH] Upload files to "/" --- README.md | 435 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 435 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..06c81ee --- /dev/null +++ b/README.md @@ -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.** + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/) +[![Platform](https://img.shields.io/badge/platform-Linux-blue.svg)](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 + +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** \ No newline at end of file