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-23 21:54:50 +07:00
parent 99bf57b154
commit 7853e94d2e
21 changed files with 65 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/architecture.md
View File

@@ -392,9 +392,9 @@ function smartsend(
```
**Return Value:**
- Returns a tuple `(env, msg_json_str)` where:
- Returns a tuple `(env, env_json_str)` where:
- `env::msgEnvelope_v1` - The envelope object containing all metadata and payloads
- `msg_json_str::String` - JSON string representation of the envelope for publishing
- `env_json_str::String` - JSON string representation of the envelope for publishing
**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.

8
docs/implementation.md
View File

@@ -151,9 +151,9 @@ All three implementations (Julia, JavaScript, Python/Micropython) follow the sam
The `smartsend` function now returns a tuple containing both the envelope object and the JSON string representation:
```julia
env, msg_json_str = smartsend(...)
env, env_json_str = smartsend(...)
# env::msgEnvelope_v1 - The envelope object with all metadata and payloads
# msg_json_str::String - JSON string for publishing to NATS
# env_json_str::String - JSON string for publishing to NATS
```
**Options:**
@@ -360,9 +360,9 @@ df = DataFrame(
)
# Send via SmartSend - wrapped in a list (type is part of each tuple)
env, msg_json_str = SmartSend("analysis_results", [("table_data", df, "table")])
env, env_json_str = SmartSend("analysis_results", [("table_data", df, "table")])
# env: msgEnvelope_v1 object with all metadata and payloads
# msg_json_str: JSON string representation of the envelope for publishing
# env_json_str: JSON string representation of the envelope for publishing
```
#### JavaScript (Receiver)

52
examples/tutorial.md
View File

@@ -109,13 +109,13 @@ from nats_bridge import smartsend
# Send a text message (is_publish=True by default)
data = [("message", "Hello World", "text")]
env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
print("Message sent!")
# Or use is_publish=False to get envelope and JSON without publishing
env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222", is_publish=False)
env, env_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222", is_publish=False)
# env: MessageEnvelope object
# msg_json_str: JSON string for publishing to NATS
# env_json_str: JSON string for publishing to NATS
```
#### JavaScript
@@ -131,11 +131,11 @@ await smartsend("/chat/room1", [
console.log("Message sent!");
// Or use isPublish=false to get envelope and JSON without publishing
const { env, msg_json_str } = await smartsend("/chat/room1", [
const { env, env_json_str } = await smartsend("/chat/room1", [
{ dataname: "message", data: "Hello World", type: "text" }
], { natsUrl: "nats://localhost:4222", isPublish: false });
// env: MessageEnvelope object
// msg_json_str: JSON string for publishing to NATS
// env_json_str: JSON string for publishing to NATS
```
#### Julia
@@ -145,9 +145,9 @@ using NATSBridge
# Send a text message
data = [("message", "Hello World", "text")]
env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
# env: msgEnvelope_v1 object with all metadata and payloads
# msg_json_str: JSON string representation of the envelope for publishing
# env_json_str: JSON string representation of the envelope for publishing
println("Message sent!")
```
@@ -208,7 +208,7 @@ config = {
# Send as dictionary type
data = [("config", config, "dictionary")]
env, msg_json_str = smartsend("/device/config", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/device/config", data, nats_url="nats://localhost:4222")
```
#### JavaScript
@@ -222,7 +222,7 @@ const config = {
update_interval: 60
};
const { env, msg_json_str } = await smartsend("/device/config", [
const { env, env_json_str } = await smartsend("/device/config", [
{ dataname: "config", data: config, type: "dictionary" }
]);
```
@@ -239,7 +239,7 @@ config = Dict(
)
data = [("config", config, "dictionary")]
env, msg_json_str = smartsend("/device/config", data)
env, env_json_str = smartsend("/device/config", data)
```
### Example 2: Sending Binary Data (Image)
@@ -255,7 +255,7 @@ with open("image.png", "rb") as f:
# Send as binary type
data = [("user_image", image_data, "binary")]
env, msg_json_str = smartsend("/chat/image", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/chat/image", data, nats_url="nats://localhost:4222")
```
#### JavaScript
@@ -267,7 +267,7 @@ const { smartsend } = require('./src/NATSBridge');
const fs = require('fs');
const image_data = fs.readFileSync('image.png');
const { env, msg_json_str } = await smartsend("/chat/image", [
const { env, env_json_str } = await smartsend("/chat/image", [
{ dataname: "user_image", data: image_data, type: "binary" }
]);
```
@@ -281,7 +281,7 @@ using NATSBridge
image_data = read("image.png")
data = [("user_image", image_data, "binary")]
env, msg_json_str = smartsend("/chat/image", data)
env, env_json_str = smartsend("/chat/image", data)
```
### Example 3: Request-Response Pattern
@@ -293,7 +293,7 @@ from nats_bridge import smartsend
# Send command with reply-to
data = [("command", {"action": "read_sensor"}, "dictionary")]
env, msg_json_str = smartsend(
env, env_json_str = smartsend(
"/device/command",
data,
nats_url="nats://localhost:4222",
@@ -301,7 +301,7 @@ env, msg_json_str = smartsend(
reply_to_msg_id="cmd-001"
)
# env: msgEnvelope_v1 object
# msg_json_str: JSON string for publishing to NATS
# env_json_str: JSON string for publishing to NATS
```
#### JavaScript (Responder)
@@ -358,7 +358,7 @@ import os
large_data = os.urandom(2_000_000) # 2MB of random data
# Send with file server URL
env, msg_json_str = smartsend(
env, env_json_str = smartsend(
"/data/large",
[("large_file", large_data, "binary")],
nats_url="nats://localhost:4222",
@@ -380,7 +380,7 @@ const largeData = new ArrayBuffer(2_000_000);
const view = new Uint8Array(largeData);
view.fill(42); // Fill with some data
const { env, msg_json_str } = await smartsend("/data/large", [
const { env, env_json_str } = await smartsend("/data/large", [
{ dataname: "large_file", data: largeData, type: "binary" }
], {
fileserverUrl: "http://localhost:8080",
@@ -396,7 +396,7 @@ using NATSBridge
# Create large data (> 1MB)
large_data = rand(UInt8, 2_000_000)
env, msg_json_str = smartsend(
env, env_json_str = smartsend(
"/data/large",
[("large_file", large_data, "binary")],
fileserver_url="http://localhost:8080"
@@ -425,7 +425,7 @@ data = [
("user_avatar", image_data, "image")
]
env, msg_json_str = smartsend("/chat/mixed", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/chat/mixed", data, nats_url="nats://localhost:4222")
```
#### JavaScript
@@ -435,7 +435,7 @@ const { smartsend } = require('./src/NATSBridge');
const fs = require('fs');
const { env, msg_json_str } = await smartsend("/chat/mixed", [
const { env, env_json_str } = await smartsend("/chat/mixed", [
{
dataname: "message_text",
data: "Hello with image!",
@@ -461,7 +461,7 @@ data = [
("user_avatar", image_data, "image")
]
env, msg_json_str = smartsend("/chat/mixed", data)
env, env_json_str = smartsend("/chat/mixed", data)
```
### Example 6: Table Data (Arrow IPC)
@@ -483,7 +483,7 @@ df = pd.DataFrame({
# Send as table type
data = [("students", df, "table")]
env, msg_json_str = smartsend("/data/students", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/data/students", data, nats_url="nats://localhost:4222")
```
#### Julia
@@ -500,7 +500,7 @@ df = DataFrame(
)
data = [("students", df, "table")]
env, msg_json_str = smartsend("/data/students", data)
env, env_json_str = smartsend("/data/students", data)
```
---
@@ -519,7 +519,7 @@ using NATSBridge
# Send dictionary from Julia to JavaScript
config = Dict("step_size" => 0.01, "iterations" => 1000)
data = [("config", config, "dictionary")]
env, msg_json_str = smartsend("/analysis/config", data, nats_url="nats://localhost:4222")
env, env_json_str = smartsend("/analysis/config", data, nats_url="nats://localhost:4222")
```
#### JavaScript Receiver
@@ -544,7 +544,7 @@ for (const payload of envelope.payloads) {
```javascript
const { smartsend } = require('./src/NATSBridge');
const { env, msg_json_str } = await smartsend("/data/transfer", [
const { env, env_json_str } = await smartsend("/data/transfer", [
{ dataname: "message", data: "Hello from JS!", type: "text" }
]);
```
@@ -568,7 +568,7 @@ for dataname, data, type in envelope["payloads"]:
from nats_bridge import smartsend
data = [("message", "Hello from Python!", "text")]
env, msg_json_str = smartsend("/chat/python", data)
env, env_json_str = smartsend("/chat/python", data)
```
#### Julia Receiver

12
examples/walkthrough.md
View File

@@ -132,7 +132,7 @@ class ChatUI {
});
}
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
`/chat/${this.currentRoom}`,
data,
{
@@ -304,7 +304,7 @@ class FileUploadService {
type: 'binary'
}];
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
`/files/${recipient}`,
data,
{
@@ -534,7 +534,7 @@ class SensorSender:
data = [("reading", reading.to_dict(), "dictionary")]
# With is_publish=False, returns (envelope, json_str) without publishing
env, msg_json_str = smartsend(
env, env_json_str = smartsend(
f"/sensors/{sensor_id}/prepare",
data,
nats_url=self.nats_url,
@@ -543,9 +543,9 @@ class SensorSender:
)
# Now you can publish manually using NATS request-reply pattern
# nc.request(subject, msg_json_str, reply_to=reply_to_topic)
# nc.request(subject, env_json_str, reply_to=reply_to_topic)
return env, msg_json_str
return env, env_json_str
def send_batch(self, readings: List[SensorReading]):
batch = SensorBatch()
@@ -833,7 +833,7 @@ class DashboardUI {
async refreshData() {
// Request fresh data
const { env, msg_json_str } = await smartsend("/dashboard/request", [
const { env, env_json_str } = await smartsend("/dashboard/request", [
{ dataname: "request", data: { type: "refresh" }, type: "dictionary" }
], {
fileserverUrl: window.config.fileserver_url

14
src/NATSBridge.jl
View File

@@ -386,9 +386,9 @@ Each payload can have a different type, enabling mixed-content messages (e.g., c
- `is_publish::Bool = true` - Whether to automatically publish the message to NATS
# Return:
- A tuple `(env, msg_json_str)` where:
- A tuple `(env, env_json_str)` where:
- `env::msgEnvelope_v1` - The envelope object containing all metadata and payloads
- `msg_json_str::String` - JSON string representation of the envelope for publishing
- `env_json_str::String` - JSON string representation of the envelope for publishing
# Example
```jldoctest
@@ -415,7 +415,7 @@ env, msg_json = smartsend("chat.subject", [
])
# Publish the JSON string directly using NATS request-reply pattern
# reply = NATS.request(nats_url, subject, msg_json_str; reply_to=reply_to_topic)
# reply = NATS.request(nats_url, subject, env_json_str; reply_to=reply_to_topic)
```
""" #[PENDING]
function smartsend(
@@ -432,7 +432,7 @@ function smartsend(
receiver_id::String = "",
reply_to::String = "",
reply_to_msg_id::String = "",
is_publish::Bool = true # some time the user want to get env and msg_json_str from this function without publishing the msg
is_publish::Bool = true # some time the user want to get env and env_json_str from this function without publishing the msg
) where {T1<:Any}
# Generate correlation ID if not provided
@@ -516,12 +516,12 @@ function smartsend(
metadata = Dict{String, Any}(),
)
msg_json_str = envelope_to_json(env) # Convert envelope to JSON
env_json_str = envelope_to_json(env) # Convert envelope to JSON
if is_publish
publish_message(nats_url, subject, msg_json_str, cid) # Publish message to NATS
publish_message(nats_url, subject, env_json_str, cid) # Publish message to NATS
end
return (env, msg_json_str)
return (env, env_json_str)
end

8
src/NATSBridge.js
View File

@@ -462,7 +462,7 @@ async function smartsend(subject, data, options = {}) {
* @param {string} options.replyToMsgId - Message ID this message is replying to (default: "")
* @param {boolean} options.isPublish - Whether to automatically publish the message to NATS (default: true)
*
* @returns {Promise<Object>} - An object with { env: MessageEnvelope, msg_json_str: string }
* @returns {Promise<Object>} - An object with { env: MessageEnvelope, env_json_str: string }
*/
const {
natsUrl = DEFAULT_NATS_URL,
@@ -559,17 +559,17 @@ async function smartsend(subject, data, options = {}) {
});
// Convert envelope to JSON string
const msg_json_str = env.toString();
const env_json_str = env.toString();
// Publish to NATS if isPublish is true
if (isPublish) {
await publish_message(natsUrl, subject, msg_json_str, correlationId);
await publish_message(natsUrl, subject, env_json_str, correlationId);
}
// Return both envelope and JSON string (tuple-like structure)
return {
env: env,
msg_json_str: msg_json_str
env_json_str: env_json_str
};
}

4
src/nats_bridge.py
View File

@@ -462,9 +462,9 @@ def smartsend(subject, data, nats_url=DEFAULT_NATS_URL, fileserver_url=DEFAULT_F
is_publish: Whether to automatically publish the message to NATS (default: True)
Returns:
tuple: (env, msg_json_str) where:
tuple: (env, env_json_str) where:
- env: MessageEnvelope object with all metadata and payloads
- msg_json_str: JSON string representation of the envelope for publishing
- env_json_str: JSON string representation of the envelope for publishing
"""
# Generate correlation ID if not provided
cid = correlation_id if correlation_id else str(uuid.uuid4())

2
test/test_js_dict_sender.js
View File

@@ -118,7 +118,7 @@ async function test_dict_send() {
// Use smartsend with dictionary type
// For small Dictionary: will use direct transport (JSON encoded)
// For large Dictionary: will use link transport (uploaded to fileserver)
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
SUBJECT,
[data1, data2],
{

2
test/test_js_file_sender.js
View File

@@ -98,7 +98,7 @@ async function test_large_binary_send() {
// Use smartsend with binary type - will automatically use link transport
// if file size exceeds the threshold (1MB by default)
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
SUBJECT,
[data1, data2],
{

2
test/test_js_mix_payload_sender.js
View File

@@ -222,7 +222,7 @@ async function test_mix_send() {
];
// Use smartsend with mixed content
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
SUBJECT,
payloads,
{

2
test/test_js_table_sender.js
View File

@@ -118,7 +118,7 @@ async function test_table_send() {
// Use smartsend with table type
// For small Table: will use direct transport (Arrow IPC encoded)
// For large Table: will use link transport (uploaded to fileserver)
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
SUBJECT,
[data1, data2],
{

2
test/test_js_text_sender.js
View File

@@ -94,7 +94,7 @@ async function test_text_send() {
// Use smartsend with text type
// For small text: will use direct transport (Base64 encoded UTF-8)
// For large text: will use link transport (uploaded to fileserver)
const { env, msg_json_str } = await smartsend(
const { env, env_json_str } = await smartsend(
SUBJECT,
[data1, data2],
{

2
test/test_julia_dict_sender.jl
View File

@@ -92,7 +92,7 @@ function test_dict_send()
# Use smartsend with dictionary type
# For small Dictionary: will use direct transport (JSON encoded)
# For large Dictionary: will use link transport (uploaded to fileserver)
env, msg_json = NATSBridge.smartsend(
env, env_json_str = NATSBridge.smartsend(
SUBJECT,
[data1, data2]; # List of (dataname, data, type) tuples
nats_url = NATS_URL,

2
test/test_julia_file_sender.jl
View File

@@ -79,7 +79,7 @@ function test_large_binary_send()
# Use smartsend with binary type - will automatically use link transport
# if file size exceeds the threshold (1MB by default)
# API: smartsend(subject, [(dataname, data, type), ...]; keywords...)
env, msg_json = NATSBridge.smartsend(
env, env_json_str = NATSBridge.smartsend(
SUBJECT,
[data1, data2]; # List of (dataname, data, type) tuples
nats_url = NATS_URL;

2
test/test_julia_mix_payloads_sender.jl
View File

@@ -186,7 +186,7 @@ function test_mix_send()
]
# Use smartsend with mixed content
env, msg_json = NATSBridge.smartsend(
env, env_json_str = NATSBridge.smartsend(
SUBJECT,
payloads; # List of (dataname, data, type) tuples
nats_url = NATS_URL,

2
test/test_julia_table_sender.jl
View File

@@ -90,7 +90,7 @@ function test_table_send()
# Use smartsend with table type
# For small DataFrame: will use direct transport (Base64 encoded Arrow IPC)
# For large DataFrame: will use link transport (uploaded to fileserver)
env, msg_json = NATSBridge.smartsend(
env, env_json_str = NATSBridge.smartsend(
SUBJECT,
[data1, data2]; # List of (dataname, data, type) tuples
nats_url = NATS_URL,

2
test/test_julia_text_sender.jl
View File

@@ -75,7 +75,7 @@ function test_text_send()
# Use smartsend with text type
# For small text: will use direct transport (Base64 encoded UTF-8)
# For large text: will use link transport (uploaded to fileserver)
env, msg_json = NATSBridge.smartsend(
env, env_json_str = NATSBridge.smartsend(
SUBJECT,
[data1, data2]; # List of (dataname, data, type) tuples
nats_url = NATS_URL,

2
test/test_micropython_dict_sender.py
View File

@@ -64,7 +64,7 @@ def main():
log_trace(correlation_id, f"Correlation ID: {correlation_id}")
# Use smartsend with dictionary type
env, msg_json = smartsend(
env, env_json_str = smartsend(
SUBJECT,
[data1, data2], # List of (dataname, data, type) tuples
nats_url=NATS_URL,

2
test/test_micropython_file_sender.py
View File

@@ -44,7 +44,7 @@ def main():
log_trace(correlation_id, f"Correlation ID: {correlation_id}")
# Use smartsend with binary type
env, msg_json = smartsend(
env, env_json_str = smartsend(
SUBJECT,
[data1, data2], # List of (dataname, data, type) tuples
nats_url=NATS_URL,

2
test/test_micropython_mixed_sender.py
View File

@@ -58,7 +58,7 @@ def main():
log_trace(correlation_id, f"Correlation ID: {correlation_id}")
# Use smartsend with mixed types
env, msg_json = smartsend(
env, env_json_str = smartsend(
SUBJECT,
data, # List of (dataname, data, type) tuples
nats_url=NATS_URL,

2
test/test_micropython_text_sender.py
View File

@@ -46,7 +46,7 @@ def main():
# Use smartsend with text type
# For small text: will use direct transport (Base64 encoded UTF-8)
# For large text: will use link transport (uploaded to fileserver)
env, msg_json = smartsend(
env, env_json_str = smartsend(
SUBJECT,
[data1, data2], # List of (dataname, data, type) tuples
nats_url=NATS_URL,