30 KiB
30 KiB
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 | | | |
|<--------------------| | | |