realtime-gateway 0.1.0__tar.gz

realtime_gateway-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+REALTIME_GATEWAY_MASTER.md
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Environments
+.venv/
+env/
+venv/
+
+# Testing & Quality
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local Project Metadata
+.github_info
+

realtime_gateway-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-01
+
+### Added
+- **Core Engine:** High-level `Gateway` orchestration facade and strongly-typed `GatewayConfig` system.
+- **Transport Abstraction:** Decoupled `ITransport` and `ITransportConnection` contracts with `WebSocketTransport` implementation.
+- **Connection Management:** `Connection` lifecycle state machine (`CONNECTING`, `AUTHENTICATING`, `CONNECTED`, `CLOSING`, `CLOSED`), `ConnectionRegistry`, and `SubscriptionManager`.
+- **Message Protocol:** Standardized `MessageEnvelope` wire format supporting `COMMAND`, `EVENT`, `HEARTBEAT`, `ERROR`, and `DISCONNECT` frames.
+- **Message Routing:** `MessageRouter` and `EventDispatcher` supporting Connection, User, Channel, and Broadcast routing targets.
+- **Distributed Scale-Out:** Decoupled `IMessageBroker` abstraction with `InMemoryBroker` and `RedisBroker` adapters, connected via `BrokerEventBridge`.
+- **Security & Limits:** `TokenBucketRateLimiter`, `ConnectionRateLimiter`, `MessageSizeGuard`, `ConnectionLimitGuard`, and `JWTAuthenticator`.
+- **Reliability & Observability:** `ConnectionWriterQueue` backpressure management, `HeartbeatManager` zombie eviction, and `MetricsCollector` tracking.
+- **Developer Experience:** PEP 561 `py.typed` compliance, optional PyPI extras (`[redis]`, `[jwt]`, `[websockets]`, `[all]`), and runnable Asyncio/FastAPI examples.

