Files

narawat 3e1c8d563e update

2026-02-25 15:20:29 +07:00

39 KiB

Raw Blame History

Implementation Guide: Bi-Directional Data Bridge

Overview

This document describes the implementation of the high-performance, bi-directional data bridge between Julia, JavaScript, and Python/Micropython applications using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.

The system enables seamless communication across all three platforms:

Julia ↔ JavaScript bi-directional messaging
JavaScript ↔ Python/Micropython bi-directional messaging
Julia ↔ Python/Micropython bi-directional messaging (via JSON serialization)

Implementation Files

NATSBridge is implemented in three languages, each providing the same API:

Language	Implementation File	Description
Julia	`src/NATSBridge.jl`	Full Julia implementation with Arrow IPC support
JavaScript	`src/NATSBridge.js`	JavaScript implementation for Node.js and browsers
Python/Micropython	`src/nats_bridge.py`	Python implementation for desktop and microcontrollers

File Server Handler Architecture

The system uses handler functions to abstract file server operations, allowing support for different file server implementations (e.g., Plik, AWS S3, custom HTTP server).

Handler Function Signatures:

# Upload handler - uploads data to file server and returns URL
# The handler is passed to smartsend as fileserver_upload_handler parameter
# It receives: (fileserver_url::String, dataname::String, data::Vector{UInt8})
# Returns: Dict{String, Any} with keys: "status", "uploadid", "fileid", "url"
fileserver_upload_handler(fileserver_url::String, dataname::String, data::Vector{UInt8})::Dict{String, Any}

# Download handler - fetches data from file server URL with exponential backoff
# The handler is passed to smartreceive as fileserver_download_handler parameter
# It receives: (url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)
# Returns: Vector{UInt8} (the downloaded data)
fileserver_download_handler(url::String, max_retries::Int, base_delay::Int, max_delay::Int, correlation_id::String)::Vector{UInt8}

This design allows the system to support multiple file server backends without changing the core messaging logic.

Multi-Payload Support (Standard API)

The system uses a standardized list-of-tuples format for all payload operations. Even when sending a single payload, the user must wrap it in a list.

API Standard:

# Input format for smartsend (always a list of tuples with type info)
[(dataname1, data1, type1), (dataname2, data2, type2), ...]

# Output format for smartreceive (returns a dictionary with payloads field containing list of tuples)
# Returns: Dict with envelope metadata and payloads field containing Vector{Tuple{String, Any, String}}
# {
#   "correlation_id": "...",
#   "msg_id": "...",
#   "timestamp": "...",
#   "send_to": "...",
#   "msg_purpose": "...",
#   "sender_name": "...",
#   "sender_id": "...",
#   "receiver_name": "...",
#   "receiver_id": "...",
#   "reply_to": "...",
#   "reply_to_msg_id": "...",
#   "broker_url": "...",
#   "metadata": {...},
#   "payloads": [(dataname1, data1, type1), (dataname2, data2, type2), ...]
# }

Supported Types:

"text" - Plain text
"dictionary" - JSON-serializable dictionaries (Dict, NamedTuple)
"table" - Tabular data (DataFrame, array of structs)
"image" - Image data (Bitmap, PNG/JPG bytes)
"audio" - Audio data (WAV, MP3 bytes)
"video" - Video data (MP4, AVI bytes)
"binary" - Generic binary data (Vector{UInt8})

This design allows per-payload type specification, enabling mixed-content messages where different payloads can use different serialization formats in a single message.

Examples:

# Single payload - still wrapped in a list
smartsend(
    "/test",
    [("dataname1", data1, "dictionary")],  # List with one tuple (data, type)
    broker_url="nats://localhost:4222",
    fileserver_upload_handler=plik_oneshot_upload
)

# Multiple payloads in one message with different types
smartsend(
    "/test",
    [("dataname1", data1, "dictionary"), ("dataname2", data2, "table")],
    broker_url="nats://localhost:4222",
    fileserver_upload_handler=plik_oneshot_upload
)

# Mixed content (e.g., chat with text, image, audio)
smartsend(
    "/chat",
    [
        ("message_text", "Hello!", "text"),
        ("user_image", image_data, "image"),
        ("audio_clip", audio_data, "audio")
    ],
    broker_url="nats://localhost:4222"
)

# Receive returns a dictionary envelope with all metadata and deserialized payloads
env = smartreceive(msg; fileserver_download_handler=_fetch_with_backoff, max_retries=5, base_delay=100, max_delay=5000)
# env["payloads"] = [("dataname1", data1, type1), ("dataname2", data2, type2), ...]
# env["correlation_id"], env["msg_id"], etc.
# env is a dictionary containing envelope metadata and payloads field

