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

2025-09-06 19:34:23 +01:00
parent ed1dc6870e
commit 356b70474c
5 changed files with 266 additions and 148 deletions
--- a/README.md
+++ b/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.
-
-Run the following commands from the root of the repository:
+To build the BENNC-JS library from source:

 ```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
-$ npm run lint
-```
+# Install dependencies
+npm install

-#### Test
+# Run tests
+npm run test

-```bash
-$ npm install
-$ npm run test
-```
+# Lint code
+npm run lint

-#### Build
+# Format code
+npm run format

-```bash
-$ npm install
-$ npm run build
+# Build library
+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.