Rust API Documentation

Rust documentation has not been generated yet. Run cargo doc in crates/juiceback/ or crates/juicehost/ to generate it, then reload this page.

cargo doc -p juiceback -p juicehost

---

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

Service ports and protocols

Service	Protocol	Default Port	Notes
juiceback	TCP (HTTP/1.1 + H2)	6401	API endpoint
juiceback	UDP (QUIC / HTTP/3)	6402	Fast uploads from modern browsers
juicehost	TCP (HTTP/1.1 + H2)	6402	Serves files and handles storage
juicehost	UDP (QUIC / HTTP/3)	6403	Fast file push from juiceback

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::Config to 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. Start juicefront -- it needs the juiceback and juicehost URLs; it serves the frontend and 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 quic feature (default on). The QUIC server reuses the same axum router as TCP so every 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 a Rust Axum application. It connects to juiceback for uploads and file management, serves the pages, and reverse-proxies API traffic.

---

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

# 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