ws13 — WebSocket API v1.1.0

Modular, extensible and operations-friendly WebSocket framework for Node.js. This release focuses on a small, stable core so dependent projects can proceed; extensions (channels, auth, history, events, admin, routing, heartbeat, message-meta, permessage-deflate) exist as planned work and will be completed and documented in follow-up releases.

Status: core stable and testable — extensions work in progress (APIs present in repository; integration examples available in examples/).

📚 Table of Contents

• ✨ Highlights
• 📦 Installation
• 🚀 Quick start
• 🧩 Core API
• 🧪 Tests
• 🧩 Extension roadmap
• 🛠 Operational notes
• 📁 Project Structure
• 📜 License - MIT

✨ Highlights (v1.1.0)

• Small, well-tested core for WebSocket handshake, frame parsing/serialisation and basic client/server modes.
• createRegistry() — lightweight connection registry with broadcast and auto-clean.
• attachServer(server, opts) — simple HTTP upgrade wiring.
• Built-in support for permessage-deflate (RFC 7692) provided as an optional extension instance.
• Client-side reconnect helpers (configurable) and heartbeat primitives in core.
• TypeScript definitions included ('index.d.ts') for IDE support.
• Tests included for core registry and basic behaviour (see 'index.test.js').

Extensions (channels, events, history, admin, routing, message-meta, heartbeat) are available as separate modules in the repo but marked WIP — README below points to that.

📦 Installation

npm:

npm install ws13

yarn:

yarn add ws13

🚀 Quick start — minimal server

This example uses the core createWebSocket exported from the package.

const http = require('http');
const createWebSocket = require('ws13');

const server = http.createServer();

const { registry } = createWebSocket.attachServer(server, {
  onConnect(ws, req) {
    ws.send('Welcome');
    ws.on('message', (evt) => {
      // simple echo
      ws.send(`Echo: ${evt.data}`);
    });
  }
});

server.listen(8080);

Client (Node.js reusing createWebSocket in client mode):

const http = require('http');
const createWebSocket = require('ws13');

const req = http.request({ host: '127.0.0.1', port: 8080, path: '/' });
const ws = createWebSocket({ request: req });

ws.on('open', () => ws.send('hello'));
ws.on('message', (evt) => console.log(evt.data));

Browser clients should use the native WebSocket API (wss:// for TLS).

🧩 Core API (summary)

• createWebSocket(options): create client or server WebSocket-like instance
• options highlights: request (IncomingMessage | ClientRequest), socket, protocol, origin, heartbeatInterval_ms, extension (or null), autoReconnect, requestFactory, shouldReconnect, isDebug.
• returned object is EventEmitter-like and supports: send(data), sendPing(data), sendPong(data), heartbeat(cb), close(code, reason). Properties: readyState, ip, port, latency_ms, bufferedAmount, protocol, extensions, url.
• createRegistry(): returns { add(ws), delete(ws), broadcast(data), size(), clients:Set }
• registry auto-cleans clients on close/error.
• attachServer(server, { registry?, onConnect? }): attaches upgrade handler and returns { registry }.
• Default permessage-deflate extension is provided in core (createPermessageDeflate) and can be disabled via createWebSocket({ extension: null }).

TypeScript definitions are available at 'index.d.ts' for full shapes and options.

🧪 Tests

Project ships basic tests for the core. Use test-runner-lite (or Node directly) to run tests.

Run all tests:

npm test

Run the core test directly:

node ./index.test.js

Example core tests included:

• registry add/delete and automatic cleanup on close/error
• attachServer integration behaviour
• basic createWebSocket attachment helpers

Add more tests as needed; tests live next to core and in each extension folder when implemented.

🧩 Extension roadmap (short)

The following extensions exist as separate modules and will be fully documented and stabilised in subsequent releases. Current status: prototype/partial implementations present in repo.

• channels — channel-based pub/sub
• message-meta — typed messages with meta (wrap/unwrap)
• heartbeat — idle/timeout hooks and monitor
• history — per-channel replay buffer (last N messages)
• events — JSON-RPC style event emitter (ws.onEvent / ws.emitEvent)
• admin — HTTP + WebSocket admin API, CSV/JSON export, disconnect/latency endpoints, live dashboard
• routing — targeted delivery (sendToUser, sendToRole, sendToIp)
• auth — authentication and role-based authorization

If your project relies on a specific extension, tell me which one and I will prioritise finishing it and publishing a stable interface.

🛠 Operational notes

• Default heartbeatInterval_ms in core is 30s (can be changed per socket).
• When enabling compression, configure maxDecompressSize to protect against decompression attacks.
• Registry clients are a Set; if you need ordered lists or sharding, wrap registry accordingly.
• The core focuses on correctness of handshake and frame handling — if you need production tuning (backpressure handling, batching or socket pooling) we can add recommended patterns.

📁 Project Structure

ws13/
    core/
        index.d.ts
        index.js
        index.test.js
        permessage-deflate.js
        README.md
    extensions/
        admin/
            index.d.ts
            index.js
            index.test.js
            README.md
            express-middleware.d.ts
            express-middleware.js
            examples/
                admin-api/
                    server.js
                admin-dashboard/
                    admin-dashboard.html
                admin-express-integration/
                    index.js
                    README.md
        auth/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                auth-channels-client.js
                auth-channels-server.js
                server-with-admin.js
        channels/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                channels/
                    client.js
                    server.js
        events/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                events/
                    client.js
                    server.js
        heartbeat/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                heartbeat/
                    client.js
        history/
            index.d.ts
            index.js
            index.test.js
            README.md
            sqlite-adapter.js
            sqlite-adapter.test.js
            examples/
                history/
                    client.js
                    server.js
        message-meta/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                message-meta/
                    client.js
                    server.js
                    routing-server.js
        routing/
            index.d.ts
            index.js
            index.test.js
            README.md
            examples/
                routing/
                    client.js
                    server.js
    logo/
        logo-ws13.png
    browser.js
    index.d.ts
    index.js
    LICENSE
    package.json
    README.md
    testRunner.js
    wrapper.mjs

📌 Contributing & development

• If you need only the core to unblock dependent projects, use the provided core export and tests. Extensions will follow; they are useful but not required for core adoption.
• Tell me which extension to stabilise first (channels, history, events, auth, admin or routing) and I’ll prepare stable API docs, tests, and examples.

📜 License

This project is licensed under the MIT License. Copyright © Manuel Lõhmus