@stonyx/sockets 0.1.0 → 0.1.1-alpha.1

package/.claude/handlers.md

@@ -0,0 +1,174 @@
+# Handlers
+
+## Overview
+
+Handlers are the primary extension point for consumers. Each handler is a class that extends `Handler` and defines a `server()` method, a `client()` method, or both. Handler files live in the handler directory (default: `./socket-handlers`).
+
+## Base Class
+
+```javascript
+// src/handler.js
+export default class Handler {
+  static skipAuth = false;
+}
+```
+
+That's it — 3 lines. The base class exists to provide the `skipAuth` default and a common prototype for `instanceof` checks.
+
+## Defining a Handler
+
+### Server-only handler
+
+```javascript
+import { Handler } from '@stonyx/sockets';
+
+export default class ValidateGameHandler extends Handler {
+  server(data, client) {
+    // data = whatever the client sent in the 'data' field
+    // client = the WebSocket client object (with .id, .ip, .meta, .send())
+
+    // Return a value to send it back as the response
+    return { valid: true };
+
+    // Return undefined/null to send no response
+  }
+}
+```
+
+### Client-only handler
+
+```javascript
+import { Handler } from '@stonyx/sockets';
+
+export default class ScanGamesHandler extends Handler {
+  client(response) {
+    // response = whatever the server sent back
+    // this.client = reference to the SocketClient instance
+
+    this.client.app.scanGames(response);
+  }
+}
+```
+
+### Dual handler (both sides)
+
+```javascript
+import { Handler } from '@stonyx/sockets';
+
+export default class EchoHandler extends Handler {
+  server(data) {
+    return data;  // echo back
+  }
+
+  client(response) {
+    console.log('Got echo:', response);
+  }
+}
+```
+
+## Auth Handler (Required)
+
+The `auth` handler is special — `SocketServer.init()` throws if it doesn't find a handler named `auth` with a `server()` method.
+
+```javascript
+import { Handler } from '@stonyx/sockets';
+import config from 'stonyx/config';
+
+export default class AuthHandler extends Handler {
+  static skipAuth = true;  // MUST be true — auth runs before authentication
+
+  server(data, client) {
+    if (data.authKey !== config.sockets.authKey) return client.close();
+
+    // Register client in the server's client map
+    this._serverRef.clientMap.set(client.id, client);
+
+    // Optionally set app-level metadata
+    client.meta = { role: 'worker' };
+
+    // Returning a truthy value triggers the framework to:
+    // 1. Set client.__authenticated = true
+    // 2. Generate and send a per-session encryption key (if encryption enabled)
+    // 3. Send the response back to the client
+    return 'success';
+  }
+
+  client(response) {
+    // this.client = the SocketClient instance
+    if (response !== 'success') this.client.promise.reject(response);
+    this.client.promise.resolve();
+  }
+}
+```
+
+### Auth enforcement rules
+
+- If a message arrives from an unauthenticated client:
+  - And the handler is the `auth` handler → allowed
+  - And the handler has `static skipAuth = true` → allowed
+  - Otherwise → rejected, connection closed
+- The framework sets `client.__authenticated = true` when the auth handler returns a truthy value
+- If the auth handler returns `undefined`/`null`/falsy, auth fails (no response sent)
+
+## Handler Discovery
+
+Both `SocketServer` and `SocketClient` call `forEachFileImport` on the handler directory:
+
+```javascript
+await forEachFileImport(handlerDir, (HandlerClass, { name }) => {
+  const instance = new HandlerClass();
+  if (typeof instance.server === 'function') {
+    instance._serverRef = this;
+    this.handlers[name] = instance;
+  }
+}, { ignoreAccessFailure: true });
+```
+
+- **Filename → handler name:** kebab-case to camelCase (`validate-game.js` → `validateGame`)
+- **Exception:** `auth.js` stays as `auth`
+- **ignoreAccessFailure:** If the handler directory doesn't exist, no error is thrown
+
+## Handler Context
+
+### Inside `server()` hooks
+
+- `this._serverRef` — the `SocketServer` instance
+- First argument `data` — the parsed `data` field from the message
+- Second argument `client` — the WebSocket client object
+
+### Inside `client()` hooks
+
+- `this.client` — the `SocketClient` instance (set via `.call()` binding)
+- First argument `response` — the parsed `response` field from the message
+
+## Wire Protocol
+
+All messages are JSON objects with a `request` field:
+
+```javascript
+// Client → Server (outgoing request)
+{ request: 'handlerName', data: { ... } }
+
+// Server → Client (response from handler return value)
+{ request: 'handlerName', response: { ... } }
+
+// Server → Client (explicit send via sendTo/broadcast)
+{ request: 'handlerName', data: { ... } }
+```
+
+## Built-in Handlers
+
+These are handled by the framework — consumers do NOT define handlers for them:
+
+### heartBeat
+
+- **Server:** Receives `heartBeat` request → responds with `{ request: 'heartBeat', response: true }`
+- **Client:** Receives `heartBeat` response → schedules next heartbeat via `setTimeout`
+- **Lifecycle:** Automatically started after successful auth; interval configured via `heartBeatInterval`
+
+### auth (framework-level handling)
+
+While consumers define the auth handler logic, the framework wraps it with:
+- Auto-setting `client.__authenticated = true` on truthy return
+- Auto-generating and transmitting per-session encryption keys
+- Auto-starting the heartbeat cycle on the client side

