update docs
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
# Architecture Documentation: NATSBridge
|
||||
|
||||
**Version**: 1.1.0
|
||||
**Date**: 2026-03-23
|
||||
**Version**: 1.2.0
|
||||
**Date**: 2026-05-13
|
||||
**Status**: Active
|
||||
**Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl)
|
||||
**Architecture Level**: C4 Container Level
|
||||
@@ -139,36 +139,31 @@ flowchart TD
|
||||
Serialize[_serialize_data]
|
||||
Deserialize[_deserialize_data]
|
||||
|
||||
BuildEnvelope[build_envelope]
|
||||
BuildPayload[build_payload]
|
||||
|
||||
PublishMessage[publish_message]
|
||||
EnvelopeToJson[envelope_to_json]
|
||||
|
||||
FileServerUpload[fileserver_upload_handler]
|
||||
FileServerDownload[fileserver_download_handler]
|
||||
|
||||
LogTrace[log_trace]
|
||||
end
|
||||
|
||||
subgraph "Data Models"
|
||||
Payload[MsgPayloadV1 Struct]
|
||||
Envelope[MsgEnvelopeV1 Struct]
|
||||
Payload[msg_payload_v1 Struct]
|
||||
Envelope[msg_envelope_v1 Struct]
|
||||
end
|
||||
|
||||
SmartSend --> Serialize
|
||||
SmartSend --> BuildEnvelope
|
||||
SmartSend --> BuildPayload
|
||||
SmartSend --> PublishMessage
|
||||
SmartSend --> EnvelopeToJson
|
||||
SmartSend --> FileServerUpload
|
||||
|
||||
|
||||
SmartReceive --> Deserialize
|
||||
SmartReceive --> FileServerDownload
|
||||
|
||||
|
||||
EnvelopeToJson --> Envelope
|
||||
Serialize --> Payload
|
||||
BuildEnvelope --> Envelope
|
||||
BuildPayload --> Payload
|
||||
|
||||
style SmartSend fill:#d1fae5,stroke:#10b981
|
||||
style SmartReceive fill:#d1fae5,stroke:#10b981
|
||||
style PublishMessage fill:#fef3c7,stroke:#f59e0b
|
||||
style FileServerUpload fill:#fef3c7,stroke:#f59e0b
|
||||
style FileServerDownload fill:#fef3c7,stroke:#f59e0b
|
||||
```
|
||||
@@ -181,15 +176,14 @@ flowchart TD
|
||||
|
||||
| Component | Purpose | Platform Support |
|
||||
|-----------|---------|------------------|
|
||||
| **smartsend** | Send data via NATS with automatic transport selection | All |
|
||||
| **smartreceive** | Receive and process NATS messages | All |
|
||||
| **smartsend** | Send data via NATS with automatic transport selection, returns (envelope, json_string) for caller to publish | All |
|
||||
| **smartreceive** | Receive and process NATS messages from JSON string | All |
|
||||
| **_serialize_data** | Serialize data according to payload type | All |
|
||||
| **_deserialize_data** | Deserialize bytes to native data types | All |
|
||||
| **_build_envelope** | Build message envelope from payloads | All |
|
||||
| **_build_payload** | Build payload object from serialized data | All |
|
||||
| **publish_message** | Publish message to NATS subject | All |
|
||||
| **envelope_to_json** | Convert msg_envelope_v1 struct to JSON string | All |
|
||||
| **log_trace** | Log trace messages with correlation ID | All |
|
||||
| **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop (Julia/JS/Python/Dart) |
|
||||
| **fileserver_download_handler** | Download payloads from HTTP server | Desktop (Julia/JS/Python/Dart) |
|
||||
| **fileserver_download_handler** | Download payloads from HTTP server with exponential backoff | Desktop (Julia/JS/Python/Dart) |
|
||||
|
||||
### Data Flow
|
||||
|
||||
@@ -211,7 +205,7 @@ flowchart TD
|
||||
|
||||
H --> L[Build envelope]
|
||||
L --> M[Convert to JSON]
|
||||
M --> N[Publish to NATS]
|
||||
M --> N[Return envelope + JSON to caller]
|
||||
|
||||
style A fill:#f9f9f9,stroke:#333
|
||||
style N fill:#e0e7ff,stroke:#3b82f6
|
||||
@@ -437,11 +431,9 @@ end
|
||||
|
||||
JavaScript uses async/await for non-blocking I/O:
|
||||
|
||||
- **Class-based NATS Client**: Connection management with `keepAlive` support
|
||||
- **Module-level Utilities**: Serialization functions
|
||||
- **Native ArrayBuffer**: Binary data handling (Browser) / Buffer (Node.js)
|
||||
- **Fetch API**: HTTP file server communication
|
||||
- **Connection Pooling**: `NATSConnectionPool` for high-throughput scenarios
|
||||
|
||||
#### Node.js Implementation (natsbridge_ssr.js)
|
||||
|
||||
@@ -449,36 +441,6 @@ JavaScript uses async/await for non-blocking I/O:
|
||||
- **Apache Arrow IPC**: Full support via `apache-arrow`
|
||||
- **Buffer for binary data**: Native Node.js Buffer handling
|
||||
|
||||
```javascript
|
||||
// Class-based NATS client with keepAlive support
|
||||
class NATSClient {
|
||||
constructor(url, keepAlive = false) {
|
||||
this.url = url;
|
||||
this.connection = null;
|
||||
this.keepAlive = keepAlive;
|
||||
}
|
||||
|
||||
async connect() {
|
||||
if (this.connection) return this.connection;
|
||||
this.connection = await nats.connect({ servers: this.url });
|
||||
return this.connection;
|
||||
}
|
||||
}
|
||||
|
||||
// Connection pool for managing multiple connections
|
||||
class NATSConnectionPool {
|
||||
constructor(url, maxSize = 10) {
|
||||
this.url = url;
|
||||
this.maxSize = maxSize;
|
||||
this.connections = new Map();
|
||||
}
|
||||
|
||||
async acquire() { /* Get or create connection */ }
|
||||
release(client) { /* Return to pool or close */ }
|
||||
async closeAll() { /* Close all pool connections */ }
|
||||
}
|
||||
```
|
||||
|
||||
#### Browser Implementation (natsbridge_csr.js)
|
||||
|
||||
- **WebSocket NATS connections**: Uses `ws://` or `wss://` URLs via `nats.ws`
|
||||
@@ -486,23 +448,6 @@ class NATSConnectionPool {
|
||||
- **Uint8Array for binary data**: Browser-compatible binary handling
|
||||
- **Web Crypto API**: UUID generation via `crypto.getRandomValues()`
|
||||
|
||||
```javascript
|
||||
// Class-based NATS client with keepAlive support
|
||||
class NATSClient {
|
||||
constructor(url, keepAlive = false) {
|
||||
this.url = url; // ws:// or wss://
|
||||
this.connection = null;
|
||||
this.keepAlive = keepAlive;
|
||||
}
|
||||
|
||||
async connect() {
|
||||
if (this.connection) return this.connection;
|
||||
this.connection = await nats.connect({ servers: this.url });
|
||||
return this.connection;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Python Architecture
|
||||
|
||||
Python uses classes for stateful operations:
|
||||
@@ -740,7 +685,7 @@ MAX_PAYLOAD_SIZE = 50_000 # 50KB hard limit
|
||||
|----------|---------|-------------|
|
||||
| `NATS_URL` | `nats://localhost:4222` | NATS server URL |
|
||||
| `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL |
|
||||
| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes |
|
||||
| `SIZE_THRESHOLD` | `500000` | Size threshold in bytes (0.5MB) |
|
||||
|
||||
### Container Deployment
|
||||
|
||||
@@ -834,6 +779,12 @@ flowchart TD
|
||||
|
||||
| Date | Version | Changes |
|
||||
|------|---------|---------|
|
||||
| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) |
|
||||
| - | - | Removed publish_message component (commented out in source) |
|
||||
| - | - | Removed NATSClient and NATSConnectionPool classes (not in ground truth) |
|
||||
| - | - | Updated component diagram to match actual module structure |
|
||||
| - | - | Updated data flow to show smartsend returns JSON for caller to publish |
|
||||
| - | - | Fixed SIZE_THRESHOLD default to 500,000 bytes |
|
||||
| 2026-03-15 | 1.1.0 | JavaScript connection management |
|
||||
| - | - | Added NATSClient with keepAlive support |
|
||||
| - | - | Added NATSConnectionPool for connection reuse |
|
||||
|
||||
Reference in New Issue
Block a user