Rust API Documentation

Auto-generated rustdoc documentation for Juicebox's backend Rust crates.

• juiceback - API Gateway
• juicehost - Storage Backend

HTTP API (OpenAPI)

The HTTP API is documented with OpenAPI. Fetch the raw JSON spec to generate clients or explore endpoints.

• OpenAPI JSON (pretty)
• OpenAPI JSON (minified)

Hosting

Juicebox runs as two separate services: juiceback(API gateway) and juicehost (file storage). You need both running to handle uploads and file serving. QUIC/HTTP/3 is optional but recommended for faster uploads.

Ports

UDP and TCP ports are independent -- you can run QUIC on the same port number as a TCP service with no conflict.

How to host

1. Set environment variables -- check the rustdoc for juiceback::config::Config and juicehost::config::Configto see every available variable.
2. Start juicehost -- it needs a directory for files and a shared API key with juiceback.
3. Start juiceback -- it needs the juicehost URL and API key, plus a SQLite database path.
4. Build the frontend -- run bun run buildin juicefront/ui/ and serve the dist/ with a reverse proxy (nginx, caddy) that proxies /api/* to juiceback.

QUIC / HTTP/3

QUIC uses UDP on the port shown above. It is only available when juiceback and juicehost are compiled with the quicfeature (default on). The QUIC server reuses the same axum router as TCP so every API endpoint is reachable over HTTP/3.

Environment variables

The only strictly required variable is JUICEHOST_API_KEY, which must be the same on both services. Everything else has a sensible default. Refer to the rustdoc for each crate's config module to see the full list.

juiceback (API gateway)

juiceback is the API gateway. It handles authentication, rate limiting, file uploads, and serves the frontend. It connects to juicehost for file storage and optionally supports QUIC/HTTP/3 for faster uploads from modern browsers.

juicehost (file storage)

juicehost is the storage backend. It stores files on disk (or S3-compatible object storage), handles file serving, and manages cleanup of expired files. It exposes an internal API for juiceback to push and manage files.

juicefront (frontend)

The frontend is an Astro SSR application. It connects to juiceback for uploads and file management. In development it runs on its own dev server; in production it is built to static files and served behind a reverse proxy.

Callgraph

A callgraph shows how functions call goes in a fancy little graph. It's useful if you want to understand the architecture!!

Install

cargo install cargo-callgraph

You also need graphviz installed to render the DOT output as an image!!

Generate

From the workspace root (juicebox2back/):

# Full workspace graph (JSON + DOT)
cargo callgraph --json target/callgraph.json --dot target/callgraph.dot

# Filter to workspace crates only (removes std/axum/tokio bullshit)
python3 scripts/callgraph-filter.py target/callgraph.json . target/callgraph-workspace.dot

# Render as PNG or SVG
dot -Tpng target/callgraph-workspace.dot -o callgraph.png
dot -Tsvg:cairo target/callgraph-workspace.dot -o callgraph.svg

Browse the graph

You can traverse the JSON output without rendering an image:

# What does main call? (depth 2)
cargo callgraph traverse --graph target/callgraph.json -i main -n 2 -o

# What calls upload_handler? (incoming)
cargo callgraph traverse --graph target/callgraph.json -i upload_handler -n 2

Testing

The project has a buncha tests for juiceback and juicehost;

Run all tests

cargo test --workspace

Run with cargo-nextest (cargo test suks)

cargo-nextest is a faster test runner that runs tests in parallel by default with better output and built-in retries. Install it once:

cargo install cargo-nextest --locked

Then run all tests:

cargo nextest run --workspace

nextest automatically runs each test in its own process, which catches issues like leaked state between tests that cargo test might miss.

Run specific tests

# By name filter
cargo nextest run -p juiceback -- test_insert_get_file

# By test binary
cargo nextest run -p juiceback --test admin_test

# Unit tests only (inline #[cfg(test)] modules)
cargo nextest run -p juiceback --lib

# Integration tests only (tests/ directories)
cargo nextest run -p juicehost --test handlers_test