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

update docs

Browse Source
This commit is contained in:
narawat
2026-05-13 17:35:46 +07:00
parent c25c6a8a43
commit b0acee053c
5 changed files with 120 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/walkthrough.md
View File

@@ -1,7 +1,7 @@
# Walkthrough: NATSBridge
**Version**: 1.0.0
**Date**: 2026-03-23
**Version**: 1.2.0
**Date**: 2026-05-13
**Status**: Active
**Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl)
@@ -213,23 +213,25 @@ NATSBridge builds the message envelope:
- **reply_to**: Tells backend where to send response
- **payloads array**: Contains all data with metadata for proper handling
#### Step 5: Publish to NATS
#### Step 5: Publish to NATS (Caller's Responsibility)
```javascript
await NATSBridge.NATSClient.connect("ws://localhost:4222");
await NATSBridge.NATSClient.publish("/agent/wine/api/v1/prompt", msgJson);
// NATS publishing is the caller's responsibility
const conn = await NATS.connect({ servers: "ws://localhost:4222" });
await conn.publish("/agent/wine/api/v1/prompt", msgJson);
```
**Rationale**:
- NATS provides low-latency message delivery
- JSON format ensures cross-platform compatibility
- `smartsend()` returns `(env, msgJson)` - caller handles publishing
#### Step 6: Julia Backend Receives Message
```julia
# Julia backend
msg = NATS.subscription.next() # Get message from NATS
env = smartreceive(msg)
nats_msg = NATS.subscription.next() # Get message from NATS
env = smartreceive(String(nats_msg.payload))
# env["payloads"] is now:
# [
@@ -355,8 +357,8 @@ const response = await plikOneshotUpload(
```julia
# Julia backend
msg = NATS.subscription.next()
env = smartreceive(msg)
nats_msg = NATS.subscription.next()
env = smartreceive(String(nats_msg.payload))
# NATSBridge automatically:
# 1. Extracts URL from payload
@@ -428,8 +430,8 @@ arrow_bytes = buf.getvalue()
```julia
# Julia backend
msg = NATS.subscription.next()
env = smartreceive(msg)
nats_msg = NATS.subscription.next()
env = smartreceive(String(nats_msg.payload))
# env["payloads"][1] is now:
# ("data", DataFrame with id, name, score columns, "arrowtable")
@@ -512,8 +514,8 @@ payload_b64 = base64.b64encode(json_bytes).decode('ascii')
```python
# Python backend
msg = await nats_consumer.next()
env = await smartreceive(msg)
nats_msg = await nats_consumer.next()
env = await smartreceive(str(nats_msg.payload))
# env["payloads"][0] is now:
# ("data", {"temperature": 25.5, "humidity": 60.0, ...}, "dictionary")
@@ -561,8 +563,8 @@ const [env, msgJson] = await NATSBridge.smartsend(
```python
# Python (Backend)
msg = await nats_consumer.next()
env = await smartreceive(msg)
nats_msg = await nats_consumer.next()
env = await smartreceive(str(nats_msg.payload))
# env["payloads"] is now:
# [
@@ -580,8 +582,8 @@ env = await smartreceive(msg)
```julia
# Julia (Backend)
msg = NATS.subscription.next()
env = smartreceive(msg)
nats_msg = NATS.subscription.next()
env = smartreceive(String(nats_msg.payload))
# env["payloads"] is now:
# [
@@ -726,7 +728,7 @@ log_trace(correlation_id, "Published to NATS")
|----------|---------|-------------|
| `NATS_URL` | `nats://localhost:4222` | NATS server URL |
| `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL |
| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes |
| `SIZE_THRESHOLD` | `500000` | Size threshold in bytes (0.5MB) |
---
@@ -769,6 +771,10 @@ log_trace(correlation_id, "Published to NATS")
| Date | Version | Changes | Specification Reference |
|------|---------|---------|------------------------|
| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/NATSBridge.jl) | All sections |
| - | - | Updated smartreceive calls to use String(nats_msg.payload) pattern | All sections |
| - | - | Removed NATSClient.publish() calls (caller responsible for NATS publishing) | All sections |
| - | - | Removed is_publish and nats_connection parameter references | All sections |
| 2026-03-23 | 1.0.0 | Updated to ASG Framework walkthrough guidelines | All sections |
| 2026-03-13 | 1.0.0 | Initial walkthrough documentation | specification.md:2-19 (all sections) |