Initial updates
This commit is contained in:
191
BENNC_PROTOCOL_SPEC.md
Normal file
191
BENNC_PROTOCOL_SPEC.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user