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

update doc

Browse Source
This commit is contained in:
narawat
2026-03-24 08:55:06 +07:00
parent 5191f1aae5
commit 14cd4c0076
3 changed files with 258 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
README.md
View File

@@ -1,6 +1,6 @@
# NATSBridge - Cross-Platform Bi-Directional Data Bridge
A high-performance, bi-directional data bridge for **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
A high-performance, bi-directional data bridge for **Julia**, **JavaScript**, **Python**, **Dart**, and **MicroPython** applications using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![NATS](https://img.shields.io/badge/NATS-Enabled-green.svg)](https://nats.io)
@@ -48,33 +48,35 @@ NATSBridge enables seamless communication across multiple platforms through NATS
| **JavaScript (Node.js)** | [`src/natsbridge_ssr.js`](src/natsbridge_ssr.js) | Node.js, async/await, Arrow IPC |
| **JavaScript (Browser)** | [`src/natsbridge_csr.js`](src/natsbridge_csr.js) | Browser, WebSocket NATS, async/await, JSON table only |
| **Python** | [`src/natsbridge.py`](src/natsbridge.py) | Desktop Python, asyncio, type hints, Arrow IPC |
| **Dart (Desktop/Flutter)** | [`src/natsbridge.dart`](src/natsbridge.dart) | Desktop/Flutter, async/await, Arrow IPC |
| **Dart Web** | [`src/natsbridge.dart`](src/natsbridge.dart) | Web, WebSocket NATS, JSON table only |
| **MicroPython** | [`src/natsbridge_mpy.py`](src/natsbridge_mpy.py) | Memory-constrained, synchronous API |
### Platform Comparison
| Feature | Julia | JavaScript | JavaScript (Browser) | Python | MicroPython |
|---------|-------|------------|----------------------|--------|-------------|
| Multiple Dispatch | ✅ Native | ❌ | ❌ | ❌ | ❌ |
| Async/Await | ❌ | ✅ Native | ✅ Native | ✅ Native | ⚠️ (uasyncio) |
| Type Safety | ✅ Strong | ⚠️ (TypeScript) | ⚠️ (TypeScript) | ✅ (Type hints) | ❌ |
| Arrow IPC | ✅ Native | ✅ Native | ❌ (Browser incompatible) | ✅ Native | ❌ |
| JSON Table | ✅ | ✅ | ✅ (Only table type) | ✅ | ⚠️ (Limited) |
| Direct Transport | ✅ | ✅ | ✅ | ✅ | ✅ |
| Link Transport | ✅ | ✅ | ✅ | ✅ | ⚠️ (Limited) |
| Handler Functions | ✅ | ✅ | ✅ | ✅ | ✅ |
| Cross-Platform API | ✅ | ✅ | ✅ | ✅ | ✅ |
| WebSocket NATS | ❌ | ❌ | ✅ | ❌ | ❌ |
| Feature | Julia | JavaScript | JavaScript (Browser) | Python | Dart | Dart Web | MicroPython |
|---------|-------|------------|----------------------|--------|------|----------|-------------|
| Multiple Dispatch | ✅ Native | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Async/Await | ❌ | ✅ Native | ✅ Native | ✅ Native | ✅ Native | ✅ Native | ⚠️ (uasyncio) |
| Type Safety | ✅ Strong | ⚠️ (TypeScript) | ⚠️ (TypeScript) | ✅ (Type hints) | ✅ Strong | ✅ Strong | ❌ |
| Arrow IPC | ✅ Native | ✅ Native | ❌ (Browser incompatible) | ✅ Native | ✅ Native | ❌ (Browser incompatible) | ❌ |
| JSON Table | ✅ | ✅ | ✅ (Only table type) | ✅ | ✅ | ✅ | ⚠️ (Limited) |
| Direct Transport | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Link Transport | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ (Limited) |
| Handler Functions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Cross-Platform API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| WebSocket NATS | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
---
## Features
- ✅ **Cross-platform messaging** for Julia, JavaScript, Python, and MicroPython applications
- ✅ **Cross-platform messaging** for Julia, JavaScript, Python, Dart, and MicroPython applications
- ✅ **Bi-directional messaging** with request-reply patterns
- ✅ **Multi-payload support** - send multiple payloads with different types in one message
- ✅ **Automatic transport selection** - direct vs link based on payload size
- ✅ **Claim-Check pattern** for payloads ≥ 500KB
- ✅ **Apache Arrow IPC** support for tabular data (Desktop: Julia/Python/Node.js)
- ✅ **Apache Arrow IPC** support for tabular data (Desktop: Julia/Python/Node.js/Dart)
- ✅ **JSON Table** support for tabular data (All platforms including Browser)
- ✅ **Exponential backoff** for reliable file server downloads
- ✅ **Correlation ID tracking** for message tracing
@@ -171,6 +173,38 @@ env, env_json_str = smartsend(
print("Message sent!")
```
#### Dart (Desktop/Flutter)
```dart
import 'package:natsbridge/natsbridge.dart';
final data = [
['message', 'Hello World', 'text']
];
final [env, envJsonStr] = await NATSBridge.send(
'/chat/room1',
data,
brokerUrl: 'nats://localhost:4222',
);
print('Message sent!');
```
#### Dart Web
```dart
import 'package:natsbridge/natsbridge.dart';
final data = [
['message', 'Hello World', 'text']
];
final [env, envJsonStr] = await NATSBridge.send(
'/chat/room1',
data,
brokerUrl: 'ws://localhost:4222', // WebSocket for browser
);
print('Message sent!');
```
---
## API Reference
@@ -335,6 +369,54 @@ env, env_json_str = NATSBridge.smartsend(
# Returns: Tuple[Dict, str]
```
#### Dart (Desktop/Flutter)
```dart
import 'package:natsbridge/natsbridge.dart';
final env, envJsonStr = await NATSBridge.send(
subject,
data, // List of [dataname, data, type] lists
brokerUrl: 'nats://localhost:4222',
fileserverUrl: 'http://localhost:8080',
fileserverUploadHandler: plikOneshotUpload,
sizeThreshold: 500000,
correlationId: uuid.v4(),
msgPurpose: 'chat',
senderName: 'NATSBridge',
receiverName: '',
receiverId: '',
replyTo: '',
replyToMsgId: '',
isPublish: true,
);
// Returns: Future<List<dynamic>> [env, env_json_str]
```
#### Dart Web
```dart
import 'package:natsbridge/natsbridge.dart';
final env, envJsonStr = await NATSBridge.send(
subject,
data, // List of [dataname, data, type] lists
brokerUrl: 'ws://localhost:4222', // WebSocket for browser
fileserverUrl: 'http://localhost:8080',
fileserverUploadHandler: plikOneshotUpload,
sizeThreshold: 500000,
correlationId: uuid.v4(),
msgPurpose: 'chat',
senderName: 'NATSBridge',
receiverName: '',
receiverId: '',
replyTo: '',
replyToMsgId: '',
isPublish: true,
);
// Returns: Future<List<dynamic>> [env, env_json_str]
```
### smartreceive
Receives and processes messages from NATS, handling both direct and link transport.
@@ -418,20 +500,50 @@ env = NATSBridge.smartreceive(
# Returns: Dict with "payloads" key
```
#### Dart (Desktop/Flutter)
```dart
import 'package:natsbridge/natsbridge.dart';
final env = await NATSBridge.receive(
msg,
fileserverDownloadHandler: fetchWithBackoff,
maxRetries: 5,
baseDelay: 100,
maxDelay: 5000,
);
// Returns: Future<Map<String, dynamic>> with "payloads" key
```
#### Dart Web
```dart
import 'package:natsbridge/natsbridge.dart';
final env = await NATSBridge.receive(
msg,
fileserverDownloadHandler: fetchWithBackoff,
maxRetries: 5,
baseDelay: 100,
maxDelay: 5000,
);
// Returns: Future<Map<String, dynamic>> with "payloads" key
```
---
## 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 dictionaries |
| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) |
| `jsontable` | `DataFrame`, `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** |
| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Image data (PNG, JPG) |
| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Audio data (WAV, MP3) |
| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Video data (MP4, AVI) |
| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `bytearray` | Generic binary data |
| Type | Julia | JavaScript | Python | Dart | Dart Web | MicroPython | Description |
|------|-------|------------|--------|------|----------|-------------|-------------|
| `text` | `String` | `string` | `str` | `String` | `String` | `str` | Plain text strings |
| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `Map` | `Map` | `dict` | JSON-serializable dictionaries |
| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | `List<Map>` (Desktop/Flutter) | ❌ (Browser incompatible) | ❌ | Tabular data (Arrow IPC) |
| `jsontable` | `DataFrame`, `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | `List<Map>` | `List<Map>` | ⚠️ | Tabular data (JSON) - **Only table type in Browser/Dart Web** |
| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Uint8List` | `bytearray` | Image data (PNG, JPG) |
| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Uint8List` | `bytearray` | Audio data (WAV, MP3) |
| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `Uint8List` | `Uint8List` | `bytearray` | Video data (MP4, AVI) |
| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `Uint8List` | `Uint8List` | `bytearray` | Generic binary data |
---
@@ -721,6 +833,7 @@ env, env_json_str = await NATSBridge.smartsend(
| **Julia** | `test/test_julia_*_sender.jl` | `test/test_julia_*_receiver.jl` |
| **JavaScript** | `test/test_js_*_sender.js` | `test/test_js_*_receiver.js` |
| **Python** | `test/test_py_*_sender.py` | `test/test_py_*_receiver.py` |
| **Dart** | `test/test_dart_*_sender.dart` | `test/test_dart_*_receiver.dart` |
### Run Tests
@@ -788,6 +901,30 @@ python3 test/test_py_table_sender.py
python3 test/test_py_table_receiver.py
```
#### Dart
```bash
# Text message exchange
dart test/test_dart_text_sender.dart
dart test/test_dart_text_receiver.dart
# Dictionary exchange
dart test/test_dart_dictionary_sender.dart
dart test/test_dart_dictionary_receiver.dart
# Binary transfer
dart test/test_dart_binary_sender.dart
dart test/test_dart_binary_receiver.dart
# Mixed payload types
dart test/test_dart_mix_payloads_sender.dart
dart test/test_dart_mix_payloads_receiver.dart
# Table exchange
dart test/test_dart_table_sender.dart
dart test/test_dart_table_receiver.dart
```
---
## Browser Deployment