Cross-Platform Interoperability

NATSBridge is designed for seamless communication between Julia, JavaScript, and Python/Micropython applications. All three implementations share the same interface and data format, ensuring compatibility across platforms.

Platform-Specific Features

Feature	Julia	JavaScript	Python/Micropython
Direct NATS transport	✅	✅	✅
HTTP file server (Claim-Check)	✅	✅	✅
Arrow IPC tables	✅	✅	✅
Base64 encoding	✅	✅	✅
Exponential backoff	✅	✅	✅
Correlation ID tracking	✅	✅	✅
Reply-to support	✅	✅	✅

Data Type Mapping

Type	Julia	JavaScript	Python/Micropython
`text`	`String`	`String`	`str`
`dictionary`	`Dict`	`Object`	`dict`
`table`	`DataFrame`	`Array<Object>`	`DataFrame` / `list`
`image`	`Vector{UInt8}`	`ArrayBuffer/Uint8Array`	`bytes`
`audio`	`Vector{UInt8}`	`ArrayBuffer/Uint8Array`	`bytes`
`video`	`Vector{UInt8}`	`ArrayBuffer/Uint8Array`	`bytes`
`binary`	`Vector{UInt8}`	`ArrayBuffer/Uint8Array`	`bytes`

Example: Julia ↔ Python ↔ JavaScript

# Julia sender - smartsend returns (env, env_json_str)
using NATSBridge
data = [("message", "Hello from Julia!", "text")]
env, env_json_str = smartsend("/cross_platform", data, broker_url="nats://localhost:4222")
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing

// JavaScript receiver
const { smartreceive } = require('./src/NATSBridge');
const env = await smartreceive(msg);
// env.payloads[0].data === "Hello from Julia!"

# Python sender
from nats_bridge import smartsend
data = [("response", "Hello from Python!", "text")]
smartsend("/cross_platform", data, broker_url="nats://localhost:4222")

All three platforms can communicate seamlessly using the same NATS subjects and data format.

Architecture

All three implementations (Julia, JavaScript, Python/Micropython) follow the same Claim-Check pattern:

┌─────────────────────────────────────────────────────────────────────────┐
│                         SmartSend Function                              │
└─────────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Is payload size < 1MB?                                                 │
└─────────────────────────────────────────────────────────────────────────┘
                              │
            ┌─────────────────┴─────────────────┐
            ▼                                   ▼
      ┌─────────────────┐                 ┌─────────────────┐
      │  Direct Path    │                 │  Link Path      │
      │  (< 1MB)        │                 │  (> 1MB)        │
      │                 │                 │                 │
      │ • Serialize to  │                 │ • Serialize to  │
      │   Buffer        │                 │   Buffer        │
      │ • Base64 encode │                 │ • Upload to     │
      │ • Publish to    │                 │   HTTP Server   │
      │   NATS          │                 │ • Publish to    │
      │                 │                 │   NATS with URL │
      └─────────────────┘                 └─────────────────┘

smartsend Return Value

The smartsend function now returns a tuple containing both the envelope object and the JSON string representation:

env, env_json_str = smartsend(...)
# env::msg_envelope_v1    - The envelope object with all metadata and payloads
# env_json_str::String    - JSON string for publishing to NATS

Options:

is_publish::Bool = true - When true (default), the message is automatically published to NATS. When false, the function returns the envelope and JSON string without publishing, allowing manual publishing via NATS request-reply pattern.

This enables two use cases:

Programmatic envelope access: Access envelope fields directly via the env object
Direct JSON publishing: Publish the JSON string directly using NATS request-reply pattern

Julia Module: `src/NATSBridge.jl`

The Julia implementation provides:

msg_envelope_v1: Struct for the unified JSON envelope
msg_payload_v1: Struct for individual payload representation
smartsend(): Handles transport selection based on payload size
smartreceive(): Handles both direct and link transport

JavaScript Module: `src/NATSBridge.js`

The JavaScript implementation provides:

MessageEnvelope class: For the unified JSON envelope
MessagePayload class: For individual payload representation
smartsend(): Handles transport selection based on payload size
smartreceive(): Handles both direct and link transport

Python/Micropython Module: `src/nats_bridge.py`

The Python/Micropython implementation provides:

MessageEnvelope class: For the unified JSON envelope
MessagePayload class: For individual payload representation
smartsend(): Handles transport selection based on payload size
smartreceive(): Handles both direct and link transport

Installation

Julia Dependencies

using Pkg
Pkg.add("NATS")
Pkg.add("Arrow")
Pkg.add("JSON3")
Pkg.add("HTTP")
Pkg.add("UUIDs")
Pkg.add("Dates")

