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

update

Browse Source
This commit is contained in:
narawat
2026-02-25 08:02:03 +07:00
parent 6a42ba7e43
commit 8c793a81b6
2 changed files with 52 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/implementation.md
View File

@@ -28,9 +28,9 @@ The system uses **handler functions** to abstract file server operations, allowi
```julia
# Upload handler - uploads data to file server and returns URL
# The handler is passed to smartsend as fileserver_upload_handler parameter
# It receives: (file_server_url::String, dataname::String, data::Vector{UInt8})
# It receives: (fileserver_url::String, dataname::String, data::Vector{UInt8})
# Returns: Dict{String, Any} with keys: "status", "uploadid", "fileid", "url"
fileserver_upload_handler(file_server_url::String, dataname::String, data::Vector{UInt8})::Dict{String, Any}
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
@@ -148,10 +148,12 @@ NATSBridge is designed for seamless communication between Julia, JavaScript, and
### Example: Julia ↔ Python ↔ JavaScript
```julia
# Julia sender
# Julia sender - smartsend returns (env, env_json_str)
using NATSBridge
data = [("message", "Hello from Julia!", "text")]
smartsend("/cross_platform", data, broker_url="nats://localhost:4222")
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
@@ -165,7 +167,7 @@ const env = await smartreceive(msg);
# Python sender
from nats_bridge import smartsend
data = [("response", "Hello from Python!", "text")]
smartsend("/cross_platform", data, nats_url="nats://localhost:4222")
smartsend("/cross_platform", data, broker_url="nats://localhost:4222")
```
All three platforms can communicate seamlessly using the same NATS subjects and data format.
@@ -324,10 +326,15 @@ node test/scenario3_julia_to_julia.js
```julia
using NATSBridge
# Subscribe to control subject
# Parse JSON envelope
# Execute simulation with parameters
# Send acknowledgment
# 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
```
**JavaScript (Sender/Receiver):**
@@ -372,12 +379,12 @@ from nats_bridge import smartsend
smartsend(
"/test",
[("dataname1", data1, "dictionary"), ("dataname2", data2, "table")],
nats_url="nats://localhost:4222",
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")], nats_url="nats://localhost:4222")
smartsend("/test", [("single_data", mydata, "dictionary")], broker_url="nats://localhost:4222")
```
#### Python/Micropython (Receiver)
@@ -459,10 +466,16 @@ df = DataFrame(
category = rand(["A", "B", "C"], 10_000_000)
)
# Send via smartsend - wrapped in a list (type is part of each tuple)
env, env_json_str = smartsend("analysis_results", [("table_data", df, "table")], broker_url="nats://localhost:4222")
# env: msg_envelope_v1 object with all metadata and payloads
# env_json_str: JSON string representation of the envelope for publishing
# 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
```
#### JavaScript (Receiver)
@@ -482,19 +495,12 @@ const table = env.payloads;
```python
from nats_bridge import smartsend
# Binary data wrapped in a list
binary_data = [
("audio_chunk", binary_buffer, "binary")
]
# Binary data wrapped in list with type
smartsend(
"binary_input",
binary_data,
nats_url="nats://localhost:4222",
metadata={
"sample_rate": 44100,
"channels": 1
}
[("audio_chunk", binary_buffer, "binary")],
broker_url="nats://localhost:4222",
metadata={"sample_rate": 44100, "channels": 1}
)
```
@@ -558,10 +564,14 @@ function process_binary(msg) {
```julia
using NATSBridge
function publish_health_status(nats_url)
# Send status wrapped in a list (type is part of each tuple)
function publish_health_status(broker_url)
# Send status wrapped in list with type
status = Dict("cpu" => rand(), "memory" => rand())
smartsend("health", [("status", status, "dictionary")], broker_url=nats_url)
env, env_json_str = smartsend(
"health",
[("status", status, "dictionary")],
broker_url=broker_url
)
sleep(5) # Every 5 seconds
end
```
@@ -604,8 +614,8 @@ def handle_device_config(msg):
env = smartreceive(msg)
# Process configuration from payloads
for dataname, data, type in env["payloads"]:
if type == "dictionary":
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:
@@ -622,7 +632,7 @@ def handle_device_config(msg):
smartsend(
"device/response",
[("config", config, "dictionary")],
nats_url="nats://localhost:4222",
broker_url="nats://localhost:4222",
reply_to=env.get("reply_to")
)
```
@@ -670,12 +680,14 @@ options_df = DataFrame(
# Check payload size (< 1MB threshold)
# Publish directly to NATS with Base64-encoded payload
# Include metadata for dashboard selection context
smartsend(
env, env_json_str = smartsend(
"dashboard.selection",
[("options_table", options_df, "table")],
nats_url="nats://localhost:4222",
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):**
@@ -709,7 +721,6 @@ await smartsend("dashboard.response", [
**Julia (Sender/Receiver):**
```julia
using NATSBridge
using DataFrames
# Build chat message with mixed payloads:
# - Text: direct transport (Base64)
@@ -733,13 +744,15 @@ chat_message = [
("large_document", large_file_bytes, "binary") # Large file, link transport
]
smartsend(
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):**