@stonyx/sockets 0.1.1-alpha.0 → 0.1.1-alpha.10

package/.claude/handlers.md

@@ -1,174 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# @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

@@ -1,135 +0,0 @@
-# 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

@@ -1,16 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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/.npmignore

@@ -1,4 +0,0 @@
-test/
-.nvmrc
-.git/
-.gitignore