bytegate 0.0.0__py3-none-any.whl

bytegate/__init__.py

@@ -0,0 +1,30 @@
+"""
+bytegate - Redis-backed WebSocket Gateway
+
+A transparent transport layer that relays bytes between API consumers
+and remote WebSocket-connected systems via Redis pub/sub.
+
+The gateway does NOT inspect message payloads - it simply moves bytes.
+"""
+
+from bytegate._version import version as __version__
+from bytegate.client import GatewayClient
+from bytegate.errors import BytegateError, ConnectionNotFound, GatewayTimeout
+from bytegate.models import GatewayEnvelope, GatewayResponse
+from bytegate.server import GatewayServer
+
+__all__ = [
+    # Version
+    "__version__",
+    # Client
+    "GatewayClient",
+    # Server
+    "GatewayServer",
+    # Models
+    "GatewayEnvelope",
+    "GatewayResponse",
+    # Errors
+    "BytegateError",
+    "ConnectionNotFound",
+    "GatewayTimeout",
+]

bytegate/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.0'
+__version_tuple__ = version_tuple = (0, 0, 0)
+
+__commit_id__ = commit_id = None

bytegate/client.py

@@ -0,0 +1,108 @@
+"""
+Bytegate Client
+
+Sends messages to remote systems via Redis pub/sub.
+The client is completely content-agnostic - it just moves bytes.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+from bytegate.errors import ConnectionNotFound, GatewayTimeout
+from bytegate.models import GatewayEnvelope, GatewayResponse
+
+LOG = logging.getLogger(__name__)
+
+# Redis key patterns
+CONNECTIONS_KEY = "bytegate:connections"
+REQUEST_CHANNEL_PATTERN = "bytegate:{connection_id}:request"
+RESPONSE_KEY_PATTERN = "bytegate:response:{request_id}"
+
+# Default timeout for waiting on responses
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+class GatewayClient:
+    """
+    Client for sending messages through the Redis gateway.
+
+    Usage:
+        client = GatewayClient(redis)
+        response = await client.send("my-connection-id", b'{"method": "ping"}')
+    """
+
+    def __init__(self, redis: "Redis") -> None:
+        self._redis = redis
+
+    async def is_connected(self, connection_id: str) -> bool:
+        """Check if a connection is registered in the gateway."""
+        result = await self._redis.hexists(CONNECTIONS_KEY, connection_id)  # type: ignore[misc]
+        return bool(result)
+
+    async def send(
+        self,
+        connection_id: str,
+        payload: bytes,
+        *,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> GatewayResponse:
+        """
+        Send a message to a remote system and wait for a response.
+
+        Args:
+            connection_id: Identifier for the remote connection
+            payload: Message payload as bytes (opaque - not inspected)
+            timeout: Maximum time to wait for response
+
+        Returns:
+            GatewayResponse containing the response payload
+
+        Raises:
+            ConnectionNotFound: If the connection is not registered
+            GatewayTimeout: If no response is received within timeout
+        """
+        if not await self.is_connected(connection_id):
+            raise ConnectionNotFound(connection_id)
+
+        envelope = GatewayEnvelope(connection_id=connection_id, payload=payload)
+        request_id = envelope.request_id
+
+        LOG.debug("Sending request %s to connection %s", request_id, connection_id)
+
+        channel = REQUEST_CHANNEL_PATTERN.format(connection_id=connection_id)
+        await self._redis.publish(channel, envelope.model_dump_json())
+
+        response_key = RESPONSE_KEY_PATTERN.format(request_id=request_id)
+        result = await self._redis.blpop([response_key], timeout=timeout)  # type: ignore[misc]
+
+        if result is None:
+            LOG.warning("Timeout waiting for response to request %s", request_id)
+            raise GatewayTimeout(connection_id, timeout)
+
+        _, response_data = result
+        response = GatewayResponse.model_validate_json(response_data)
+
+        LOG.debug("Received response for request %s", request_id)
+        return response
+
+    async def send_no_wait(self, connection_id: str, payload: bytes) -> str:
+        """
+        Send a message without waiting for a response.
+
+        Returns the request_id for tracking purposes.
+
+        Raises:
+            ConnectionNotFound: If the connection is not registered
+        """
+        if not await self.is_connected(connection_id):
+            raise ConnectionNotFound(connection_id)
+
+        envelope = GatewayEnvelope(connection_id=connection_id, payload=payload)
+
+        channel = REQUEST_CHANNEL_PATTERN.format(connection_id=envelope.connection_id)
+        await self._redis.publish(channel, envelope.model_dump_json())
+
+        return envelope.request_id

bytegate/errors.py

@@ -0,0 +1,26 @@
+"""
+Bytegate errors.
+
+Simple hierarchy: one base class, minimal specific exceptions.
+"""
+
+
+class BytegateError(Exception):
+    """Base exception for all bytegate errors."""
+
+
+class ConnectionNotFound(BytegateError):
+    """The requested connection is not registered in the gateway."""
+
+    def __init__(self, connection_id: str) -> None:
+        self.connection_id = connection_id
+        super().__init__(f"Connection not found: {connection_id}")
+
+
+class GatewayTimeout(BytegateError):
+    """Timed out waiting for a response from the remote system."""
+
+    def __init__(self, connection_id: str, timeout: float) -> None:
+        self.connection_id = connection_id
+        self.timeout = timeout
+        super().__init__(f"Timeout after {timeout}s waiting for response from: {connection_id}")

bytegate/models.py

@@ -0,0 +1,68 @@
+"""
+Bytegate message models.
+
+These models define the envelope format for gateway messages.
+The `payload` field is raw bytes - the gateway does not inspect it.
+"""
+
+from base64 import b64decode, b64encode
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+
+def _generate_request_id() -> str:
+    return uuid4().hex
+
+
+class GatewayEnvelope(BaseModel):
+    """
+    Envelope for messages sent through the gateway.
+
+    The gateway only inspects the envelope metadata (request_id, connection_id).
+    The payload is passed through as-is without inspection or validation.
+
+    When serialized to JSON, payload bytes are base64-encoded.
+    """
+
+    request_id: str = Field(default_factory=_generate_request_id)
+    connection_id: str
+    payload: bytes  # Opaque - the gateway does not inspect this
+
+    @field_serializer("payload")
+    def serialize_payload(self, value: bytes) -> str:
+        """Encode bytes as base64 for JSON serialization."""
+        return b64encode(value).decode("ascii")
+
+    @field_validator("payload", mode="before")
+    @classmethod
+    def deserialize_payload(cls, value: str | bytes) -> bytes:
+        """Decode base64 string back to bytes during parsing."""
+        if isinstance(value, bytes):
+            return value
+        return b64decode(value)
+
+
+class GatewayResponse(BaseModel):
+    """
+    Response envelope returned through the gateway.
+
+    Like the request envelope, the payload is opaque bytes.
+    """
+
+    request_id: str
+    payload: bytes  # Opaque - the gateway does not inspect this
+    error: str | None = None  # Set if the remote system returned an error
+
+    @field_serializer("payload")
+    def serialize_payload(self, value: bytes) -> str:
+        """Encode bytes as base64 for JSON serialization."""
+        return b64encode(value).decode("ascii")
+
+    @field_validator("payload", mode="before")
+    @classmethod
+    def deserialize_payload(cls, value: str | bytes) -> bytes:
+        """Decode base64 string back to bytes during parsing."""
+        if isinstance(value, bytes):
+            return value
+        return b64decode(value)

bytegate/router.py

@@ -0,0 +1,191 @@
+"""
+FastAPI Router for Bytegate WebSocket Endpoint
+
+Provides a WebSocket endpoint for remote systems to connect to the gateway.
+All payloads are raw bytes - the gateway does not inspect content.
+"""
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+from pydantic import ValidationError
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis  # noqa: F401
+
+from bytegate.models import GatewayEnvelope, GatewayResponse
+
+LOG = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/bytegate", tags=["bytegate"])
+
+# Redis key patterns (must match client.py and server.py)
+CONNECTIONS_KEY = "bytegate:connections"
+REQUEST_CHANNEL_PATTERN = "bytegate:{connection_id}:request"
+RESPONSE_KEY_PATTERN = "bytegate:response:{request_id}"
+RESPONSE_KEY_TTL_SECONDS = 60
+HEARTBEAT_INTERVAL_SECONDS = 10
+
+
+@router.websocket("/{connection_id}")
+async def bytegate_websocket(websocket: WebSocket, connection_id: str) -> None:
+    """
+    WebSocket endpoint for remote system connections.
+
+    The connection_id should be a unique identifier for the remote system.
+    All messages are passed through as raw bytes - the gateway does not
+    inspect or validate payloads.
+    """
+    await websocket.accept()
+    LOG.info("New bytegate connection: %s", connection_id)
+
+    redis: Redis = websocket.app.extra["redis"]
+    server_id: str = websocket.app.extra.get("server_id", "unknown")
+
+    try:
+        async with _connection_lifecycle(redis, connection_id, server_id):
+            await _run_connection(websocket, redis, connection_id)
+    except WebSocketDisconnect:
+        LOG.info("Bytegate connection disconnected: %s", connection_id)
+    except Exception:
+        LOG.exception("Error in bytegate connection: %s", connection_id)
+
+
+@asynccontextmanager
+async def _connection_lifecycle(
+    redis: "Redis",
+    connection_id: str,
+    server_id: str,
+) -> AsyncIterator[None]:
+    """Register/unregister connection in Redis with heartbeat."""
+    await redis.hset(CONNECTIONS_KEY, connection_id, server_id)  # type: ignore[misc]
+    LOG.info("Registered connection %s on server %s", connection_id, server_id)
+
+    heartbeat_task = asyncio.create_task(_heartbeat(redis, connection_id, server_id))
+
+    try:
+        yield
+    finally:
+        heartbeat_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await heartbeat_task
+
+        await redis.hdel(CONNECTIONS_KEY, connection_id)  # type: ignore[misc]
+        LOG.info("Unregistered connection %s", connection_id)
+
+
+async def _heartbeat(
+    redis: "Redis",
+    connection_id: str,
+    server_id: str,
+) -> None:
+    """Periodically refresh connection registration."""
+    while True:
+        await asyncio.sleep(HEARTBEAT_INTERVAL_SECONDS)
+        await redis.hset(CONNECTIONS_KEY, connection_id, server_id)  # type: ignore[misc]
+
+
+async def _run_connection(
+    websocket: WebSocket,
+    redis: "Redis",
+    connection_id: str,
+) -> None:
+    """Main connection loop: bridge Redis pub/sub with WebSocket."""
+    pending_requests: dict[str, asyncio.Future[bytes]] = {}
+
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(_redis_to_websocket(websocket, redis, connection_id, pending_requests))
+        tg.create_task(_websocket_to_redis(websocket, pending_requests))
+
+
+async def _redis_to_websocket(
+    websocket: WebSocket,
+    redis: "Redis",
+    connection_id: str,
+    pending_requests: dict[str, asyncio.Future[bytes]],
+) -> None:
+    """Subscribe to Redis and forward requests to WebSocket."""
+    channel_name = REQUEST_CHANNEL_PATTERN.format(connection_id=connection_id)
+    pubsub = redis.pubsub()
+
+    try:
+        await pubsub.subscribe(channel_name)
+        LOG.debug("Subscribed to channel %s", channel_name)
+
+        async for message in pubsub.listen():
+            if message["type"] != "message":
+                continue
+
+            await _handle_redis_message(websocket, redis, message["data"], pending_requests)
+    finally:
+        await pubsub.unsubscribe(channel_name)
+        await pubsub.close()
+
+
+async def _handle_redis_message(
+    websocket: WebSocket,
+    redis: "Redis",
+    data: bytes | str,
+    pending_requests: dict[str, asyncio.Future[bytes]],
+) -> None:
+    """Process a request from Redis, forward to WebSocket, wait for response."""
+    try:
+        if isinstance(data, bytes):
+            data = data.decode("utf-8")
+
+        envelope = GatewayEnvelope.model_validate_json(data)
+        request_id = envelope.request_id
+
+        LOG.debug("Forwarding request %s to WebSocket", request_id)
+
+        # Track this request
+        response_future: asyncio.Future[bytes] = asyncio.get_running_loop().create_future()
+        pending_requests[request_id] = response_future
+
+        # Forward payload to WebSocket (transparent - raw bytes)
+        await websocket.send_bytes(envelope.payload)
+
+        # Wait for response
+        try:
+            response_payload = await asyncio.wait_for(response_future, timeout=30.0)
+            response = GatewayResponse(request_id=request_id, payload=response_payload)
+        except TimeoutError:
+            response = GatewayResponse(
+                request_id=request_id,
+                payload=b"",
+                error="Timeout waiting for WebSocket response",
+            )
+        finally:
+            pending_requests.pop(request_id, None)
+
+        # Publish response to Redis
+        response_key = RESPONSE_KEY_PATTERN.format(request_id=request_id)
+        await redis.lpush(response_key, response.model_dump_json())  # type: ignore[misc]
+        await redis.expire(response_key, RESPONSE_KEY_TTL_SECONDS)
+
+    except ValidationError:
+        LOG.exception("Invalid message format from Redis")
+    except Exception:
+        LOG.exception("Error handling Redis message")
+
+
+async def _websocket_to_redis(
+    websocket: WebSocket,
+    pending_requests: dict[str, asyncio.Future[bytes]],
+) -> None:
+    """Receive messages from WebSocket and resolve pending requests."""
+    while True:
+        # Receive as bytes
+        message = await websocket.receive_bytes()
+
+        # Match response to oldest pending request (FIFO order)
+        if pending_requests:
+            request_id = next(iter(pending_requests))
+            future = pending_requests.get(request_id)
+            if future and not future.done():
+                future.set_result(message)

bytegate/server.py

@@ -0,0 +1,210 @@
+"""
+Bytegate Server
+
+Manages WebSocket connections from remote systems and bridges them with Redis.
+The server is completely content-agnostic - it just moves bytes.
+
+This module provides a standalone server for use outside of FastAPI.
+For FastAPI integration, use the router module instead.
+"""
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+    from websockets.asyncio.server import ServerConnection
+
+from bytegate.models import GatewayEnvelope, GatewayResponse
+
+LOG = logging.getLogger(__name__)
+
+# Redis key patterns (must match client.py)
+CONNECTIONS_KEY = "bytegate:connections"
+REQUEST_CHANNEL_PATTERN = "bytegate:{connection_id}:request"
+RESPONSE_KEY_PATTERN = "bytegate:response:{request_id}"
+RESPONSE_KEY_TTL_SECONDS = 60
+HEARTBEAT_INTERVAL_SECONDS = 10
+
+
+class GatewayServer:
+    """
+    Gateway server for bridging WebSocket connections with Redis.
+
+    This class manages multiple WebSocket connections and handles the
+    Redis pub/sub communication for each.
+
+    Usage:
+        server = GatewayServer(redis, server_id="pod-1")
+        await server.handle_connection(connection_id, websocket)
+    """
+
+    def __init__(
+        self,
+        redis: "Redis",
+        server_id: str,
+        *,
+        on_connect: Callable[[str], Awaitable[None]] | None = None,
+        on_disconnect: Callable[[str], Awaitable[None]] | None = None,
+    ) -> None:
+        self._redis = redis
+        self._server_id = server_id
+        self._active_connections: set[str] = set()
+        self._on_connect = on_connect
+        self._on_disconnect = on_disconnect
+
+    @property
+    def server_id(self) -> str:
+        return self._server_id
+
+    @property
+    def active_connections(self) -> list[str]:
+        """List of currently active connection IDs."""
+        return list(self._active_connections)
+
+    async def handle_connection(
+        self,
+        connection_id: str,
+        websocket: "ServerConnection",
+    ) -> None:
+        """
+        Handle a WebSocket connection lifecycle.
+
+        This method blocks until the connection closes.
+        """
+        self._active_connections.add(connection_id)
+
+        try:
+            await self._register(connection_id)
+
+            if self._on_connect:
+                await self._on_connect(connection_id)
+
+            await self._run_connection(connection_id, websocket)
+
+        finally:
+            await self._unregister(connection_id)
+            self._active_connections.discard(connection_id)
+
+            if self._on_disconnect:
+                await self._on_disconnect(connection_id)
+
+    async def _register(self, connection_id: str) -> None:
+        """Register connection in Redis."""
+        await self._redis.hset(CONNECTIONS_KEY, connection_id, self._server_id)  # type: ignore[misc]
+        LOG.info("Registered connection %s on server %s", connection_id, self._server_id)
+
+    async def _unregister(self, connection_id: str) -> None:
+        """Remove connection from Redis."""
+        await self._redis.hdel(CONNECTIONS_KEY, connection_id)  # type: ignore[misc]
+        LOG.info("Unregistered connection %s", connection_id)
+
+    async def _run_connection(
+        self,
+        connection_id: str,
+        websocket: "ServerConnection",
+    ) -> None:
+        """Main loop: bridge Redis pub/sub with WebSocket."""
+        pending_requests: dict[str, asyncio.Future[bytes]] = {}
+
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(self._heartbeat(connection_id))
+            tg.create_task(self._redis_to_websocket(connection_id, websocket, pending_requests))
+            tg.create_task(self._websocket_to_redis(websocket, pending_requests))
+
+    async def _heartbeat(self, connection_id: str) -> None:
+        """Periodically refresh connection registration."""
+        while True:
+            await asyncio.sleep(HEARTBEAT_INTERVAL_SECONDS)
+            await self._redis.hset(CONNECTIONS_KEY, connection_id, self._server_id)  # type: ignore[misc]
+
+    async def _redis_to_websocket(
+        self,
+        connection_id: str,
+        websocket: "ServerConnection",
+        pending_requests: dict[str, asyncio.Future[bytes]],
+    ) -> None:
+        """Subscribe to Redis and forward requests to WebSocket."""
+        channel_name = REQUEST_CHANNEL_PATTERN.format(connection_id=connection_id)
+        pubsub = self._redis.pubsub()
+
+        try:
+            await pubsub.subscribe(channel_name)
+            LOG.debug("Subscribed to channel %s", channel_name)
+
+            async for message in pubsub.listen():
+                if message["type"] != "message":
+                    continue
+
+                await self._handle_redis_message(websocket, message["data"], pending_requests)
+        finally:
+            await pubsub.unsubscribe(channel_name)
+            await pubsub.close()
+
+    async def _handle_redis_message(
+        self,
+        websocket: "ServerConnection",
+        data: bytes | str,
+        pending_requests: dict[str, asyncio.Future[bytes]],
+    ) -> None:
+        """Process a request from Redis, forward to WebSocket, wait for response."""
+        try:
+            if isinstance(data, bytes):
+                data = data.decode("utf-8")
+
+            envelope = GatewayEnvelope.model_validate_json(data)
+            request_id = envelope.request_id
+
+            LOG.debug("Forwarding request %s to WebSocket", request_id)
+
+            # Track this request
+            response_future: asyncio.Future[bytes] = asyncio.get_running_loop().create_future()
+            pending_requests[request_id] = response_future
+
+            # Forward payload to WebSocket (transparent - raw bytes)
+            await websocket.send(envelope.payload)
+
+            # Wait for response
+            try:
+                response_payload = await asyncio.wait_for(response_future, timeout=30.0)
+                response = GatewayResponse(request_id=request_id, payload=response_payload)
+            except TimeoutError:
+                response = GatewayResponse(
+                    request_id=request_id,
+                    payload=b"",
+                    error="Timeout waiting for WebSocket response",
+                )
+            finally:
+                pending_requests.pop(request_id, None)
+
+            # Publish response to Redis
+            response_key = RESPONSE_KEY_PATTERN.format(request_id=request_id)
+            await self._redis.lpush(response_key, response.model_dump_json())  # type: ignore[misc]
+            await self._redis.expire(response_key, RESPONSE_KEY_TTL_SECONDS)
+
+        except Exception:
+            LOG.exception("Error handling Redis message")
+
+    async def _websocket_to_redis(
+        self,
+        websocket: "ServerConnection",
+        pending_requests: dict[str, asyncio.Future[bytes]],
+    ) -> None:
+        """Receive messages from WebSocket and resolve pending requests."""
+        async for message in websocket:
+            # Ensure we have bytes
+            if isinstance(message, str):
+                message = message.encode("utf-8")
+
+            # Match response to oldest pending request (FIFO order)
+            if pending_requests:
+                request_id = next(iter(pending_requests))
+                future = pending_requests.get(request_id)
+                if future and not future.done():
+                    future.set_result(message)
+
+    async def shutdown(self) -> None:
+        """Gracefully shutdown the server."""
+        LOG.info("Shutting down bytegate server %s", self._server_id)

bytegate-0.0.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: bytegate
+Version: 0.0.0
+Summary: A transparent Redis-backed WebSocket gateway that relays bytes between distributed systems.
+Author: Jan Bjørge
+License: MIT
+Project-URL: Homepage, https://github.com/janbjorge/bytegate
+Project-URL: Repository, https://github.com/janbjorge/bytegate
+Project-URL: Documentation, https://github.com/janbjorge/bytegate#readme
+Project-URL: Issues, https://github.com/janbjorge/bytegate/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redis>=5.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# bytegate
+
+A transparent Redis-backed WebSocket gateway that relays bytes between distributed systems.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/bytegate)](https://pypi.org/project/bytegate/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bytegate)](https://pypi.org/project/bytegate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is bytegate?
+
+Bytegate is a **transparent transport layer** that connects WebSocket clients to your backend services through Redis pub/sub. It acts as a relay - it doesn't inspect, validate, or transform your data. It just moves bytes.
+
+```
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│  Remote System  │◄──WS───►│    Bytegate     │◄─Redis─►│   Your API      │
+│  (WebSocket)    │         │    Server       │         │   (Client)      │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+```
+
+### Why bytegate?
+
+- **Transparent**: Payloads are raw bytes - encode/decode however you want
+- **Simple**: One concept (connection_id), two components (client/server)
+- **Scalable**: Multiple API pods can send to any connected WebSocket via Redis
+- **Async-native**: Built on `asyncio`, `redis-py`, and `websockets`
+- **Framework-friendly**: FastAPI router included, or use standalone
+
+## Installation
+
+```bash
+pip install bytegate
+
+# With FastAPI support
+pip install bytegate[fastapi]
+```
+
+## Quick Start
+
+### Server Side (WebSocket Handler)
+
+The server accepts WebSocket connections and bridges them with Redis:
+
+```python
+from fastapi import FastAPI
+from redis import asyncio as aioredis
+
+from bytegate import router
+
+app = FastAPI()
+app.include_router(router)
+
+@app.on_event("startup")
+async def startup():
+    app.extra["redis"] = aioredis.from_url("redis://localhost")
+    app.extra["server_id"] = "pod-1"  # Unique identifier for this server
+```
+
+Remote systems connect via WebSocket to `/bytegate/{connection_id}`.
+
+### Client Side (Send Messages)
+
+Any service can send messages to connected WebSocket clients:
+
+```python
+from redis import asyncio as aioredis
+from bytegate import GatewayClient
+
+redis = aioredis.from_url("redis://localhost")
+client = GatewayClient(redis)
+
+# Check if a connection exists
+if await client.is_connected("device-123"):
+    # Send bytes and wait for response
+    response = await client.send("device-123", b'{"command": "ping"}')
+    print(response.payload)  # Raw bytes from the remote system
+
+# Fire-and-forget (no response)
+request_id = await client.send_no_wait("device-123", b"heartbeat")
+```
+
+## Architecture
+
+### How It Works
+
+1. **Remote system connects** via WebSocket → Server registers `connection_id` in Redis
+2. **API sends message** → Client publishes to Redis channel `bytegate:{connection_id}:request`
+3. **Server receives** → Forwards payload bytes to WebSocket, waits for response
+4. **Response flows back** → Server publishes to Redis list `bytegate:response:{request_id}`
+5. **API receives response** → Client returns the bytes to caller
+
+### Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Bytes-only payload** | You decide encoding. JSON? Protobuf? MessagePack? Your choice. |
+| **FIFO response matching** | Simple request-response pattern. One request, one response. |
+| **Redis pub/sub + lists** | Pub/sub for fan-out, lists for reliable response delivery. |
+| **Heartbeat registration** | Connections re-register every 10s. Stale entries auto-expire. |
+
+## API Reference
+
+### `GatewayClient`
+
+```python
+client = GatewayClient(redis: aioredis.Redis)
+
+# Check connection status
+await client.is_connected(connection_id: str) -> bool
+
+# Send and wait for response
+await client.send(
+    connection_id: str,
+    payload: bytes,
+    timeout: float = 30.0
+) -> GatewayResponse
+
+# Send without waiting
+await client.send_no_wait(
+    connection_id: str,
+    payload: bytes
+) -> str  # Returns request_id
+```
+
+### `GatewayServer` (Standalone)
+
+For non-FastAPI usage:
+
+```python
+from bytegate import GatewayServer
+
+server = GatewayServer(
+    redis=redis,
+    server_id="my-server",
+    on_connect=async_callback,    # Optional
+    on_disconnect=async_callback  # Optional
+)
+
+# Handle a websocket connection (blocks until disconnect)
+await server.handle_connection(connection_id, websocket)
+```
+
+### Models
+
+```python
+from bytegate import GatewayEnvelope, GatewayResponse
+
+# Request envelope (internal, but useful for testing)
+envelope = GatewayEnvelope(
+    connection_id="device-123",
+    payload=b"raw bytes here"
+)
+# request_id is auto-generated
+
+# Response from remote system
+response = GatewayResponse(
+    request_id="abc123",
+    payload=b"response bytes",
+    error=None  # Or error message string
+)
+```
+
+### Errors
+
+```python
+from bytegate import BytegateError, ConnectionNotFound, GatewayTimeout
+
+try:
+    response = await client.send("device-123", b"data")
+except ConnectionNotFound as e:
+    print(f"Device {e.connection_id} not connected")
+except GatewayTimeout as e:
+    print(f"Timeout after {e.timeout}s waiting for {e.connection_id}")
+except BytegateError:
+    print("Other bytegate error")
+```
+
+## Redis Keys
+
+| Key Pattern | Type | Purpose |
+|-------------|------|---------|
+| `bytegate:connections` | Hash | Maps `connection_id` → `server_id` |
+| `bytegate:{connection_id}:request` | Pub/Sub | Channel for incoming requests |
+| `bytegate:response:{request_id}` | List | Response queue (TTL: 60s) |
+
+## Requirements
+
+- Python 3.11+
+- Redis 5.0+ (for streams/pub-sub)
+- `redis[hiredis]` (recommended for performance)
+- `pydantic` 2.0+
+- `websockets` 12.0+
+- `fastapi` 0.100+ (optional, for router)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

bytegate-0.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+bytegate/__init__.py,sha256=DeM9zoT0Ec6Ul3Kf6wD8GXT0bV-2tncIlADREmRCUrY,785
+bytegate/_version.py,sha256=ZUZqmAVZt0gh0Pbj4cYM1PmY1fBwaR8CjTz4JqhQ7Us,704
+bytegate/client.py,sha256=RTCQlrMisQF5BPKCdb3qrghMa3Ia20wqQzO5unAmyXI,3603
+bytegate/errors.py,sha256=Wt0TwdSqbf8o1so5deWf7FTQ6jo8kx8f-VFwTlTFO7s,794
+bytegate/models.py,sha256=0An3CSKvotIDQ2Tt22umqNcyucfODUVRUW1f_z50HEM,2135
+bytegate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bytegate/router.py,sha256=mBZwMU1I6Nbn1NHotnnq0E9dLffHrTRWYysjW_15lMA,6505
+bytegate/server.py,sha256=5l83VVKv-99v1UiEa0RFApnNi_v9Gr0aFNivCr1Utqw,7569
+bytegate-0.0.0.dist-info/licenses/LICENSE,sha256=NAfva4Mdl-fLh0bACrfC-Q10C2mD0J5tlJw0kpv9z8k,1068
+bytegate-0.0.0.dist-info/METADATA,sha256=YowSw3j2tLrxZ2_0yvw2BXvSSeG-2y95cO4KTl3O_7w,7795
+bytegate-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bytegate-0.0.0.dist-info/top_level.txt,sha256=qSElWNN7Sxnn4GCwDCwLL0EveOCvW7W-iHvyma9aoNI,9
+bytegate-0.0.0.dist-info/RECORD,,

bytegate-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bytegate-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jan Bjørge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 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,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bytegate-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bytegate