blossom-server

Blossom blob storage API server built on blossom-rs.

Quick Start

# Default: filesystem storage + SQLite metadata
cargo run -p blossom-server

# In-memory (no persistence, good for testing)
cargo run -p blossom-server -- --memory

# Custom bind address and base URL
cargo run -p blossom-server -- --bind 0.0.0.0:8080 --base-url https://blobs.example.com

Options

blossom-server [OPTIONS]

Options:
  -b, --bind <ADDR>              Listen address [default: 0.0.0.0:3000]
  -u, --base-url <URL>           Public base URL [default: http://localhost:3000]
  -d, --data-dir <PATH>          Blob storage directory [default: ./blobs]
      --memory                   Use in-memory storage (no persistence)
      --db-path <PATH>           SQLite database path [default: ./blossom.db]
      --require-auth             Require BIP-340 auth for uploads
      --max-upload-size <BYTES>  Max upload size in bytes
      --body-limit <BYTES>       Max HTTP body size [default: 268435456 (256 MB)]
      --allowed-types <TYPES>    Comma-separated MIME types (empty = all)
      --whitelist <FILE>         Path to pubkey whitelist file
      --whitelist-reload-secs <N> Whitelist hot-reload interval [default: 0 (disabled)]
      --stats-flush-secs <N>    Stats flush interval [default: 60]
      --keygen                   Generate a keypair and exit
      --tls-cert <FILE>          TLS certificate (PEM)
      --tls-key <FILE>           TLS private key (PEM)
      --rate-limit-max <N>       Max requests per bucket [default: 60]
      --rate-limit-refill <F>    Token refill rate per second [default: 1.0]
      --no-rate-limit            Disable rate limiting
      --webhook-urls <URLS>      Webhook URLs (comma-separated)
      --cors-origins <ORIGINS>   CORS allowed origins (comma-separated, default: all)
      --enable-admin             Enable admin endpoints at /admin/*
      --media                    Enable media processing on PUT /media (BUD-05)
      --log-level <LEVEL>        Log level [default: info]

API Endpoints

Features

CORS

Enabled by default — allows all origins, methods, and headers. Suitable for browser-based Nostr clients.

Graceful Shutdown

On Ctrl+C, the server flushes accumulated access statistics to the database before exiting.

Stats Flush

Access statistics (egress bytes, last accessed) accumulate in memory via lock-free DashMap counters and flush to the database periodically (default: every 60 seconds) and on shutdown.

Whitelist Hot-Reload

When --whitelist-reload-secs is set, the whitelist file is re-read at that interval without restarting the server.

TLS

Optional TLS via rustls. Provide --tls-cert and --tls-key PEM files.

cargo run -p blossom-server -- --tls-cert cert.pem --tls-key key.pem

Logging

Structured JSON logs to stdout with OTEL-compatible field names. Control verbosity with --log-level or RUST_LOG.

RUST_LOG=blossom_rs::server=debug cargo run -p blossom-server

Access Control

Create a whitelist file with one hex pubkey per line:

# allowed-keys.txt
a1b2c3...  (64-char hex pubkey)
d4e5f6...

cargo run -p blossom-server -- \
  --require-auth \
  --whitelist allowed-keys.txt \
  --whitelist-reload-secs 30

Roadmap