510 lines
30 KiB
Markdown
510 lines
30 KiB
Markdown
# Blossom Protocol Flow Charts
|
|
|
|
This document provides ASCII flow charts illustrating how each Blossom Upgrade Document (BUD) works in practice.
|
|
|
|
---
|
|
|
|
## BUD-01: Basic Blob Retrieval
|
|
|
|
### GET Request Flow
|
|
```
|
|
Client Request nginx Database
|
|
| | |
|
|
| GET /<sha256> | |
|
|
|--------------------------->| |
|
|
| | |
|
|
| | Check file exists |
|
|
| | in blobs/ directory |
|
|
| | |
|
|
| File Found | |
|
|
|<---------------------------| |
|
|
| 200 OK + File Content | |
|
|
| | |
|
|
| File Not Found | |
|
|
|<---------------------------| |
|
|
| 404 Not Found | |
|
|
```
|
|
|
|
### HEAD Request Flow
|
|
```
|
|
Client Request FastCGI App Database
|
|
| | |
|
|
| HEAD /<sha256> | |
|
|
|------------------------->| |
|
|
| | |
|
|
| | Query blob metadata |
|
|
| |-------------------------->|
|
|
| | |
|
|
| | Blob exists |
|
|
| |<--------------------------|
|
|
| | size, type, uploaded_at |
|
|
| | |
|
|
| 200 OK + Headers | |
|
|
|<-------------------------| |
|
|
| Content-Type: image/png | |
|
|
| Content-Length: 12345 | |
|
|
| | |
|
|
| | Blob not found |
|
|
| |<--------------------------|
|
|
| | |
|
|
| 404 Not Found | |
|
|
|<-------------------------| |
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-02: Blob Upload & Authentication
|
|
|
|
### Upload Without Authentication
|
|
```
|
|
Client FastCGI App File System Database
|
|
| | | |
|
|
| PUT /upload | | |
|
|
|--------------------------->| | |
|
|
| Content: <binary data> | | |
|
|
| | | |
|
|
| | Calculate SHA-256 | |
|
|
| | hash of data | |
|
|
| | | |
|
|
| | Write to blobs/ | |
|
|
| |-------------------------->| |
|
|
| | | File saved |
|
|
| |<--------------------------| |
|
|
| | | |
|
|
| | Store metadata | |
|
|
| |----------------------------------------------->|
|
|
| | | | INSERT |
|
|
| |<-----------------------------------------------|
|
|
| | | |
|
|
| 200 OK | | |
|
|
|<---------------------------| | |
|
|
| { | | |
|
|
| "url": "https://...", | | |
|
|
| "sha256": "abc123...", | | |
|
|
| "size": 12345, | | |
|
|
| "type": "image/png", | | |
|
|
| "uploaded": 1234567890 | | |
|
|
| } | | |
|
|
```
|
|
|
|
### Upload With Nostr Authentication
|
|
```
|
|
Client FastCGI App Nostr Validation File System Database
|
|
| | | | |
|
|
| PUT /upload | | | |
|
|
|--------------------------->| | | |
|
|
| Authorization: Nostr <evt> | | | |
|
|
| Content: <binary data> | | | |
|
|
| | | | |
|
|
| | Parse auth event | | |
|
|
| |-------------------------->| | |
|
|
| | | • Verify signature | |
|
|
| | | • Check expiration | |
|
|
| | | • Validate tags | |
|
|
| |<--------------------------| | |
|
|
| | Valid ✓ | | |
|
|
| | | | |
|
|
| | Calculate hash | | |
|
|
| | | | |
|
|
| | Compare with 'x' tag | | |
|
|
| | in auth event | | |
|
|
| | | | |
|
|
| | Hash matches ✓ | | |
|
|
| | | | |
|
|
| | Save file | | |
|
|
| |----------------------------------------------->| |
|
|
| | | | Write | |
|
|
| |<-----------------------------------------------| |
|
|
| | | | |
|
|
| | Store metadata | | |
|
|
| |-------------------------------------------------------------->|
|
|
| | (include uploader_pubkey) | | | INSERT |
|
|
| |<--------------------------------------------------------------|
|
|
| | | | |
|
|
| 200 OK + Blob Descriptor | | | |
|
|
|<---------------------------| | | |
|
|
```
|
|
|
|
### Authentication Failure Flows
|
|
```
|
|
Invalid Signature:
|
|
Client --> FastCGI --> Nostr Validation --> 401 Unauthorized
|
|
|
|
Expired Event:
|
|
Client --> FastCGI --> Nostr Validation --> 401 Unauthorized
|
|
|
|
Hash Mismatch:
|
|
Client --> FastCGI --> Hash Check --> 409 Conflict
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-03: User Server Lists
|
|
|
|
### Server List Publication
|
|
```
|
|
User/Client Nostr Relay Other Clients
|
|
| | |
|
|
| Publish kind:10063 | |
|
|
| event with server tags | |
|
|
|------------------------>| |
|
|
| { | |
|
|
| "kind": 10063, | |
|
|
| "tags": [ | |
|
|
| ["server", "cdn1"], | |
|
|
| ["server", "cdn2"] | |
|
|
| ] | |
|
|
| } | |
|
|
| | |
|
|
| | Store event |
|
|
| | |
|
|
| | |
|
|
| | Query for user's |
|
|
| | server list |
|
|
| |<--------------------------|
|
|
| | |
|
|
| | Return server list |
|
|
| |-------------------------->|
|
|
```
|
|
|
|
### Client Blob Discovery
|
|
```
|
|
Client Original URL Author's Servers
|
|
| | |
|
|
| GET blob from URL | |
|
|
|------------------------->| |
|
|
| | |
|
|
| 404 Not Found | |
|
|
|<-------------------------| |
|
|
| | |
|
|
| Extract SHA-256 hash | |
|
|
| from URL | |
|
|
| | |
|
|
| Query nostr for author's | |
|
|
| server list (kind:10063) | |
|
|
| | |
|
|
| Try each server in order | |
|
|
|--------------------------------------------------->|
|
|
| | |
|
|
| GET /<sha256> | |
|
|
| | |
|
|
| 200 OK + File Content | |
|
|
|<---------------------------------------------------|
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-04: Blob Mirroring
|
|
|
|
### Mirror Request Flow
|
|
```
|
|
Client Server B Server A Database
|
|
| | | |
|
|
| PUT /mirror | | |
|
|
|------------------------>| | |
|
|
| { | | |
|
|
| "url": "https:// | | |
|
|
| serverA/abc123..." | | |
|
|
| } | | |
|
|
| Authorization: <event> | | |
|
|
| | | |
|
|
| | Validate auth event | |
|
|
| | (check x tag matches) | |
|
|
| | | |
|
|
| | Download from URL | |
|
|
| |------------------------>| |
|
|
| | | |
|
|
| | Stream blob content | |
|
|
| |<------------------------| |
|
|
| | | |
|
|
| | Calculate SHA-256 | |
|
|
| | during download | |
|
|
| | | |
|
|
| | Verify hash matches | |
|
|
| | x tag in auth event | |
|
|
| | | |
|
|
| | Save blob locally | |
|
|
| | | |
|
|
| | Store metadata | |
|
|
| |------------------------------------------------>|
|
|
| | | | INSERT |
|
|
| |<------------------------------------------------|
|
|
| | | |
|
|
| 200 OK | | |
|
|
|<------------------------| | |
|
|
| Blob Descriptor | | |
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-05: Media Optimization
|
|
|
|
### Media Processing Flow
|
|
```
|
|
Client Media Server Optimization Engine File System
|
|
| | | |
|
|
| PUT /media | | |
|
|
|------------------------>| | |
|
|
| Content: <raw image> | | |
|
|
| Content-Type: image/png | | |
|
|
| Authorization: <event> | | |
|
|
| | | |
|
|
| | Validate auth | |
|
|
| | (type="media") | |
|
|
| | | |
|
|
| | Process media | |
|
|
| |------------------------>| |
|
|
| | | • Resize/compress |
|
|
| | | • Format conversion |
|
|
| | | • Quality optimization|
|
|
| |<------------------------| Optimized media |
|
|
| | | |
|
|
| | Calculate new hash | |
|
|
| | | |
|
|
| | Save optimized blob | |
|
|
| |------------------------------------------------>|
|
|
| | | | Write |
|
|
| |<------------------------------------------------|
|
|
| | | |
|
|
| 200 OK | | |
|
|
|<------------------------| | |
|
|
| { | | |
|
|
| "url": "new_hash...", | | |
|
|
| "sha256": "def456...",| | |
|
|
| "size": 8765, | | |
|
|
| "type": "image/webp" | | |
|
|
| } | | |
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-06: Upload Requirements
|
|
|
|
### Upload Requirement Check
|
|
```
|
|
Client FastCGI App Configuration
|
|
| | |
|
|
| HEAD /upload | |
|
|
|------------------------>| |
|
|
| Authorization: <event> | |
|
|
| (optional) | |
|
|
| | |
|
|
| | Check server config |
|
|
| |------------------------>|
|
|
| | | • Max file size
|
|
| | | • Auth required?
|
|
| | | • Allowed types
|
|
| |<------------------------| • Rate limits
|
|
| | |
|
|
| | Validate auth if |
|
|
| | provided |
|
|
| | |
|
|
| 200 OK | |
|
|
|<------------------------| |
|
|
| X-Upload-Size-Limit: | |
|
|
| 10485760 | |
|
|
| X-Upload-Auth-Required: | |
|
|
| true | |
|
|
| X-Upload-Types: | |
|
|
| image/*,video/* | |
|
|
```
|
|
|
|
### Upload Policy Enforcement
|
|
```
|
|
Client FastCGI App Policy Check
|
|
| | |
|
|
| PUT /upload | |
|
|
|------------------------>| |
|
|
| Content-Length: 50MB | |
|
|
| | |
|
|
| | Check against limits |
|
|
| |------------------------>|
|
|
| | | Size: 50MB > 10MB ✗
|
|
| |<------------------------| REJECT
|
|
| | |
|
|
| 413 Payload Too Large | |
|
|
|<------------------------| |
|
|
| { | |
|
|
| "error": "File too | |
|
|
| large. Max: 10MB" | |
|
|
| } | |
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-07: Paid Upload/Download
|
|
|
|
### Payment Required Flow
|
|
```
|
|
Client Paid Server Payment Provider
|
|
| | |
|
|
| PUT /upload | |
|
|
|------------------------>| |
|
|
| | |
|
|
| | Check payment required |
|
|
| | |
|
|
| 402 Payment Required | |
|
|
|<------------------------| |
|
|
| X-Lightning: lnbc... | |
|
|
| X-Cashu: creq... | |
|
|
| | |
|
|
| User pays invoice | |
|
|
|-------------------------------------------------->|
|
|
| | |
|
|
| PUT /upload (retry) | |
|
|
|------------------------>| |
|
|
| X-Lightning: <preimage> | |
|
|
| | |
|
|
| | Verify payment proof |
|
|
| |------------------------>|
|
|
| | | Valid ✓
|
|
| |<------------------------|
|
|
| | |
|
|
| | Process upload |
|
|
| | |
|
|
| 200 OK + Blob Desc | |
|
|
|<------------------------| |
|
|
```
|
|
|
|
### Payment Methods
|
|
```
|
|
Lightning Payment:
|
|
Client --> Server --> Lightning Node --> Payment Verification --> Upload Success
|
|
|
|
Cashu Payment:
|
|
Client --> Server --> Cashu Mint --> Token Validation --> Upload Success
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-08: NIP-94 File Metadata
|
|
|
|
### Enhanced Blob Descriptor
|
|
```
|
|
Client Upload FastCGI App Metadata Generation Response
|
|
| | | |
|
|
| PUT /upload | | |
|
|
|---------------------> | | |
|
|
| | | |
|
|
| | Process file | |
|
|
| | | |
|
|
| | Generate NIP-94 tags | |
|
|
| |------------------------>| |
|
|
| | | • ["url", "..."] |
|
|
| | | • ["m", "image/png"] |
|
|
| | | • ["x", "hash..."] |
|
|
| | | • ["size", "12345"] |
|
|
| | | • ["magnet", "..."] |
|
|
| |<------------------------| NIP-94 tags |
|
|
| | | |
|
|
| | Build response | |
|
|
| |------------------------------------------------>|
|
|
| Enhanced Response | | |
|
|
|<--------------------- | | |
|
|
| { | | |
|
|
| "url": "...", | | |
|
|
| "sha256": "...", | | |
|
|
| "nip94": [ | | |
|
|
| ["url", "..."], | | |
|
|
| ["m", "..."], | | |
|
|
| ["x", "..."] | | |
|
|
| ] | | |
|
|
| } | | |
|
|
```
|
|
|
|
---
|
|
|
|
## BUD-09: Blob Reporting
|
|
|
|
### Content Moderation Flow
|
|
```
|
|
Client/User FastCGI App Moderation System Action
|
|
| | | |
|
|
| PUT /report | | |
|
|
|---------------------> | | |
|
|
| NIP-56 report event | | |
|
|
| { | | |
|
|
| "kind": 1984, | | |
|
|
| "tags": [ | | |
|
|
| ["x", "hash..."] | | |
|
|
| ], | | |
|
|
| "content": "spam" | | |
|
|
| } | | |
|
|
| | | |
|
|
| | Validate report | |
|
|
| | | |
|
|
| | Store report | |
|
|
| |------------------------>| |
|
|
| | | • Log report |
|
|
| | | • Check reporter |
|
|
| | | • Queue for review |
|
|
| |<------------------------| Stored |
|
|
| | | |
|
|
| 200 OK | | |
|
|
|<--------------------- | | |
|
|
| | | |
|
|
| | | Manual Review |
|
|
| | |---------------------> |
|
|
| | | | Remove blob
|
|
| | | | Block hash
|
|
| | | | Ban user
|
|
```
|
|
|
|
### Automated Moderation
|
|
```
|
|
Trusted Reporter Report --> Immediate Action --> Blob Removed
|
|
|
|
Multiple Reports --> Temporary Hide --> Manual Review --> Final Decision
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Ginxsom Architecture Flow
|
|
|
|
### Nginx + FastCGI Integration
|
|
```
|
|
Internet nginx FastCGI App Database File System
|
|
| | | | |
|
|
| GET /<sha256> | | | |
|
|
|-------------------->| | | |
|
|
| | Direct file serve | | |
|
|
| |----------------------------------------->| |
|
|
| | | | blobs/ |
|
|
| File Content |<-----------------------------------------| <hash> |
|
|
|<--------------------| | | |
|
|
| | | | |
|
|
| HEAD /<sha256> | | | |
|
|
|-------------------->| | | |
|
|
| | Forward to FastCGI | | |
|
|
| |-------------------->| | |
|
|
| | | Query metadata | |
|
|
| | |------------------->| |
|
|
| | | | SELECT |
|
|
| | |<-------------------| |
|
|
| | Headers response | | |
|
|
| |<--------------------| | |
|
|
| Metadata Headers | | | |
|
|
|<--------------------| | | |
|
|
| | | | |
|
|
| PUT /upload | | | |
|
|
|-------------------->| | | |
|
|
| | Forward to FastCGI | | |
|
|
| |-------------------->| | |
|
|
| | | Process upload | |
|
|
| | | | |
|
|
| | | Store metadata | |
|
|
| | |------------------->| |
|
|
| | | | INSERT |
|
|
| | |<-------------------| |
|
|
| | | | |
|
|
| | | Save file | |
|
|
| | |-------------------------------------->|
|
|
| | | | Write |
|
|
| | |<--------------------------------------|
|
|
| | JSON response | | |
|
|
| |<--------------------| | |
|
|
| Blob Descriptor | | | |
|
|
|<--------------------| | | |
|
|
```
|
|
|