realtime_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: realtime-gateway
+Version: 0.1.0
+Summary: A reusable, transport-agnostic real-time WebSocket gateway package for Python
+Author-email: Aryan Singla <aryansingla45@gmail.com>
+License: MIT
+Keywords: asyncio,gateway,pubsub,realtime,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: pyjwt>=2.8.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: websockets>=12.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Provides-Extra: jwt
+Requires-Dist: pyjwt>=2.8.0; extra == 'jwt'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: websockets
+Requires-Dist: websockets>=12.0; extra == 'websockets'
+Description-Content-Type: text/markdown
+
+# Realtime Gateway
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Types: Mypy](https://img.shields.io/badge/types-strict%20mypy-blueviolet.svg)](https://mypy-lang.org/)
+
+**Realtime Gateway** is a high-performance, transport-agnostic real-time WebSocket gateway engine for Python. Built on modern `asyncio`, it provides decoupled connection handling, pub/sub subscription routing, token bucket rate limiting, authenticated channels, and horizontal scale-out via Redis Pub/Sub.
+
+---
+
+## Key Features
+
+- **Transport Agnostic Core**: Core engine runs independent of specific network protocols. Built-in `WebSocketTransport` adapter included.
+- **Zero Core Dependencies**: Core installation requires zero third-party packages outside Python's standard library.
+- **Pub/Sub Cluster Scale-Out**: Scale horizontally across multiple instances using `RedisBroker` or run single-instance with `InMemoryBroker`.
+- **Built-in Security Guards**: Token bucket rate limiters, message/frame size guards, maximum connection limits, and anti-Slowloris connection eviction.
+- **Authentication & Authorization**: Decoupled `IAuthenticator` (PyJWT support) and `IAuthorizer` interface contracts.
+- **Observability Built-in**: `MetricsCollector` tracking active connections, message throughput, and rate limit drops.
+- **Strictly Typed & PEP 561 Compliant**: 100% typed codebase with `py.typed` marker for downstream `mypy`/`pyright` validation.
+
+---
+
+## Installation
+
+```bash
+# Core install (zero third-party dependencies)
+pip install realtime-gateway
+
+# With all optional adapters (Redis, PyJWT, websockets)
+pip install realtime-gateway[all]
+```
+
+---
+
+## 10-Line Quickstart
+
+```python
+import asyncio
+from realtime_gateway import Gateway, GatewayConfig
+
+async def main() -> None:
+    # Initialize gateway with strongly-typed configuration
+    config = GatewayConfig(host="127.0.0.1", port=8765, max_connections=1000)
+    gateway = Gateway(config=config)
+
+    print("Starting Realtime Gateway on ws://127.0.0.1:8765...")
+    await gateway.start()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Documentation Guide
+
+- [Architecture Guide](docs/architecture.md): System design, component interaction, and domain models.
+- [Wire Protocol Specification](docs/protocol.md): JSON envelope formats, message types, and status codes.
+- [Configuration Reference](docs/configuration.md): `GatewayConfig` parameters and environment variable overrides.
+- [Framework Integration](docs/integration.md): Plugging into FastAPI, Django, and standalone Asyncio apps.
+- [Production Deployment](docs/deployment.md): Horizontal scaling with Redis Pub/Sub behind load balancers.
+- [Security Guidance](docs/security.md): TLS/WSS termination, token validation, and rate limit tuning.
+- [ADR Index](docs/adr/README.md): Master index of all Architectural Decision Records (ADR-0001 to ADR-0016).
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE).

realtime_gateway-0.1.0/README.md

@@ -0,0 +1,70 @@
+# Realtime Gateway
+
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Types: Mypy](https://img.shields.io/badge/types-strict%20mypy-blueviolet.svg)](https://mypy-lang.org/)
+
+**Realtime Gateway** is a high-performance, transport-agnostic real-time WebSocket gateway engine for Python. Built on modern `asyncio`, it provides decoupled connection handling, pub/sub subscription routing, token bucket rate limiting, authenticated channels, and horizontal scale-out via Redis Pub/Sub.
+
+---
+
+## Key Features
+
+- **Transport Agnostic Core**: Core engine runs independent of specific network protocols. Built-in `WebSocketTransport` adapter included.
+- **Zero Core Dependencies**: Core installation requires zero third-party packages outside Python's standard library.
+- **Pub/Sub Cluster Scale-Out**: Scale horizontally across multiple instances using `RedisBroker` or run single-instance with `InMemoryBroker`.
+- **Built-in Security Guards**: Token bucket rate limiters, message/frame size guards, maximum connection limits, and anti-Slowloris connection eviction.
+- **Authentication & Authorization**: Decoupled `IAuthenticator` (PyJWT support) and `IAuthorizer` interface contracts.
+- **Observability Built-in**: `MetricsCollector` tracking active connections, message throughput, and rate limit drops.
+- **Strictly Typed & PEP 561 Compliant**: 100% typed codebase with `py.typed` marker for downstream `mypy`/`pyright` validation.
+
+---
+
+## Installation
+
+```bash
+# Core install (zero third-party dependencies)
+pip install realtime-gateway
+
+# With all optional adapters (Redis, PyJWT, websockets)
+pip install realtime-gateway[all]
+```
+
+---
+
+## 10-Line Quickstart
+
+```python
+import asyncio
+from realtime_gateway import Gateway, GatewayConfig
+
+async def main() -> None:
+    # Initialize gateway with strongly-typed configuration
+    config = GatewayConfig(host="127.0.0.1", port=8765, max_connections=1000)
+    gateway = Gateway(config=config)
+
+    print("Starting Realtime Gateway on ws://127.0.0.1:8765...")
+    await gateway.start()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Documentation Guide
+
+- [Architecture Guide](docs/architecture.md): System design, component interaction, and domain models.
+- [Wire Protocol Specification](docs/protocol.md): JSON envelope formats, message types, and status codes.
+- [Configuration Reference](docs/configuration.md): `GatewayConfig` parameters and environment variable overrides.
+- [Framework Integration](docs/integration.md): Plugging into FastAPI, Django, and standalone Asyncio apps.
+- [Production Deployment](docs/deployment.md): Horizontal scaling with Redis Pub/Sub behind load balancers.
+- [Security Guidance](docs/security.md): TLS/WSS termination, token validation, and rate limit tuning.
+- [ADR Index](docs/adr/README.md): Master index of all Architectural Decision Records (ADR-0001 to ADR-0016).
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE).

realtime_gateway-0.1.0/USAGE.md