package/.claude/index.md

@@ -0,0 +1,36 @@
+# @stonyx/sockets — Agent Documentation Index
+
+Comprehensive reference for AI agents working on the `@stonyx/sockets` package. Start here, then drill into specific docs as needed.
+
+## Quick Orientation
+
+`@stonyx/sockets` is a Stonyx framework module providing WebSocket server/client with handler auto-discovery, auth enforcement, AES-256-GCM encryption, and built-in heartbeat. It follows the same conventions as `@stonyx/rest-server` and `stonyx-orm`.
+
+## Documentation
+
+- [architecture.md](./architecture.md) — Module structure, singleton pattern, Stonyx integration, handler discovery lifecycle
+- [handlers.md](./handlers.md) — Handler class API, server/client hooks, auth flow, skipAuth, wire protocol
+- [encryption.md](./encryption.md) — AES-256-GCM encryption, key derivation, handshake flow, session keys
+- [configuration.md](./configuration.md) — All config options, env vars, defaults, how config loads via Stonyx
+- [testing.md](./testing.md) — Test structure, running tests, sample handlers, writing new tests
+- [api-reference.md](./api-reference.md) — Complete method/property reference for SocketServer, SocketClient, Handler
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/main.js` | Entry point — `Sockets` default class (Stonyx auto-init) + barrel exports |
+| `src/server.js` | `SocketServer` — singleton, handler discovery, auth gate, message dispatch |
+| `src/client.js` | `SocketClient` — singleton, handler discovery, connect/auth/heartbeat |
+| `src/handler.js` | `Handler` base class (3 lines — just `skipAuth` flag) |
+| `src/encryption.js` | AES-256-GCM encrypt/decrypt, key derivation, session key generation |
+| `config/environment.js` | Default config with env var overrides |
+
+## Conventions
+
+- **Singleton pattern:** `if (Class.instance) return Class.instance;` in constructor
+- **Stonyx module keywords:** `stonyx-async` + `stonyx-module` in package.json
+- **Config namespace:** `config.sockets` (camelCase of package name minus `@stonyx/`)
+- **Logging:** `log.socket()` via `logColor: 'white'` + `logMethod: 'socket'` in config
+- **Handler discovery:** `forEachFileImport` from `@stonyx/utils/file`, kebab-to-camelCase naming
+- **Test runner:** `stonyx test` (not plain `qunit`) — bootstraps Stonyx before running tests

package/.claude/testing.md

@@ -0,0 +1,135 @@
+# Testing
+
+## Running Tests
+
+```bash
+# From the stonyx-sockets directory
+npx stonyx test
+
+# Or via pnpm
+pnpm test
+```
+
+**Important:** Use `stonyx test`, not plain `qunit`. The Stonyx test runner bootstraps the framework (config, logging, module init) before running QUnit. Without it, `stonyx/config` and `log.socket()` won't be available.
+
+## Test Structure
+
+```
+test/
+├── config/
+│   └── environment.js            # Test-specific config overrides
+├── sample/
+│   └── socket-handlers/
+│       ├── auth.js               # Sample auth handler (server + client hooks)
+│       └── echo.js               # Simple echo handler (both hooks)
+├── unit/
+│   ├── handler-test.js           # Base Handler class tests
+│   ├── encryption-test.js        # AES-256-GCM encrypt/decrypt tests
+│   ├── server-test.js            # SocketServer unit tests (no network)
+│   └── client-test.js            # SocketClient unit tests (no network)
+└── integration/
+    └── socket-test.js            # Full server+client round-trip tests
+```
+
+## Test Config
+
+```javascript
+// test/config/environment.js
+export default {
+  sockets: {
+    handlerDir: './test/sample/socket-handlers',
+    heartBeatInterval: 60000,   // Long interval so timers don't fire during tests
+    encryption: 'false',        // Disabled for test simplicity
+  }
+}
+```
+
+## Sample Handlers
+
+### auth.js
+
+Validates `authKey` against config, registers client in `clientMap`, resolves the connection promise. Has `static skipAuth = true`.
+
+### echo.js
+
+Server returns whatever data it receives. Client stores the response on `client._lastEchoResponse` for test assertions.
+
+## Writing Unit Tests
+
+Unit tests do NOT start a WebSocket server. They test class behavior directly:
+
+```javascript
+import QUnit from 'qunit';
+import SocketServer from '../../src/server.js';
+
+const { module, test } = QUnit;
+
+module('[Unit] SocketServer', function (hooks) {
+  hooks.afterEach(function () {
+    const server = SocketServer.instance;
+    if (server) server.reset();
+  });
+
+  test('Singleton pattern', function (assert) {
+    const s1 = new SocketServer();
+    const s2 = new SocketServer();
+    assert.strictEqual(s1, s2);
+    s1.reset();
+  });
+});
+```
+
+Key patterns:
+- Always call `reset()` in `afterEach` to clear the singleton
+- Use `sinon` for stubs/spies when needed
+- Restore sinon in `afterEach` with `sinon.restore()`
+
+## Writing Integration Tests
+
+Integration tests start a real server and client:
+
+```javascript
+import QUnit from 'qunit';
+import SocketServer from '../../src/server.js';
+import SocketClient from '../../src/client.js';
+import { setupIntegrationTests } from 'stonyx/test-helpers';
+
+const { module, test } = QUnit;
+
+module('[Integration] Sockets', function (hooks) {
+  setupIntegrationTests(hooks);  // Waits for Stonyx.ready
+
+  hooks.afterEach(function () {
+    const client = SocketClient.instance;
+    const server = SocketServer.instance;
+    if (client) client.reset();
+    if (server) server.reset();
+  });
+
+  test('Round-trip', async function (assert) {
+    const server = new SocketServer();
+    await server.init();
+
+    const client = new SocketClient();
+    await client.init();
+
+    client.send({ request: 'echo', data: { msg: 'hello' } });
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    assert.deepEqual(client._lastEchoResponse, { msg: 'hello' });
+  });
+});
+```
+
+Key patterns:
+- `setupIntegrationTests(hooks)` — adds a `hooks.before` that `await Stonyx.ready`
+- Always clean up in `afterEach` — `reset()` terminates connections and clears state
+- Use `setTimeout` + `await` for async message assertions (messages are async)
+- For multiple clients: null out `SocketClient.instance` between creations, track extras for cleanup
+
+## Common Gotchas
+
+- **Process hangs after tests:** Usually caused by un-cleared heartbeat timers or unclosed WebSocket servers. Ensure `reset()` is called for all instances.
+- **`log.socket is not a function`:** Running `qunit` directly instead of `stonyx test`. The Stonyx bootstrap is required.
+- **`moduleClass is not a constructor`:** The `src/main.js` default export must be a class (not just named exports). The `Sockets` class serves as the Stonyx auto-init entry point.
+- **Port conflicts:** Integration tests use port 2667 by default. If tests run in parallel with other services, override `SOCKET_PORT`.

package/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [dev, main]
+
+concurrency:
+  group: ci-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to NPM
+
+on:
+  repository_dispatch:
+    types: [cascade-publish]
+  workflow_dispatch:
+    inputs:
+      version-type:
+        description: 'Version type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      custom-version:
+        description: 'Custom version (optional, overrides version-type)'
+        required: false
+        type: string
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+  pull-requests: write
+
+jobs:
+  publish:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
+    with:
+      version-type: ${{ github.event.inputs.version-type }}
+      custom-version: ${{ github.event.inputs.custom-version }}
+      cascade-source: ${{ github.event.client_payload.source_package || '' }}
+    secrets: inherit
+
+  cascade:
+    needs: publish
+    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
+    with:
+      package-name: ${{ needs.publish.outputs.package-name }}
+      published-version: ${{ needs.publish.outputs.published-version }}
+    secrets: inherit

package/README.md

@@ -1,6 +1,15 @@
 # @stonyx/sockets
 
-WebSocket server and client module for the Stonyx framework.
+WebSocket server and client module for the [Stonyx framework](https://github.com/abofs/stonyx), providing plug-and-play handler discovery, built-in authentication enforcement, AES-256-GCM encryption, and automatic heartbeat keep-alive.
+
+## Highlights
+
+* **Handler auto-discovery:** Drop handler files into a directory and the framework registers them automatically.
+* **Unified handler files:** A single file can define both `server()` and `client()` hooks.
+* **Auth enforcement:** An `auth` handler is required. Unauthenticated requests are rejected by default.
+* **Built-in heartbeat:** Keep-alive is managed by the framework — no handler needed.
+* **Encryption by default:** AES-256-GCM with per-session keys, zero external dependencies.
+* **Singleton pattern:** Matches the conventions of `@stonyx/rest-server` and `stonyx-orm`.
 
 ## Installation
 
@@ -8,8 +17,245 @@ WebSocket server and client module for the Stonyx framework.
 npm install @stonyx/sockets
 ```
 
