foxy-io 0.0.5

A configuration-driven and hyper-extensible HTTP proxy library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Foxy 🦊

[![CI](https://img.shields.io/github/actions/workflow/status/johan-steffens/foxy/publish.yml)](https://github.com/johan-steffens/foxy/actions/workflows/publish.yml)
[![Crates.io Version](https://img.shields.io/crates/v/foxy-io)](https://crates.io/crates/foxy-io)
[![Crates.io Downloads](https://img.shields.io/crates/d/foxy-io?style=flat-square)](https://crates.io/crates/foxy-io)
[![Crates.io License](https://img.shields.io/github/license/johan-steffens/foxy)](https://github.com/johan-steffens/foxy/blob/main/LICENSE.md)
[![Rust Version](https://img.shields.io/badge/rust-1.70%2B-blue?style=flat-square)](https://blog.rust-lang.org/2023/06/01/Rust-1.70.0.html)

A minimal, configuration-driven, hyper-extendible 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
- 🚀 **Modern Async Architecture**: Built on Tokio and Hyper for high performance
- 📦 **Lightweight Dependencies**: Minimal external dependencies for core functionality
- 🧩 **Highly Extensible**: Custom predicates and filters through trait-based design

## Quickstart

### Run the basic proxy example

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

### Run it in your code

Add Foxy as a dependency to your `Cargo.toml` file
```toml
[dependencies]
foxy-io = "..."
```

Build an instance and start the server.

```rust
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?;
```

## 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:

```json
{
  "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.md).

### Configuration Sources

Foxy supports multiple configuration sources with priority order:

```rust
// 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`

## Development Status

- [x] Configuration System
- [x] Loader Module
- [x] Core HTTP Proxy
- [x] Predicate-based Routing
- [x] Request/Response Filters
- [ ] Additional Security Features

## License

This project is licensed under [Mozilla Public License Version 2.0](LICENSE.md)