wsPrism

The Enterprise-Grade Realtime Gateway
Native Performance. Universal Extensibility.

Introduction

wsPrism is a high-performance, standalone realtime gateway designed to sit between your clients (Frontend / Game Client) and your business logic (Backend).

While modern web backends are excellent at handling RESTful requests, they often struggle with the heavy concurrency, statefulness, and extreme low-latency requirements of persistent socket connections.
wsPrism solves this by offloading the heavy lifting of connection management to a dedicated, Rust-powered process.

We built wsPrism with a specific philosophy:

“The core should be fast and safe, but the usage should be universal.”

You do not need to be a Rust expert to use wsPrism.
It is designed to be an enterprise-grade platform that is highly configurable, secure by default, and extensible to fit any domain—from multiplayer games and trading platforms to live collaborative tools.

Architecture Overview

wsPrism acts as the traffic controller for your realtime infrastructure.

graph TD
    Client_A[Client] -->|WebSocket| Transport
    Client_B[Client] -->|WebSocket| Transport

    subgraph Process [wsPrism Process]
        Transport[Transport Layer]
        Policy[Policy Engine]
        
        subgraph Core [Realtime Core]
            Router[Dispatcher]
            Registry[Session Registry]
            Presence[Room Presence]
        end
        
        Transport --> Policy --> Router
        
        Router -->|Hot Lane - Binary| Service_Echo[Native / Hot Service]
        Router -->|Ext Lane - Text| Service_Chat[Script / WASM Service]
    end
    
    Service_Chat -.->|WebHook / RPC| Backend[Your Backend API]

Key Features

⚡ Ultra-Low Latency Core
Built on tokio and axum, utilizing a lock-free, session-oriented architecture optimized for tail latency.

🏢 Multi-Tenancy
Run multiple isolated tenants (projects) on a single wsPrism instance, each with independent configuration and policies.

🛡️ Policy Engine – Secure by Default
Define strict allowlists, rate limits, payload size limits, and behavioral rules per tenant.

🧠 Deterministic QoS
Prioritized message delivery:

• Lossy channels for high-frequency game state updates
• Reliable channels for chat, commands, and events

🔌 Transport Agnostic Design
Business logic is fully decoupled from the transport layer:

• WebSocket today
• QUIC / TCP / Custom transports tomorrow

Disclaimer & Liability

⚠️ Please Read Carefully

wsPrism is currently an experimental, personal prototype project.

While it is designed with enterprise-grade architecture and performance principles in mind, it is provided “as is”, without warranty of any kind, express or implied, including but not limited to:

• Merchantability
• Fitness for a particular purpose
• Non-infringement

By using this software, you acknowledge and agree that:

• Use at Your Own Risk
  You are solely responsible for determining the appropriateness of using or redistributing this software.

• No Liability
  In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from or in connection with the software.

• Not Production Certified
  This software has not yet undergone formal security audits or large-scale production verification.

License

This project is licensed under the Apache License 2.0.

Design Philosophy

wsPrism was built to solve the specific challenges of scaling realtime applications. Here are the core principles that guide its development.

1. The “Sidecar” Architecture

wsPrism is not just a library; it is a Realtime Edge Gateway.

In a traditional setup, your monolithic backend handles everything: database queries, business logic, and maintaining thousands of idle WebSocket connections. This scales poorly because stateful connections consume resources even when idle.

wsPrism separates concerns:

• It handles the “connection storm” (handshakes, heartbeats, ping/pong).
• It manages thousands of concurrent stateful sessions.
• It routes filtered, valid messages to your services.

Result: Your main backend logic remains stateless and scalable (like standard REST APIs), while wsPrism guarantees low-latency delivery.

2. Rust Performance, Human Accessibility

We utilize Rust for the Core Engine to guarantee memory safety, zero-cost abstractions, and stable tail latencies. This is critical for high-frequency trading or gaming where a garbage collector pause is unacceptable.

However, wsPrism is designed as a Platform, not just a framework for Rust developers:

• Configurable Policies: Rate limits, packet sizes, and allowlists are managed via simple YAML configurations.
• Ops-Ready: Built-in metrics (Prometheus) and structured logging for enterprise observability.
• Extensible: (Future roadmap) Write plugins in scripting languages or WASM.

3. The “Dual Lane” Protocol

Most frameworks force you to choose between “Easy JSON” (Socket.io) or “Fast Binary” (gRPC / Raw UDP). wsPrism unifies them into a single connection.

A. Ext Lane (Text / JSON)

• Use Case: Chat, lobby logic, room management, complex data structures.
• Priority: Reliable delivery.
• Format: Human-readable JSON. Easy to debug and develop.

B. Hot Lane (Binary)

• Use Case: Player movement, physics synchronization, market ticks, high-frequency signals.
• Priority: Latency critical (Lossy / Latest-state-wins).
• Format: Compact Binary. Zero-allocation routing, minimal overhead, routed strictly by Service ID and OpCode.

Getting Started

This guide will help you get the wsPrism gateway up and running in minutes.

1. Configuration

First, create a wsprism.yaml file in your project root.
This file controls networking, security policies, and tenant isolation.

Note:
This is a minimal configuration for quick testing.
For a complete list of options (rate limiting, session modes, etc.), please refer to the Configuration Guide.

version: 1

gateway:
  listen: "0.0.0.0:8080"
  ping_interval_ms: 5000
  idle_timeout_ms: 10000

tenants:
  - id: acme
    limits:
      max_frame_bytes: 65536
    policy:
      # Allow basic room and chat commands
      ext_allowlist:
        - "room:join"
        - "room:leave"
        - "chat:*"

      # Allow all binary opcodes for service ID 1
      hot_allowlist:
        - "1:*"

2. Run the Gateway

You can start the gateway using Cargo (when developing from source) or a pre-built binary.

Using Cargo

# Enable debug logging to see detailed startup information
RUST_LOG=wsprism_gateway=debug cargo run --release -- --config wsprism.yaml

Using Binary

./wsprism start --config wsprism.yaml

3. Verify

Check your terminal output.
You should see logs indicating that the server is active and the tenant configuration is loaded:

INFO  wsprism::server > 🚀 wsPrism Gateway active at 0.0.0.0:8080
INFO  wsprism::loader > Loaded configuration for tenant: "acme"

4. Connect

Now connect a WebSocket client (browser console, Postman, game engine, etc.).

URL format

ws://<host>:<port>/v1/ws?tenant=<id>&ticket=<auth_token>

Example

ws://localhost:8080/v1/ws?tenant=acme&ticket=dev

Tip:
The ticket parameter is currently a placeholder for development.
In production, this would typically be a signed JWT or session token.

5. Send Messages (Hello World)

Once connected, wsPrism allows communication via two distinct lanes.

A. Ext Lane (Text / JSON)

Use this for chat, logic, and room management.

{
  "v": 1,
  "svc": "chat",
  "type": "send",
  "room": "lobby",
  "data": {
    "msg": "Hello wsPrism!"
  }
}

B. Hot Lane (Binary)

Use this for high-frequency data such as player movement or market ticks.

Binary format

[svc_id (u8)] [opcode (u8)] [flags (u8)] [payload...]

Example

• Service ID: 1
• OpCode: 1
• Flags: 0
• Payload: arbitrary bytes

Hex representation

01 01 00 DE AD BE EF

What’s Next?

• Learn how to configure Rate Limits and Session Policies in the Configuration Guide.
• Understand the Design Philosophy behind the Dual Lane architecture.
• Explore the internal mechanics in the Architecture documentation.

Configuration Guide

wsPrism is configured via a single YAML file (wsprism.yaml) located in your project root.
This file controls networking, security policies, rate limits, session behavior, tenant isolation, and observability.

Full Configuration Example

Below is a comprehensive example showing different tenant configurations:

