update

2026-02-25 08:02:03 +07:00
parent 6a42ba7e43
commit 8c793a81b6
2 changed files with 52 additions and 37 deletions
--- a/AI_prompt.txt
+++ b/AI_prompt.txt
@@ -15,3 +15,5 @@ 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 

 I update architecture.md and NATSBridge.jl. Use them as ground truth and update implementation.md accordingly. Also look for any inconsistency.
+
+
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -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):**