JavaScript Dependencies

npm install nats.js apache-arrow uuid base64-url

Python/Micropython Dependencies

Copy src/nats_bridge.py to your device
Ensure you have the following dependencies:

For Python (desktop):
```
pip install nats-py
```
For Micropython:
- urequests for HTTP requests
- base64 for base64 encoding (built-in)
- json for JSON handling (built-in)
- socket for networking (built-in)
- uuid for UUID generation (built-in)

Usage Tutorial

Step 1: Start NATS Server

docker run -p 4222:4222 nats:latest

Step 2: Start HTTP File Server (optional)

# Create a directory for file uploads
mkdir -p /tmp/fileserver

# Use any HTTP server that supports POST for file uploads
# Example: Python's built-in server
python3 -m http.server 8080 --directory /tmp/fileserver

Step 3: Run Test Scenarios

# Scenario 1: Command & Control (JavaScript sender)
node test/scenario1_command_control.js

# Scenario 2: Large Arrow Table (JavaScript sender)
node test/scenario2_large_table.js

# Scenario 3: Julia-to-Julia communication
# Run both Julia and JavaScript versions
julia test/scenario3_julia_to_julia.jl
node test/scenario3_julia_to_julia.js

API Consistency Across Languages

High-Level API (Consistent Across All Languages):

smartsend(subject, data, ...) - Main publishing function
smartreceive(msg, ...) - Main receiving function
Message envelope structure (msg_envelope_v1 / MessageEnvelope)
Payload structure (msg_payload_v1 / MessagePayload)
Transport strategy (direct vs link based on size threshold)
Supported payload types: text, dictionary, table, image, audio, video, binary

Low-Level Native Functions (Language-Specific Conventions):

Julia: NATS.connect(), publish_message(), function overloading
JavaScript: nats.js client, native async/await patterns
Python: nats-python client, native async/await patterns

Connection Reuse Pattern - Key Differences:

Julia: Uses NATS_connection keyword parameter with function overloading for automatic connection management
JavaScript/Python: Achieved by creating NATS client outside the function and reusing it in custom handlers or custom publish implementations

Why the Difference?

Julia supports function overloading and keyword arguments, allowing NATS_connection to be passed as an optional parameter
JavaScript/Python use a simpler is_publish option to control automatic publishing
is_publish is simply a switch: when true, publish automatically; when false, return (env, env_json_str) without publishing
For connection reuse in JavaScript/Python, create a NATS client once and reuse it in your custom fileserver_upload_handler or custom publish logic

Usage

Scenario 1: Command & Control (Small Dictionary)

Focus: Sending small dictionary configurations across platforms. This is the simplest use case for command and control scenarios.

Julia (Sender/Receiver):

using NATSBridge

# Send small dictionary config (wrapped in list with type)
config = Dict("step_size" => 0.01, "iterations" => 1000, "threshold" => 0.5)
env, env_json_str = smartsend(
    "control",
    [("config", config, "dictionary")],
    broker_url="nats://localhost:4222"
)
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing

Julia (Sender/Receiver) with NATS_connection for connection reuse:

using NATSBridge

# Create connection once for high-frequency publishing
conn = NATS.connect("nats://localhost:4222")

# Send multiple messages using the same connection (saves connection overhead)
for i in 1:100
    config = Dict("iteration" => i, "data" => rand())
    smartsend(
        "control",
        [("config", config, "dictionary")],
        NATS_connection=conn,  # Reuse connection
        is_publish=true
    )
end

# Close connection when done
NATS.close(conn)

Use Case: High-frequency publishing scenarios where connection reuse provides performance benefits by avoiding the overhead of establishing a new NATS connection for each message.

JavaScript (Sender/Receiver):

const { smartsend } = require('./src/NATSBridge');

// Create small dictionary config
// Send via smartsend with type="dictionary"
const config = {
    step_size: 0.01,
    iterations: 1000,
    threshold: 0.5
};

// Use is_publish option to control automatic publishing
await smartsend("control", [
    { dataname: "config", data: config, type: "dictionary" }
], {
    is_publish: true  // Automatically publish to NATS
});

Connection Reuse in JavaScript: To achieve connection reuse in JavaScript, create a NATS client outside the function and use it in a custom fileserver_upload_handler or custom publish implementation:

const { connect } = require('nats');
const { smartsend } = require('./src/NATSBridge');

// Create connection once
const nc = await connect({ servers: ['nats://localhost:4222'] });

