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

4
AI_prompt.txt
View File

@@ -14,4 +14,6 @@ Role: Principal Systems Architect & Lead Software Engineer.Objective: Implement
Create a walkthrough for Julia service-A service sending a mix-content chat message to Julia service-B. the chat message must includes Create a walkthrough for Julia service-A service sending a mix-content chat message to Julia service-B. the chat message must includes
I update architecture.md and NATSBridge.jl. Use them as ground truth and update implementation.md accordingly. Also look for any inconsistency. I update architecture.md and NATSBridge.jl. Use them as ground truth and update implementation.md accordingly. Also look for any inconsistency.

85
docs/implementation.md
View File

@@ -28,9 +28,9 @@ The system uses **handler functions** to abstract file server operations, allowi
```julia ```julia
# Upload handler - uploads data to file server and returns URL # Upload handler - uploads data to file server and returns URL
# The handler is passed to smartsend as fileserver_upload_handler parameter # 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" # 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 # Download handler - fetches data from file server URL with exponential backoff
# The handler is passed to smartreceive as fileserver_download_handler parameter # 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 ### Example: Julia ↔ Python ↔ JavaScript
```julia ```julia
# Julia sender # Julia sender - smartsend returns (env, env_json_str)
using NATSBridge using NATSBridge
data = [("message", "Hello from Julia!", "text")] 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 ```javascript
@@ -165,7 +167,7 @@ const env = await smartreceive(msg);
# Python sender # Python sender
from nats_bridge import smartsend from nats_bridge import smartsend
data = [("response", "Hello from Python!", "text")] 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. 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 ```julia
using NATSBridge using NATSBridge
# Subscribe to control subject # Send small dictionary config (wrapped in list with type)
# Parse JSON envelope config = Dict("step_size" => 0.01, "iterations" => 1000, "threshold" => 0.5)
# Execute simulation with parameters env, env_json_str = smartsend(
# Send acknowledgment "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):** **JavaScript (Sender/Receiver):**
@@ -372,12 +379,12 @@ from nats_bridge import smartsend
smartsend( smartsend(
"/test", "/test",
[("dataname1", data1, "dictionary"), ("dataname2", data2, "table")], [("dataname1", data1, "dictionary"), ("dataname2", data2, "table")],
nats_url="nats://localhost:4222", broker_url="nats://localhost:4222",
fileserver_url="http://localhost:8080" fileserver_url="http://localhost:8080"
) )
# Even single payload must be wrapped in a list with type # 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) #### Python/Micropython (Receiver)
@@ -459,10 +466,16 @@ df = DataFrame(
category = rand(["A", "B", "C"], 10_000_000) category = rand(["A", "B", "C"], 10_000_000)
) )
# Send via smartsend - wrapped in a list (type is part of each tuple) # Send via smartsend - wrapped in list with type
env, env_json_str = smartsend("analysis_results", [("table_data", df, "table")], broker_url="nats://localhost:4222") # Large payload will use link transport (HTTP fileserver)
# env: msg_envelope_v1 object with all metadata and payloads env, env_json_str = smartsend(
# env_json_str: JSON string representation of the envelope for publishing "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) #### JavaScript (Receiver)
@@ -482,19 +495,12 @@ const table = env.payloads;
```python ```python
from nats_bridge import smartsend from nats_bridge import smartsend
# Binary data wrapped in a list # Binary data wrapped in list with type
binary_data = [
("audio_chunk", binary_buffer, "binary")
]
smartsend( smartsend(
"binary_input", "binary_input",
binary_data, [("audio_chunk", binary_buffer, "binary")],
nats_url="nats://localhost:4222", broker_url="nats://localhost:4222",
metadata={ metadata={"sample_rate": 44100, "channels": 1}
"sample_rate": 44100,
"channels": 1
}
) )
``` ```
@@ -558,10 +564,14 @@ function process_binary(msg) {
```julia ```julia
using NATSBridge using NATSBridge
function publish_health_status(nats_url) function publish_health_status(broker_url)
# Send status wrapped in a list (type is part of each tuple) # Send status wrapped in list with type
status = Dict("cpu" => rand(), "memory" => rand()) 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 sleep(5) # Every 5 seconds
end end
``` ```
@@ -604,8 +614,8 @@ def handle_device_config(msg):
env = smartreceive(msg) env = smartreceive(msg)
# Process configuration from payloads # Process configuration from payloads
for dataname, data, type in env["payloads"]: for dataname, data, payload_type in env["payloads"]:
if type == "dictionary": if payload_type == "dictionary":
print(f"Received configuration: {data}") print(f"Received configuration: {data}")
# Apply configuration to device # Apply configuration to device
if "wifi_ssid" in data: if "wifi_ssid" in data:
@@ -622,7 +632,7 @@ def handle_device_config(msg):
smartsend( smartsend(
"device/response", "device/response",
[("config", config, "dictionary")], [("config", config, "dictionary")],
nats_url="nats://localhost:4222", broker_url="nats://localhost:4222",
reply_to=env.get("reply_to") reply_to=env.get("reply_to")
) )
``` ```
@@ -670,12 +680,14 @@ options_df = DataFrame(
# Check payload size (< 1MB threshold) # Check payload size (< 1MB threshold)
# Publish directly to NATS with Base64-encoded payload # Publish directly to NATS with Base64-encoded payload
# Include metadata for dashboard selection context # Include metadata for dashboard selection context
smartsend( env, env_json_str = smartsend(
"dashboard.selection", "dashboard.selection",
[("options_table", options_df, "table")], [("options_table", options_df, "table")],
nats_url="nats://localhost:4222", broker_url="nats://localhost:4222",
metadata=Dict("context" => "user_selection") metadata=Dict("context" => "user_selection")
) )
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing
``` ```
**JavaScript (Receiver):** **JavaScript (Receiver):**
@@ -709,7 +721,6 @@ await smartsend("dashboard.response", [
**Julia (Sender/Receiver):** **Julia (Sender/Receiver):**
```julia ```julia
using NATSBridge using NATSBridge
using DataFrames
# Build chat message with mixed payloads: # Build chat message with mixed payloads:
# - Text: direct transport (Base64) # - Text: direct transport (Base64)
@@ -733,13 +744,15 @@ chat_message = [
("large_document", large_file_bytes, "binary") # Large file, link transport ("large_document", large_file_bytes, "binary") # Large file, link transport
] ]
smartsend( env, env_json_str = smartsend(
"chat.room123", "chat.room123",
chat_message, chat_message,
broker_url="nats://localhost:4222", broker_url="nats://localhost:4222",
msg_purpose="chat", msg_purpose="chat",
reply_to="chat.room123.responses" reply_to="chat.room123.responses"
) )
# env: msg_envelope_v1 with all metadata and payloads
# env_json_str: JSON string for publishing
``` ```
**JavaScript (Sender/Receiver):** **JavaScript (Sender/Receiver):**