ws-scale 0.1.0__tar.gz

ws_scale-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.

ws_scale-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ws-scale
+Version: 0.1.0
+Summary: A websocket server application
+Project-URL: Homepage, https://github.com/stevinho29/ws-scale
+Project-URL: Issues, https://github.com/stevinho29/ws-scale/issues
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.14.1
+Requires-Dist: redis>=8.0.1
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
+# ws-scale
+
+A Python library for building scalable WebSocket servers with distributed Snowflake-style ID generation. Each WebSocket node registers with a central master, receives a unique node ID, and generates collision-free 64-bit IDs across the cluster using Redis for coordination.
+
+## Architecture
+
+```
+┌─────────────────────────┐
+│   IDGeneratorMaster     │  HTTP :9000
+│  (aiohttp, one per DC)  │◄──── register / heartbeat
+└────────────┬────────────┘
+             │ Redis :6379
+┌────────────▼────────────┐        ┌──────────────────────────┐
+│   WebsocketServer #1    │        │   WebsocketServer #2     │
+│  + IDGeneratorNode      │        │  + IDGeneratorNode       │
+│  (websockets, :8080)    │        │  (websockets, :8081)     │
+└─────────────────────────┘        └──────────────────────────┘
+```
+
+- **IDGeneratorMaster** — HTTP server that allocates node IDs and evicts stale nodes (no heartbeat in 2 min). Supports up to 32 nodes per datacenter.
+- **IDGeneratorNode** — Registers with the master on startup, sends heartbeats every 60 s, and generates Snowflake IDs (41-bit timestamp | 5-bit datacenter | 5-bit node | 12-bit sequence).
+- **WebsocketServer** — Wraps `websockets.serve`, bootstraps an `IDGeneratorNode`, and routes connections to a user-supplied async handler.
+
+## Requirements
+
+- Python 3.13+
+- Redis
+
+## Installation
+
+```bash
+pip install ws-scale
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add ws-scale
+```
+
+## Configuration
+
+Settings can be provided via a Python module or environment variables.
+
+| Setting | Default | Description |
+|---|---|---|
+| `WS_REDIS_HOST` | `localhost` | Redis hostname |
+| `WS_REDIS_PORT` | `6379` | Redis port |
+| `WS_MASTER_HOST` | `http://0.0.0.0` | ID master hostname |
+| `WS_MASTER_PORT` | `9000` | ID master port |
+
+**Via settings module** (`settings.py`):
+
+```python
+WS_REDIS_HOST = "localhost"
+WS_REDIS_PORT = 6379
+
+WS_MASTER_HOST = "http://0.0.0.0"
+WS_MASTER_PORT = 9000
+```
+
+**Via environment variables** (pass `settings_path=None`):
+
+```bash
+export WS_REDIS_HOST=localhost
+export WS_REDIS_PORT=6379
+export WS_MASTER_HOST=http://0.0.0.0
+export WS_MASTER_PORT=9000
+```
+
+## Quick Start
+
+```python
+import asyncio
+from wsscale import IDGeneratorMaster, WebsocketServer
+
+async def handle(conn):
+    async for message in conn:
+        await conn.send(f"echo: {message}")
+
+async def main():
+    master = IDGeneratorMaster(datacenter_id=0, settings_path="settings")
+    server = WebsocketServer(datacenter_id=0, port=8080, settings_path="settings")
+
+    await master.cleanup()   # clear stale Redis state on fresh start
+    await master.serve()     # start HTTP master on WS_MASTER_PORT
+    await server.bootstrap(handler=handle)  # register node, start heartbeat, serve WS
+
+asyncio.run(main())
+```
+
+Run the bundled example from the command line:
+
+```bash
+python src/example.py --port 8080 --datacenter 0 --generator True
+```
+
+## API Reference
+
+### `WebsocketServer(datacenter_id, port, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `int` | 5-bit datacenter identifier (0–31) |
+| `port` | `int` | TCP port for the WebSocket server |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await bootstrap(handler)`** — Registers the ID node, starts the heartbeat loop, and runs the WebSocket server.
+
+---
+
+### `IDGeneratorMaster(datacenter_id, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `str` | Logical datacenter identifier |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await serve()`** — Starts the aiohttp HTTP server exposing `POST /register` and `POST /heartbeat`.  
+**`await cleanup()`** — Removes all node entries from Redis (call before `serve()` on a fresh start).  
+**`await monitor_nodes()`** — Evicts nodes that have missed heartbeats for more than 2 minutes.
+
+---
+
+### `IDGeneratorNode(server_host, server_port, data_center_id, redis_host, redis_port)`
+
+Typically instantiated automatically by `WebsocketServer`, but can be used standalone.
+
+**`await generate_id(datacenter_id, node_id) → int`** — Returns a 64-bit Snowflake-style unique ID.  
+**`await register()`** — Contacts the master and obtains a `node_id`.  
+**`await heart_beat_loop(interval_seconds)`** — Sends periodic heartbeats to the master forever.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ws_scale-0.1.0/README.md

@@ -0,0 +1,135 @@
+# ws-scale
+
+A Python library for building scalable WebSocket servers with distributed Snowflake-style ID generation. Each WebSocket node registers with a central master, receives a unique node ID, and generates collision-free 64-bit IDs across the cluster using Redis for coordination.
+
+## Architecture
+
+```
+┌─────────────────────────┐
+│   IDGeneratorMaster     │  HTTP :9000
+│  (aiohttp, one per DC)  │◄──── register / heartbeat
+└────────────┬────────────┘
+             │ Redis :6379
+┌────────────▼────────────┐        ┌──────────────────────────┐
+│   WebsocketServer #1    │        │   WebsocketServer #2     │
+│  + IDGeneratorNode      │        │  + IDGeneratorNode       │
+│  (websockets, :8080)    │        │  (websockets, :8081)     │
+└─────────────────────────┘        └──────────────────────────┘
+```
+
+- **IDGeneratorMaster** — HTTP server that allocates node IDs and evicts stale nodes (no heartbeat in 2 min). Supports up to 32 nodes per datacenter.
+- **IDGeneratorNode** — Registers with the master on startup, sends heartbeats every 60 s, and generates Snowflake IDs (41-bit timestamp | 5-bit datacenter | 5-bit node | 12-bit sequence).
+- **WebsocketServer** — Wraps `websockets.serve`, bootstraps an `IDGeneratorNode`, and routes connections to a user-supplied async handler.
+
+## Requirements
+
+- Python 3.13+
+- Redis
+
+## Installation
+
+```bash
+pip install ws-scale
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add ws-scale
+```
+
+## Configuration
+
+Settings can be provided via a Python module or environment variables.
+
+| Setting | Default | Description |
+|---|---|---|
+| `WS_REDIS_HOST` | `localhost` | Redis hostname |
+| `WS_REDIS_PORT` | `6379` | Redis port |
+| `WS_MASTER_HOST` | `http://0.0.0.0` | ID master hostname |
+| `WS_MASTER_PORT` | `9000` | ID master port |
+
+**Via settings module** (`settings.py`):
+
+```python
+WS_REDIS_HOST = "localhost"
+WS_REDIS_PORT = 6379
+
+WS_MASTER_HOST = "http://0.0.0.0"
+WS_MASTER_PORT = 9000
+```
+
+**Via environment variables** (pass `settings_path=None`):
+
+```bash
+export WS_REDIS_HOST=localhost
+export WS_REDIS_PORT=6379
+export WS_MASTER_HOST=http://0.0.0.0
+export WS_MASTER_PORT=9000
+```
+
+## Quick Start
+
+```python
+import asyncio
+from wsscale import IDGeneratorMaster, WebsocketServer
+
+async def handle(conn):
+    async for message in conn:
+        await conn.send(f"echo: {message}")
+
+async def main():
+    master = IDGeneratorMaster(datacenter_id=0, settings_path="settings")
+    server = WebsocketServer(datacenter_id=0, port=8080, settings_path="settings")
+
+    await master.cleanup()   # clear stale Redis state on fresh start
+    await master.serve()     # start HTTP master on WS_MASTER_PORT
+    await server.bootstrap(handler=handle)  # register node, start heartbeat, serve WS
+
+asyncio.run(main())
+```
+
+Run the bundled example from the command line:
+
+```bash
+python src/example.py --port 8080 --datacenter 0 --generator True
+```
+
+## API Reference
+
+### `WebsocketServer(datacenter_id, port, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `int` | 5-bit datacenter identifier (0–31) |
+| `port` | `int` | TCP port for the WebSocket server |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await bootstrap(handler)`** — Registers the ID node, starts the heartbeat loop, and runs the WebSocket server.
+
+---
+
+### `IDGeneratorMaster(datacenter_id, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `str` | Logical datacenter identifier |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await serve()`** — Starts the aiohttp HTTP server exposing `POST /register` and `POST /heartbeat`.  
+**`await cleanup()`** — Removes all node entries from Redis (call before `serve()` on a fresh start).  
+**`await monitor_nodes()`** — Evicts nodes that have missed heartbeats for more than 2 minutes.
+
+---
+
+### `IDGeneratorNode(server_host, server_port, data_center_id, redis_host, redis_port)`
+
+Typically instantiated automatically by `WebsocketServer`, but can be used standalone.
+
+**`await generate_id(datacenter_id, node_id) → int`** — Returns a 64-bit Snowflake-style unique ID.  
+**`await register()`** — Contacts the master and obtains a `node_id`.  
+**`await heart_beat_loop(interval_seconds)`** — Sends periodic heartbeats to the master forever.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ws_scale-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "ws-scale"
+version = "0.1.0"
+description = "A websocket server application"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "aiohttp>=3.14.1",
+    "redis>=8.0.1",
+    "websockets>=16.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+authors = [
+  { name="Ndemanou steve", email="ndemanousteve@gmail.com" },
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+Homepage = "https://github.com/stevinho29/ws-scale"
+Issues = "https://github.com/stevinho29/ws-scale/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ws_scale-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ws_scale-0.1.0/src/ws_scale.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ws-scale
+Version: 0.1.0
+Summary: A websocket server application
+Project-URL: Homepage, https://github.com/stevinho29/ws-scale
+Project-URL: Issues, https://github.com/stevinho29/ws-scale/issues
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.14.1
+Requires-Dist: redis>=8.0.1
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
+# ws-scale
+
+A Python library for building scalable WebSocket servers with distributed Snowflake-style ID generation. Each WebSocket node registers with a central master, receives a unique node ID, and generates collision-free 64-bit IDs across the cluster using Redis for coordination.
+
+## Architecture
+
+```
+┌─────────────────────────┐
+│   IDGeneratorMaster     │  HTTP :9000
+│  (aiohttp, one per DC)  │◄──── register / heartbeat
+└────────────┬────────────┘
+             │ Redis :6379
+┌────────────▼────────────┐        ┌──────────────────────────┐
+│   WebsocketServer #1    │        │   WebsocketServer #2     │
+│  + IDGeneratorNode      │        │  + IDGeneratorNode       │
+│  (websockets, :8080)    │        │  (websockets, :8081)     │
+└─────────────────────────┘        └──────────────────────────┘
+```
+
+- **IDGeneratorMaster** — HTTP server that allocates node IDs and evicts stale nodes (no heartbeat in 2 min). Supports up to 32 nodes per datacenter.
+- **IDGeneratorNode** — Registers with the master on startup, sends heartbeats every 60 s, and generates Snowflake IDs (41-bit timestamp | 5-bit datacenter | 5-bit node | 12-bit sequence).
+- **WebsocketServer** — Wraps `websockets.serve`, bootstraps an `IDGeneratorNode`, and routes connections to a user-supplied async handler.
+
+## Requirements
+
+- Python 3.13+
+- Redis
+
+## Installation
+
+```bash
+pip install ws-scale
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add ws-scale
+```
+
+## Configuration
+
+Settings can be provided via a Python module or environment variables.
+
+| Setting | Default | Description |
+|---|---|---|
+| `WS_REDIS_HOST` | `localhost` | Redis hostname |
+| `WS_REDIS_PORT` | `6379` | Redis port |
+| `WS_MASTER_HOST` | `http://0.0.0.0` | ID master hostname |
+| `WS_MASTER_PORT` | `9000` | ID master port |
+
+**Via settings module** (`settings.py`):
+
+```python
+WS_REDIS_HOST = "localhost"
+WS_REDIS_PORT = 6379
+
+WS_MASTER_HOST = "http://0.0.0.0"
+WS_MASTER_PORT = 9000
+```
+
+**Via environment variables** (pass `settings_path=None`):
+
+```bash
+export WS_REDIS_HOST=localhost
+export WS_REDIS_PORT=6379
+export WS_MASTER_HOST=http://0.0.0.0
+export WS_MASTER_PORT=9000
+```
+
+## Quick Start
+
+```python
+import asyncio
+from wsscale import IDGeneratorMaster, WebsocketServer
+
+async def handle(conn):
+    async for message in conn:
+        await conn.send(f"echo: {message}")
+
+async def main():
+    master = IDGeneratorMaster(datacenter_id=0, settings_path="settings")
+    server = WebsocketServer(datacenter_id=0, port=8080, settings_path="settings")
+
+    await master.cleanup()   # clear stale Redis state on fresh start
+    await master.serve()     # start HTTP master on WS_MASTER_PORT
+    await server.bootstrap(handler=handle)  # register node, start heartbeat, serve WS
+
+asyncio.run(main())
+```
+
+Run the bundled example from the command line:
+
+```bash
+python src/example.py --port 8080 --datacenter 0 --generator True
+```
+
+## API Reference
+
+### `WebsocketServer(datacenter_id, port, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `int` | 5-bit datacenter identifier (0–31) |
+| `port` | `int` | TCP port for the WebSocket server |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await bootstrap(handler)`** — Registers the ID node, starts the heartbeat loop, and runs the WebSocket server.
+
+---
+
+### `IDGeneratorMaster(datacenter_id, settings_path=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `datacenter_id` | `str` | Logical datacenter identifier |
+| `settings_path` | `str \| None` | Dotted module path to a settings file, or `None` to use env vars |
+
+**`await serve()`** — Starts the aiohttp HTTP server exposing `POST /register` and `POST /heartbeat`.  
+**`await cleanup()`** — Removes all node entries from Redis (call before `serve()` on a fresh start).  
+**`await monitor_nodes()`** — Evicts nodes that have missed heartbeats for more than 2 minutes.
+
+---
+
+### `IDGeneratorNode(server_host, server_port, data_center_id, redis_host, redis_port)`
+
+Typically instantiated automatically by `WebsocketServer`, but can be used standalone.
+
+**`await generate_id(datacenter_id, node_id) → int`** — Returns a 64-bit Snowflake-style unique ID.  
+**`await register()`** — Contacts the master and obtains a `node_id`.  
+**`await heart_beat_loop(interval_seconds)`** — Sends periodic heartbeats to the master forever.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ws_scale-0.1.0/src/ws_scale.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/ws_scale.egg-info/PKG-INFO
+src/ws_scale.egg-info/SOURCES.txt
+src/ws_scale.egg-info/dependency_links.txt
+src/ws_scale.egg-info/requires.txt
+src/ws_scale.egg-info/top_level.txt
+src/wsscale/__init__.py
+src/wsscale/cache/__init__.py
+src/wsscale/cache/redis.py
+src/wsscale/ids/__init__.py
+src/wsscale/ids/master.py
+src/wsscale/ids/node.py
+src/wsscale/ws/__init__.py
+src/wsscale/ws/server.py

ws_scale-0.1.0/src/ws_scale.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ws_scale-0.1.0/src/ws_scale.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp>=3.14.1
+redis>=8.0.1
+websockets>=16.0

ws_scale-0.1.0/src/ws_scale.egg-info/top_level.txt

@@ -0,0 +1 @@
+wsscale

ws_scale-0.1.0/src/wsscale/__init__.py

@@ -0,0 +1,5 @@
+from wsscale.ids.master import IDGeneratorMaster
+from wsscale.ids.node import IDGeneratorNode
+from wsscale.ws.server import WebsocketServer
+
+__all__ = [IDGeneratorNode, IDGeneratorMaster, WebsocketServer]

ws_scale-0.1.0/src/wsscale/cache/redis.py

@@ -0,0 +1,21 @@
+import redis.asyncio as redis
+from redis import Redis
+
+class RedisInstance:
+    """Manages a single async Redis client connection."""
+
+    def __init__(self, redis_host:str, redis_port:int):
+        """
+        Args:
+            redis_host: Hostname or IP address of the Redis server.
+            redis_port: Port number the Redis server is listening on.
+        """
+        self.client:Redis = redis.Redis(host=redis_host, port=redis_port)
+
+    def get_instance(self):
+        """Return the underlying async Redis client."""
+        return self.client
+
+    async def __del__(self):
+        """Close the Redis connection when the instance is garbage-collected."""
+        await self.client.aclose()

ws_scale-0.1.0/src/wsscale/ids/master.py

@@ -0,0 +1,201 @@
+from datetime import datetime, timezone
+from typing import Optional
+from aiohttp import web
+from importlib import import_module
+import os
+import json
+import logging
+
+from wsscale.cache.redis import RedisInstance
+logger = logging.getLogger("ws-scale.ids.master")
+
+
+class IDGeneratorMaster:
+    """
+    HTTP server that manages node registration and liveness for distributed Snowflake ID generation.
+
+    Nodes register themselves to receive a unique node ID, then send periodic heartbeats.
+    Nodes that miss heartbeats for more than two minutes are evicted via ``monitor_nodes``.
+    """
+
+    MAX_NODES = 32
+
+    def __init__(self, datacenter_id: str, settings_path:str=None):
+        """
+        Args:
+            datacenter_id: Logical datacenter identifier for this master instance.
+            settings_path: Dotted module path to a settings file (e.g. ``"app.settings"``).
+                           Falls back to environment variables when omitted.
+        """
+        self.datacenter_id = datacenter_id
+        if settings_path:
+            try:
+                settings = import_module(name=settings_path)
+                redis_host = getattr(settings, "WS_REDIS_HOST")
+                redis_port = getattr(settings, "WS_REDIS_PORT")
+                id_master_host = getattr(settings, "WS_MASTER_HOST")
+                id_master_port = getattr(settings, "WS_MASTER_PORT")
+            except ModuleNotFoundError:
+                logger.error(f"Settings module not found, invalid path {settings_path}")
+                raise
+        else:
+            redis_host = os.environ.get("WS_REDIS_HOST")
+            redis_port = os.environ.get("WS_REDIS_PORT")
+            id_master_host = os.environ.get("WS_MASTER_HOST")
+            id_master_port = os.environ.get("WS_MASTER_PORT")
+
+        self.port = id_master_port
+        self.host = id_master_host
+        self.redis = RedisInstance(redis_host=redis_host, redis_port=redis_port).get_instance()
+        self.log_header = "[IDGeneratorMaster]"
+
+    def _get_now(self) -> float:
+        """Return the current UTC time as a millisecond-precision Unix timestamp."""
+        return datetime.now(tz=timezone.utc).timestamp() * 1000
+
+    async def _generate_node_id(self) -> Optional[int]:
+        """Atomically allocate the next node ID from Redis.
+
+        Returns:
+            The new node ID (1-based), or ``None`` if ``MAX_NODES`` has been reached.
+        """
+        node_key = "node_count"
+        count_bytes = await self.redis.get(node_key)
+        count = int(count_bytes.decode()) if count_bytes else 0
+        if count < self.MAX_NODES:
+            return await self.redis.incr(node_key, 1)
+        return None
+
+    async def _cache_node(self, node_id: int) -> None:
+        """Store a node's initial last-seen timestamp in Redis.
+
+        Args:
+            node_id: The node to cache.
+        """
+        await self.redis.set(name=f"node_{node_id}", value=self._get_now())
+
+    async def _update_node(self, node_id: int, heart_beat: float) -> None:
+        """Overwrite a node's last-seen timestamp with a new heartbeat value.
+
+        Args:
+            node_id: The node whose timestamp should be updated.
+            heart_beat: New timestamp in milliseconds.
+        """
+        await self.redis.set(name=f"node_{node_id}", value=heart_beat)
+
+    async def _delete_nodes(self, node_ids: list[int]) -> None:
+        """Remove one or more nodes from Redis.
+
+        Args:
+            node_ids: List of node IDs to delete. No-op if the list is empty.
+        """
+        if node_ids:
+            await self.redis.delete(*[f"node_{id}" for id in node_ids])
+
+    async def _get_node(self, node_id: int):
+        """Fetch a single node's last-seen timestamp from Redis.
+
+        Args:
+            node_id: The node to look up.
+
+        Returns:
+            The raw bytes value stored in Redis, or ``None`` if the key does not exist.
+        """
+        return await self.redis.get(name=f"node_{node_id}")
+
+    async def _get_nodes(self, node_ids: list[int]):
+        """Fetch last-seen timestamps for multiple nodes in one round-trip.
+
+        Args:
+            node_ids: List of node IDs to look up.
+
+        Returns:
+            A list of raw bytes values (or ``None`` for missing keys), in the same order as ``node_ids``.
+        """
+        return await self.redis.mget([f"node_{id}" for id in node_ids])
+
+    async def register(self, request: web.Request) -> web.Response:
+        """HTTP POST /register — allocate a node ID and cache it.
+
+        Returns:
+            201 with ``{"node_id": <int>}`` on success, or 400 if the node limit is reached.
+        """
+        node_id = await self._generate_node_id()
+        if not node_id:
+            return web.Response(
+                status=400,
+                content_type="application/json",
+                body=json.dumps({"message": "maximum number of nodes has been reached"}).encode(),
+            )
+        await self._cache_node(node_id=node_id)
+        return web.Response(
+            status=201,
+            content_type="application/json",
+            body=json.dumps({"message": f"node registered with success: {node_id}", "node_id": node_id}).encode(),
+        )
+
+    async def heartbeat(self, request: web.Request) -> web.Response:
+        """HTTP POST /heartbeat — refresh a node's last-seen timestamp.
+
+        Expects a JSON body with ``{"node_id": <int>}``.
+
+        Returns:
+            200 on success, 400 if the body is invalid or the node is unknown.
+        """
+        log_header = f"{self.log_header}[heartbeat]"
+        try:
+            body = await request.json()
+        except json.JSONDecodeError:
+            return web.Response(
+                status=400,
+                content_type="application/json",
+                body=json.dumps({"message": "invalid or empty body"}).encode()
+            )
+        node_id = body.get("node_id")
+
+        node = await self._get_node(node_id=node_id)
+        if node:
+            await self._update_node(node_id=node_id, heart_beat=self._get_now())
+            logger.info(f"{log_header} last seen date updated with success for node: {node_id}")
+            return web.Response(
+                status=200,
+                content_type="application/json",
+                body=json.dumps({"message": "last seen date updated with success"}).encode(),
+            )
+        logger.info(f"{log_header} unknown node with id {node_id}")
+        return web.Response(
+            status=400,
+            content_type="application/json",
+            body=json.dumps({"message": f"unknown node with id {node_id}"}).encode(),
+        )
+
+    async def monitor_nodes(self) -> None:
+        """Evict nodes that have not sent a heartbeat in the last two minutes."""
+        log_header = f"{self.log_header}[monitor_nodes]"
+        two_minutes_ago = self._get_now() - 60 * 2 * 1000
+        node_heart_beats = await self._get_nodes(list(range(self.MAX_NODES)))
+        to_remove = []
+        for i, heart_beat in enumerate(node_heart_beats):
+            if heart_beat:
+                hb_value = float(heart_beat.decode() if isinstance(heart_beat, bytes) else heart_beat)
+                if hb_value < two_minutes_ago:
+                    to_remove.append(i)
+        await self._delete_nodes(to_remove)
+        logger.info(f"{log_header} nodes {to_remove} removed")
+
+    async def serve(self) -> None:
+        """Start the aiohttp HTTP server and block until it is stopped."""
+        app = web.Application()
+        app.router.add_post("/register", self.register)
+        app.router.add_post("/heartbeat", self.heartbeat)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, None, self.port)
+        await site.start()
+        logger.info(f"{self.log_header} id master server listening on localhost:{self.port}")
+
+    async def cleanup(self):
+        """Delete all node entries from Redis (intended for graceful shutdown)."""
+        log_header = f"{self.log_header}[cleanup]"
+        await self._delete_nodes(list(range(self.MAX_NODES)))
+        logger.info(f"{log_header} redis database cleaned up with success")

ws_scale-0.1.0/src/wsscale/ids/node.py

@@ -0,0 +1,122 @@
+import logging
+import asyncio
+from aiohttp import ClientSession
+from datetime import datetime, timezone
+
+from wsscale.cache.redis import RedisInstance
+
+logger = logging.getLogger("ws-scale.ids.node")
+    
+    
+class IDGeneratorNode:
+    """
+    Snowflake-style distributed ID generator node.
+
+    Each node registers with the ``IDGeneratorMaster`` to obtain a unique ``node_id``,
+    then uses that ID together with a datacenter ID, a millisecond timestamp, and a
+    per-millisecond sequence counter to produce 64-bit sortable unique IDs.
+    """
+
+    def __init__(self,
+                 server_host:str,
+                 server_port:int,
+                 data_center_id:int,
+                 redis_host:str,
+                 redis_port:int
+                 ):
+        """
+        Args:
+            server_host: Hostname or URL of the ``IDGeneratorMaster`` server.
+            server_port: Port the master server is listening on.
+            data_center_id: Logical datacenter identifier embedded in generated IDs.
+            redis_host: Hostname of the Redis server used for sequence counters.
+            redis_port: Port of the Redis server.
+        """
+        self.epoch = datetime.now(tz=timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
+        self.redis = RedisInstance(redis_host=redis_host, redis_port=redis_port).get_instance()
+        self.server_url = f"{server_host}:{server_port}"
+        self.data_center_id = data_center_id
+        self.node_id = None
+        self.registered = False
+        self.log_header = "[IDGeneratorNode]"
+        
+    def get_elapsed_time_since_custom_epoch(self):
+        """Return milliseconds elapsed since the custom epoch (midnight UTC of the start day)."""
+        now = datetime.now(tz=timezone.utc)
+        delta = (now - self.epoch).total_seconds()
+        return delta * 1000
+    
+    async def get_sequence_number(self) -> int:
+        """Atomically retrieve and increment the per-millisecond sequence counter from Redis.
+
+        The key expires after 1 ms so the counter resets each millisecond.
+
+        Returns:
+            Current sequence number for this millisecond.
+        """
+        sequence_key = f'{self.node_id}_sequence_number'
+        if await self.redis.get(sequence_key):
+            sequence = await self.redis.incr(name=sequence_key, amount=1)
+        else:
+            sequence = await self.redis.set(name=sequence_key, value=0, px=1)
+        return sequence
+    
+    
+    async def generate_id(self, datacenter_id:int, node_id:int) -> int:
+        """Produce a 64-bit Snowflake-style unique ID.
+
+        Bit layout: 41-bit timestamp | 5-bit datacenter ID | 5-bit node ID | 12-bit sequence.
+
+        Args:
+            datacenter_id: 5-bit datacenter identifier (0–31).
+            node_id: 5-bit node identifier (0–31).
+
+        Returns:
+            A globally unique 64-bit integer.
+        """
+        timestamp = self.get_elapsed_time_since_custom_epoch()
+        sequence_number = await self.get_sequence_number()
+        _id = (int(timestamp) << 22) | (datacenter_id << 17) | (node_id << 12) | sequence_number
+        return int(_id)
+    
+    async def register(self):
+        """Register this node with the master server to obtain a unique ``node_id``."""
+        log_header = f"{self.log_header}[register]"
+        async with ClientSession() as client:
+            logger.info(f"{log_header} start registering id generator node to master")
+            async with client.post(url=self.server_url + '/register', timeout=30) as req:
+                if req.status == 201:
+                    body = await req.json()
+                    self.node_id = body.get("node_id")
+                    self.registered = True
+                    logger.info(f"{log_header} node registered with success, node_id: {self.node_id}")
+                else:
+                    logger.error(f"{log_header} request to register ended with status code {req.status}")
+                    logger.error(f"{log_header} {await req.text()}")
+
+    async def heart_beat_loop(self, interval_seconds):
+        """Run ``heart_beat`` on a fixed interval forever.
+
+        Args:
+            interval_seconds: Seconds to wait between each heartbeat.
+        """
+        log_header = f"{self.log_header}[heart_beat_loop]"
+        while True:
+            await asyncio.sleep(delay=interval_seconds)
+            logger.info(f"{log_header} heart beat called after {interval_seconds}")
+            await self.heart_beat()
+
+    async def heart_beat(self):
+        """Send a single heartbeat POST to the master server to renew this node's liveness."""
+        log_header = f"{self.log_header}[heart_beat]"
+        logger.info(f"{log_header} about to send heart beat for node: {self.node_id}")
+        async with ClientSession() as client:
+            async with client.post(
+                url=self.server_url + "/heartbeat",
+                json={"node_id": self.node_id},
+                timeout=30) as req:
+                if req.status == 200:
+                    logger.info(f"{log_header} heart beat sent with success")
+                else:
+                    logger.error(f"{log_header} request to send heart beat ended with status code {req.status}")
+                    logger.error(f"{log_header} {await req.text()}")

ws_scale-0.1.0/src/wsscale/ws/server.py

@@ -0,0 +1,80 @@
+
+import asyncio
+import logging
+import os
+from importlib import import_module
+from typing import Callable, Awaitable, Optional, Any
+from websockets.asyncio.connection import Connection
+from websockets.asyncio.server import serve, Server
+from wsscale.ids.node import IDGeneratorNode
+
+
+Handler = Awaitable[Callable[[Connection], Any]]
+
+
+logger = logging.getLogger("ws-scale.server")
+
+class WebsocketServer:
+    """
+    Main entry point for the WebSocket server application.
+
+    Initializes an ``IDGeneratorNode``, registers it with the master on startup,
+    and drives a ``websockets`` server that routes incoming connections to the
+    caller-supplied handler.
+    """
+
+    def __init__(self, datacenter_id:int, port:int, settings_path:Optional[str]=None):
+        """
+        Args:
+            datacenter_id: 5-bit datacenter identifier embedded in generated IDs.
+            port: Local TCP port the WebSocket server will listen on.
+            settings_path: Dotted module path to a settings file (e.g. ``"app.settings"``).
+                           Falls back to environment variables when omitted.
+        """
+        self.port = port
+        self.server: Server = None
+        self.log_header = "[WebsocketServer]"
+        if settings_path:
+            try:
+                settings = import_module(name=settings_path)
+                redis_host = getattr(settings, "WS_REDIS_HOST")
+                redis_port = getattr(settings, "WS_REDIS_PORT")
+                id_master_host = getattr(settings, "WS_MASTER_HOST")
+                id_master_port = getattr(settings, "WS_MASTER_PORT")
+            except ModuleNotFoundError:
+                logger.error(f"Settings module not found, invalid path {settings_path}")
+                raise
+                
+        else:
+            redis_host = os.environ.get("WS_REDIS_HOST")
+            redis_port = os.environ.get("WS_REDIS_PORT")
+            id_master_host = os.environ.get("WS_MASTER_HOST")
+            id_master_port = os.environ.get("WS_MASTER_PORT")
+
+        try:
+            self.node = IDGeneratorNode(
+                server_host=id_master_host, 
+                server_port=id_master_port, 
+                data_center_id=datacenter_id,
+                redis_host=redis_host,
+                redis_port=redis_port
+            )
+        except Exception as e:
+            logger.warning(e)
+            logger.error("Unable to start id generator node, please verify your configuration")
+
+    async def bootstrap(self, handler: Handler):
+        """Register the ID node, start the heartbeat task, and run the WebSocket server.
+
+        Args:
+            handler: Async callable that handles each incoming WebSocket connection.
+        """
+        log_header = f"{self.log_header}[bootstrap]"
+        await self.node.register()
+        asyncio.create_task(self.node.heart_beat_loop(interval_seconds=60))
+        logger.info(f"{log_header} websockets server listening on localhost:{self.port}")
+        async with serve(handler=handler, host="", port=self.port) as server:
+            self.server = server
+            await server.serve_forever()
+        
+