// Send multiple messages using the same connection
for (let i = 0; i < 100; i++) {
    const config = { iteration: i, data: Math.random() };
    
    // Option 1: Use is_publish=false and publish manually with your connection
    const { env, env_json_str } = await smartsend("control", [
        { dataname: "config", data: config, type: "dictionary" }
    ], { is_publish: false });
    
    // Publish with your existing connection
    await nc.publish("control", env_json_str);
}

// Close connection when done
await nc.close();

Python/Micropython (Sender/Receiver):

from nats_bridge import smartsend

# Create small dictionary config
# Send via smartsend with type="dictionary"
config = {
    "step_size": 0.01,
    "iterations": 1000,
    "threshold": 0.5
}

# Use is_publish parameter to control automatic publishing
smartsend("control", [("config", config, "dictionary")], is_publish=True)

Connection Reuse in Python: To achieve connection reuse in Python, create a NATS client outside the function and use it in a custom fileserver_upload_handler or custom publish implementation:

from nats_bridge import smartsend
import nats

# Create connection once
nc = await nats.connect("nats://localhost:4222")

# Send multiple messages using the same connection
for i in range(100):
    config = {"iteration": i, "data": random.random()}
    
    # Option 1: Use is_publish=False and publish manually with your connection
    env, env_json_str = smartsend("control", [("config", config, "dictionary")], is_publish=False)
    
    # Publish with your existing connection
    await nc.publish("control", env_json_str)

# Close connection when done
await nc.close()

Basic Multi-Payload Example

Python/Micropython (Sender)

from nats_bridge import smartsend

# Send multiple payloads in one message (type is required per payload)
smartsend(
    "/test",
    [("dataname1", data1, "dictionary"), ("dataname2", data2, "table")],
    broker_url="nats://localhost:4222",
    fileserver_url="http://localhost:8080"
)

# Even single payload must be wrapped in a list with type
smartsend("/test", [("single_data", mydata, "dictionary")], broker_url="nats://localhost:4222")

Python/Micropython (Receiver)

from nats_bridge import smartreceive

# Receive returns a dictionary with envelope metadata and payloads field
env = smartreceive(msg)
# env["payloads"] = [(dataname1, data1, "dictionary"), (dataname2, data2, "table"), ...]

JavaScript (Sender)

const { smartsend } = require('./src/NATSBridge');

// Single payload wrapped in a list
const config = [{
    dataname: "config",
    data: { step_size: 0.01, iterations: 1000 },
    type: "dictionary"
}];

await smartsend("control", config, {
    correlationId: "unique-id"
});

// Multiple payloads
const configs = [
    {
        dataname: "config1",
        data: { step_size: 0.01 },
        type: "dictionary"
    },
    {
        dataname: "config2", 
        data: { iterations: 1000 },
        type: "dictionary"
    }
];

await smartsend("control", configs);

JavaScript (Receiver)

const { smartreceive } = require('./src/NATSBridge');

// Subscribe to messages
const nc = await connect({ servers: ['nats://localhost:4222'] });
const sub = nc.subscribe("control");

for await (const msg of sub) {
    const env = await smartreceive(msg);
    
    // Process the payloads from the envelope
    for (const payload of env.payloads) {
        const { dataname, data, type } = payload;
        console.log(`Received ${dataname} of type ${type}`);
        console.log(`Data: ${JSON.stringify(data)}`);
    }
    
    // Also access envelope metadata
    console.log(`Correlation ID: ${env.correlation_id}`);
    console.log(`Message ID: ${env.msg_id}`);
}

Scenario 2: Deep Dive Analysis (Large Arrow Table)

Julia (Sender)

using Arrow
using DataFrames

# Create large DataFrame
df = DataFrame(
    id = 1:10_000_000,
    value = rand(10_000_000),
    category = rand(["A", "B", "C"], 10_000_000)
)

# Send via smartsend - wrapped in list with type
# Large payload will use link transport (HTTP fileserver)
env, env_json_str = smartsend(
    "analysis_results",
    [("table_data", df, "table")],
    broker_url="nats://localhost:4222",
    fileserver_url="http://localhost:8080"
)
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing

smartsend Function Signature (Julia)

function smartsend(
  subject::String,
  data::AbstractArray{Tuple{String, Any, String}, 1};  # List of (dataname, data, type) tuples
  broker_url::String = DEFAULT_BROKER_URL,  # NATS server URL
  fileserver_url = DEFAULT_FILESERVER_URL,
  fileserver_upload_handler::Function = plik_oneshot_upload,
  size_threshold::Int = DEFAULT_SIZE_THRESHOLD,
  correlation_id::Union{String, Nothing} = nothing,
  msg_purpose::String = "chat",
  sender_name::String = "NATSBridge",
  receiver_name::String = "",
  receiver_id::String = "",
  reply_to::String = "",
  reply_to_msg_id::String = "",
  is_publish::Bool = true,
  NATS_connection::Union{NATS.Connection, Nothing} = nothing  # Pre-existing NATS connection (optional)
)

