@stonyx/sockets 0.1.1-alpha.1 → 0.1.1-beta.0

package/config/environment.js

@@ -5,7 +5,10 @@ const {
   SOCKET_HEARTBEAT_INTERVAL,
   SOCKET_HANDLER_DIR,
   SOCKET_LOG,
-  SOCKET_ENCRYPTION
+  SOCKET_ENCRYPTION,
+  SOCKET_RECONNECT_BASE_DELAY,
+  SOCKET_RECONNECT_MAX_DELAY,
+  SOCKET_MAX_RECONNECT_ATTEMPTS,
 } = process.env;
 
 const port = SOCKET_PORT ?? 2667;
@@ -14,10 +17,14 @@ export default {
   port,
   address: SOCKET_ADDRESS ?? `ws://localhost:${port}`,
   authKey: SOCKET_AUTH_KEY ?? 'AUTH_KEY',
+  authData: {},
   heartBeatInterval: SOCKET_HEARTBEAT_INTERVAL ?? 30000,
   handlerDir: SOCKET_HANDLER_DIR ?? './socket-handlers',
   log: SOCKET_LOG ?? false,
   logColor: 'white',
   logMethod: 'socket',
   encryption: SOCKET_ENCRYPTION ?? 'true',
+  reconnectBaseDelay: SOCKET_RECONNECT_BASE_DELAY ?? 1000,
+  reconnectMaxDelay: SOCKET_RECONNECT_MAX_DELAY ?? 60000,
+  maxReconnectAttempts: SOCKET_MAX_RECONNECT_ATTEMPTS ?? Infinity,
 };

package/package.json

