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 ### Sending Flow
```mermaid ```
flowchart TD ┌─────────────────────────────────────────────────────────────────┐
A[User calls smartsend(subject, data)] --> B[Serialize payload according to payload_type] │ 1. User calls smartsend(subject, data) │
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] │ 2. For each payload: │
F --> G │ - Serialize data according to payload_type │
G --> H[Convert to JSON string] │ - Calculate serialized size │
H --> I[Publish to NATS subject] └─────────────────────────────────────────────────────────────────┘
I --> J[Return envelope and JSON string] │
├─ Size < Threshold ────────────────►┐
style A fill:#f9f9f9,stroke:#333 │ │
style D fill:#e0e7ff,stroke:#3b82f6 ▼ ▼
style I fill:#e0e7ff,stroke:#3b82f6 ┌─────────────────────────────────────────────────────────────────┐ │
│ 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 ### Receiving Flow
```mermaid ```
flowchart TD ┌─────────────────────────────────────────────────────────────────┐
A[NATS message arrives] --> B[Parse JSON envelope] │ 1. NATS message arrives │
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] │ 2. Parse JSON envelope │
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] │ 3. For each payload: │
│ - Check transport type │
style A fill:#f9f9f9,stroke:#333 └─────────────────────────────────────────────────────────────────┘
style D fill:#e0e7ff,stroke:#3b82f6 │
style K fill:#e0e7ff,stroke:#3b82f6 ├─ 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 │
└─────────────────────────────────────────────────────────────────┘
``` ```
--- ---