New Keyword Parameter:

NATS_connection::Union{NATS.Connection, Nothing} = nothing - Pre-existing NATS connection. When provided, smartsend uses this connection instead of creating a new one, avoiding the overhead of connection establishment. This is useful for high-frequency publishing scenarios.

Connection Handling Logic:

if is_publish == false
  # skip publish
elseif is_publish == true && NATS_connection === nothing
  publish_message(broker_url, subject, env_json_str, cid)  # Creates new connection
elseif is_publish == true && NATS_connection !== nothing
  publish_message(NATS_connection, subject, env_json_str, cid)  # Uses provided connection
end

Example with pre-existing connection:

using NATSBridge

# Create connection once
conn = NATS.connect("nats://localhost:4222")

# Send multiple messages using the same connection
for i in 1:100
    data = rand(1000)
    smartsend(
        "analysis_results",
        [("table_data", data, "table")],
        NATS_connection=conn,  # Reuse connection
        is_publish=true
    )
end

# Close connection when done
NATS.close(conn)

publish_message Function

The publish_message function provides two overloads for publishing messages to NATS:

Overload 1 - URL-based publishing (creates new connection):

function publish_message(broker_url::String, subject::String, message::String, correlation_id::String)
  conn = NATS.connect(broker_url)  # Create NATS connection
  publish_message(conn, subject, message, correlation_id)
end

Overload 2 - Connection-based publishing (uses pre-existing connection):

function publish_message(conn::NATS.Connection, subject::String, message::String, correlation_id::String)
  try
    NATS.publish(conn, subject, message)  # Publish message to NATS
    log_trace(correlation_id, "Message published to $subject")
  finally
    NATS.drain(conn)  # Ensure connection is closed properly
  end
end

Use Case: Use the connection-based overload when you already have an established NATS connection and want to publish multiple messages without the overhead of creating a new connection for each publish.

Integration with smartsend:

# When NATS_connection is provided to smartsend, it uses the connection-based publish_message
env, env_json_str = smartsend(
    "my.subject",
    [("data", payload_data, "type")],
    NATS_connection=my_connection,  # Pre-existing connection
    is_publish=true
)
# Uses: publish_message(NATS_connection, subject, env_json_str, cid)

# When NATS_connection is not provided, it uses the URL-based publish_message
env, env_json_str = smartsend(
    "my.subject",
    [("data", payload_data, "type")],
    broker_url="nats://localhost:4222",
    is_publish=true
)
# Uses: publish_message(broker_url, subject, env_json_str, cid)

API Consistency Note:

Julia: Uses NATS_connection keyword parameter with function overloading for automatic connection management
JavaScript/Python: Use is_publish option and achieve connection reuse by creating NATS client outside the function and reusing it in custom handlers or custom publish implementations

JavaScript (Receiver)

const { smartreceive } = require('./src/NATSBridge');

const env = await smartreceive(msg);

// Use table data from the payloads field
// Note: Tables are sent as arrays of objects in JavaScript
const table = env.payloads;

Scenario 3: Live Binary Processing

Python/Micropython (Sender)

from nats_bridge import smartsend

# Binary data wrapped in list with type
smartsend(
    "binary_input",
    [("audio_chunk", binary_buffer, "binary")],
    broker_url="nats://localhost:4222",
    metadata={"sample_rate": 44100, "channels": 1}
)

JavaScript (Sender)

const { smartsend } = require('./src/NATSBridge');

// Binary data wrapped in a list
const binaryData = [{
    dataname: "audio_chunk",
    data: binaryBuffer,  // ArrayBuffer or Uint8Array
    type: "binary"
}];

await smartsend("binary_input", binaryData, {
    metadata: {
        sample_rate: 44100,
        channels: 1
    }
});

Python/Micropython (Receiver)

from nats_bridge import smartreceive

# Receive binary data
def process_binary(msg):
    env = smartreceive(msg)
    
    # Process the binary data from env.payloads
    for dataname, data, type in env["payloads"]:
        if type == "binary":
            # data is bytes
            print(f"Received binary data: {dataname}, size: {len(data)}")
            # Perform FFT or AI transcription here

JavaScript (Receiver)

const { smartreceive } = require('./src/NATSBridge');

// Receive binary data
function process_binary(msg) {
    const env = await smartreceive(msg);
    
    // Process the binary data from env.payloads
    for (const payload of env.payloads) {
        if (payload.type === "binary") {
            // data is an ArrayBuffer or Uint8Array
            console.log(`Received binary data: ${payload.dataname}, size: ${payload.data.length}`);
            // Perform FFT or AI transcription here
        }
    }
}

