update
This commit is contained in:
@@ -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, 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
|
||||
|
||||
#### Julia
|
||||
@@ -610,6 +662,34 @@ async function smartreceive(
|
||||
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
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user