feat: enhance BenncClient with websocket-ts integration and improved reconnection logic

README.md

@@ -2,54 +2,198 @@
 
 [![Build Status](https://drone.jacknet.io/api/badges/TerribleCodeClub/bennc-js/status.svg)](https://drone.jacknet.io/TerribleCodeClub/bennc-js)
 
-An implementation of the [BENNC](https://wiki.jacknet.io/books/simontech/chapter/bennc) client specification.
+A TypeScript implementation of the [BENNC](https://wiki.jacknet.io/books/simontech/chapter/bennc) (Butlersaurus Ephemeral No NONCEnse Chat) protocol specification. This library provides both low-level protocol utilities and a high-level client for connecting to BENNC chat servers via WebSocket.
+
+## Features
+
+- **Complete BENNC Protocol Support**: All message types (0x0000-0xFFFF) including subscribe, basic chat, user data, keepalive, history, and unsubscribe
+- **High-Level Client**: `BenncClient` class with automatic reconnection and event-driven architecture
+- **Browser & Node.js Compatible**: Works in modern browsers and Node.js environments
+- **TypeScript First**: Full type safety with comprehensive TypeScript definitions
+- **Encryption Support**: Built-in Romulus-M AEAD encryption for secure messaging
+- **Automatic Reconnection**: Configurable backoff strategies (constant, exponential)
+- **Small Bundle Size**: Minimal dependencies and efficient implementation
+
+## Installation
+
+```bash
+npm install @3t/bennc
+```
+
+## Quick Start
+
+### Using the BenncClient (Recommended)
+
+```typescript
+import { BenncClient, MessageTypes } from '@3t/bennc';
+
+const client = new BenncClient({
+  url: 'wss://your-bennc-server.com',
+  autoReconnect: true,
+  reconnectBackoff: 'exponential',
+  reconnectDelay: 1000,
+});
+
+// Listen for events
+client.addEventListener('connected', () => {
+  console.log('Connected to BENNC server');
+  
+  // Subscribe to basic messages
+  client.subscribe(MessageTypes.Basic);
+});
+
+client.addEventListener('message:1', (event) => {
+  const { senderId, data } = event.detail;
+  console.log(`Message from ${senderId}:`, new TextDecoder().decode(data));
+});
+
+client.addEventListener('disconnected', (event) => {
+  console.log('Disconnected:', event.detail);
+});
+
+// Connect to server
+await client.connect();
+
+// Send a message
+client.sendBasicMessage('Hello, BENNC!');
+```
+
+### Using Low-Level Protocol Functions
+
+```typescript
+import { packers, unpackers, MessageTypes } from '@3t/bennc';
+
+// Pack a basic message
+const messageData = new TextEncoder().encode('Hello World');
+const packet = packers[MessageTypes.Basic](messageData);
+
+// Unpack incoming message
+const incomingMessage = unpackers[MessageTypes.Basic](receivedData);
+```
+
+## API Reference
+
+### BenncClient
+
+#### Constructor Options
+
+```typescript
+interface BenncClientOptions {
+  url: string;                    // WebSocket server URL
+  protocols?: string[];           // WebSocket protocols
+  autoReconnect?: boolean;        // Enable auto-reconnection (default: true)
+  reconnectBackoff?: 'constant' | 'exponential'; // Backoff strategy (default: 'exponential')
+  reconnectDelay?: number;        // Reconnection delay in ms (default: 1000)
+  maxReconnectAttempts?: number;  // Max reconnection attempts (default: 10)
+}
+```
+
+#### Methods
+
+- `connect(): Promise<void>` - Connect to the BENNC server
+- `disconnect(): void` - Disconnect from the server
+- `isConnected(): boolean` - Check connection status
+- `subscribe(messageType: MessageTypes): void` - Subscribe to message type
+- `unsubscribe(messageType: MessageTypes): void` - Unsubscribe from message type
+- `sendBasicMessage(message: string, key?: Uint8Array): void` - Send encrypted chat message
+- `sendUserDataRequest(username: string, colour: Color, clientId: string, key?: Uint8Array): void` - Request user data
+- `sendUserDataResponse(username: string, colour: Color, clientId: string, key?: Uint8Array): void` - Respond with user data
+- `sendKeepalive(): void` - Send keepalive message
+- `requestHistory(): void` - Request message history
+
+#### Events
+
+The client extends `EventTarget` and emits the following events:
+
+- `connected` - Successfully connected to server
+- `disconnected` - Disconnected from server (detail: `{code, reason}`)
+- `reconnecting` - Attempting to reconnect
+- `error` - Connection or protocol error (detail: error object)
+- `packet` - Raw incoming packet (detail: packet object)
+- `message` - Parsed message (detail: `{messageType, senderId, data}`)
+- `message:${messageType}` - Specific message type events (detail: `{senderId, data}`)
+- `unknown-message` - Unknown message type received
+- `parse-error` - Error parsing incoming message
+
+### Message Types
+
+```typescript
+enum MessageTypes {
+  Subscribe = 0x0000,
+  Basic = 0x0001,
+  UserDataRequest = 0x0002,
+  UserDataResponse = 0x0003,
+  Keepalive = 0x0005,
+  GetHistory = 0xfffe,
+  Unsubscribe = 0xffff,
+}
+```
+
+### Protocol Constants
+
+```typescript
+const MAX_DATA_LENGTH = 1000;  // Maximum data payload size
+const DEFAULT_KEY: Uint8Array; // Default encryption key
+```
 
 ## Build
 
-To build the BENNC-JS library, first clone this repository.
+To build the BENNC-JS library from source:
-
-Run the following commands from the root of the repository:
 
 ```bash
+$ git clone <repository-url>
+$ cd bennc-js
 $ npm install
 $ npm run build
 ```
 
 The build output will be saved to the `dist` directory.
 
-## Development instructions
+## Protocol Details
 
-Requirements:
+BENNC uses a binary protocol with the following message structure:
 
-- The latest LTS builds of Node and npm.
+**Client → Server**: `[Type(2)|Length(2)|Data(0-1000)]`
+**Server → Client**: `[Type(2)|SenderId(4)|Length(2)|Data(0-1000)]`
 
-Follow the instructions below to lint, test and build BENNC-JS.
+- All integers are big-endian
+- Maximum data payload is 1000 bytes (including encryption overhead)
+- Encrypted message types (0x0001, 0x0002, 0x0003) use Romulus-M AEAD with 16-byte nonces
+- Reserved sender IDs: 0xFFFFFF00-0xFFFFFFFF
 
-#### Lint
+## Development
+
+Requirements: Node.js LTS and npm
+
+### Commands
 
 ```bash
-$ npm install
+# Install dependencies
-$ npm run lint
+npm install
-```
 
-#### Test
+# Run tests
+npm run test
 
-```bash
+# Lint code
-$ npm install
+npm run lint
-$ npm run test
-```
 
-#### Build
+# Format code
+npm run format
 
-```bash
+# Build library
-$ npm install
+npm run build
-$ npm run build
 ```
 
 ### Visual Studio Code
 
-This repository contains the necessary configuration files to debug, test and build BENNC-JS using only Visual Studio Code.
+This repository includes VS Code configuration for debugging and testing. Use `Ctrl+Shift+B` (or `⇧⌘B`) to run the build task.
 
-Run the build task (`Ctrl+Shift+B` or `⇧⌘B`) to automatically compile the Typescript source files in the background.
+Unit tests use [Jest](https://jestjs.io/) with VS Code support via the [Jest extension](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest).
 
-Unit tests use the [Jest](https://jestjs.io/) library. Support for Visual Studio Code is offered through the [Jest marketplace package](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest) maintained by Orta.
+## License
+
+ISC License - see package.json for details.
+
+## Contributing
+
+This is part of the BENNC protocol ecosystem. Please refer to the [BENNC specification](https://wiki.jacknet.io/books/simontech/chapter/bennc) for protocol details.

package-lock.json

@@ -12,7 +12,8 @@
       "dependencies": {
         "@3t/romulus": "^1.0.2",
         "@types/color": "^3.0.3",
-        "color": "^4.2.0"
+        "color": "^4.2.0",
+        "websocket-ts": "^2.2.1"
       },
       "devDependencies": {
         "@types/jest": "^30.0.0",
@@ -4451,6 +4452,12 @@
         "makeerror": "1.0.12"
       }
     },
+    "node_modules/websocket-ts": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/websocket-ts/-/websocket-ts-2.2.1.tgz",
+      "integrity": "sha512-YKPDfxlK5qOheLZ2bTIiktZO1bpfGdNCPJmTEaPW7G9UXI1GKjDdeacOrsULUS000OPNxDVOyAuKLuIWPqWM0Q==",
+      "license": "MIT"
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -7714,6 +7721,11 @@
         "makeerror": "1.0.12"
       }
     },
+    "websocket-ts": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/websocket-ts/-/websocket-ts-2.2.1.tgz",
+      "integrity": "sha512-YKPDfxlK5qOheLZ2bTIiktZO1bpfGdNCPJmTEaPW7G9UXI1GKjDdeacOrsULUS000OPNxDVOyAuKLuIWPqWM0Q=="
+    },
     "which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",

package.json

@@ -29,7 +29,8 @@
   "dependencies": {
     "@3t/romulus": "^1.0.2",
     "@types/color": "^3.0.3",
-    "color": "^4.2.0"
+    "color": "^4.2.0",
+    "websocket-ts": "^2.2.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

src/BenncClient.ts

@@ -0,0 +1,211 @@
+import {
+  WebsocketBuilder,
+  ConstantBackoff,
+  ExponentialBackoff,
+} from "websocket-ts";
+import { MessageTypes } from "./common";
+import { packOutgoingPacket, unpackIncomingPacket } from "./messages/packet";
+import { packers, unpackers } from "./mapping";
+import { numberToUint16BE } from "./utilities/number";
+import Color from "color";
+
+export interface BenncClientOptions {
+  url: string;
+  protocols?: string[];
+  autoReconnect?: boolean;
+  reconnectBackoff?: "constant" | "linear" | "exponential";
+  reconnectDelay?: number;
+  maxReconnectAttempts?: number;
+}
+
+export class BenncClient extends EventTarget {
+  private ws: any = null;
+  private options: BenncClientOptions;
+
+  constructor(options: BenncClientOptions) {
+    super();
+    this.options = {
+      autoReconnect: true,
+      reconnectBackoff: "exponential",
+      reconnectDelay: 1000,
+      maxReconnectAttempts: 10,
+      ...options,
+    };
+  }
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (
+        this.ws &&
+        (this.ws.state === WebSocket.OPEN ||
+          this.ws.state === WebSocket.CONNECTING)
+      ) {
+        resolve();
+        return;
+      }
+
+      const builder = new WebsocketBuilder(this.options.url);
+
+      if (this.options.protocols) {
+        builder.withProtocols(this.options.protocols);
+      }
+
+      if (this.options.autoReconnect) {
+        let backoff;
+        switch (this.options.reconnectBackoff) {
+          case "constant":
+            backoff = new ConstantBackoff(this.options.reconnectDelay!);
+            break;
+          case "exponential":
+          default:
+            backoff = new ExponentialBackoff(this.options.reconnectDelay!);
+            break;
+        }
+        builder.withBackoff(backoff);
+      }
+
+      this.ws = builder
+        .onOpen(() => {
+          this.dispatchEvent(new CustomEvent("connected"));
+          resolve();
+        })
+        .onClose((_: any, event: any) => {
+          this.dispatchEvent(
+            new CustomEvent("disconnected", {
+              detail: { code: event.code, reason: event.reason },
+            }),
+          );
+        })
+        .onError((_: any, error: any) => {
+          this.dispatchEvent(new CustomEvent("error", { detail: error }));
+          reject(error);
+        })
+        .onMessage((_: any, event: any) => {
+          this.handleMessage(event.data);
+        })
+        .onReconnect(() => {
+          this.dispatchEvent(new CustomEvent("reconnecting"));
+        })
+        .build();
+    });
+  }
+
+  disconnect(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.ws && this.ws.state === WebSocket.OPEN;
+  }
+
+  getConnectionState(): { connected: boolean; connecting: boolean } {
+    return {
+      connected: this.ws?.state === WebSocket.OPEN || false,
+      connecting: this.ws?.state === WebSocket.CONNECTING || false,
+    };
+  }
+
+  private sendRawMessage(messageType: number, data?: Uint8Array): void {
+    if (!this.isConnected()) {
+      throw new Error("Client is not connected");
+    }
+
+    const packet = packOutgoingPacket({
+      messageType: numberToUint16BE(messageType),
+      data,
+    });
+
+    this.ws.send(packet);
+  }
+
+  subscribe(messageType: MessageTypes): void {
+    const packer = packers[MessageTypes.Subscribe];
+    const data = packer({ messageType });
+    this.sendRawMessage(MessageTypes.Subscribe, data);
+  }
+
+  unsubscribe(messageType: MessageTypes): void {
+    const packer = packers[MessageTypes.Unsubscribe];
+    const data = packer({ messageType });
+    this.sendRawMessage(MessageTypes.Unsubscribe, data);
+  }
+
+  sendBasicMessage(message: string, key?: Uint8Array): void {
+    const encoder = new TextEncoder();
+    const messageBytes = encoder.encode(message);
+    const packer = packers[MessageTypes.Basic];
+    const data = packer(messageBytes, key);
+    this.sendRawMessage(MessageTypes.Basic, data);
+  }
+
+  sendUserDataRequest(
+    username: string,
+    colour: Color,
+    clientId: string,
+    key?: Uint8Array,
+  ): void {
+    const packer = packers[MessageTypes.UserDataRequest];
+    const data = packer({ username, colour, clientId }, key);
+    this.sendRawMessage(MessageTypes.UserDataRequest, data);
+  }
+
+  sendUserDataResponse(
+    username: string,
+    colour: Color,
+    clientId: string,
+    key?: Uint8Array,
+  ): void {
+    const packer = packers[MessageTypes.UserDataResponse];
+    const data = packer({ username, colour, clientId }, key);
+    this.sendRawMessage(MessageTypes.UserDataResponse, data);
+  }
+
+  sendKeepalive(): void {
+    const packer = packers[MessageTypes.Keepalive];
+    const data = packer();
+    this.sendRawMessage(MessageTypes.Keepalive, data);
+  }
+
+  requestHistory(): void {
+    const packer = packers[MessageTypes.GetHistory];
+    const data = packer();
+    this.sendRawMessage(MessageTypes.GetHistory, data);
+  }
+
+  private handleMessage(data: ArrayBuffer): void {
+    try {
+      const packet = unpackIncomingPacket(data);
+      this.dispatchEvent(new CustomEvent("packet", { detail: packet }));
+
+      const unpacker = unpackers[packet.messageType as keyof typeof unpackers];
+      if (unpacker) {
+        const unpackedData = unpacker(packet.data);
+        const messageEvent = {
+          messageType: packet.messageType,
+          senderId: packet.senderId,
+          data: unpackedData,
+        };
+        this.dispatchEvent(
+          new CustomEvent("message", { detail: messageEvent }),
+        );
+        this.dispatchEvent(
+          new CustomEvent(`message:${packet.messageType}`, {
+            detail: {
+              senderId: packet.senderId,
+              data: unpackedData,
+            },
+          }),
+        );
+      } else {
+        this.dispatchEvent(
+          new CustomEvent("unknown-message", { detail: packet }),
+        );
+      }
+    } catch (error) {
+      this.dispatchEvent(new CustomEvent("parse-error", { detail: error }));
+    }
+  }
+}

src/index.ts

@@ -7,3 +7,5 @@ export type { SubscribeMessage } from "./messages/subscribe";
 export type { BasicMessage } from "./messages/basic";
 export type { UserDataRequestMessage } from "./messages/userDataRequest";
 export type { UserDataResponseMessage } from "./messages/userDataResponse";
+export { BenncClient } from "./BenncClient";
+export type { BenncClientOptions } from "./BenncClient";