Scenario 4: Catch-Up (JetStream)

Julia (Producer)

using NATSBridge

function publish_health_status(broker_url)
    # Send status wrapped in list with type
    status = Dict("cpu" => rand(), "memory" => rand())
    env, env_json_str = smartsend(
        "health",
        [("status", status, "dictionary")],
        broker_url=broker_url
    )
    sleep(5)  # Every 5 seconds
end

JavaScript (Consumer)

const { connect } = require('nats');
const { smartreceive } = require('./src/NATSBridge');

const nc = await connect({ servers: ['nats://localhost:4222'] });
const js = nc.jetstream();

// Request replay from last 10 minutes
const consumer = await js.pullSubscribe("health", { 
    durable_name: "catchup",
    max_batch: 100,
    max_ack_wait: 30000
});

// Process historical and real-time messages
for await (const msg of consumer) {
    const env = await smartreceive(msg);
    // env.payloads contains the list of payloads
    // Each payload has: dataname, data, type
    msg.ack();
}

Scenario 4: Micropython Device Control

Focus: Sending configuration to a Micropython device over NATS. This demonstrates the lightweight nature of the Python implementation suitable for microcontrollers.

Python/Micropython (Receiver/Device):

from nats_bridge import smartsend, smartreceive
import json

# Device configuration handler
def handle_device_config(msg):
    env = smartreceive(msg)
    
    # Process configuration from payloads
    for dataname, data, payload_type in env["payloads"]:
        if payload_type == "dictionary":
            print(f"Received configuration: {data}")
            # Apply configuration to device
            if "wifi_ssid" in data:
                wifi_ssid = data["wifi_ssid"]
                wifi_password = data["wifi_password"]
                update_wifi_config(wifi_ssid, wifi_password)
    
    # Send confirmation back
    config = {
        "status": "configured",
        "wifi_ssid": "MyNetwork",
        "ip": get_device_ip()
    }
    smartsend(
        "device/response",
        [("config", config, "dictionary")],
        broker_url="nats://localhost:4222",
        reply_to=env.get("reply_to")
    )

JavaScript (Sender/Controller):

const { smartsend } = require('./src/NATSBridge');

// Send configuration to Micropython device
await smartsend("device/config", [
    {
        dataname: "config",
        data: {
            wifi_ssid: "MyNetwork",
            wifi_password: "password123",
            update_interval: 60,
            temperature_threshold: 30.0
        },
        type: "dictionary"
    }
]);

Use Case: A controller sends WiFi and operational configuration to a Micropython device (e.g., ESP32). The device receives the configuration, applies it, and sends back a confirmation with its current status.

Scenario 5: Selection (Low Bandwidth)

Focus: Small Arrow tables, Julia to JavaScript. The Action: Julia wants to send a small DataFrame to show on a JavaScript dashboard for the user to choose.

Julia (Sender):

using NATSBridge
using DataFrames

# Create small DataFrame (e.g., 50KB - 500KB)
options_df = DataFrame(
    id = 1:10,
    name = ["Option A", "Option B", "Option C", "Option D", "Option E",
            "Option F", "Option G", "Option H", "Option I", "Option J"],
    description = ["Description A", "Description B", "Description C", "Description D", "Description E",
                   "Description F", "Description G", "Description H", "Description I", "Description J"]
)

# Convert to Arrow IPC stream
# Check payload size (< 1MB threshold)
# Publish directly to NATS with Base64-encoded payload
# Include metadata for dashboard selection context
env, env_json_str = smartsend(
    "dashboard.selection",
    [("options_table", options_df, "table")],
    broker_url="nats://localhost:4222",
    metadata=Dict("context" => "user_selection")
)
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing

JavaScript (Receiver):

const { smartreceive, smartsend } = require('./src/NATSBridge');

// Receive NATS message with direct transport
const env = await smartreceive(msg);

// Decode Base64 payload (for direct transport)
// For tables, data is in env.payloads
const table = env.payloads;  // Array of objects

// User makes selection
const selection = uiComponent.getSelectedOption();

// Send selection back to Julia
await smartsend("dashboard.response", [
    { dataname: "selected_option", data: selection, type: "dictionary" }
]);

Use Case: Julia server generates a list of available options (e.g., file selections, configuration presets) as a small DataFrame and sends to JavaScript dashboard for user selection. The selection is then sent back to Julia for processing.

Scenario 6: Chat System

