rust-camo

A high-performance image proxy written in Rust.

Features

• HMAC-SHA1 URL Signing - Compatible with go-camo (hex and base64 encoding)
• SSRF Protection - Blocks private IPs (RFC1918, loopback, link-local)
• Content-Type Filtering - Allows image/*, optionally video/* and audio/*
• Image Format Conversion - Convert JPEG/PNG to WebP (GIF and APNG passed through unchanged to preserve animation)
• Memory Caching - LRU cache with TTL support using moka
• Prometheus Metrics - Optional /metrics endpoint

Installation

cargo build --release

Development

# Run tests
cargo test

# Run in dev mode
cargo run -- --key test-key

# Check for issues
cargo check
cargo clippy

Usage

Running the Server

# Basic usage
rust-camo --key YOUR_HMAC_KEY

# With image conversion (WebP based on browser support)
rust-camo --key YOUR_HMAC_KEY --enable-conversion

# With all options
rust-camo \
  --key YOUR_HMAC_KEY \
  --listen 0.0.0.0:8080 \
  --enable-conversion \
  --cache-size 256 \
  --metrics

# For testing (disable SSRF protection)
rust-camo --key YOUR_HMAC_KEY --disable-ip-filter --enable-conversion

Generating Signed URLs

# Hex encoding (default)
url-tool --key YOUR_HMAC_KEY encode https://example.com/image.png

# Base64 encoding
url-tool --key YOUR_HMAC_KEY encode -b base64 https://example.com/image.png

# With prefix
url-tool --key YOUR_HMAC_KEY -p https://proxy.example.com encode https://example.com/image.png

Decoding URLs

url-tool --key YOUR_HMAC_KEY decode /abc123def456/68747470733a2f2f...

Configuration

Flag	Env Variable	Default	Description
--key	RUSTCAMO_HMAC	required	HMAC key for URL signing
--listen		0.0.0.0:8080	Address to bind
--timeout		4s	Upstream request timeout
--max-redirects		3	Maximum redirects to follow
--max-size		0	Max response size in KB (0 = unlimited)
--enable-conversion		false	Enable WebP conversion
--convert-quality		80	Image conversion quality (0-100)
--cache-size		256	Memory cache size in MB (0 = disabled)
--cache-ttl		3600	Cache TTL in seconds
--cache-private-domains			Comma-separated domains to cache even with cache-control: private
--cache-dir			Disk cache directory (optional)
--metrics		false	Enable Prometheus metrics
--disable-ip-filter		false	Disable SSRF protection (testing only)
--verbose		false	Enable debug logging

Nginx Integration

rust-camo is designed to run behind nginx for SSL termination:

server {
    listen 443 ssl http2;
    server_name proxy.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Docker Deployment

# Build the image
docker build -t rust-camo .

# Run with docker
docker run -d -p 8080:8080 \
  -e RUSTCAMO_HMAC=your-secret-key \
  rust-camo --enable-conversion

# Or use docker compose
export RUSTCAMO_HMAC=your-secret-key
docker compose up -d

License

MIT