v0.1.1 - Cleaning things up.
This commit is contained in:
Your Name
509
docs/BLOSSOM_FLOW.md
Normal file
509
docs/BLOSSOM_FLOW.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# 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 | | | |
|
||||
|<--------------------| | | |
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user