-## Usage
+## Quick Start
+
+### 1. Create handler files
+
+```
+socket-handlers/        # default directory (configurable)
+  auth.js               # REQUIRED — must have a server() hook
+  scan-games.js         # app-specific handlers
+  validate-game.js
+```
+
+### 2. Write a handler
+
+Each handler extends `Handler` and defines a `server()` method, a `client()` method, or both:
+
+```javascript
+// socket-handlers/auth.js
+import { Handler } from '@stonyx/sockets';
+import config from 'stonyx/config';
+
+export default class AuthHandler extends Handler {
+  static skipAuth = true;  // auth handler must work before authentication
+
+  server(data, client) {
+    if (data.authKey !== config.sockets.authKey) return client.close();
+
+    this._serverRef.clientMap.set(client.id, client);
+    return 'success';
+  }
+
+  client(response) {
+    if (response !== 'success') this.client.promise.reject(response);
+    this.client.promise.resolve();
+  }
+}
+```
 
 ```javascript
-import { SocketServer, SocketClient, Handler } from '@stonyx/sockets';
+// socket-handlers/scan-games.js — client-only handler
+import { Handler } from '@stonyx/sockets';
+
+export default class ScanGamesHandler extends Handler {
+  client(validGames) {
+    this.client.app.scanGames(validGames);
+  }
+}
+```
+
+### 3. Start the server / client
+
+With Stonyx auto-initialization (recommended):
+
+```bash
+stonyx serve
+```
+
+Or manually:
+
+```javascript
+import { SocketServer, SocketClient } from '@stonyx/sockets';
+
+// Server side
+const server = new SocketServer();
+await server.init();
+
+// Client side
+const client = new SocketClient();
+await client.init();
+```
+
+## Handler Architecture
+
+### How handlers are discovered
+
+On `init()`, both `SocketServer` and `SocketClient` scan the handler directory using `forEachFileImport`. Each file's default export is inspected:
+
+- Has a `server()` method → registered on `SocketServer`
+- Has a `client()` method → registered on `SocketClient`
+- Has both → registered on both sides
+
+Handler filenames are converted from kebab-case to camelCase: `validate-game.js` → `validateGame`.
+
+### Handler hooks
+
+**Server hook:** `server(data, client)` — receives the request data and the client object. Return a value to send it back as a response.
+
+**Client hook:** `client(response)` — receives the server's response. Inside the hook, `this.client` references the `SocketClient` instance.
+
+### skipAuth
+
+Set `static skipAuth = true` on a handler class to allow it to execute before the client is authenticated. The `auth` handler must always set this.
+
+## Sending Messages
+
+### Client → Server
+
+```javascript
+// From app code
+client.send({ request: 'handlerName', data: { ... } });
+
+// From within a client handler
+this.client.send({ request: 'handlerName', data: { ... } });
 ```
