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

rename to smartpack n smartunpack

Browse Source
This commit is contained in:
narawat
2026-05-18 19:30:58 +07:00
parent cc95bc97d3
commit 396e0848da
21 changed files with 323 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/specification.md
View File

@@ -13,8 +13,8 @@
This document defines the **technical contract** for msghandler - the cross-platform bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Dart**, **Rust**, and **MicroPython** applications using a message broker as the transport layer.
This specification serves as the single source of truth for:
- **Inputs**: What data structures are accepted by `smartsend()`
- **Outputs**: What data structures are returned by `smartreceive()`
- **Inputs**: What data structures are accepted by `smartpack()`
- **Outputs**: What data structures are returned by `smartunpack()`
- **Data Shapes**: Exact field names, types, and constraints
- **Error Codes**: Standardized error responses for failure scenarios
@@ -24,7 +24,7 @@ This specification serves as the single source of truth for:
|----------------------|-------------------|-------------|
| Section 2 (Message Envelope) | FR-012, FR-013, NFR-101, NFR-102 | Message envelope structure and validation |
| Section 3 (Payload Schema) | FR-001, FR-002, FR-003, FR-004, NFR-101, NFR-102 | Payload structure and field definitions |
| Section 4 (Payload Format) | FR-006, FR-007 | Tuple format for smartsend() |
| Section 4 (Payload Format) | FR-006, FR-007 | Tuple format for smartpack() |
| Section 5 (Enumerations) | FR-003, FR-004, FR-006, NFR-101 | Enumerations for transport and encoding |
| Section 6 (Transport Protocols) | FR-003, FR-004, NFR-104, NFR-105 | Direct and link transport protocols |
| Section 7 (Size Thresholds) | FR-004, FR-005, NFR-104, NFR-105 | Size thresholds for transport selection |
@@ -143,9 +143,9 @@ This specification serves as the single source of truth for:
## Payload Format
### Tuple Format for `smartsend()`
### Tuple Format for `smartpack()`
The `smartsend()` function accepts data as an array of tuples with the format:
The `smartpack()` function accepts data as an array of tuples with the format:
```
("data_name", data, "data_type")
@@ -161,17 +161,17 @@ The `smartsend()` function accepts data as an array of tuples with the format:
```julia
# Julia
smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])
smartpack("/chat/user/v1/message", [("msg", "Hello World", "text")])
```
```python
# Python
await smartsend("/chat/user/v1/message", [("msg", "Hello World", "text")])
await smartpack("/chat/user/v1/message", [("msg", "Hello World", "text")])
```
```typescript
// JavaScript
await smartsend("/chat/user/v1/message", [["msg", "Hello World", "text"]]);
await smartpack("/chat/user/v1/message", [["msg", "Hello World", "text"]]);
```
### Multiple Payloads Example
@@ -182,7 +182,7 @@ data = [
("msg", "Hello", "text"),
("img", binary_data, "image")
]
smartsend("/agent/v1/process", data)
smartpack("/agent/v1/process", data)
```
```python
@@ -191,7 +191,7 @@ data = [
("msg", "Hello", "text"),
("img", binary_data, "image")
]
await smartsend("/agent/v1/process", data)
await smartpack("/agent/v1/process", data)
```
### Data Type Mapping
@@ -411,12 +411,12 @@ When `transport = "link"`, the `data` field contains a URL pointing to the uploa
## API Contract
### `smartsend` Function Signature
### `smartpack` Function Signature
#### Julia
```julia
function smartsend(
function smartpack(
subject::String,
data::AbstractArray{Tuple{String, T1, String}, 1};
broker_url::String = DEFAULT_BROKER_URL,
@@ -440,7 +440,7 @@ function smartsend(
#### Python
```python
async def smartsend(
async def smartpack(
subject: str,
data: List[Tuple[str, Any, str]],
broker_url: str = DEFAULT_BROKER_URL,
@@ -464,7 +464,7 @@ async def smartsend(
#### JavaScript (Node.js)
```typescript
async function smartsend(
async function smartpack(
subject: string,
data: Array<[string, any, string]>,
options?: {
@@ -490,7 +490,7 @@ async function smartsend(
#### JavaScript (Browser)
```typescript
async function smartsend(
async function smartpack(
subject: string,
data: Array<[string, any, string]>,
options?: {
@@ -516,7 +516,7 @@ async function smartsend(
#### MicroPython
```python
def smartsend(
def smartpack(
subject: str,
data: List[Tuple[str, Any, str]],
size_threshold: int = 100_000, # Lower threshold for memory constraints
@@ -529,7 +529,7 @@ def smartsend(
#### Dart (Desktop/Flutter)
```dart
Future<[Map<String, dynamic>, String]> smartsend(
Future<[Map<String, dynamic>, String]> smartpack(
String subject,
List<List<dynamic>> data, {
String brokerUrl = DEFAULT_BROKER_URL,
@@ -553,7 +553,7 @@ Future<[Map<String, dynamic>, String]> smartsend(
#### Dart Web
```dart
Future<[Map<String, dynamic>, String]> smartsend(
Future<[Map<String, dynamic>, String]> smartpack(
String subject,
List<List<dynamic>> data, {
String brokerUrl = DEFAULT_BROKER_URL,
@@ -578,14 +578,14 @@ Future<[Map<String, dynamic>, String]> smartsend(
#### Rust
```rust
pub async fn smartsend(
pub async fn smartpack(
subject: &str,
data: &[(String, Payload, String)],
options: &SmartsendOptions,
options: &smartpackOptions,
) -> Result<(MsgEnvelopeV1, String), msghandlerError>
// SmartsendOptions struct
pub struct SmartsendOptions {
// smartpackOptions struct
pub struct smartpackOptions {
pub broker_url: String,
pub fileserver_url: String,
pub fileserver_upload_handler: Option<UploadHandler>,
@@ -636,12 +636,12 @@ pub struct MsgEnvelopeV1 {
**Note**: Publishing via the transport layer is the caller's responsibility. Returns `Result<(MsgEnvelopeV1, String), msghandlerError>`. Uses `serde` for JSON serialization.
### `smartreceive` Function Signature
### `smartunpack` Function Signature
#### Julia
```julia
function smartreceive(
function smartunpack(
msg_json_str::String; # Pass payload from transport subscription
fileserver_download_handler::Function = _fetch_with_backoff,
max_retries::Int = 5,
@@ -655,7 +655,7 @@ function smartreceive(
#### Python
```python
async def smartreceive(
async def smartunpack(
msg_json_str: str, # JSON string from transport message payload
fileserver_download_handler: Callable = fetch_with_backoff,
max_retries: int = 5,
@@ -669,7 +669,7 @@ async def smartreceive(
#### JavaScript (Node.js)
```typescript
async function smartreceive(
async function smartunpack(
msg_json_str: string, // JSON string from transport message payload
options?: {
fileserver_download_handler?: Function;
@@ -683,7 +683,7 @@ async function smartreceive(
#### JavaScript (Browser)
```typescript
async function smartreceive(
async function smartunpack(
msg_json_str: string, // JSON string from transport message payload
options?: {
fileserver_download_handler?: Function;
@@ -699,7 +699,7 @@ async function smartreceive(
#### MicroPython
```python
def smartreceive(msg_json_str: str, **kwargs) -> Dict[str, Any]:
def smartunpack(msg_json_str: str, **kwargs) -> Dict[str, Any]:
```
**Note**: Input is the JSON string payload from the transport message.
@@ -707,7 +707,7 @@ def smartreceive(msg_json_str: str, **kwargs) -> Dict[str, Any]:
#### Dart (Desktop/Flutter)
```dart
Future<Map<String, dynamic>> smartreceive(
Future<Map<String, dynamic>> smartunpack(
Map<String, dynamic> msg_json_str, // JSON object from transport message payload
{
Function? fileserverDownloadHandler,
@@ -722,7 +722,7 @@ Future<Map<String, dynamic>> smartreceive(
#### Dart Web
```dart
Future<Map<String, dynamic>> smartreceive(
Future<Map<String, dynamic>> smartunpack(
Map<String, dynamic> msg_json_str, // JSON object from transport message payload
{
Function? fileserverDownloadHandler,
@@ -737,13 +737,13 @@ Future<Map<String, dynamic>> smartreceive(
#### Rust
```rust
pub async fn smartreceive(
pub async fn smartunpack(
msg_json_str: &str, // JSON string from transport message payload
options: &SmartreceiveOptions,
options: &smartunpackOptions,
) -> Result<MsgEnvelopeV1, msghandlerError>
// SmartreceiveOptions struct
pub struct SmartreceiveOptions {
// smartunpackOptions struct
pub struct smartunpackOptions {
pub fileserver_download_handler: Option<DownloadHandler>,
pub max_retries: u32,
pub base_delay: u64,
@@ -933,7 +933,7 @@ The browser implementation ([`src/msghandler_csr.js`](../src/msghandler_csr.js))
```mermaid
flowchart TD
A[User calls smartsend subject data] --> B[Serialize payload according to payload_type]
A[User calls smartpack subject data] --> B[Serialize payload according to payload_type]
B --> C{Calculate serialized size}
C -->|Size < Threshold| D[Direct Transport: Encode as Base64]
C -->|Size >= Threshold| E[Link Transport: Upload to file server]
@@ -1156,8 +1156,8 @@ flowchart TD
| - | - | Updated all NATS references to generic "transport layer"/"message broker" | All |
| - | - | Removed NATS client packages from dependencies tables | All |
| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/msghandler.jl) | All |
| - | - | Updated smartsend signatures: removed is_publish, nats_connection; added sender_name | FR-001 through FR-014 |
| - | - | Updated smartreceive signatures: takes msg_json_str::String instead of msg | FR-001 through FR-014 |
| - | - | Updated smartpack signatures: removed is_publish, nats_connection; added sender_name | FR-001 through FR-014 |
| - | - | Updated smartunpack signatures: takes msg_json_str::String instead of msg | FR-001 through FR-014 |
| - | - | Removed publishMessage function and NATSClient/NATSConnectionPool classes from browser section | FR-013, FR-014 |
| - | - | Added plik_oneshot_upload(filepath) overload to file server interface | FR-008, FR-009 |
| - | - | Fixed SIZE_THRESHOLD default to 500,000 bytes | FR-003, FR-004 |