HTTPCan

A simple, high‑performance HTTP request & response service built with Rust and Actix Web. Fully compatible with httpbin.org, with modern streaming and AI‑friendly enhancements.

Quick Links: Quick Start · Installation · Configuration · Examples · OpenAPI & Web UI · API Reference · Library · Development · License

✨ Features

• HTTPBin compatible: Use as a drop‑in replacement for testing/migration
• Modern streaming: Native SSE and NDJSON, AI‑compatible formats (OpenAI/Ollama)
• Tiny Docker image: <10MB, fast to pull and start
• Minimal memory footprint: Efficient async Rust I/O
• High throughput: Actix Web + Tokio

Quick Start

Choose one way to run:

# Docker (recommended)
docker run -p 8080:8080 ghcr.io/seedvector/httpcan:latest
curl http://localhost:8080/get

# Cargo
cargo install httpcan
httpcan
curl http://localhost:8080/get

Installation

🐳 Docker

# Latest image
docker run -p 8080:8080 ghcr.io/seedvector/httpcan:latest

# Custom port
docker run -p 3000:3000 ghcr.io/seedvector/httpcan:latest --port 3000

# Header filtering
docker run -p 8080:8080 ghcr.io/seedvector/httpcan:latest --exclude-headers "foo, x-bar-*"

📦 Cargo

# Install globally
cargo install httpcan

# Run
httpcan
httpcan --port 3000
httpcan --exclude-headers "foo, x-bar-*"
httpcan --port 3000 --no-current-server --exclude-headers "x-forwarded-*,cf-*"

🛠️ From Source

git clone https://github.com/seedvector/httpcan.git
cd httpcan

# Default (8080)
cargo run

# Custom port
cargo run -- --port 3000

# Release build
cargo build --release
./target/release/httpcan --port 8080

🧰 Configuration

CLI flags:

Notes:

• Built‑in filtering includes reverse proxy/CDN providers (Nginx, Cloudflare, AWS, GCP, Azure).
• When using Docker, ensure -p host:container mapping matches your --port if you override it.

Usage Examples

# Basic GET
curl http://localhost:8080/get

# POST with JSON
curl -X POST http://localhost:8080/post \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Auth

# Basic auth
curl -u username:password http://localhost:8080/basic-auth/username/password

# Username only (empty password) — enhanced
curl -u username: http://localhost:8080/basic-auth/username

Status & Redirects

# Specific status
curl http://localhost:8080/status/418

# Random from list
curl http://localhost:8080/status/200,404,500

# Redirect to a URL (supports form/json)
curl -X POST http://localhost:8080/redirect-to -d "url=https://example.com"

Compression & Formats

curl -H "Accept-Encoding: gzip" http://localhost:8080/gzip
curl http://localhost:8080/json
curl http://localhost:8080/xml

Streaming (SSE/NDJSON)

# SSE
curl http://localhost:8080/sse?count=3&format=simple
curl http://localhost:8080/sse/5?format=openai&delay=2000

# NDJSON
curl http://localhost:8080/ndjson?count=3&format=simple
curl http://localhost:8080/ndjson/5?format=ollama&model=llama3&delay=1500

Cookies & Inspection

curl http://localhost:8080/cookies
curl http://localhost:8080/headers
curl http://localhost:8080/ip

OpenAPI & Web UI

• OpenAPI spec: GET /openapi.json
• Web UI / API info: visit / in a browser; renders HTML or JSON based on Accept header

API Reference

HTTPBin Compatibility (Overview)

• Methods: GET /get, POST /post, PUT /put, PATCH /patch, DELETE /delete
• Anything: /anything, /anything/{anything} (supports multiple methods)
• Auth: Basic, Hidden Basic, Digest
• Formats: JSON, XML, HTML, robots.txt, encoding/utf8, gzip/deflate/brotli
• Dynamic: uuid, bytes, stream, range, links, delay, drip
• Redirects: redirect, relative-redirect, absolute-redirect, redirect-to
• Inspection: headers, ip, user-agent
• Response: cache, etag, response-headers
• Cookies: cookies CRUD
• Images: image, image/png, image/jpeg, image/webp, image/svg
• Status: /status/{codes} (single or comma‑separated)

For the full, up‑to‑date list and schemas, consult the OpenAPI spec.

HTTPCan Enhancements

• Echo endpoint: /echo reflects request body and headers (multi‑method)
• Auth+: Basic auth with username only; JWT Bearer decode/inspect at /jwt-bearer
• Status+: Content‑type priority: Accept > request Content-Type > default; supports custom bodies via query/body
• Redirects+: POST /redirect-to supports application/x-www-form-urlencoded, multipart/form-data, application/json
• Streaming+: SSE/NDJSON endpoints with count, delay, and AI formats (OpenAI/Ollama)
• File uploads+: Multiple files with the same field return as array across multipart endpoints

🦀 Library Usage

Add dependency:

[dependencies]
httpcan = "0.5"

Embed server:

use httpcan::HttpCanServer;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    HttpCanServer::new()
        .port(3000)
        .host("127.0.0.1")
        .exclude_header("foo, x-bar-*")
        .run()
        .await?;
    Ok(())
}

More examples and advanced config: see LIBRARY_USAGE.md.

Development

# Run checks
cargo fmt --all
cargo clippy --all -- -D warnings
cargo test

# Run locally
cargo run -- --port 8080

Contributions are welcome! Please open issues/PRs for discussion.

License

MIT — see LICENSE.