diff --git a/AI_prompt.md b/AI_prompt.md index 77d6779..318f4dc 100644 --- a/AI_prompt.md +++ b/AI_prompt.md @@ -160,3 +160,13 @@ now help me update the following fileaccording to ASG_Framework/ASG_Framework.md +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 + + + + diff --git a/docs/architecture.md b/docs/architecture.md index d33127a..592fd7d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -10,7 +10,7 @@ ## 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: - **System Structure**: How components fit together and interact @@ -56,17 +56,20 @@ flowchart TD Julia_App[Julia Application] JS_App[JavaScript Application
Node.js/Browser] Python_App[Python Application
Desktop] + Dart_App[Dart Application
Desktop/Flutter/Web] MicroPython_App[MicroPython Device] end Julia_App -->|NATS| NATS_Server JS_App -->|NATS| NATS_Server Python_App -->|NATS| NATS_Server + Dart_App -->|NATS| NATS_Server MicroPython_App -->|NATS| NATS_Server Julia_App -->|HTTP| File_Server JS_App -->|HTTP| File_Server Python_App -->|HTTP| File_Server + Dart_App -->|HTTP| File_Server MicroPython_App -->|HTTP| File_Server style NATS_Server fill:#fff3e0,stroke:#f57c00 @@ -74,6 +77,7 @@ flowchart TD style Julia_App fill:#e8f5e9,stroke:#4caf50 style JS_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 ``` @@ -85,6 +89,7 @@ flowchart TD Julia_Module[Julia NATSBridge Module] JS_Module[JavaScript NATSBridge Module] Python_Module[Python NATSBridge Module] + Dart_Module[Dart NATSBridge Module] MicroPython_Module[MicroPython NATSBridge Module] end @@ -101,6 +106,7 @@ flowchart TD Julia_Module --> NATS_Client JS_Module --> NATS_Client Python_Module --> NATS_Client + Dart_Module --> NATS_Client MicroPython_Module --> NATS_Client NATS_Client --> NATS_Broker @@ -108,6 +114,7 @@ flowchart TD Julia_Module --> File_Client JS_Module --> File_Client Python_Module --> File_Client + Dart_Module --> File_Client MicroPython_Module --> File_Client File_Client --> File_Server @@ -115,6 +122,7 @@ flowchart TD style Julia_Module fill:#e8f5e9,stroke:#4caf50 style JS_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 NATS_Broker fill:#fff3e0,stroke:#f57c00 style File_Server fill:#f3e5f5,stroke:#9c27b4 @@ -180,8 +188,8 @@ flowchart TD | **_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 | -| **fileserver_upload_handler** | Upload large payloads to HTTP server | Desktop | -| **fileserver_download_handler** | Download payloads from 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 (Julia/JS/Python/Dart) | ### Data Flow @@ -296,8 +304,8 @@ end |------|-------------|---------------|----------|-----------| | `text` | Plain text string | UTF-8 bytes | Base64 | All | | `dictionary` | JSON object | JSON string | Base64/JSON | All | -| `arrowtable` | Apache Arrow IPC | Arrow IPC stream | Base64/arrow-ipc | Desktop (Julia/Python/Node.js) | -| `jsontable` | JSON array of objects | JSON string | Base64/json | All (including Browser) | +| `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/Dart Web) | | `image` | Binary image data | Raw bytes | Base64 | All | | `audio` | Binary audio data | Raw bytes | Base64 | All | | `video` | Binary video data | Raw bytes | Base64 | All | @@ -339,7 +347,10 @@ flowchart TD | 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 | ### Transport Selection Flow @@ -510,6 +521,50 @@ class NATSBridge: 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 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 | | 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 | ### Environment Variables @@ -771,7 +826,7 @@ flowchart TD | 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_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.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 | ### 16.3 External Dependencies @@ -827,6 +883,10 @@ flowchart TD | 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 | 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 | --- diff --git a/docs/requirements.md b/docs/requirements.md index 4efd51e..ed178da 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -11,15 +11,19 @@ ### 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) | 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 Python developer**, I want to send tabular data to Julia applications | P1 | DataFrame exchange works with both Arrow IPC and JSON formats | +| **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/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 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) 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 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 | @@ -47,7 +51,7 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | 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 | | Unified API | Consistent `smartsend()` and `smartreceive()` functions across all platforms | | 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 | pyarrow | Latest stable | | Browser | nats.ws | Latest stable | +| Dart | nats | Latest stable | +| Dart | http | Latest stable | +| Dart | uuid | Latest stable | ### 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 | | Python | 3.8+ | pyarrow required for arrowtable support | | 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 | --- @@ -179,16 +187,16 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless ### 6.1 Supported Payload Types -| Type | Julia | JavaScript | Python | MicroPython | Description | -|------|-------|------------|--------|-------------|-------------| -| `text` | `String` | `string` | `str` | `str` | Plain text strings | -| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `dict` | JSON-serializable data | -| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) | -| `jsontable` | `Vector{NamedTuple}` | `Array` | `list[dict]` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** | -| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Image binary data | -| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Audio binary data | -| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Video binary data | -| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `bytearray` | Generic binary data | +| Type | Julia | JavaScript | Python | Dart | MicroPython | Description | +|------|-------|------------|--------|------|-------------|-------------| +| `text` | `String` | `string` | `str` | `String` | `str` | Plain text strings | +| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `Map` | `dict` | JSON-serializable data | +| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | `List` (Desktop), `List` (Flutter) | ❌ | Tabular data (Arrow IPC) | +| `jsontable` | `Vector{NamedTuple}` | `Array` | `list[dict]` | `List` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** | +| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Image binary data | +| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Audio binary data | +| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `bytearray` | Video binary data | +| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `Uint8List` | `bytearray` | Generic binary data | ### 6.2 Encoding Requirements @@ -208,7 +216,10 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | 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 | ### 7.2 Maximum Payload Size @@ -216,6 +227,9 @@ NATSBridge is a cross-platform, bi-directional data bridge that enables seamless | Platform | Maximum | Notes | |----------|---------|-------| | 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 | --- @@ -351,7 +365,7 @@ function smartreceive( |-----------|---------|-------| | NATS Server | 1 instance | Single node for development | | 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 | ### 12.2 Environment Variables @@ -376,7 +390,7 @@ function smartreceive( | 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 -- [`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 - [`docs/specification.md`](./specification.md) - Technical specification - [`docs/ui-specification.md`](./ui-specification.md) - UI specification diff --git a/docs/specification.md b/docs/specification.md index e9dedad..e97bf91 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -10,7 +10,7 @@ ## 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: - **Inputs**: What data structures are accepted by `smartsend()` @@ -229,8 +229,8 @@ await smartsend("/agent/v1/process", data) |-------|-------------|---------------------|------------------| | `text` | Plain text string | All | `base64` | | `dictionary` | JSON object/dictionary | All | `base64`, `json` | -| `arrowtable` | Apache Arrow IPC table | Desktop (Julia/Python/Node.js) | `base64`, `arrow-ipc` | -| `jsontable` | JSON array of objects | All (including Browser) | `base64`, `json` | +| `arrowtable` | Apache Arrow IPC table | Desktop (Julia/Python/Node.js/Dart) | `base64`, `arrow-ipc` | +| `jsontable` | JSON array of objects | All (including Browser/Dart Web) | `base64`, `json` | | `image` | Binary image data | All | `base64` | | `audio` | Binary audio data | All | `base64` | | `video` | Binary video data | All | `base64` | @@ -550,6 +550,58 @@ def smartsend( ) -> Tuple[Dict, str]: ``` +#### Dart (Desktop/Flutter) + +```dart +Future<[Map, String]> smartsend( + String subject, + List> 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]> smartsend( + String subject, + List> 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 #### Julia @@ -610,6 +662,34 @@ async function smartreceive( def smartreceive(msg: Any, **kwargs) -> Dict[str, Any]: ``` +#### Dart (Desktop/Flutter) + +```dart +Future> smartreceive( + Map msg, { + Function? fileserverDownloadHandler, + int maxRetries = 5, + int baseDelay = 100, + int maxDelay = 5000, +}) async { + // Returns envelope with processed payloads +} +``` + +#### Dart Web + +```dart +Future> smartreceive( + Map msg, { + Function? fileserverDownloadHandler, + int maxRetries = 5, + int baseDelay = 100, + int maxDelay = 5000, +}) async { + // Returns envelope with processed payloads +} +``` + --- ## File Server Interface @@ -666,11 +746,11 @@ function fileserver_download_handler( ## Platform-Specific Constraints -### Desktop (Julia/Python/Node.js) +### Desktop (Julia/Python/Node.js/Dart) | 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 | | File server upload | ✅ Supported | HTTP/HTTPS | | File server download | ✅ Supported | HTTP/HTTPS | @@ -686,6 +766,36 @@ function fileserver_download_handler( | File server download | ✅ Supported | HTTP/HTTPS | | 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 | 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_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.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 | ### 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 | Julia | Node.js | Browser | Python | MicroPython | -|--------------|-------|---------|---------|--------|-------------| -| `text` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `arrowtable` | ✅ | ✅ | ❌ | ✅ | ❌ | -| `jsontable` | ✅ | ✅ | ✅ | ✅ | ⚠️ | -| `image` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `video` | ✅ | ✅ | ✅ | ✅ | ✅ | -| `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | +| Payload Type | Julia | Node.js | Browser | Python | Dart | MicroPython | +|--------------|-------|---------|---------|--------|------|-------------| +| `text` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `dictionary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `arrowtable` | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | +| `jsontable` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ | +| `image` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `audio` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `video` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| `binary` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | --- @@ -864,6 +975,10 @@ flowchart TD | Python | nats-py | Latest | NATS client | | Python | aiohttp | Latest | HTTP file server | | 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 | ### Optional Dependencies diff --git a/docs/walkthrough.md b/docs/walkthrough.md index 3c86170..4f5c554 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough.md @@ -9,7 +9,7 @@ ## 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: - **User scenarios** - Real-world use cases from developer perspective @@ -701,7 +701,10 @@ log_trace(correlation_id, "Published to NATS") | 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 | --- @@ -714,7 +717,7 @@ log_trace(correlation_id, "Published to NATS") |-----------|---------|-------| | NATS Server | 1 instance | Single node for development | | 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 | ### 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_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.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) | ---