Focus: Every conversational message is composed of any number and any combination of components, spanning the full spectrum from small to large. This includes text, images, audio, video, tables, and files—specifically accommodating everything from brief snippets to high-resolution images, large audio files, extensive tables, and massive documents. Support for claim-check delivery and full bi-directional messaging.

Multi-Payload Support: The system supports mixed-payload messages where a single message can contain multiple payloads with different transport strategies. The smartreceive function iterates through all payloads in the envelope and processes each according to its transport type.

Julia (Sender/Receiver):

using NATSBridge

# Build chat message with mixed payloads:
# - Text: direct transport (Base64)
# - Small images: direct transport (Base64)
# - Large images: link transport (HTTP URL)
# - Audio/video: link transport (HTTP URL)
# - Tables: direct or link depending on size
# - Files: link transport (HTTP URL)
# 
# Each payload uses appropriate transport strategy:
# - Size < 1MB → direct (NATS + Base64)
# - Size >= 1MB → link (HTTP upload + NATS URL)
# 
# Include claim-check metadata for delivery tracking
# Support bidirectional messaging with replyTo fields

# Example: Chat with text, small image, and large file
chat_message = [
    ("message_text", "Hello, this is a test message!", "text"),
    ("user_avatar", image_bytes, "image"),  # Small image, direct transport
    ("large_document", large_file_bytes, "binary")  # Large file, link transport
]

env, env_json_str = smartsend(
    "chat.room123",
    chat_message,
    broker_url="nats://localhost:4222",
    msg_purpose="chat",
    reply_to="chat.room123.responses"
)
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing

JavaScript (Sender/Receiver):

const { smartsend, smartreceive } = require('./src/NATSBridge');

// Build chat message with mixed content:
// - User input text: direct transport
// - Selected image: check size, use appropriate transport
// - Audio recording: link transport for large files
// - File attachment: link transport
// 
// Parse received message:
// - Direct payloads: decode Base64
// - Link payloads: fetch from HTTP with exponential backoff
// - Deserialize all payloads appropriately
// 
// Render mixed content in chat interface
// Support bidirectional reply with claim-check delivery confirmation

// Example: Send chat with mixed content
const message = [
    {
        dataname: "text",
        data: "Hello from JavaScript!",
        type: "text"
    },
    {
        dataname: "image",
        data: selectedImageBuffer,  // Small image (ArrayBuffer or Uint8Array)
        type: "image"
    },
    {
        dataname: "audio",
        data: audioUrl,  // Large audio, link transport
        type: "audio"
    }
];

await smartsend("chat.room123", message);

Use Case: Full-featured chat system supporting rich media. User can send text, small images directly, or upload large files that get uploaded to HTTP server and referenced via URLs. Claim-check pattern ensures reliable delivery tracking for all message components.

Implementation Note: The smartreceive function iterates through all payloads in the envelope and processes each according to its transport type. See the standard API format in Section 1: msg_envelope_v1 supports Vector{msg_payload_v1} for multiple payloads.

Configuration

Environment Variables

Variable	Default	Description
`NATS_URL`	`nats://localhost:4222`	NATS server URL
`FILESERVER_URL`	`http://localhost:8080`	HTTP file server URL (base URL without `/upload` suffix)
`SIZE_THRESHOLD`	`1_000_000`	Size threshold in bytes (1MB)

Message Envelope Schema

{
  "correlation_id": "uuid-v4-string",
  "msg_id": "uuid-v4-string",
  "timestamp": "2024-01-15T10:30:00Z",
  
  "send_to": "topic/subject",
  "msg_purpose": "ACK | NACK | updateStatus | shutdown | chat",
  "sender_name": "agent-wine-web-frontend",
  "sender_id": "uuid4",
  "receiver_name": "agent-backend",
  "receiver_id": "uuid4",
  "reply_to": "topic",
  "reply_to_msg_id": "uuid4",
  "broker_url": "nats://localhost:4222",
  
  "metadata": {
    "content_type": "application/octet-stream",
    "content_length": 123456
  },
  
  "payloads": [
    {
      "id": "uuid4",
      "dataname": "login_image",
      "payload_type": "image",
      "transport": "direct",
      "encoding": "base64",
      "size": 15433,
      "data": "base64-encoded-string",
      "metadata": {
        "checksum": "sha256_hash"
      }
    }
  ]
}

Performance Considerations

Zero-Copy Reading

Use Arrow's memory-mapped file reading
Avoid unnecessary data copying during deserialization
Use Apache Arrow's native IPC reader

Exponential Backoff

Maximum retry count: 5
Base delay: 100ms, max delay: 5000ms
Implemented in all three implementations (Julia, JavaScript, Python/Micropython)

Correlation ID Logging

