ginxsom/README.md

ginxsom 🌸

A high-performance Blossom server implementation in C, designed for optimal integration with nginx for blazing-fast file serving.

Overview

ginxsom is a Blossom protocol server implemented as a FastCGI application that integrates seamlessly with nginx. nginx handles static file serving directly while ginxsom processes authenticated operations (uploads, deletes, management) via FastCGI. This architecture provides optimal performance with nginx's excellent static file serving and C's efficiency for cryptographic operations.

Why ginxsom?

• Performance: C application with nginx static serving = maximum throughput
• Simplicity: Clean separation between static serving (nginx) and dynamic operations (C app)
• Scalability: nginx handles the heavy file serving load, C app handles auth and metadata
• Standards Compliant: Full Blossom protocol implementation with nostr authentication

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Client    │    │    nginx     │    │ ginxsom FastCGI │
│             │───▶│              │───▶│                 │
│             │    │              │    │                 │
└─────────────┘    └──────────────┘    └─────────────────┘
                          │                      │
                          ▼                      ▼
                   ┌─────────────┐    ┌─────────────────┐
                   │    Blobs    │    │   SQLite DB     │
                   │ (flat files)│    │  (metadata)     │
                   └─────────────┘    └─────────────────┘

Request Flow

1. File Retrieval (GET /<sha256>): nginx serves directly from disk
2. File Upload (PUT /upload): nginx calls ginxsom via FastCGI for authentication + storage
3. File Management (DELETE, LIST): nginx calls ginxsom via FastCGI
4. Metadata Operations: ginxsom manages SQLite database

Blossom Protocol Support

ginxsom implements the following Blossom Upgrade Documents (BUDs):

• BUD-01: Server requirements and blob retrieval ✅
• BUD-02: Blob upload and management ✅
• BUD-06: Upload requirements ✅

Supported Endpoints

Endpoint	Method	Description	Handler
/<sha256>	GET	Retrieve blob	nginx → disk
/<sha256>	HEAD	Check blob exists	nginx → disk
/upload	PUT	Upload new blob	nginx → FastCGI ginxsom
/upload	HEAD	Check upload requirements	nginx → FastCGI ginxsom
/list/<pubkey>	GET	List user's blobs	nginx → FastCGI ginxsom
/<sha256>	DELETE	Delete blob	nginx → FastCGI ginxsom

Installation

Prerequisites

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential libssl-dev libsqlite3-dev libfcgi-dev pkg-config

# RHEL/CentOS/Fedora  
sudo dnf install gcc make openssl-devel sqlite-devel fcgi-devel pkgconfig

# macOS
brew install openssl sqlite fcgi pkg-config

Building ginxsom

git clone https://github.com/yourusername/ginxsom.git
cd ginxsom
make

Installation

sudo make install
# Installs to /usr/local/bin/ginxsom

Configuration

ginxsom Configuration

Create /etc/ginxsom/config.conf:

[server]
socket_path = /run/ginxsom.sock
max_file_size = 104857600  # 100MB
storage_path = /var/lib/ginxsom/blobs
database_path = /var/lib/ginxsom/blobs.db

[auth]
require_auth_upload = true
require_auth_get = false
require_auth_list = false

[limits]
max_blobs_per_user = 1000
rate_limit_uploads = 10  # per minute

nginx Configuration

Add to your nginx configuration:

server {
    listen 80;
    server_name your-blossom-server.com;
    
    # CORS headers for all responses
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, HEAD, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Authorization, Content-Type, Content-Length, X-SHA-256, X-Content-Type, X-Content-Length";
    add_header Access-Control-Max-Age 86400;
    
    # Handle preflight OPTIONS requests
    if ($request_method = 'OPTIONS') {
        return 204;
    }
    
    # Static blob serving - nginx handles directly
    location ~ ^/([a-f0-9]{64})(\.[a-zA-Z0-9]+)?$ {
        root /var/lib/ginxsom/blobs;
        try_files /$1$2 =404;
        add_header Accept-Ranges bytes;
        
        # Set content type based on file extension if not detected
        location ~* \.(pdf)$ { add_header Content-Type application/pdf; }
        location ~* \.(jpg|jpeg)$ { add_header Content-Type image/jpeg; }
        location ~* \.(png)$ { add_header Content-Type image/png; }
        location ~* \.(mp4)$ { add_header Content-Type video/mp4; }
    }
    
    # All other requests go to ginxsom FastCGI
    location / {
        include fastcgi_params;
        fastcgi_pass unix:/run/ginxsom.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        
        # Handle large uploads
        client_max_body_size 100M;
        fastcgi_request_buffering off;
    }
}

Usage

Starting the Server

# Start ginxsom FastCGI daemon
sudo spawn-fcgi -s /run/ginxsom.sock -f /usr/local/bin/ginxsom -u www-data -g www-data

# Or with systemd
sudo systemctl enable ginxsom
sudo systemctl start ginxsom

Testing

# Check server is running
curl -I http://localhost/upload

# Upload a file (requires nostr authorization)
curl -X PUT http://localhost/upload \
  -H "Authorization: Nostr eyJ..." \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

# Retrieve a file
curl http://localhost/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

API Documentation

Authentication

All write operations require nostr event authentication via the Authorization header:

Authorization: Nostr <base64-encoded-nostr-event>

The nostr event must be kind 24242 with appropriate tags:

• t tag: upload, delete, list, or get
• x tag: SHA-256 hash for blob-specific operations
• expiration tag: Unix timestamp when event expires

Blob Descriptors

Successful uploads return blob descriptors:

{
  "url": "https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf",
  "sha256": "b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553",
  "size": 184292,
  "type": "application/pdf",
  "uploaded": 1725105921
}

File Storage

Current (Flat) Structure

/var/lib/ginxsom/blobs/
├── b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
├── a8472f6d93e42c1e5b4e9f3a7b2c8d4e6f9a1b3c5d7e8f0a1b2c3d4e5f6a7b8.png
└── ...

Future (Optimized) Structure

/var/lib/ginxsom/blobs/
├── b1/
│   └── 67/
│       └── b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
├── a8/
│   └── 47/
│       └── a8472f6d93e42c1e5b4e6f9a1b3c5d7e8f0a1b2c3d4e6f9a1b3c5d7e8f0a1b2c3d4e5f6a7b8.png

File and Extension Handling

ginxsom implements a sophisticated file and extension handling strategy that optimizes both performance and flexibility:

Database-Driven Architecture

The system uses the SQLite database as the single source of truth for blob existence and metadata:

-- Database schema (clean SHA-256 hashes, no extensions)
CREATE TABLE blobs (
    sha256 TEXT PRIMARY KEY,           -- Clean hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
    size INTEGER NOT NULL,
    type TEXT NOT NULL,
    uploaded_at INTEGER NOT NULL,
    uploader_pubkey TEXT,
    filename TEXT                      -- Original filename: document.pdf
);

Key Benefits:

• Database Lookup vs Filesystem: FastCGI queries the database instead of checking filesystem
• Single Source of Truth: Database definitively knows if a blob exists
• Extension Irrelevant: Database uses clean SHA-256 hashes without extensions
• Performance: Database queries are faster than filesystem stat() calls

URL and Extension Support

ginxsom supports flexible URL patterns for maximum client compatibility:

# Both forms work identically:
GET /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
GET /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

# HEAD requests work with or without extensions:
HEAD /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
HEAD /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

nginx File Storage Strategy

Files are stored on disk with extensions for nginx MIME type detection and optimal performance:

# Blossom-compliant nginx configuration
location ~ ^/([a-f0-9]{64}).*$ {
    root /var/lib/ginxsom/blobs;
    try_files /$1* =404;
}

How it works:

1. Hash-only lookup: nginx extracts the 64-character SHA-256 hash from the URL, ignoring any extension
2. Wildcard matching: try_files /$1* finds any file starting with that hash
3. Blossom compliance: Serves correct file regardless of URL extension

Examples:

Client requests: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

• nginx extracts hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
• nginx looks for: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553*
• nginx finds: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
• nginx serves the PDF with correct Content-Type: application/pdf

Client requests: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.mp3

• nginx extracts same hash: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
• nginx looks for: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553*
• nginx finds: b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
• nginx serves the PDF (not 404) with correct Content-Type: application/pdf

Key Benefits:

• Blossom Protocol Compliance: Accepts any extension, returns correct MIME type
• Performance: nginx serves files directly without FastCGI involvement
• Flexibility: URLs work with correct extension, wrong extension, or no extension
• MIME Detection: nginx determines Content-Type from actual file extension on disk

This approach ensures that files are always found by their SHA-256 hash regardless of what extension (if any) is used in the request URL, while maintaining nginx's excellent static file serving performance.

HEAD Request Handling

HEAD requests are processed differently to ensure accuracy:

1. nginx receives HEAD request: /b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
2. nginx forwards to FastCGI: All HEAD requests go to ginxsom for metadata
3. ginxsom extracts clean hash: Strips .pdf → b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553
4. ginxsom queries database: SELECT size, type FROM blobs WHERE sha256 = ?
5. ginxsom returns headers: Content-Length, Content-Type, etc.

Why This Approach?

Performance:

• GET requests: nginx serves directly from disk (no database hit)
• HEAD requests: Single database query (no filesystem checking)
• Extension mismatches: Eliminated by database-driven approach

Reliability:

• Database is authoritative source of blob existence
• No race conditions between filesystem and metadata
• Consistent behavior regardless of URL format

Flexibility:

• Clients can use URLs with or without extensions
• Browser-friendly URLs with proper file extensions
• API-friendly clean hash URLs

Scalability:

• nginx handles the heavy lifting (file serving)
• FastCGI only processes metadata operations
• Database queries scale better than filesystem operations

Development

Project Structure

ginxsom/
├── src/
│   ├── main.c              # Main server loop
│   ├── config.c            # Configuration parsing
│   ├── server.c            # HTTP server logic
│   ├── auth.c              # Nostr authentication
│   ├── storage.c           # File storage operations
│   ├── database.c          # SQLite operations
│   └── utils.c             # Utility functions
├── include/
│   └── ginxsom.h           # Main header file
├── tests/
│   └── test_*.c            # Unit tests
├── docs/
│   └── api.md              # API documentation
├── Makefile
└── README.md

Building for Development

make debug    # Build with debug symbols
make test     # Run test suite
make clean    # Clean build artifacts

Dependencies

• libssl: For cryptographic operations (nostr event verification)
• libsqlite3: For metadata storage
• libfcgi: For FastCGI functionality

Performance Characteristics

• Static File Serving: nginx performance (typically >10k req/s)
• Upload Processing: Limited by disk I/O and crypto verification
• Memory Usage: Minimal - FastCGI processes are lightweight
• Concurrent Operations: nginx manages FastCGI process pool efficiently
• Process Management: nginx spawns/manages ginxsom FastCGI processes

Security Considerations

• All uploads require valid nostr event signatures
• SHA-256 verification prevents data corruption
• Rate limiting prevents abuse
• File size limits prevent disk exhaustion
• No script execution - blobs stored as static files

Monitoring

ginxsom provides metrics via /metrics endpoint:

# HELP ginxsom_uploads_total Total number of uploads processed
# TYPE ginxsom_uploads_total counter
ginxsom_uploads_total 1234

# HELP ginxsom_storage_bytes Total bytes stored
# TYPE ginxsom_storage_bytes gauge  
ginxsom_storage_bytes 1073741824

License

[License information here]

Contributing

[Contributing guidelines here]

---

Note: This project is under active development. Please report bugs and feature requests via GitHub issues.