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

update_docs #10

Merged
ton merged 29 commits from update_docs into main 2026-03-14 00:53:03 +00:00
Conversation 0 Commits 29 Files Changed 9 +34 -82
1 changed files with 34 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit e99fb09298 - Show all commits

116
docs/spec.md
View File

@@ -572,92 +572,44 @@ function fileserver_download_handler(
### Sending Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ 1. User calls smartsend(subject, data) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. For each payload: │
│ - Serialize data according to payload_type │
│ - Calculate serialized size │
└─────────────────────────────────────────────────────────────────┘
│
├─ Size < Threshold ────────────────►┐
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐ │
│ 3. Direct Transport: │ │
│ - Encode as Base64 │ │
│ - Include in payload.data │ │
└─────────────────────────────────────────────────────────────────┘ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────┐ │
│ 4. Build envelope with metadata │ │
│ - correlation_id, msg_id, timestamp │ │
│ - sender/receiver info │ │
│ - payloads array │ │
└─────────────────────────────────────────────────────────────────┘ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────┐ │
│ 5. Convert envelope to JSON string │ │
│ 6. Publish to NATS subject │ │
└─────────────────────────────────────────────────────────────────┘ │
│
┌─────────────────────────────────────────────────────────────────┐ │
│ 7. Return envelope and JSON string to caller │ │
└─────────────────────────────────────────────────────────────────┘ │
│
```mermaid
flowchart TD
A[User calls smartsend\(subject, data\)] --> B[Serialize payload according to payload_type]
B --> C{Calculate serialized size}
C -->|Size < Threshold| D[Direct Transport: Encode as Base64]
C -->|Size >= Threshold| E[Link Transport: Upload to file server]
D --> F[Build envelope with metadata]
E --> F
F --> G[Convert envelope to JSON string]
G --> H[Publish to NATS subject]
H --> I[Return envelope and JSON string to caller]
style A fill:#f9f9f9,stroke:#333
style I fill:#e0e7ff,stroke:#3b82f6
style D fill:#d1fae5,stroke:#10b981
style E fill:#fef3c7,stroke:#f59e0b
```
### Receiving Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ 1. NATS message arrives │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Parse JSON envelope │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. For each payload: │
│ - Check transport type │
└─────────────────────────────────────────────────────────────────┘
│
├─ transport == "direct" ──────────►┐
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐ │
│ 4. Direct Transport: │ │
│ - Extract Base64 data │ │
│ - Decode Base64 │ │
│ - Deserialize based on payload_type │ │
└─────────────────────────────────────────────────────────────────┘ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────┐ │
│ 5. Link Transport: │ │
│ - Extract URL from data │ │
│ - Fetch with exponential backoff │ │
│ - Deserialize based on payload_type │ │
└─────────────────────────────────────────────────────────────────┘ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────┐ │
│ 6. Replace payloads array with deserialized tuples │ │
│ - [(dataname, data, type), ...] │ │
└─────────────────────────────────────────────────────────────────┘ │
│
┌─────────────────────────────────────────────────────────────────┐
│ 7. Return envelope with processed payloads │
└─────────────────────────────────────────────────────────────────┘
```mermaid
flowchart TD
A[NATS message arrives] --> B[Parse JSON envelope]
B --> C[For each payload: Check transport type]
C -->|transport == direct| D[Direct Transport: Extract Base64]
C -->|transport == link| E[Link Transport: Fetch from URL]
D --> F[Decode Base64]
E --> G[Fetch with exponential backoff]
F --> H[Deserialize based on payload_type]
G --> H
H --> I[Build payloads array]
I --> J[Replace payloads array with deserialized tuples]
J --> K[Return envelope with processed payloads]
style A fill:#f9f9f9,stroke:#333
style K fill:#e0e7ff,stroke:#3b82f6
style D fill:#d1fae5,stroke:#10b981
style E fill:#fef3c7,stroke:#f59e0b
```
---