209 lines
7.6 KiB
Markdown
209 lines
7.6 KiB
Markdown
# BENNC Protocol Implementation Guide
|
|
|
|
**BENNCv1** (Butlersaurus Ephemeral No NONCEnse Chat) - Complete implementation documentation for a binary pub/sub messaging protocol with encryption and compression.
|
|
|
|
## Quick Implementation Checklist
|
|
|
|
1. **Connect** to server (TCP or WebSocket)
|
|
2. **Subscribe** to message types you want to receive
|
|
3. **Encrypt** data with Romulus-M (except subscribe/unsubscribe)
|
|
4. **Send keepalive** every 30 seconds when idle
|
|
5. **Handle** incoming messages and sender IDs
|
|
|
|
## Connection Endpoints
|
|
|
|
| Protocol | Endpoint |
|
|
| --------------- | --------------------------------- |
|
|
| TCP | `chat.3t.network:10009` |
|
|
| WebSocket (TLS) | `wss://chat.3t.network:443/BENNC` |
|
|
| WebSocket | `ws://chat.3t.network:80/BENNC` |
|
|
|
|
## Core Requirements
|
|
|
|
- **Encoding**: Big-endian integers, UTF-8 strings
|
|
- **Encryption**: Romulus-M with 16-byte nonce + message type as additional data (big-endian uint16)
|
|
- **Compression**: ZSTD (when specified per message type)
|
|
- **Max Data Size**: 1000 bytes per message (including nonce for encrypted messages)
|
|
- **Keepalive**: Send every 30 seconds when idle
|
|
- **Reserved IDs**: 0xFFFFFF00-0xFFFFFFFF for client internal use (256 IDs for local messages, system notifications, etc.)
|
|
|
|
## Message Structure
|
|
|
|
**Client → Server:**
|
|
|
|
```
|
|
┌─────────────┬─────────────┬─────────────────────────┐
|
|
│ Message Type│ Length │ Data │
|
|
│ (2 bytes) │ (2 bytes) │ (0-1000 bytes) │
|
|
└─────────────┴─────────────┴─────────────────────────┘
|
|
```
|
|
|
|
**Server → Client:**
|
|
|
|
```
|
|
┌─────────────┬─────────────┬─────────────┬─────────────────────┐
|
|
│ Message Type│ Sender ID │ Length │ Data │
|
|
│ (2 bytes) │ (4 bytes) │ (2 bytes) │ (0-1000 bytes) │
|
|
└─────────────┴─────────────┴─────────────┴─────────────────────┘
|
|
```
|
|
|
|
_Sender ID is randomly generated per connection to identify message source._
|
|
|
|
## Encryption Implementation
|
|
|
|
**For encrypted messages (types 0x0001, 0x0002, 0x0003, 0x0006, 0x0007):**
|
|
|
|
1. Generate random 16-byte nonce
|
|
2. Prepare additional data: message type as big-endian uint16
|
|
3. Encrypt plaintext using Romulus-M AEAD
|
|
4. Prepend nonce to ciphertext
|
|
5. Total data = nonce (16 bytes) + ciphertext ≤ 1000 bytes
|
|
|
|
## Compression Implementation
|
|
|
|
- **Algorithm**: ZSTD (Zstandard) at default compression level
|
|
- **Application**: Per message type (all messages of type or none)
|
|
- **Order**: Compression applied **before** encryption
|
|
- **Scope**: Only the data portion, headers remain uncompressed
|
|
- **Currently used by**: Advanced Text Messages (0x0006, 0x0007)
|
|
|
|
## Message Types Reference
|
|
|
|
| ID | Name | Subscribable | Encrypted | Compressed | Purpose |
|
|
| ------ | ------------------ | ------------ | --------- | ---------- | ----------------------------- |
|
|
| 0x0000 | Subscribe | ❌ | ❌ | ❌ | Subscribe to message type |
|
|
| 0x0001 | Basic Message | ✅ | ✅ | ❌ | Chat messages |
|
|
| 0x0002 | Request User Data | ✅ | ✅ | ❌ | Request user info |
|
|
| 0x0003 | User Data Response | ✅ | ✅ | ❌ | Respond with user info |
|
|
| 0x0005 | Keepalive | ❌ | ❌ | ❌ | Prevent connection timeout |
|
|
| 0x0006 | Advanced Text | ✅ | ✅ | ✅ | Long/rich text messages |
|
|
| 0x0007 | Edit Advanced Text | ✅ | ✅ | ✅ | Edit/delete advanced text |
|
|
| 0xFFFF | Unsubscribe | ❌ | ❌ | ❌ | Unsubscribe from message type |
|
|
|
|
---
|
|
|
|
## Message Type Specifications
|
|
|
|
### Subscribe (0x0000)
|
|
|
|
Subscribe to receive messages of specified type. Must resubscribe after disconnect.
|
|
|
|
**Data:** Message type to subscribe to (2 bytes, big-endian)
|
|
|
|
---
|
|
|
|
### Basic Message (0x0001)
|
|
|
|
UTF-8 chat messages. 16-byte nonce + encrypted data ≤ 1000 bytes total.
|
|
|
|
**Data:** Encrypted UTF-8 string
|
|
|
|
---
|
|
|
|
### Request User Data (0x0002)
|
|
|
|
Request user information from all users. Clients should respond with User Data Response (0x0003).
|
|
|
|
**Data Structure:**
|
|
|
|
- Username length (2 bytes, big-endian)
|
|
- Username (up to 32 bytes, UTF-8)
|
|
- Color RGB (3 bytes: R, G, B values)
|
|
- Client identifier length (2 bytes, big-endian)
|
|
- Client identifier (up to 32 bytes, UTF-8)
|
|
|
|
---
|
|
|
|
### User Data Response (0x0003)
|
|
|
|
Send user information in response to Request User Data (0x0002).
|
|
|
|
**Data Structure:** Same as Request User Data
|
|
|
|
- Username length (2 bytes, big-endian)
|
|
- Username (up to 32 bytes, UTF-8)
|
|
- Color RGB (3 bytes: R, G, B values)
|
|
- Client identifier length (2 bytes, big-endian)
|
|
- Client identifier (up to 32 bytes, UTF-8)
|
|
|
|
---
|
|
|
|
### Keepalive (0x0005)
|
|
|
|
Prevent connection timeout when idle. Send every 30 seconds when no other traffic. Not forwarded to other clients and cannot be subscribed to.
|
|
|
|
**Data:** None - empty message
|
|
|
|
---
|
|
|
|
### Unsubscribe (0xFFFF)
|
|
|
|
Stop receiving messages of specified type.
|
|
|
|
**Data:** Message type to unsubscribe from (2 bytes, big-endian)
|
|
|
|
---
|
|
|
|
### Advanced Text (0x0006)
|
|
|
|
Multi-packet messages for long text with markdown formatting and ZSTD compression.
|
|
|
|
**Implementation Notes:**
|
|
|
|
- Text is compressed **before** splitting into packets
|
|
- Header is not compressed
|
|
- Packets may arrive out of order - use packet numbers to reconstruct
|
|
- Message ID identifies the complete message, not individual packets
|
|
- Warn users before displaying very large messages
|
|
|
|
**Data Structure:**
|
|
|
|
- Message ID (4 bytes, big-endian)
|
|
- Packet number (2 bytes, big-endian, 0-indexed)
|
|
- Final packet number (2 bytes, big-endian, 0-indexed)
|
|
- Compressed markdown text (remaining bytes, ZSTD)
|
|
|
|
### Edit Advanced Text (0x0007)
|
|
|
|
Edit or delete existing Advanced Text messages. Use same Message ID to replace existing message. Empty compressed text deletes the message. Client replaces original when final packet received.
|
|
|
|
**Data Structure:** Same as Advanced Text (0x0006)
|
|
|
|
---
|
|
|
|
## Implementation Guidelines
|
|
|
|
### Validation Requirements
|
|
|
|
- All length fields must not exceed their specified maximums
|
|
- Username/Client ID lengths must match actual string lengths
|
|
- Message data must not exceed 1000 bytes (including nonce)
|
|
- Packet numbers must be sequential and within final packet range
|
|
|
|
### Connection Lifecycle
|
|
|
|
1. **Connect** to server (TCP/WebSocket)
|
|
2. **Subscribe** to required message types
|
|
3. **Send keepalive** every 30 seconds when idle
|
|
4. **Resubscribe** after any disconnection
|
|
5. **Handle** out-of-order packets for Advanced Text
|
|
|
|
### Common Issues
|
|
|
|
- **Encryption fails**: Ensure message type in additional data matches packet header
|
|
- **Messages dropped**: Check total size ≤ 1000 bytes including nonce
|
|
- **Connection timeout**: Verify keepalive frequency
|
|
- **Advanced Text garbled**: Reconstruct packets in correct order before decompression
|
|
|
|
---
|
|
|
|
## Protocol Features
|
|
|
|
- **Binary pub/sub messaging** with server-side routing
|
|
- **End-to-end encryption** using Romulus-M AEAD
|
|
- **ZSTD compression** for large text messages
|
|
- **Multi-packet support** for long messages
|
|
- **TCP and WebSocket** transport options
|
|
|
|
This is a documentation-only repository. The protocol specification is final and changes are not permitted.
|