@@ -0,0 +1,196 @@
+# Realtime Gateway - Developer Usage Guide
+
+Welcome to the **Realtime Gateway**! This guide is designed to help you integrate and use this package for your real-time use cases. 
+
+## What is this?
+
+The Realtime Gateway is a production-ready, protocol-agnostic WebSocket gateway. It manages connection lifecycles, pub/sub channels, security limits, scaling via brokers, and heartbeats. 
+
+Instead of re-inventing WebSocket connection management in every web service (FastAPI, Django, etc.), you can embed this gateway into your application or run it as a standalone service.
+
+---
+
+## 1. Installation
+
+The package can be installed with optional dependencies depending on your needs. For local development, you can use:
+
+```bash
+uv pip install -e .[all]
+```
+*(Available extras: `[redis]`, `[jwt]`, `[websockets]`, `[all]`)*
+
+---
+
+## 2. Basic Standalone Usage (Asyncio)
+
+The core entry point is the `Gateway` class, which orchestrates everything. You can configure it using `GatewayConfig`.
+
+```python
+import asyncio
+from realtime_gateway import Gateway, GatewayConfig
+
+async def main():
+    # 1. Define configuration (limits, ports, timeouts)
+    config = GatewayConfig(
+        host="127.0.0.1",
+        port=8765,
+        max_connections=10_000,
+        rate_limit_rps=20.0,
+    )
+    
+    # 2. Initialize the Gateway
+    gateway = Gateway(config=config)
+    
+    # 3. Start it up
+    print(f"Gateway listening on ws://{config.host}:{config.port}")
+    await gateway.start()
+    
+    try:
+        # Keep process alive
+        await asyncio.Event().wait()
+    finally:
+        # 4. Clean shutdown
+        await gateway.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 3. Integrating with FastAPI (or other ASGI frameworks)
+
+You don't need a separate process to run the gateway; it can run concurrently in the same event loop as your API server!
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from realtime_gateway import Gateway, GatewayConfig
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize gateway from environment variables
+    config = GatewayConfig.from_env()
+    gateway = Gateway(config=config)
+    
+    # Attach to app state if your HTTP routes need to interact with it
+    app.state.gateway = gateway
+
+    # Start gateway
+    await gateway.start()
+    
+    yield # Hand over to FastAPI application
+    
+    # Stop cleanly when FastAPI shuts down
+    await gateway.stop()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+---
+
+## 4. The Message Protocol
+
+The gateway expects messages from the client to be sent in a strict envelope format (JSON). The base format is:
+
+```json
+{
+  "version": "1",
+  "id": "msg-1234",
+  "type": "command", 
+  "payload": {
+      "action": "...",
+      "...": "..."
+  }
+}
+```
+
+### Built-in Actions: Subscribe & Publish
+
+The gateway has built-in routing for pub/sub via channels. 
+
+**Subscribing to a channel:**
+```json
+{
+  "type": "command",
+  "payload": {
+    "action": "subscribe",
+    "channel": "notifications:user-123"
+  }
+}
+```
+
+**Publishing a message to a channel:**
+```json
+{
+  "type": "command",
+  "payload": {
+    "action": "publish",
+    "channel": "notifications:user-123",
+    "message": {
+      "alert": "Your report is ready!"
+    }
+  }
+}
+```
+*Note: Any client subscribed to `notifications:user-123` will instantly receive the `publish` payload as an `event` message.*
+
+**Heartbeats:**
+To prevent the gateway from closing inactive connections, clients must occasionally send ping frames:
+```json
+{
+  "type": "command",
+  "payload": {
+    "action": "ping"
+  }
+}
+```
+
+---
+
+## 5. Scaling Out (Multi-Instance)
+
+By default, the `Gateway` uses an `InMemoryBroker`. This means clients connected to Instance A cannot publish messages to clients on Instance B.
+
+To solve this, inject the `RedisBroker`. The `Gateway` accepts injected adapters.
+
+```python
+from realtime_gateway import Gateway
+from realtime_gateway.adapters.broker.redis import RedisBroker
+
+async def main():
+    # Setup Redis Broker
+    broker = RedisBroker(redis_url="redis://localhost:6379")
+    
+    # Inject it into the Gateway
+    gateway = Gateway(broker=broker)
+    
+    await gateway.start()
+```
+Now, if Client A connects to Gateway A and publishes to `chat:lobby`, the message goes to Redis, which forwards it to Gateway B, which delivers it to Client B. 
+
+---
+
+## 6. Extending the Gateway (Custom Authorization)
+
+If you need a custom way to verify user tokens or set permissions, you can implement the `IAuthenticator` interface and inject it exactly like the broker above:
+
+```python
+from realtime_gateway import Gateway
+from realtime_gateway.interfaces.authenticator import IAuthenticator
+
+class MyCustomAuth(IAuthenticator):
+    async def authenticate(self, credentials):
+        # your custom logic here
+        pass
+
+gateway = Gateway(authenticator=MyCustomAuth())
+```
+
+---
+
+## Summary for Developers
+1. **Don't touch the TCP/WebSocket layer.** The `WebSocketTransport` handles it.
+2. **Don't hardcode Redis/RabbitMQ.** Inject the `IMessageBroker` if needed.
+3. **Use the `Gateway` facade.** It wraps rate limiting, metrics, heartbeats, and message routing.
+4. **Follow the protocol.** Use the `MessageEnvelope` structure on the frontend.

realtime_gateway-0.1.0/docs/adr/0001-core-architecture.md

@@ -0,0 +1,73 @@
+# ADR-001: Core Architecture & Infrastructure Decoupling
+
+* **Status:** Accepted
+* **Date:** 2026-08-24
+* **Deciders:** Realtime Gateway Architecture Team
+* **Parent Epic:** EPIC-01 — System Definition
+* **Ticket:** #2 — Write problem statement & system decision
+
+---
+
+## Context and Problem Statement
+
+Real-time applications requiring persistent bidirectional communication often tightly couple their business logic to specific WebSocket libraries, HTTP frameworks (e.g., FastAPI, Starlette), pub/sub message brokers (e.g., Redis, RabbitMQ), or authentication providers (e.g., PyJWT). 
+
+When these infrastructure technologies evolve or change, or when another Python project attempts to reuse the real-time gateway capability, the tight coupling forces costly refactoring or framework lock-in.
+
+We need an architectural strategy that guarantees the gateway core remains decoupled from external transport, broker, and authentication technologies while delivering high performance, reliability, and clean package reusability.
+
+---
+
+## Decision Drivers
+
+1. **Reusability:** The gateway must be installable as a standalone Python package (`realtime-gateway`) in any downstream Python application.
+2. **Framework Independence:** Core domain logic must not import or depend on FastAPI, Django, Redis, PyJWT, or specific WebSocket server implementations.
+3. **Maintainability & Testability:** Core components must be testable in memory using standard Python `asyncio` without requiring running Redis servers or active network sockets.
+4. **Security & Liveness:** Architectural boundaries must enforce strict backpressure, rate limits, and heartbeat management.
+
+---
+
+## Considered Options
+
+1. **Option 1: Direct Framework Integration (FastAPI/Starlette + Redis)**
+   - *Pros:* Faster initial prototype.
+   - *Cons:* Locks the package into FastAPI/Starlette; forces consumers to adopt Redis even for single-instance deployments; hard to test core logic in isolation.
+
+2. **Option 2: Hexagonal / Ports-and-Adapters Architecture (Chosen)**
+   - *Pros:* Complete decoupling of core logic from infrastructure details. Transport (`Transport`), Broker (`MessageBroker`), Authentication (`Authenticator`), and Authorization (`Authorizer`) are abstract interfaces. Core owns domain logic (`ConnectionManager`, `Router`, `SubscriptionManager`, `Gateway`).
+   - *Cons:* Requires establishing explicit abstract interfaces upfront.
+
+3. **Option 3: Custom Protocols over Raw Sockets**
+   - *Pros:* Total low-level control.
+   - *Cons:* Reinventing TCP/TLS/WebSocket framing creates immense maintenance burden and security risks without adding gateway domain value.
+
+---
+
+## Decision Outcome
+
+Chosen Option: **Option 2 (Hexagonal Architecture)**.
+
+### Architecture Rules
+1. `src/realtime_gateway/core/` owns domain entities (`Connection`, `Principal`, `Message`, `Subscription`) and domain logic (`ConnectionManager`, `Router`). Core files MUST NOT import external infrastructure packages.
+2. `src/realtime_gateway/interfaces/` defines abstract `typing.Protocol` or `abc.ABC` contracts for all external interactions (`Transport`, `MessageBroker`, `Authenticator`, `Authorizer`, `Serializer`, `Observer`).
+3. `src/realtime_gateway/adapters/` houses concrete technology implementations (e.g., WebSocket transport, Redis pub/sub broker, JWT authentication). Adapters are optional dependencies.
+4. The core package MUST be usable out of the box with zero required external binary dependencies.
+
+---
+
+## Consequences
+
+### Positive
+* **Zero Leakage:** Infrastructure choices do not leak into gateway state management.
+* **Testability:** 100% of core routing, connection state machine, sub/pub, and backpressure logic can be unit-tested cleanly in memory without network IO.
+* **Pluggability:** Downstream applications can inject custom authenticators, brokers, or transports without modifying package internals.
+
+### Negative / Trade-offs
+* Requires careful maintenance of interface contracts (`interfaces/`).
+* Adapters must strictly convert third-party exceptions and data types to core gateway representations.
+
+---
+
+## Compliance Verification
+
+Automated architecture tests (`tests/unit/test_architecture_boundary.py`) will continuously verify that `realtime_gateway.core` and `realtime_gateway.interfaces` maintain zero imports from concrete infrastructure libraries (`redis`, `websockets`, `jwt`, `fastapi`, `starlette`).

realtime_gateway-0.1.0/docs/adr/0002-system-goals-and-non-goals.md

@@ -0,0 +1,49 @@
+# ADR-002: System Goals, System Boundaries, and Non-Goals
+
+* **Status:** Accepted
+* **Date:** 2026-08-24
+* **Deciders:** Realtime Gateway Architecture Team
+* **Parent Epic:** EPIC-01 — System Definition
+* **Ticket:** #3 — Define goals and non-goals
+
+---
+
+## Context and Problem Statement
+
+Real-time communication engines frequently suffer from scope creep. Without explicit architectural boundaries, a real-time gateway risk evolving into a bloated monolith—attempting to serve as an HTTP web framework, a persistent database, an identity provider (OAuth/JWT issuer), a TCP wire-protocol engine, or a full API gateway.
+
+To maintain a focused, high-performance, and reusable Python package (`realtime-gateway`), we must formally define the explicit goals (what the gateway MUST do) and non-goals (what the gateway MUST NOT do).
+
+---
+
+## System Goals (In Scope)
+
+1. **Persistent Connection Management:** Track, maintain, and transition WebSocket client connection lifecycles (`CONNECTING`, `AUTHENTICATING`, `CONNECTED`, `CLOSING`, `CLOSED`).
+2. **Abstract Authentication & Authorization Boundaries:** Intercept client connections and message actions via replaceable `Authenticator` and `Authorizer` interfaces.
+3. **Flexible Sub/Pub Routing:** Support direct connection targeting, user-targeted delivery, channel broadcasting, and multicast routing.
+4. **Reliability & Resource Protection:** Bounded outgoing queues, backpressure handling, idle/pong heartbeat timeouts, and dead connection cleanup.
+5. **Horizontal Scalability:** Support multi-instance gateway clusters via a pluggable `MessageBroker` abstraction (In-Memory and Redis Pub/Sub).
+6. **Observability:** Structured lifecycle event logging, metric counters/histograms, and correlation ID tracing.
+7. **Clean Package Interface:** Minimal core dependencies, installable via `uv`/`pip` into any downstream Python codebase.
+
+---
+
+## Non-Goals (Explicitly Out of Scope)
+
+1. **Not an HTTP Application Server:** The gateway does not handle general REST API routing, static file serving, or general HTTP requests.
+2. **Not a TCP/WebSocket Wire Protocol Implementation:** Wire-level framing, TLS termination, and socket masking are delegated to mature WebSocket transport libraries behind our `Transport` adapter boundary.
+3. **Not a Message Broker / Storage Replacement:** The gateway is a real-time router, not a persistent queue or storage database (e.g., Redis, RabbitMQ, Kafka, Postgres).
+4. **Not an Identity Provider:** The gateway validates tokens via an `Authenticator` interface but does not issue tokens, manage user passwords, or act as an OAuth server.
+5. **Not a General Service Mesh or HTTP API Gateway:** The gateway strictly handles real-time traffic control; it does not replace Envoy, Kong, or NGINX for REST/gRPC microservices traffic.
+
+---
+
+## Consequences
+
+### Positive
+- Prevents bloat and keeps `realtime-gateway` core clean, fast, and easy to maintain.
+- Downstream applications can integrate the gateway without replacing their existing HTTP web frameworks or authentication servers.
+- Clear test boundaries: tests focus on real-time traffic control, routing, state management, and backpressure.
+
+### Negative / Trade-offs
+- Downstream applications must provide or plug in their own authentication token issuers and HTTP servers.

realtime_gateway-0.1.0/docs/adr/0003-actors-and-system-roles.md

@@ -0,0 +1,84 @@
+# ADR-003: Actors, System Roles, and Principal Identity Boundaries
+
+* **Status:** Accepted
+* **Date:** 2026-08-24
+* **Deciders:** Realtime Gateway Architecture Team
+* **Parent Epic:** EPIC-01 — System Definition
+* **Ticket:** #4 — Identify actors and system roles
+
+---
+
+## Context and Problem Statement
+
+A real-time gateway operates at the boundary between external clients (browsers, mobile apps), backend application services, and underlying infrastructure (WebSocket transports, pub/sub brokers).
+
+Without a clean taxonomy of actors, system roles, and identity representations, system designs risk blurring boundaries—such as coupling the gateway's connection registry directly to a specific application's `User` database model or allowing unauthorized client actors to broadcast arbitrary messages across channels.
+
+We need to explicitly define the system actors, operational roles, and the generic `Principal` identity contract.
+
+---
+
+## Actor Taxonomy
+
+| Actor | Type | Description |
+| :--- | :--- | :--- |
+| **External Client** | Human / Device / Client App | Connects via WebSocket/Transport to send commands and receive real-time events. |
+| **Consuming Application** | Backend Service | Embeds `realtime-gateway` package, authenticates/authorizes clients, and dispatches domain events. |
+| **Gateway Core Engine** | System Component | Internal orchestrator managing connection state machine, router tables, heartbeat liveness, and backpressure. |
+| **Infrastructure Adapters** | External Drivers | Pluggable implementations (`Transport`, `MessageBroker`, `Authenticator`, `Authorizer`) bridging technology boundaries. |
+
+---
+
+## System Roles & Identity States
+
+```text
+               ┌──────────────────────────┐
+               │    Anonymous Connection  │
+               └────────────┬─────────────┘
+                            │  Authenticates
+                            ▼
+               ┌──────────────────────────┐
+               │  Authenticated Principal │
+               └────────────┬─────────────┘
+                            │  Subscribes
+                            ▼
+               ┌──────────────────────────┐
+               │    Channel Subscriber    │
+               └──────────────────────────┘
+```
+
+1. **Anonymous Connection:** An unauthenticated connection state (`CONNECTING` / `AUTHENTICATING`). Can only send initial credentials or heartbeat ping/pong frames; cannot subscribe or broadcast.
+2. **Authenticated Principal:** A connection associated with a validated identity (`Principal`). Can hold multiple active connections across devices.
+3. **Channel Subscriber:** An authenticated connection registered to receive events for specific logical channels (e.g. `orders:123`, `user:456`).
+4. **Message Publisher:** An actor (consuming application or authorized client) permitted by `Authorizer` to push events to target connections or channels.
+5. **Gateway Cluster Instance:** An individual node in a scaled gateway deployment communicating cross-instance events via a shared message broker topic.
+
+---
+
+## Principal Identity Contract
+
+The gateway MUST NOT depend on any consuming application's User model, database schema, or auth framework. 
+
+Identity is represented by an immutable domain model:
+
+```python
+@dataclass(frozen=True)
+class Principal:
+    id: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+```
+
+- **`id`**: Unique string identifier representing the user, device, or service.
+- **`metadata`**: Immutable mapping holding tenant IDs, roles, scopes, or claims required by downstream authorizers.
+
+---
+
+## Consequences
+
+### Positive
+- **Decoupled User Model:** The gateway operates seamlessly with any user system (SQL databases, Auth0, Firebase, custom microservices).
+- **Strict Role Boundaries:** Clear separation between connection-level state and authenticated principal identity.
+- **Multi-Device Support:** A single `Principal` can own multiple concurrent connections (`for_user(user_id)` mapping).
+
+### Negative / Trade-offs
+- Downstream applications must map their internal user objects to the gateway's `Principal` during authentication.