• Standard SaaS – Balanced settings for general applications
• High-Security (Banking-style) – Strict single-session enforcement and audit-friendly behavior
• High-Throughput (Gaming-style) – Optimized for massive concurrency and low latency

# wsprism.yaml
# ----------------=========================================----------------
# wsPrism Gateway Configuration
# ----------------=========================================----------------

version: 1  # (required) Config schema version. Currently only 1 is supported.

gateway:
  # -----------------------------------------------------------------------
  # 1. Network & Lifecycle
  # -----------------------------------------------------------------------
  listen: "0.0.0.0:8080"
  ping_interval_ms: 20000
  idle_timeout_ms: 60000
  writer_send_timeout_ms: 1500
  drain_grace_ms: 5000

  # -----------------------------------------------------------------------
  # 2. Handshake Defender (DoS Protection)
  # -----------------------------------------------------------------------
  handshake_limit:
    enabled: true
    global_rps: 500
    global_burst: 1000
    per_ip_rps: 10
    per_ip_burst: 20
    max_ip_entries: 50000

  # -----------------------------------------------------------------------
tenants:
  # =======================================================================
  # Tenant A: "acme" (Standard SaaS)
  # =======================================================================
  - id: acme
    limits:
      max_frame_bytes: 65536
      max_sessions_total: 10000
      max_rooms_total: 500
      max_users_per_room: 100
      max_rooms_per_user: 10

    policy:
      rate_limit_rps: 1000
      rate_limit_burst: 2000
      rate_limit_scope: both

      sessions:
        mode: multi
        max_sessions_per_user: 4
        on_exceed: kick_oldest

      hot_error_mode: silent
      hot_requires_active_room: true

      ext_allowlist:
        - "room:join"
        - "room:leave"
        - "chat:*"

      hot_allowlist:
        - "1:*"

  # =======================================================================
  # Tenant B: "bank" (High Security)
  # =======================================================================
  - id: bank
    limits:
      max_frame_bytes: 16384
      max_sessions_total: 1000
      max_rooms_total: 0
      max_users_per_room: 0
      max_rooms_per_user: 0

    policy:
      rate_limit_rps: 100
      rate_limit_burst: 200
      rate_limit_scope: tenant

      sessions:
        mode: single
        max_sessions_per_user: 1
        on_exceed: deny

      hot_error_mode: sys_error
      hot_requires_active_room: true

      ext_allowlist:
        - "auth:verify"
        - "msg:secure"

      hot_allowlist: []

  # =======================================================================
  # Tenant C: "game" (High Throughput)
  # =======================================================================
  - id: game
    limits:
      max_frame_bytes: 65536
      max_sessions_total: 100000
      max_rooms_total: 5000
      max_users_per_room: 200
      max_rooms_per_user: 0

    policy:
      rate_limit_rps: 5000
      rate_limit_burst: 10000
      rate_limit_scope: connection

      sessions:
        mode: multi
        max_sessions_per_user: 10
        on_exceed: kick_oldest

      hot_error_mode: silent
      hot_requires_active_room: true

      ext_allowlist:
        - "room:*"
        - "match:*"

      hot_allowlist:
        - "1:*"
        - "2:10"

Schema Reference

Root Fields

Gateway Section

Network & Lifecycle

Handshake Defender (DoS Protection)

Observability

Tenant Limits (Resource Governance)

Hard limits to prevent resource exhaustion.
0 means unlimited.

Policy Object

1. Rate Limiting

Token Bucket–based flow control.

2. Session Management

3. Hot Lane (Binary Protocol)

4. Allowlists (Routing Security)

Deny-by-default routing.

Best Practices

🎮 Games / Realtime Systems

• Session Mode: multi
• Rate Limit Scope: connection
• Hot Error Mode: silent

🏦 Banking / High Security

• Session Mode: single
• Rate Limit Scope: tenant
• Avoid wildcards in allowlists

Overview

Dual Lane Protocol

Policy Engine

Rust API Docs