RCC (Rust Cloud Coordinator)

A clean-room, Linux-first reimplementation of a cloud-based game engine backend with sandboxed WASM execution.

---

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

# 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

cargo run --release --bin rcc-service
# Starts on 0.0.0.0:50051 (gRPC)

Terminal 2 - Executor

cargo run --release --bin rcc-soap
# Starts on 0.0.0.0:8080 (WebSocket)

Terminal 3 - Client

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

# 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:

[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

# 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

# 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 for guidelines.

Before submitting a PR:

1. Review the 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 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
• Discord: https://discord.gg/rcc-dev
• Issue Tracker: GitHub Issues
• Security Reports: security@rcc-engine.io (PGP key in repository)

---

Built with 🦀 Rust • Designed for the cloud • Sandboxed by default