Log correlation_id at every stage
Include: send, receive, serialize, deserialize
Use structured logging format

Testing

Run the test scripts for each platform:

Python/Micropython Tests

# Basic functionality test
python test/test_micropython_basic.py

JavaScript Tests

# Text message exchange
node test/test_js_to_js_text_sender.js
node test/test_js_to_js_text_receiver.js

# Dictionary exchange
node test/test_js_to_js_dict_sender.js
node test/test_js_to_js_dict_receiver.js

# File transfer (direct transport)
node test/test_js_to_js_file_sender.js
node test/test_js_to_js_file_receiver.js

# Mixed payload types
node test/test_js_to_js_mix_payloads_sender.js
node test/test_js_to_js_mix_payloads_receiver.js

# Table (Arrow IPC) exchange
node test/test_js_to_js_table_sender.js
node test/test_js_to_js_table_receiver.js

Julia Tests

# Text message exchange
julia test/test_julia_to_julia_text_sender.jl
julia test/test_julia_to_julia_text_receiver.jl

# Dictionary exchange
julia test/test_julia_to_julia_dict_sender.jl
julia test/test_julia_to_julia_dict_receiver.jl

# File transfer
julia test/test_julia_to_julia_file_sender.jl
julia test/test_julia_to_julia_file_receiver.jl

# Mixed payload types
julia test/test_julia_to_julia_mix_payloads_sender.jl
julia test/test_julia_to_julia_mix_payloads_receiver.jl

# Table exchange
julia test/test_julia_to_julia_table_sender.jl
julia test/test_julia_to_julia_table_receiver.jl

Cross-Platform Tests

# Julia ↔ JavaScript communication
julia test/test_julia_to_julia_text_sender.jl
node test/test_js_to_js_text_receiver.js

# Python ↔ JavaScript communication
python test/test_micropython_basic.py
node test/test_js_to_js_text_receiver.js

Troubleshooting

Common Issues

NATS Connection Failed
- Julia/JavaScript/Python: Ensure NATS server is running
- Python/Micropython: Check nats_url parameter and network connectivity
HTTP Upload Failed
- Ensure file server is running
- Check fileserver_url configuration
- Verify upload permissions
- Micropython: Ensure urequests is available and network is connected
Arrow IPC Deserialization Error
- Ensure data is properly serialized to Arrow format
- Check Arrow version compatibility
Python/Micropython Specific Issues
- Import Error: Ensure nats_bridge.py is in the correct path
- Memory Error (Micropython): Reduce payload size or use link transport for large payloads
- Unicode Error: Ensure proper encoding when sending text data

License

MIT

39 KiB Raw Blame History

Implementation Guide: Bi-Directional Data Bridge

Overview

Implementation Files

File Server Handler Architecture

Multi-Payload Support (Standard API)

Cross-Platform Interoperability

Platform-Specific Features

Data Type Mapping

Example: Julia ↔ Python ↔ JavaScript

Architecture

smartsend Return Value

Julia Module: src/NATSBridge.jl

JavaScript Module: src/NATSBridge.js

Python/Micropython Module: src/nats_bridge.py

Installation

Julia Dependencies

JavaScript Dependencies

Python/Micropython Dependencies

Usage Tutorial

Step 1: Start NATS Server

Step 2: Start HTTP File Server (optional)

Step 3: Run Test Scenarios

API Consistency Across Languages

Usage

Scenario 1: Command & Control (Small Dictionary)

Basic Multi-Payload Example

Python/Micropython (Sender)

Python/Micropython (Receiver)

JavaScript (Sender)

JavaScript (Receiver)

Scenario 2: Deep Dive Analysis (Large Arrow Table)

Julia (Sender)

smartsend Function Signature (Julia)

publish_message Function

JavaScript (Receiver)

Scenario 3: Live Binary Processing

Python/Micropython (Sender)

JavaScript (Sender)

Python/Micropython (Receiver)

JavaScript (Receiver)

Scenario 4: Catch-Up (JetStream)

Julia (Producer)

JavaScript (Consumer)

Scenario 4: Micropython Device Control

Scenario 5: Selection (Low Bandwidth)

Scenario 6: Chat System

Configuration

Environment Variables

Message Envelope Schema

Performance Considerations

Zero-Copy Reading

Exponential Backoff

Correlation ID Logging

Testing

Python/Micropython Tests

JavaScript Tests

Julia Tests

Cross-Platform Tests

Troubleshooting

Common Issues

License

39 KiB

Raw Blame History

Julia Module: `src/NATSBridge.jl`

JavaScript Module: `src/NATSBridge.js`

Python/Micropython Module: `src/nats_bridge.py`