@@ -4,12 +4,15 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.1",
+  "version": "0.1.1-beta.0",
   "description": "WebSocket server and client module for the Stonyx framework",
   "main": "src/main.js",
   "type": "module",
   "files": [
-    "*"
+    "src",
+    "config",
+    "LICENSE.md",
+    "README.md"
   ],
   "exports": {
     ".": "./src/main.js",

package/src/client.js

@@ -2,11 +2,18 @@ import { WebSocket } from 'ws';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
+import { sleep } from '@stonyx/utils/promise';
 import { encrypt, decrypt, deriveKey } from './encryption.js';
 
 export default class SocketClient {
   handlers = {};
   reconnectCount = 0;
+  _intentionalClose = false;
+
+  onDisconnect = null;
+  onReconnecting = null;
+  onReconnected = null;
+  onReconnectFailed = null;
 
   constructor() {
     if (SocketClient.instance) return SocketClient.instance;
@@ -41,7 +48,7 @@ export default class SocketClient {
 
   async connect() {
     return new Promise((resolve, reject) => {
-      const { address, authKey } = config.sockets;
+      const { address, authKey, authData } = config.sockets;
       this.promise = { resolve, reject };
 
       log.socket(`Connecting to remote server: ${address}`);
@@ -51,13 +58,14 @@ export default class SocketClient {
       socket.onmessage = this.onMessage.bind(this);
       socket.onclose = this.onClose.bind(this);
       socket.onerror = event => {
-        console.error(event);
+        log.socket(`Error connecting to socket server`);
         reject('Error connecting to socket server');
       };
 
       socket.onopen = () => {
+        this._intentionalClose = false;
         this.reconnectCount = 0;
-        this.send({ request: 'auth', data: { authKey } }, true);
+        this.send({ request: 'auth', data: { authKey, ...authData } }, true);
       };
     });
   }
@@ -71,12 +79,12 @@ export default class SocketClient {
         const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
         parsed = JSON.parse(decrypt(raw, key));
       } else {
-        parsed = JSON.parse(payload);
+        const raw = Buffer.isBuffer(payload) ? payload.toString() : payload;
+        parsed = JSON.parse(raw);
       }
 
       const { request, response, sessionKey } = parsed;
 
-      // Built-in auth session key handling + heartbeat kickoff
       if (request === 'auth') {
         if (sessionKey && this.encryptionEnabled) {
           this.sessionKey = Buffer.from(sessionKey, 'base64');
@@ -84,7 +92,6 @@ export default class SocketClient {
         this.nextHeartBeat();
       }
 
-      // Built-in heartbeat — schedule next beat on response
       if (request === 'heartBeat') {
         this.nextHeartBeat();
         return;
@@ -93,13 +100,12 @@ export default class SocketClient {
       const handler = this.handlers[request];
 
       if (!handler) {
-        console.error(`Call to invalid handler: ${request}`);
+        log.socket(`Call to invalid handler: ${request}`);
         return;
       }
 
       handler.client.call({ client: this, ...handler }, response);
     } catch (error) {
-      console.error(error);
       log.socket(`Invalid payload received from remote server`);
     }
   }
@@ -125,21 +131,55 @@ export default class SocketClient {
   onClose() {
     log.socket('Disconnected from remote server');
     if (this._heartBeatTimer) clearTimeout(this._heartBeatTimer);
+
+    this.onDisconnect?.();
+
+    if (!this._intentionalClose) {
+      this.reconnect();
+    }
   }
 
   close() {
+    this._intentionalClose = true;
     if (this._heartBeatTimer) clearTimeout(this._heartBeatTimer);
     if (this.socket) this.socket.close();
   }
 
-  reconnect() {
-    if (this.reconnectCount > 5) {
+  getReconnectDelay() {
+    const {
+      reconnectBaseDelay = 1000,
+      reconnectMaxDelay = 60000,
+    } = config.sockets;
+
+    const exponential = reconnectBaseDelay * Math.pow(2, this.reconnectCount - 1);
+    const capped = Math.min(exponential, reconnectMaxDelay);
+    const jitter = Math.floor(Math.random() * 1000);
+    return capped + jitter;
+  }
+
+  async reconnect() {
+    const { maxReconnectAttempts = Infinity } = config.sockets;
+
+    this.reconnectCount++;
+
+    if (this.reconnectCount > maxReconnectAttempts) {
       log.socket('Max reconnect attempts exceeded');
+      this.onReconnectFailed?.();
       return;
     }
 
-    this.reconnectCount++;
-    return this.connect();
+    const delay = this.getReconnectDelay();
+    this.onReconnecting?.(this.reconnectCount, delay);
+    log.socket(`Reconnecting (attempt ${this.reconnectCount}, delay ${delay}ms)`);
+
+    await sleep(delay / 1000);
+
+    try {
+      await this.connect();
+      this.onReconnected?.();
+    } catch {
+      // onClose will fire and trigger the next reconnect attempt
+    }
   }
 
   reset() {
@@ -147,6 +187,11 @@ export default class SocketClient {
     this.handlers = {};
     this.sessionKey = null;
     this.reconnectCount = 0;
+    this._intentionalClose = false;
+    this.onDisconnect = null;
+    this.onReconnecting = null;
+    this.onReconnected = null;
+    this.onReconnectFailed = null;
     SocketClient.instance = null;
   }
 }

package/src/server.js

@@ -63,7 +63,7 @@ export default class SocketServer {
     }
   }
 
-  onMessage(payload, client) {
+  async onMessage(payload, client) {
     try {
       let parsed;
 
@@ -96,7 +96,7 @@ export default class SocketServer {
         return;
       }
 
-      const response = handler.server(data, client);
+      const response = await handler.server(data, client);
       if (response === undefined || response === null) return;
 
       if (request === 'auth' && response) {
@@ -139,18 +139,29 @@ export default class SocketServer {
     const { ip } = client;
     log.socket(`[${ip}] Client disconnected`);
     this.clientMap.delete(client.id);
+    this.onClientDisconnect?.(client);
   }
 
-  sendTo(clientId, request, data) {
+  sendTo(clientId, request, response) {
     const client = this.clientMap.get(clientId);
     if (!client) return;
-    client.send({ request, data });
+    client.send({ request, response });
   }
 
-  broadcast(request, data) {
+  sendToByMeta(key, value, request, response) {
+    for (const [, client] of this.clientMap) {
+      if (client.meta?.[key] === value && client.__authenticated) {
+        client.send({ request, response });
+        return true;
+      }
+    }
+    return false;
+  }
+
+  broadcast(request, response) {
     for (const [, client] of this.clientMap) {
       if (client.__authenticated) {
-        client.send({ request, data });
+        client.send({ request, response });
       }
     }
   }

package/.claude/api-reference.md

@@ -1,247 +0,0 @@
-# API Reference
-
-## Exports
-
-```javascript
-// Main entry (src/main.js)
-import { SocketServer, SocketClient, Handler } from '@stonyx/sockets';
-
-// Sub-path exports
-import SocketServer from '@stonyx/sockets/server';
-import SocketClient from '@stonyx/sockets/client';
-import Handler from '@stonyx/sockets/handler';
-```
-
-The default export from `@stonyx/sockets` is the `Sockets` class (used by Stonyx for auto-init). Consumer code should use the named exports.
-
----
-
-## SocketServer
-
-**File:** `src/server.js`
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `clientMap` | `Map<number, client>` | Connected clients keyed by auto-assigned ID |
-| `handlers` | `Object<string, Handler>` | Discovered server handlers keyed by name |
-| `wss` | `WebSocketServer \| null` | The underlying `ws` WebSocketServer instance |
-| `encryptionEnabled` | `boolean` | Whether AES-256-GCM encryption is active |
-| `globalKey` | `Buffer` | Derived encryption key from authKey (if encryption enabled) |
-
-### Static
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `SocketServer.instance` | `SocketServer \| null` | Singleton instance |
-
-### Methods
-
-#### `constructor()`
-
-Returns the existing singleton or creates a new one. Does NOT start the server.
-
-#### `async init()`
-
-Full initialization sequence:
-1. Discovers handlers from `config.sockets.handlerDir`
-2. Validates that an `auth` handler exists
-3. Configures encryption if enabled
-4. Starts `WebSocketServer` on `config.sockets.port`
-5. Wires connection/message/close events
-
-#### `sendTo(clientId, request, data)`
-
-Send a message to a specific client by numeric ID.
-
-- `clientId` — number, the client's auto-assigned ID
-- `request` — string, the handler name
-- `data` — any serializable value
-
-Does nothing if the client doesn't exist.
-
-#### `broadcast(request, data)`
-
-Send a message to all authenticated clients in `clientMap`.
-
-- `request` — string, the handler name
-- `data` — any serializable value
-
-#### `close()`
-
-Terminates all connected clients and closes the WebSocket server.
-
-#### `reset()`
-
-Calls `close()`, clears `clientMap`, clears `handlers`, resets the client ID counter, sets `SocketServer.instance = null`. Used in tests.
-
-### Internal Methods
-
-#### `async discoverHandlers()`
-
-Scans handler directory. For each file: instantiates the class, checks for `server()` method, registers it in `this.handlers`.
-
-#### `validateAuthHandler()`
-
-Throws `Error` if `this.handlers.auth` doesn't exist.
-
-#### `onMessage(payload, client)`
-
-Main message dispatcher. Decrypts (if enabled), parses JSON, routes to handler or built-in heartbeat, enforces auth gate.
-
-#### `prepareSend(client)`
-
-Replaces `client.send()` with a wrapper that JSON-stringifies and encrypts (if enabled).
-
-#### `handleDisconnect(client)`
-
-Removes client from `clientMap`, logs disconnection.
-
----
-
-## SocketClient
-
-**File:** `src/client.js`
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `handlers` | `Object<string, Handler>` | Discovered client handlers keyed by name |
-| `socket` | `WebSocket \| null` | The underlying `ws` WebSocket instance |
-| `reconnectCount` | `number` | Current reconnection attempt count |
-| `promise` | `{ resolve, reject }` | Connection promise callbacks |
-| `encryptionEnabled` | `boolean` | Whether AES-256-GCM encryption is active |
-| `globalKey` | `Buffer` | Derived encryption key from authKey (if encryption enabled) |
-| `sessionKey` | `Buffer \| null` | Per-session key received from server after auth |
-
-### Static
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `SocketClient.instance` | `SocketClient \| null` | Singleton instance |
-
-### Methods
-
-#### `constructor()`
-
-Returns the existing singleton or creates a new one. Does NOT connect.
-
-#### `async init()`
-
-Full initialization:
-1. Discovers handlers from `config.sockets.handlerDir`
-2. Configures encryption if enabled
-3. Calls `connect()`
-
-Returns the Promise from `connect()`.
-
-#### `send(payload, useGlobalKey = false)`
-
-Send a message to the server.
-
-- `payload` — object with `request` and optionally `data` fields
-- `useGlobalKey` — boolean, use the global key instead of session key (internal, for auth)
-
-#### `close()`
-
-Clears heartbeat timer and closes the WebSocket connection.
-
-#### `reconnect()`
-
-Attempts to reconnect. Returns the `connect()` Promise. Fails after 5 consecutive attempts.
-
-#### `reset()`
-
-Calls `close()`, clears handlers, clears session key, resets reconnect counter, sets `SocketClient.instance = null`. Used in tests.
-
-### Internal Methods
-
-#### `async discoverHandlers()`
-
-Scans handler directory. For each file: instantiates the class, checks for `client()` method, registers it.
-
-#### `async connect()`
-
-Creates WebSocket, wires events, sends auth on open. Returns Promise that resolves when auth handler resolves it.
-
-#### `onMessage({ data: payload })`
-
-Decrypts, parses, handles built-in auth/heartbeat, routes to handler.
-
-#### `heartBeat()`
-
-Sends `{ request: 'heartBeat' }` to the server.
-
-#### `nextHeartBeat()`
-
-Schedules `heartBeat()` via `setTimeout` at `config.sockets.heartBeatInterval`.
-
-#### `onClose()`
-
-Logs disconnection, clears heartbeat timer.
-
----
-
-## Handler
-
-**File:** `src/handler.js`
-
-### Static Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `skipAuth` | `boolean` | `false` | Set `true` to allow pre-auth access (server side only) |
-
-### Instance Methods (defined by subclasses)
-
-#### `server(data, client)`
-
-Server-side hook. Called when a message with the matching handler name arrives.
-
-- `data` — the parsed `data` field from the incoming message
-- `client` — the WebSocket client object with `.id`, `.ip`, `.meta`, `.send()`, `.__authenticated`
-- **Return value:** sent back as the `response` field. Return `undefined`/`null` to send nothing.
-
-#### `client(response)`
-
-Client-side hook. Called when a response with the matching handler name arrives from the server.
-
-- `response` — the parsed `response` field from the message
-- **Context:** `this.client` references the `SocketClient` instance
-
-### Instance Properties (set by framework)
-
-| Property | Set by | Description |
-|----------|--------|-------------|
-| `_serverRef` | `SocketServer.discoverHandlers()` | Reference to the SocketServer instance |
-| `_clientRef` | `SocketClient.discoverHandlers()` | Reference to the SocketClient instance |
-
----
-
-## Client Object (Server-Side)
-
-The raw WebSocket client is augmented by the framework:
-
-| Property | Type | Set by | Description |
-|----------|------|--------|-------------|
-| `id` | `number` | Framework (on connect) | Auto-incrementing numeric ID |
-| `ip` | `string` | Framework (on connect) | Remote IP address |
-| `__authenticated` | `boolean` | Framework (on auth) | Auth state |
-| `__sessionKey` | `Buffer` | Framework (on auth, if encryption) | Per-session encryption key |
-| `meta` | `any` | Consumer (in auth handler) | App-defined metadata |
-| `send(payload)` | `function` | Framework (`prepareSend`) | Sends JSON, auto-encrypts if enabled |
-
----
-
-## Encryption Functions
-
-**File:** `src/encryption.js`
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `encrypt` | `(data: string, key: Buffer) → Buffer` | AES-256-GCM encrypt, returns `iv + tag + ciphertext` |
-| `decrypt` | `(buffer: Buffer, key: Buffer) → string` | AES-256-GCM decrypt, returns UTF-8 string |
-| `generateSessionKey` | `() → Buffer` | `crypto.randomBytes(32)` |
-| `deriveKey` | `(authKey: string) → Buffer` | `crypto.scryptSync(authKey, 'stonyx-sockets', 32)` |

package/.claude/architecture.md

@@ -1,117 +0,0 @@
-# Architecture
-
-## Module Structure
-
-```
-stonyx-sockets/
-├── config/environment.js      # Default config, env var overrides
-├── src/
-│   ├── main.js                # Sockets class (Stonyx entry) + barrel exports
-│   ├── server.js              # SocketServer singleton
-│   ├── client.js              # SocketClient singleton
-│   ├── handler.js             # Base Handler class
-│   └── encryption.js          # AES-256-GCM utilities
-└── test/
-    ├── config/environment.js  # Test config overrides
-    ├── sample/socket-handlers # Auth + echo sample handlers
-    ├── unit/                  # Handler, encryption, server, client unit tests
-    └── integration/           # Full server+client round-trip tests
-```
-
-## Stonyx Integration
-
-### Auto-Initialization
-
-The package declares `stonyx-async` + `stonyx-module` keywords. When Stonyx starts:
-
-1. Reads `config/environment.js` and merges into `config.sockets`
-2. Registers `log.socket()` via `logColor: 'white'` + `logMethod: 'socket'`
-3. Imports `src/main.js`, instantiates the default `Sockets` class, calls `.init()`
-
-The `Sockets` default export is a thin entry point — it does NOT auto-start the WebSocket server. The actual server/client initialization is deferred to when the consumer explicitly creates `new SocketServer()` or `new SocketClient()` and calls `.init()`.
-
-### Standalone Mode (Testing)
-
-When running `stonyx test` from within the package directory, Stonyx detects the `stonyx-` prefix in the path and transforms the config:
-
-```javascript
-// config/environment.js exports { port, address, authKey, ... }
-// Stonyx wraps it as: { sockets: { port, address, authKey, ... } }
-```
-
-Test overrides from `test/config/environment.js` are merged on top.
-
-## Singleton Pattern
-
-Both `SocketServer` and `SocketClient` use the Stonyx singleton convention:
-
-```javascript
-constructor() {
-  if (SocketServer.instance) return SocketServer.instance;
-  SocketServer.instance = this;
-}
-```
-
-`reset()` sets the static instance back to `null` (used in tests).
-
-## Initialization Lifecycle
-
-### SocketServer.init()
-
-1. **discoverHandlers()** — scans `config.sockets.handlerDir` via `forEachFileImport`
-   - For each file: instantiates the class, checks for `server()` method
-   - Stores instance in `this.handlers[name]` (kebab-to-camelCase)
-   - Sets `instance._serverRef = this` for access to the server within handlers
-2. **validateAuthHandler()** — throws if `this.handlers.auth` doesn't exist
-3. **Configure encryption** — if enabled, derives global key from `authKey`
-4. **Start WebSocketServer** on configured port
-5. **Wire connection events** — on each connection: assign ID, set IP, wrap send, bind message/close listeners
-
-### SocketClient.init()
-
-1. **discoverHandlers()** — same as server, but checks for `client()` method
-   - Sets `instance._clientRef = this` for access to the client within handlers
-2. **Configure encryption** — if enabled, derives global key from `authKey`
-3. **connect()** — returns Promise that resolves after auth completes
-   - Creates WebSocket to `config.sockets.address`
-   - On open: sends auth request
-   - On auth response: resolves the promise, starts heartbeat
-
-## Message Flow
-
-### Server onMessage
-
-```
-payload received
-  → decrypt (if encryption enabled, using session key or global key for auth)
-  → JSON.parse
-  → heartBeat? → respond with true, return
-  → handler lookup by request name
-  → auth gate: if not auth handler, not skipAuth, not authenticated → reject + close
-  → call handler.server(data, client)
-  → if return value is truthy:
-      → if auth request: set __authenticated, generate session key, respond
-      → else: send { request, response } back to client
-```
-
-### Client onMessage
-
-```
-payload received
-  → decrypt (if encryption enabled, using session key or global key)
-  → JSON.parse
-  → auth response? → store session key, start heartbeat
-  → heartBeat response? → schedule next heartbeat, return
-  → handler lookup by request name
-  → call handler.client(response) with this.client bound
-```
-
-## Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `ws` | WebSocket server (`WebSocketServer`) and client (`WebSocket`) |
-| `stonyx` | Framework core — config, logging, module lifecycle |
-| `@stonyx/utils` (dev) | `forEachFileImport` for handler auto-discovery |
-| `qunit` (dev) | Test framework |
-| `sinon` (dev) | Stubs and spies for unit tests |