Metadata-Version: 2.5
Name: realtime-gateway
Version: 0.1.1
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).
