crabcrop

crabcrop is an on-demand image optimization service written in Rust. You request an image with the operations encoded in the URL, resize, crop, convert, filter, and crabcrop fetches the source image, applies the operations in order, and returns the result. There are no pre-generated thumbnails and no build step: the URL is the API.

crabcrop is for sites and apps that serve the same images at many sizes and want signed, cacheable image URLs in front of an origin image store.

Install

Shell installer (macOS and Linux):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dayvson/crabcrop/releases/latest/download/crabcrop-installer.sh | sh

Homebrew: download crabcrop.rb from the latest release, then:

brew install --formula ./crabcrop.rb

Docker: the base image, and the AI variant with background removal and face detection on board:

docker pull ghcr.io/dayvson/crabcrop:0.1.0
docker pull ghcr.io/dayvson/crabcrop-ai:0.1.0
docker run -e CRABCROP_SECRET=your-secret -p 3000:3000 ghcr.io/dayvson/crabcrop:0.1.0

Release binaries: prebuilt tarballs for macOS and Linux, on x86_64 and arm64, are on the releases page. To build from source instead, see Deployment.

Quickstart

1. Start the server. A secret is required. For local development, also allow unsigned URLs:

CRABCROP_SECRET=local-dev-secret CRABCROP_ALLOW_UNSAFE=1 cargo run --release
# crabcrop listening on port 3000

2. Request an image. This resizes a source photo to 300×200:

curl "http://localhost:3000/unsafe/300x200/https://example.com/photo.jpg" --output photo.jpg

Replace example.com/photo.jpg with the URL of an image you control. You get back a 300×200 JPEG.

3. Sign your URLs in production. Drop CRABCROP_ALLOW_UNSAFE and put an HMAC signature in the first path segment:

curl "http://localhost:3000/3c1f6c180116661877bd4c85fd201a178087d74c1cc188cc584e819d901308c6/300x200/https://example.com/photo.jpg" --output photo.jpg

That signature is HMAC-SHA256 of 300x200/https://example.com/photo.jpg under the secret your-secret. See Sign a request.

How requests work

Every image request has three parts:

GET /<signature>/<operations>/<source-url>

/unsafe/crop:1200x630:smart/filters:grayscale:quality(80)/https://example.com/photo.jpg

Sign a request

Compute HMAC-SHA256 over the remainder of the path, the operations and the source URL exactly as they appear, with no leading slash, keyed with your CRABCROP_SECRET, and hex-encode the result:

printf '%s' '300x200/https://example.com/photo.jpg' | openssl dgst -sha256 -hmac 'your-secret'
# SHA2-256(stdin)= 3c1f6c180116661877bd4c85fd201a178087d74c1cc188cc584e819d901308c6

Use that hex string as the first path segment. Anyone can verify the scheme against this test vector: with secret Jefe, the HMAC-SHA256 of what do ye want for nothing? is ba5396e10039ec002bf1fde117eee48df8c2f06bc47b5f2d3272ea77f6862da9.

A request with a bad signature gets 403 and the body bad signature. The literal signature unsafe skips verification, but only when the server runs with CRABCROP_ALLOW_UNSAFE=1 (or true, yes, on). Keep it off in

... View full README on GitHub