+
+### Server → Client
+
+```javascript
+// Auto-reply (return value from server() hook becomes the response)
+server(data, client) {
+  return 'success';  // sends { request, response: 'success' } back
+}
+
+// Send to a specific client by ID
+server.sendTo(clientId, 'scanGames', gamesList);
+
+// Broadcast to all authenticated clients
+server.broadcast('announcement', { msg: 'shutdown in 5m' });
+
+// Filter by metadata using clientMap directly
+for (const [id, client] of server.clientMap) {
+  if (client.meta?.role === 'worker') {
+    client.send({ request: 'scanGames', data: games });
+  }
+}
+```
+
+### Wire Protocol
+
+All messages are JSON:
+
+```javascript
+{ request: 'handlerName', data: { ... } }        // outgoing request
+{ request: 'handlerName', response: { ... } }     // reply
+```
+
+## Client Object (Server-Side)
+
+Each connected WebSocket client is augmented with:
+
+| Property | Description |
+|----------|-------------|
+| `client.id` | Auto-assigned numeric ID (incrementing) |
+| `client.ip` | Remote IP address |
+| `client.meta` | App-defined metadata (set in your auth handler) |
+| `client.__authenticated` | Framework-managed auth flag |
+| `client.send(payload)` | Wrapped send that handles JSON + encryption |
+
+## Built-in Mechanisms
+
+### Heartbeat
+
+The framework automatically manages keep-alive. After successful authentication, the client begins sending periodic `heartBeat` requests at the configured interval. The server responds automatically. No handler needed.
+
+### Authentication Flow
+
+1. Client connects and sends `{ request: 'auth', data: { authKey } }`
+2. Server routes to the `auth` handler's `server()` method
+3. If the handler returns a truthy value, `client.__authenticated` is set to `true`
+4. Response is sent back; if encryption is enabled, a per-session key is included
+5. Client's `auth` handler `client()` method processes the response
+6. Heartbeat cycle begins automatically
+
+**Auth enforcement:** Any message from an unauthenticated client is rejected and the connection is closed, unless the handler has `static skipAuth = true`.
+
+**Missing auth handler:** `SocketServer.init()` throws if no `auth` handler with a `server()` method exists.
+
+## Encryption
+
+Enabled by default (`SOCKET_ENCRYPTION=true`). Uses Node.js native `crypto` — zero external dependencies.
+
+- **Algorithm:** AES-256-GCM
+- **Key derivation:** `crypto.scryptSync` from the `authKey` string
+- **Handshake:** Auth request/response use the global key; server generates a per-session key for all subsequent messages
+- **Wire format:** `iv (12 bytes) + auth tag (16 bytes) + ciphertext`
+
+Disable with `SOCKET_ENCRYPTION=false`.
+
+## Configuration
+
+Configuration is read from `stonyx/config` under `sockets`:
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `port` | `SOCKET_PORT` | `2667` | WebSocket server port |
+| `address` | `SOCKET_ADDRESS` | `ws://localhost:2667` | Client connection address |
+| `authKey` | `SOCKET_AUTH_KEY` | `'AUTH_KEY'` | Shared authentication key |
+| `heartBeatInterval` | `SOCKET_HEARTBEAT_INTERVAL` | `30000` | Heartbeat interval in ms |
+| `handlerDir` | `SOCKET_HANDLER_DIR` | `'./socket-handlers'` | Handler directory path |
+| `encryption` | `SOCKET_ENCRYPTION` | `'true'` | Enable AES-256-GCM encryption |
+
+## API Reference
+
+### SocketServer
+
+| Method | Description |
+|--------|-------------|
+| `new SocketServer()` | Singleton constructor |
+| `async init()` | Discover handlers, validate auth, start WebSocket server |
+| `sendTo(clientId, request, data)` | Send to one client by ID |
+| `broadcast(request, data)` | Send to all authenticated clients |
+| `clientMap` | `Map<id, client>` of connected clients |
+| `close()` | Terminate all connections and stop the server |
+| `reset()` | Close + clear all state (for testing) |
+
+### SocketClient
+
+| Method | Description |
+|--------|-------------|
+| `new SocketClient()` | Singleton constructor |
+| `async init()` | Discover handlers, connect, authenticate |
+| `send(payload)` | Send a message to the server |
+| `close()` | Close the connection |
+| `reconnect()` | Reconnect (max 5 retries) |
+| `reset()` | Close + clear all state (for testing) |
+
+### Handler
+
+| Property / Method | Description |
+|-------------------|-------------|
+| `static skipAuth = false` | Set `true` to allow pre-auth access |
+| `server(data, client)` | Server-side hook (optional) |
+| `client(response)` | Client-side hook (optional) |
+| `this._serverRef` | Reference to SocketServer (in server hooks) |
+| `this.client` | Reference to SocketClient (in client hooks) |
+
+## Example Project Structure
+
+```
+my-app/
+├── config/
+│   └── environment.js
+├── socket-handlers/
+│   ├── auth.js              # Required
+│   ├── scan-games.js
+│   └── validate-game.js
+├── package.json
+└── app.js
+```
+
+## License
+
+Apache — do what you want, just keep attribution.

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.1",
   "description": "WebSocket server and client module for the Stonyx framework",
   "main": "src/main.js",
   "type": "module",
@@ -18,7 +18,8 @@
     "./handler": "./src/handler.js"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "repository": {
     "type": "git",