ton/NATSBridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

update

Browse Source
This commit is contained in:
narawat
2026-03-23 14:50:00 +07:00
parent fa039f2820
commit 4f141b130e
5 changed files with 252 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
AI_prompt.md
View File

@@ -160,3 +160,13 @@ now help me update the following fileaccording to ASG_Framework/ASG_Framework.md
<!-- ------------------------------------------- 100 ------------------------------------------- --> <!-- ------------------------------------------- 100 ------------------------------------------- -->
Check NATSBridge/docs folder. I would like to expand this package to include Dart support.
Can you update the content of the following files according to ASG_Framework/ASG_Framework.md:
- NATSBridge/docs/requirements.md
- NATSBridge/docs/specification.md
- NATSBridge/docs/walkthrough.md
- NATSBridge/docs/architecture.md

76
docs/architecture.md
View File

@@ -10,7 +10,7 @@
## 1. Executive Summary ## 1. Executive Summary
This document defines the **blueprint** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus. This document defines the **blueprint** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus.
This architecture document serves as the single source of truth for: This architecture document serves as the single source of truth for:
- **System Structure**: How components fit together and interact - **System Structure**: How components fit together and interact
@@ -56,17 +56,20 @@ flowchart TD
Julia_App[Julia Application] Julia_App[Julia Application]
JS_App[JavaScript Application<br/>Node.js/Browser] JS_App[JavaScript Application<br/>Node.js/Browser]
Python_App[Python Application<br/>Desktop] Python_App[Python Application<br/>Desktop]
Dart_App[Dart Application<br/>Desktop/Flutter/Web]
MicroPython_App[MicroPython Device] MicroPython_App[MicroPython Device]
end end
Julia_App -->|NATS| NATS_Server Julia_App -->|NATS| NATS_Server
JS_App -->|NATS| NATS_Server JS_App -->|NATS| NATS_Server
Python_App -->|NATS| NATS_Server Python_App -->|NATS| NATS_Server
Dart_App -->|NATS| NATS_Server
MicroPython_App -->|NATS| NATS_Server MicroPython_App -->|NATS| NATS_Server
Julia_App -->|HTTP| File_Server Julia_App -->|HTTP| File_Server
JS_App -->|HTTP| File_Server JS_App -->|HTTP| File_Server
Python_App -->|HTTP| File_Server Python_App -->|HTTP| File_Server
Dart_App -->|HTTP| File_Server
MicroPython_App -->|HTTP| File_Server MicroPython_App -->|HTTP| File_Server
style NATS_Server fill:#fff3e0,stroke:#f57c00 style NATS_Server fill:#fff3e0,stroke:#f57c00
@@ -74,6 +77,7 @@ flowchart TD
style Julia_App fill:#e8f5e9,stroke:#4caf50 style Julia_App fill:#e8f5e9,stroke:#4caf50
style JS_App fill:#e3f2fd,stroke:#2196f3 style JS_App fill:#e3f2fd,stroke:#2196f3
style Python_App fill:#e3f2fd,stroke:#2196f3 style Python_App fill:#e3f2fd,stroke:#2196f3
style Dart_App fill:#fff0f6,stroke:#e91e63
style MicroPython_App fill:#fce4ec,stroke:#e91e63 style MicroPython_App fill:#fce4ec,stroke:#e91e63
``` ```
@@ -85,6 +89,7 @@ flowchart TD
Julia_Module[Julia NATSBridge Module] Julia_Module[Julia NATSBridge Module]
JS_Module[JavaScript NATSBridge Module] JS_Module[JavaScript NATSBridge Module]
Python_Module[Python NATSBridge Module] Python_Module[Python NATSBridge Module]
Dart_Module[Dart NATSBridge Module]
MicroPython_Module[MicroPython NATSBridge Module] MicroPython_Module[MicroPython NATSBridge Module]
end end
@@ -101,6 +106,7 @@ flowchart TD
Julia_Module --> NATS_Client Julia_Module --> NATS_Client
JS_Module --> NATS_Client JS_Module --> NATS_Client
Python_Module --> NATS_Client Python_Module --> NATS_Client
Dart_Module --> NATS_Client
MicroPython_Module --> NATS_Client MicroPython_Module --> NATS_Client
NATS_Client --> NATS_Broker NATS_Client --> NATS_Broker
@@ -108,6 +114,7 @@ flowchart TD
Julia_Module --> File_Client Julia_Module --> File_Client
JS_Module --> File_Client JS_Module --> File_Client
Python_Module --> File_Client Python_Module --> File_Client
Dart_Module --> File_Client
MicroPython_Module --> File_Client MicroPython_Module --> File_Client
File_Client --> File_Server File_Client --> File_Server
@@ -115,6 +122,7 @@ flowchart TD
style Julia_Module fill:#e8f5e9,stroke:#4caf50 style Julia_Module fill:#e8f5e9,stroke:#4caf50
style JS_Module fill:#e3f2fd,stroke:#2196f3 style JS_Module fill:#e3f2fd,stroke:#2196f3
style Python_Module fill:#e3f2fd,stroke:#2196f3 style Python_Module fill:#e3f2fd,stroke:#2196f3
style Dart_Module fill:#fff0f6,stroke:#e91e63
style MicroPython_Module fill:#fce4ec,stroke:#e91e63 style MicroPython_Module fill:#fce4ec,stroke:#e91e63
style NATS_Broker fill:#fff3e0,stroke:#f57c00 style NATS_Broker fill:#fff3e0,stroke:#f57c00
style File_Server fill:#f3e5f5,stroke:#9c27b4 style File_Server fill:#f3e5f5,stroke:#9c27b4
@@ -180,8 +188,8 @@ flowchart TD
| **_build_envelope** | Build message envelope from payloads | All | | **_build_envelope** | Build message envelope from payloads | All |
| **_build_payload** | Build payload object from serialized data | All | | **_build_payload** | Build payload object from serialized data | All |
| **publish_message** | Publish message to NATS subject | All | | **publish_message** | Publish message to NATS subject | All |
| **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop | | **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop (Julia/JS/Python/Dart) |
| **fileserver_download_handler** | Download payloads from HTTP server | Desktop | | **fileserver_download_handler** | Download payloads from HTTP server | Desktop (Julia/JS/Python/Dart) |
### Data Flow ### Data Flow
@@ -296,8 +304,8 @@ end
|------|-------------|---------------|----------|-----------| |------|-------------|---------------|----------|-----------|
| `text` | Plain text string | UTF-8 bytes | Base64 | All | | `text` | Plain text string | UTF-8 bytes | Base64 | All |
| `dictionary` | JSON object | JSON string | Base64/JSON | All | | `dictionary` | JSON object | JSON string | Base64/JSON | All |
| `arrowtable` | Apache Arrow IPC | Arrow IPC stream | Base64/arrow-ipc | Desktop (Julia/Python/Node.js) | | `arrowtable` | Apache Arrow IPC | Arrow IPC stream | Base64/arrow-ipc | Desktop (Julia/Python/Node.js/Dart) |
| `jsontable` | JSON array of objects | JSON string | Base64/json | All (including Browser) | | `jsontable` | JSON array of objects | JSON string | Base64/json | All (including Browser/Dart Web) |
| `image` | Binary image data | Raw bytes | Base64 | All | | `image` | Binary image data | Raw bytes | Base64 | All |
| `audio` | Binary audio data | Raw bytes | Base64 | All | | `audio` | Binary audio data | Raw bytes | Base64 | All |
| `video` | Binary video data | Raw bytes | Base64 | All | | `video` | Binary video data | Raw bytes | Base64 | All |
@@ -339,7 +347,10 @@ flowchart TD
| Platform | Size Threshold | Notes | | Platform | Size Threshold | Notes |
|----------|----------------|-------| |----------|----------------|-------|
| Desktop (Julia/JS/Python) | 500,000 bytes (0.5MB) | Default threshold | | Desktop (Julia/JS/Python/Dart) | 500,000 bytes (0.5MB) | Default threshold |
| Dart Desktop | 500,000 bytes (0.5MB) | Default threshold |
| Dart Flutter | 500,000 bytes (0.5MB) | Default threshold |
| Dart Web | 500,000 bytes (0.5MB) | Default threshold |
| MicroPython | 100,000 bytes (100KB) | Lower threshold for memory constraints | | MicroPython | 100,000 bytes (100KB) | Lower threshold for memory constraints |
### Transport Selection Flow ### Transport Selection Flow
@@ -510,6 +521,50 @@ class NATSBridge:
self.fileserver_url = fileserver_url or self.DEFAULT_FILESERVER_URL self.fileserver_url = fileserver_url or self.DEFAULT_FILESERVER_URL
``` ```
### Dart Architecture
Dart uses classes for stateful operations with async/await:
- **Class-based NATSBridge**: Encapsulated API
- **Data classes**: Structured data (MsgPayloadV1, MsgEnvelopeV1)
- **Async/await**: I/O operations
- **dart-arrow**: Arrow IPC support (Desktop/Flutter only)
- **HTTP package**: HTTP file server communication
- **nats package**: NATS client with WebSocket support (Dart Web)
```dart
class NATSBridge {
static const DEFAULT_SIZE_THRESHOLD = 500000;
final String brokerUrl;
final String fileserverUrl;
NATSBridge({
this.brokerUrl = 'nats://localhost:4222',
this.fileserverUrl = 'http://localhost:8080',
});
}
```
#### Dart Desktop (Dart SDK)
- **TCP NATS connections**: Uses `nats://` or `tls://` URLs
- **Apache Arrow IPC**: Full support via `dart-arrow`
- **Uint8List for binary data**: Native Dart binary handling
#### Dart Flutter (Dart SDK)
- **TCP NATS connections**: Uses `nats://` or `tls://` URLs
- **Apache Arrow IPC**: Full support via `dart-arrow`
- **Uint8List for binary data**: Native Dart binary handling
#### Dart Web (Dart SDK)
- **WebSocket NATS connections**: Uses `ws://` or `wss://` URLs via `nats` package
- **No Apache Arrow**: Uses `jsontable` for tabular data only
- **Uint8List for binary data**: Browser-compatible binary handling
- **Fetch API**: HTTP file server communication via `http` package
### Browser Architecture ### Browser Architecture
Browser JavaScript has specific constraints due to security and compatibility: Browser JavaScript has specific constraints due to security and compatibility:
@@ -676,7 +731,7 @@ MAX_PAYLOAD_SIZE = 50_000 # 50KB hard limit
|-----------|---------|-------| |-----------|---------|-------|
| NATS Server | 1 instance | Single node for development | | NATS Server | 1 instance | Single node for development |
| File Server | 1 instance | HTTP server for large payloads | | File Server | 1 instance | HTTP server for large payloads |
| Client Memory | 50MB | Desktop platforms | | Client Memory | 50MB | Desktop platforms (Julia/JS/Python/Dart) |
| Client Memory | 256KB | MicroPython devices | | Client Memory | 256KB | MicroPython devices |
### Environment Variables ### Environment Variables
@@ -771,7 +826,7 @@ flowchart TD
| Version | Supported Platforms | | Version | Supported Platforms |
|---------|---------------------| |---------|---------------------|
| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, MicroPython 1.19+ | | v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, MicroPython 1.19+ |
--- ---
@@ -809,6 +864,7 @@ flowchart TD
| [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
| [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
| [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
| [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | specification.md:2-19 (all sections) | FR-001 through FR-014, NFR-101 through NFR-405 |
| [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | FR-005, FR-006, FR-012 | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | FR-005, FR-006, FR-012 |
### 16.3 External Dependencies ### 16.3 External Dependencies
@@ -827,6 +883,10 @@ flowchart TD
| Python | nats-py | Latest | NATS client | specification.md:11 | FR-013, FR-014 | | Python | nats-py | Latest | NATS client | specification.md:11 | FR-013, FR-014 |
| Python | aiohttp | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 | | Python | aiohttp | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 |
| Python | pyarrow | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 | | Python | pyarrow | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 |
| Dart | nats | Latest | NATS client | specification.md:11 | FR-013, FR-014 |
| Dart | http | Latest | HTTP file server | specification.md:11 | FR-008, FR-009 |
| Dart | uuid | Latest | UUID generation | specification.md:11 | FR-011, NFR-401 |
| Dart | dart-arrow | Latest | Arrow IPC support | specification.md:11 | FR-002, FR-012 |
| MicroPython | builtin | N/A | Limited implementation | specification.md:11 | FR-005, FR-006, FR-012 | | MicroPython | builtin | N/A | Limited implementation | specification.md:11 | FR-005, FR-006, FR-012 |
--- ---

55
docs/requirements.md
View File

@@ -11,15 +11,19 @@
### 1.1 Business Goal ### 1.1 Business Goal
NATSBridge is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB) by uploading them to an HTTP file server instead of sending raw binary data over NATS. NATSBridge is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB) by uploading them to an HTTP file server instead of sending raw binary data over NATS.
### 1.2 User Stories (with acceptance criteria) ### 1.2 User Stories (with acceptance criteria)
| Story | Priority | Acceptance Criteria | | Story | Priority | Acceptance Criteria |
|-------|----------|---------------------| |-------|----------|---------------------|
| **As a Julia developer**, I want to send text messages to JavaScript applications that lives on a server and also on a browser | P1 | Text messages are serialized, encoded, and received correctly across platforms | | **As a Julia developer**, I want to send text messages to JavaScript/Dart applications that lives on a server and also on a browser | P1 | Text messages are serialized, encoded, and received correctly across platforms |
| **As a Python developer**, I want to send tabular data to Julia applications | P1 | DataFrame exchange works with both Arrow IPC and JSON formats | | **As a Python developer**, I want to send tabular data to Julia/Dart applications | P1 | DataFrame exchange works with both Arrow IPC and JSON formats |
| **As a JavaScript developer**, I want to send large files (>0.5MB) from JavaScript applications that lives on a server and also on a browser to other applications | P1 | Large files are automatically uploaded to file server and URLs are sent via NATS | | **As a JavaScript developer**, I want to send large files (>0.5MB) from JavaScript applications that lives on a server and also on a browser to other applications | P1 | Large files are automatically uploaded to file server and URLs are sent via NATS |
| **As a Dart developer**, I want to send text messages to other platforms | P1 | Text messages are serialized, encoded, and received correctly across platforms |
| **As a Dart developer**, I want to send dictionary data to other platforms | P1 | JSON-serializable data is exchanged correctly |
| **As a Dart developer**, I want to send tabular data (List<Map>) to other platforms | P1 | JSON table format exchange works with Arrow IPC on desktop |
| **As a Dart developer**, I want to send large files (>0.5MB) | P1 | Large files are automatically uploaded to file server and URLs are sent via NATS |
| **As a MicroPython developer**, I want to send sensor data with minimal memory usage | P1 | Direct transport works for payloads <100KB on memory-constrained devices | | **As a MicroPython developer**, I want to send sensor data with minimal memory usage | P1 | Direct transport works for payloads <100KB on memory-constrained devices |
| **As a developer**, I want to send mixed-content messages (text + image + file) | P1 | NATSBridge accepts list of (dataname, data, type) tuples and handles each payload appropriately | | **As a developer**, I want to send mixed-content messages (text + image + file) | P1 | NATSBridge accepts list of (dataname, data, type) tuples and handles each payload appropriately |
| **As a developer**, I want to receive multi-payload messages | P1 | NATSBridge returns payloads as list of tuples with correct types preserved | | **As a developer**, I want to receive multi-payload messages | P1 | NATSBridge returns payloads as list of tuples with correct types preserved |
@@ -47,7 +51,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
| Feature | Description | | Feature | Description |
|---------|-------------| |---------|-------------|
| Cross-platform interoperability | Seamless data exchange between Julia, JavaScript, Python, and MicroPython | | Cross-platform interoperability | Seamless data exchange between Julia, JavaScript, Python, Dart, and MicroPython |
| Intelligent transport selection | Direct transport (<0.5MB) vs Link transport (≥0.5MB) based on payload size | | Intelligent transport selection | Direct transport (<0.5MB) vs Link transport (≥0.5MB) based on payload size |
| Unified API | Consistent `smartsend()` and `smartreceive()` functions across all platforms | | Unified API | Consistent `smartsend()` and `smartreceive()` functions across all platforms |
| Multi-payload support | List of (dataname, data, type) tuples with appropriate handling | | Multi-payload support | List of (dataname, data, type) tuples with appropriate handling |
@@ -81,6 +85,9 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
| Python | aiohttp | Latest stable | | Python | aiohttp | Latest stable |
| Python | pyarrow | Latest stable | | Python | pyarrow | Latest stable |
| Browser | nats.ws | Latest stable | | Browser | nats.ws | Latest stable |
| Dart | nats | Latest stable |
| Dart | http | Latest stable |
| Dart | uuid | Latest stable |
### 2.4 Platform Compatibility ### 2.4 Platform Compatibility
@@ -90,6 +97,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
| Node.js | 16+ | nats.js required, Arrow IPC supported | | Node.js | 16+ | nats.js required, Arrow IPC supported |
| Python | 3.8+ | pyarrow required for arrowtable support | | Python | 3.8+ | pyarrow required for arrowtable support |
| Browser | Latest | No Arrow IPC (uses jsontable only) | | Browser | Latest | No Arrow IPC (uses jsontable only) |
| Dart | 2.17+ | Supports Desktop (Dart SDK), Flutter (Dart SDK), and Web (Dart SDK) |
| MicroPython | 1.19+ | Limited to direct transport | | MicroPython | 1.19+ | Limited to direct transport |
--- ---
@@ -179,16 +187,16 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
### 6.1 Supported Payload Types ### 6.1 Supported Payload Types
| Type | Julia | JavaScript | Python | MicroPython | Description | | Type | Julia | JavaScript | Python | Dart | MicroPython | Description |
|------|-------|------------|--------|-------------|-------------| |------|-------|------------|--------|------|-------------|-------------|
| `text` | `String` | `string` | `str` | `str` | Plain text strings | | `text` | `String` | `string` | `str` | `String` | `str` | Plain text strings |
| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `dict` | JSON-serializable data | | `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `Map` | `dict` | JSON-serializable data |
| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) | | `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | `List<Map>` (Desktop), `List<dynamic>` (Flutter) | ❌ | Tabular data (Arrow IPC) |
| `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** | | `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | `List<Map>` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** |
| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Image binary data | | `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Image binary data |
| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Audio binary data | | `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Audio binary data |
| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Video binary data | | `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Video binary data |
| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `bytearray` | Generic binary data | | `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `Uint8List` | `bytearray` | Generic binary data |
### 6.2 Encoding Requirements ### 6.2 Encoding Requirements
@@ -208,7 +216,10 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
| Platform | Threshold | Notes | | Platform | Threshold | Notes |
|----------|-----------|-------| |----------|-----------|-------|
| Desktop (Julia/JS/Python) | 0.5MB | Default size threshold | | Desktop (Julia/JS/Python/Dart) | 0.5MB | Default size threshold |
| Dart Desktop | 0.5MB | Default size threshold |
| Dart Flutter | 0.5MB | Default size threshold |
| Dart Web | 0.5MB | Default size threshold |
| MicroPython | 100KB | Lower threshold for memory constraints | | MicroPython | 100KB | Lower threshold for memory constraints |
### 7.2 Maximum Payload Size ### 7.2 Maximum Payload Size
@@ -216,6 +227,9 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless
| Platform | Maximum | Notes | | Platform | Maximum | Notes |
|----------|---------|-------| |----------|---------|-------|
| Desktop | Unlimited | Limited by NATS server configuration | | Desktop | Unlimited | Limited by NATS server configuration |
| Dart Desktop | Unlimited | Limited by NATS server configuration |
| Dart Flutter | Unlimited | Limited by NATS server configuration |
| Dart Web | Unlimited | Limited by NATS server configuration |
| MicroPython | 50KB | Hard limit due to 256KB-1MB memory | | MicroPython | 50KB | Hard limit due to 256KB-1MB memory |
--- ---
@@ -351,7 +365,7 @@ function smartreceive(
|-----------|---------|-------| |-----------|---------|-------|
| NATS Server | 1 instance | Single node for development | | NATS Server | 1 instance | Single node for development |
| File Server | 1 instance | HTTP server for large payloads | | File Server | 1 instance | HTTP server for large payloads |
| Client Memory | 50MB | Desktop platforms | | Client Memory | 50MB | Desktop platforms (Julia/JS/Python/Dart) |
| Client Memory | 256KB | MicroPython devices | | Client Memory | 256KB | MicroPython devices |
### 12.2 Environment Variables ### 12.2 Environment Variables
@@ -376,7 +390,7 @@ function smartreceive(
| Version | Supported Platforms | | Version | Supported Platforms |
|---------|---------------------| |---------|---------------------|
| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Browser (latest), MicroPython 1.19+ | | v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Dart 2.17+, Browser (latest), MicroPython 1.19+ |
--- ---
@@ -390,7 +404,12 @@ function smartreceive(
## 15. References ## 15. References
- [`src/NATSBridge.jl`](../src/NATSBridge.jl) - Ground truth implementation - [`src/NATSBridge.jl`](../src/NATSBridge.jl) - Ground truth implementation (Julia)
- [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) - Server-side JavaScript implementation
- [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) - Client-side JavaScript implementation
- [`src/natsbridge.py`](../src/natsbridge.py) - Python implementation
- [`src/natsbridge.dart`](../src/natsbridge.dart) - Dart implementation
- [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) - MicroPython implementation
- [`README.md`](../README.md) - Project overview - [`README.md`](../README.md) - Project overview
- [`docs/specification.md`](./specification.md) - Technical specification - [`docs/specification.md`](./specification.md) - Technical specification
- [`docs/ui-specification.md`](./ui-specification.md) - UI specification - [`docs/ui-specification.md`](./ui-specification.md) - UI specification

145
docs/specification.md
View File

@@ -10,7 +10,7 @@
## 1. Technical Contract Overview ## 1. Technical Contract Overview
This document defines the **technical contract** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus. This document defines the **technical contract** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus.
This specification serves as the single source of truth for: This specification serves as the single source of truth for:
- **Inputs**: What data structures are accepted by `smartsend()` - **Inputs**: What data structures are accepted by `smartsend()`
@@ -229,8 +229,8 @@ await smartsend("/agent/v1/process", data)
|-------|-------------|---------------------|------------------| |-------|-------------|---------------------|------------------|
| `text` | Plain text string | All | `base64` | | `text` | Plain text string | All | `base64` |
| `dictionary` | JSON object/dictionary | All | `base64`, `json` | | `dictionary` | JSON object/dictionary | All | `base64`, `json` |
| `arrowtable` | Apache Arrow IPC table | Desktop (Julia/Python/Node.js) | `base64`, `arrow-ipc` | | `arrowtable` | Apache Arrow IPC table | Desktop (Julia/Python/Node.js/Dart) | `base64`, `arrow-ipc` |
| `jsontable` | JSON array of objects | All (including Browser) | `base64`, `json` | | `jsontable` | JSON array of objects | All (including Browser/Dart Web) | `base64`, `json` |
| `image` | Binary image data | All | `base64` | | `image` | Binary image data | All | `base64` |
| `audio` | Binary audio data | All | `base64` | | `audio` | Binary audio data | All | `base64` |
| `video` | Binary video data | All | `base64` | | `video` | Binary video data | All | `base64` |
@@ -550,6 +550,58 @@ def smartsend(
) -> Tuple[Dict, str]: ) -> Tuple[Dict, str]:
``` ```
#### Dart (Desktop/Flutter)
```dart
Future<[Map<String, dynamic>, String]> smartsend(
String subject,
List<List<dynamic>> data, {
String brokerUrl = 'nats://localhost:4222',
String fileserverUrl = 'http://localhost:8080',
Function? fileserverUploadHandler,
int sizeThreshold = 500000,
String? correlationId,
String msgPurpose = 'chat',
String senderName = 'NATSBridge',
String receiverName = '',
String receiverId = '',
String replyTo = '',
String replyToMsgId = '',
bool isPublish = true,
dynamic natsConnection,
String? msgId,
String? senderId,
}) async {
// Returns [envelope, jsonString]
}
```
#### Dart Web
```dart
Future<[Map<String, dynamic>, String]> smartsend(
String subject,
List<List<dynamic>> data, {
String brokerUrl = 'nats://localhost:4222',
String fileserverUrl = 'http://localhost:8080',
Function? fileserverUploadHandler,
int sizeThreshold = 500000,
String? correlationId,
String msgPurpose = 'chat',
String senderName = 'NATSBridge',
String receiverName = '',
String receiverId = '',
String replyTo = '',
String replyToMsgId = '',
bool isPublish = true,
dynamic natsConnection,
String? msgId,
String? senderId,
}) async {
// Returns [envelope, jsonString]
}
```
### `smartreceive` Function Signature ### `smartreceive` Function Signature
#### Julia #### Julia
@@ -610,6 +662,34 @@ async function smartreceive(
def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]: def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]:
``` ```
#### Dart (Desktop/Flutter)
```dart
Future<Map<String, dynamic>> smartreceive(
Map<String, dynamic> msg, {
Function? fileserverDownloadHandler,
int maxRetries = 5,
int baseDelay = 100,
int maxDelay = 5000,
}) async {
// Returns envelope with processed payloads
}
```
#### Dart Web
```dart
Future<Map<String, dynamic>> smartreceive(
Map<String, dynamic> msg, {
Function? fileserverDownloadHandler,
int maxRetries = 5,
int baseDelay = 100,
int maxDelay = 5000,
}) async {
// Returns envelope with processed payloads
}
```
--- ---
## File Server Interface ## File Server Interface
@@ -666,11 +746,11 @@ function fileserver_download_handler(
## Platform-Specific Constraints ## Platform-Specific Constraints
### Desktop (Julia/Python/Node.js) ### Desktop (Julia/Python/Node.js/Dart)
| Feature | Status | Notes | | Feature | Status | Notes |
|---------|--------|-------| |---------|--------|-------|
| Arrow IPC | ✅ Supported | Requires Arrow.jl/pyarrow | | Arrow IPC | ✅ Supported | Requires Arrow.jl/pyarrow/dart-arrow |
| JSON table | ✅ Supported | Human-readable format | | JSON table | ✅ Supported | Human-readable format |
| File server upload | ✅ Supported | HTTP/HTTPS | | File server upload | ✅ Supported | HTTP/HTTPS |
| File server download | ✅ Supported | HTTP/HTTPS | | File server download | ✅ Supported | HTTP/HTTPS |
@@ -686,6 +766,36 @@ function fileserver_download_handler(
| File server download | ✅ Supported | HTTP/HTTPS | | File server download | ✅ Supported | HTTP/HTTPS |
| Size threshold | 500KB | Configurable | | Size threshold | 500KB | Configurable |
### Dart Desktop (Dart SDK)
| Feature | Status | Notes |
|---------|--------|-------|
| Arrow IPC | ✅ Supported | Requires dart-arrow package |
| JSON table | ✅ Supported | Human-readable format |
| File server upload | ✅ Supported | HTTP/HTTPS |
| File server download | ✅ Supported | HTTP/HTTPS |
| Size threshold | 500KB | Configurable |
### Dart Flutter (Dart SDK)
| Feature | Status | Notes |
|---------|--------|-------|
| Arrow IPC | ✅ Supported | Requires dart-arrow package |
| JSON table | ✅ Supported | Human-readable format |
| File server upload | ✅ Supported | HTTP/HTTPS |
| File server download | ✅ Supported | HTTP/HTTPS |
| Size threshold | 500KB | Configurable |
### Dart Web (Dart SDK)
| Feature | Status | Notes |
|---------|--------|-------|
| Arrow IPC | ❌ Not supported | Apache Arrow not browser-compatible |
| JSON table | ✅ Supported | Only table type available in browser |
| File server upload | ✅ Supported | HTTP/HTTPS |
| File server download | ✅ Supported | HTTP/HTTPS |
| Size threshold | 500KB | Configurable |
### MicroPython ### MicroPython
| Feature | Status | Notes | | Feature | Status | Notes |
@@ -707,6 +817,7 @@ function fileserver_download_handler(
| [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | Server-side JavaScript | | [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | Server-side JavaScript |
| [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | Client-side rendering | | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | Client-side rendering |
| [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | Desktop Python | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | Desktop Python |
| [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | Desktop/Flutter/Web |
| [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | Memory-constrained | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | Memory-constrained |
### Browser Implementation Notes ### Browser Implementation Notes
@@ -721,16 +832,16 @@ The browser implementation ([`src/natsbridge_csr.js`](../src/natsbridge_csr.js))
### Payload Type Availability by Platform ### Payload Type Availability by Platform
| Payload Type | Julia | Node.js | Browser | Python | MicroPython | | Payload Type | Julia | Node.js | Browser | Python | Dart | MicroPython |
|--------------|-------|---------|---------|--------|-------------| |--------------|-------|---------|---------|--------|------|-------------|
| `text` | ✅ | ✅ | ✅ | ✅ | ✅ | | `text` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | | `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `arrowtable` | ✅ | ✅ | ❌ | ✅ | ❌ | | `arrowtable` | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `jsontable` | ✅ | ✅ | ✅ | ✅ | ⚠️ | | `jsontable` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| `image` | ✅ | ✅ | ✅ | ✅ | ✅ | | `image` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | | `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `video` | ✅ | ✅ | ✅ | ✅ | ✅ | | `video` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | | `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
--- ---
@@ -864,6 +975,10 @@ flowchart TD
| Python | nats-py | Latest | NATS client | | Python | nats-py | Latest | NATS client |
| Python | aiohttp | Latest | HTTP file server | | Python | aiohttp | Latest | HTTP file server |
| Python | pyarrow | Latest | Arrow IPC support | | Python | pyarrow | Latest | Arrow IPC support |
| Dart | nats | Latest | NATS client |
| Dart | http | Latest | HTTP file server |
| Dart | uuid | Latest | UUID generation |
| Dart | dart-arrow | Latest | Arrow IPC support (Desktop/Flutter) |
| MicroPython | builtin | N/A | Limited implementation | | MicroPython | builtin | N/A | Limited implementation |
### Optional Dependencies ### Optional Dependencies

10
docs/walkthrough.md
View File

@@ -9,7 +9,7 @@
## 1. Executive Summary ## 1. Executive Summary
This document provides the **end-to-end trace** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus. This document provides the **end-to-end trace** for NATSBridge - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS as the message bus.
This walkthrough serves as the primary onboarding guide for new developers and explains: This walkthrough serves as the primary onboarding guide for new developers and explains:
- **User scenarios** - Real-world use cases from developer perspective - **User scenarios** - Real-world use cases from developer perspective
@@ -701,7 +701,10 @@ log_trace(correlation_id, "Published to NATS")
| Platform | Threshold | Notes | | Platform | Threshold | Notes |
|----------|-----------|-------| |----------|-----------|-------|
| Desktop (Julia/JS/Python) | 500,000 bytes (0.5MB) | Default threshold | | Desktop (Julia/JS/Python/Dart) | 500,000 bytes (0.5MB) | Default threshold |
| Dart Desktop | 500,000 bytes (0.5MB) | Default threshold |
| Dart Flutter | 500,000 bytes (0.5MB) | Default threshold |
| Dart Web | 500,000 bytes (0.5MB) | Default threshold |
| MicroPython | 100,000 bytes (100KB) | Lower threshold for memory constraints | | MicroPython | 100,000 bytes (100KB) | Lower threshold for memory constraints |
--- ---
@@ -714,7 +717,7 @@ log_trace(correlation_id, "Published to NATS")
|-----------|---------|-------| |-----------|---------|-------|
| NATS Server | 1 instance | Single node for development | | NATS Server | 1 instance | Single node for development |
| File Server | 1 instance | HTTP server for large payloads | | File Server | 1 instance | HTTP server for large payloads |
| Client Memory | 50MB | Desktop platforms | | Client Memory | 50MB | Desktop platforms (Julia/JS/Python/Dart) |
| Client Memory | 256KB | MicroPython devices | | Client Memory | 256KB | MicroPython devices |
### Environment Variables ### Environment Variables
@@ -757,6 +760,7 @@ log_trace(correlation_id, "Published to NATS")
| [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) | | [`src/natsbridge_ssr.js`](../src/natsbridge_ssr.js) | Node.js | Arrow IPC, async/await | specification.md:2-19 (all sections) |
| [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) | | [`src/natsbridge_csr.js`](../src/natsbridge_csr.js) | Browser | JSON table only, WebSocket NATS | specification.md:2-19 (all sections) |
| [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) | | [`src/natsbridge.py`](../src/natsbridge.py) | Python | Arrow IPC, async/await | specification.md:2-19 (all sections) |
| [`src/natsbridge.dart`](../src/natsbridge.dart) | Dart | Full feature set, Arrow IPC, async/await | specification.md:2-19 (all sections) |
| [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) | | [`src/natsbridge_mpy.py`](../src/natsbridge_mpy.py) | MicroPython | Limited to direct transport | specification.md:2-19 (all sections) |
--- ---