Foxy 🦊

A minimal, configuration-driven, hyper-extensible Rust HTTP proxy library.

Features

• 🛣️ Powerful Routing: Predicate-based routing with path patterns, HTTP methods, headers, and query matching
• 🔄 Flexible Filters: Pre- and post-processing filters for request/response modification
• ⚙️ Configuration Superpowers: Layered configuration from files and environment variables
• 🌐 Fine-grained Control: Route-specific filter chains for precise request handling
• 🔒 Pluggable Security Chain: configurable, provider-based request authentication with built-in providers
• 🚀 Modern Async Architecture: Built on Tokio and Hyper for high performance
• 📦 Lightweight Dependencies: Minimal external dependencies for core functionality
• 🧩 Highly Extensible: Custom predicates, filters and security providers via simple traits
• 🚢 Docker Support: Official container image for rapid deployment

Quickstart

Run the basic proxy example

git clone https://github.com/johan-steffens/foxy.git
cd foxy
cargo run --example basic-proxy

Run it in your code

Add Foxy as a dependency to your Cargo.toml file

[dependencies]
foxy-io = "..."

Build an instance and start the server.

use foxy::Foxy;

// Create a new Foxy instance with layered configuration
let foxy = Foxy::loader()
    .with_env_vars()                  // Environment variables (highest priority)
    .with_config_file("config.toml")  // File-based config (medium priority)
    .with_config_file("defaults.toml") // Defaults (lowest priority)
    .build().await?;

// Start the proxy server and wait for it to complete
foxy.start().await?;

Run with Docker

Prerequisites: Docker 20.10+ installed

The project publishes multi‑arch images to GitHub Container Registry:

docker pull johansteffens/foxy:latest

Run the proxy, exposing the default port 8080 on your host:

docker run --rm -p 8080:8080 johansteffens/foxy:latest

Passing a custom configuration file

1. Create (or copy) a config.* file on your host.
2. Ensure your configuration binds to address 0.0.0.0
3. Mount it into the container and tell Foxy where to find it with the FOXY_CONFIG_FILE environment variable:

docker run --rm -p 8080:8080 -v "$(pwd)/config.json:/app/config.json:ro" -e FOXY_CONFIG_FILE=/app/config.json johansteffens/foxy:latest 

Run with docker‑compose

If you prefer docker‑compose, drop the snippet below into docker-compose.yml and run docker compose up -d:

version: "3.9"
services:
  foxy:
    image: johansteffens/foxy:latest
    container_name: foxy
    ports:
      - "8080:8080"
    environment:
      # Tell Foxy to load the configuration we mounted
      FOXY_CONFIG_FILE: /config/config.json
    volumes:
      # Mount your custom configuration
      - ./config.json:/config/config.json:ro

Tip: When you update config.json, simply restart the container with
docker-compose restart foxy to pick up the changes.

Core Principles

• Predictable Routing: Predicate-based matching with clear priorities determines how requests are routed
• Configurable Processing: Route-specific and global filters for request/response modification
• Extensibility: Trait-based design enables custom predicates and filters
• Configuration-Driven: All behavior controlled via flexible configuration with sensible defaults

Configuration

Foxy's power comes from its rich configuration system. Here's a brief overview:

{
  "routes": [
    {
      "id": "api-route",
      "target": "https://api.example.com",
      "filters": [
        {
          "type": "path_rewrite",
          "config": {
            "pattern": "^/api/(.*)$",
            "replacement": "/v2/$1"
          }
        }
      ],
      "predicates": [
        {
          "type_": "path",
          "config": {
            "pattern": "/api/*"
          }
        }
      ]
    }
  ]
}

For detailed information on all configuration options, see the Configuration Guide.

Configuration Sources

Foxy supports multiple configuration sources with priority order:

// Build a layered configuration
let foxy = Foxy::loader()
    .with_env_vars()                   // First priority
    .with_config_file("config.json")   // Second priority
    .build().await?;

Example: FOXY_SERVER_PORT=8080 → server.port

Enabling security

Add a security_chain with a configured provider to your proxy configuration:

{
  "proxy": {
    "security_chain": [
      {
        "type": "oidc",
        "config": {
          "issuer-uri": "https://id.example.com/.well-known/openid-configuration",
          "aud": "my-api",
          "bypass-routes": [
            { "methods": ["GET"], "path": "/health" }
          ]
        }
      }
    ]
  }
}

That’s it — requests hitting /api/** will be validated against the IDP while /health remains public. Full configuration examples can be found in the Configuration Guide.

Streaming bodies

• Foxy proxies request and response bodies as streams end‑to‑end to ensure there's no full body buffering in memory.
• Large uploads/downloads back‑pressure correctly.
• Memory usage is bound only by socket buffers.

Detailed timing metrics

• Foxy records and logs three high‑resolution latencies on every call (DEBUG level):

[timing] <METHOD> <PATH> -> <STATUS> | total=<X> upstream=<Y> internal=<Z>

Request and Response body logging

• LoggingFilter peeks and logs the first 1 000 bytes/characters of every request and response body (UTF‑8‑lossy).
• Binary or very large payloads are safe—the remainder of the stream is forwarded untouched.
• Please note: enabling request and response logging will introduce additional latency to your calls.

Development Status

• Configuration System
• Loader Module
• Core HTTP Proxy
• Predicate-based Routing
• Request/Response Filters
• Security Chain
  • OIDC provider
  • Basic auth provider

License

This project is licensed under Mozilla Public License Version 2.0