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 +82 -33
1 changed files with 82 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 42fffb8a4f - Show all commits

115
docs/spec.md
View File

@@ -572,43 +572,92 @@ function fileserver_download_handler(
### Sending Flow
```mermaid
flowchart TD
A[User calls smartsend(subject, data)] --> B[Serialize payload according to payload_type]
B --> C[Calculate serialized size]
C --> D{Size < Threshold?}
D -->|Yes| E[Direct Transport: Base64 encode]
D -->|No| F[Link Transport: Upload to file server]
E --> G[Build envelope with metadata]
F --> G
G --> H[Convert to JSON string]
H --> I[Publish to NATS subject]
I --> J[Return envelope and JSON string]
style A fill:#f9f9f9,stroke:#333
style D fill:#e0e7ff,stroke:#3b82f6
style I fill:#e0e7ff,stroke:#3b82f6
```
┌─────────────────────────────────────────────────────────────────┐
│ 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 │ │
└─────────────────────────────────────────────────────────────────┘ │
│
```
### Receiving Flow
```mermaid
flowchart TD
A[NATS message arrives] --> B[Parse JSON envelope]
B --> C[Process each payload]
C --> D{Check transport type}
D -->|direct| E[Extract Base64 data]
D -->|link| F[Extract URL from data]
E --> G[Decode Base64]
F --> H[Fetch with exponential backoff]
G --> I[Deserialize based on payload_type]
H --> I
I --> J[Build payloads array]
J --> K[Return envelope with processed payloads]
style A fill:#f9f9f9,stroke:#333
style D fill:#e0e7ff,stroke:#3b82f6
style K fill:#e0e7ff,stroke:#3b82f6
```
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────┘
```
---