ProxyCraft

ProxyCraft is the easiest and quickest way to deploy a web proxy.

✨ Features

ProxyCraft offers many features:

• 🔒 Protocol Support: Handle HTTP, HTTPS, WebSockets, TCP/UDP, and SOCKS proxies
• 🔐 Authentication: Support for various auth methods (Basic, Digest, NTLM, Kerberos)
• 🔄 Connection Pooling: Efficient reuse of connections to improve performance
• ⚖️ Load Balancing: Distribute traffic across multiple proxies
• 🏥 Health Checking: Automatic detection and recovery from failed proxies
• 💾 Caching: Store and reuse responses for identical requests
• 🔄 Retry Mechanisms: Automatically retry failed requests
• 🔧 Circuit Breaking: Prevent cascading failures
• 📊 Metrics Collection: Track proxy performance, latency, error rates
• 🔐 TLS/SSL Termination: Handle encryption/decryption
• 🌍 IP Rotation: Change public IP addresses for scraping
• 🎯 Geo-targeting: Route requests through proxies in specific locations

🚀 Quick Start

Installation

pip install proxycraft

Or with uv:

uv add proxycraft

Basic Usage

from proxycraft import ProxyCraft

if __name__ == "__main__":
    proxycraft: ProxyCraft = ProxyCraft(config_file='proxy.json')
    proxycraft.serve(host='0.0.0.0', port=8091)

📋 Configuration Example

{
  "version": "1.0",
  "name": "Simple example",
  "endpoints": [
    {
      "prefix": "/",
      "match": "**/*",
      "backends": {
        "https": {
          "url": "https://jsonplaceholder.typicode.com/posts"
        }
      },
      "upstream": {
        "proxy": {
          "enabled": true
        }
      }
    }
  ]
}

🐳 Docker Usage

docker build -t proxycraft -f dockerfiles/proxycraft.Dockerfile .
docker run  -p 8080:8080 proxycraft

Project structure

proxycraft/
├── app/              # ASGI application composition root
├── features/         # Capability-owned modules (routing, backends, middleware, …)
└── shared/           # Cross-cutting infrastructure (logging, connection pooling)

See docs/architecture.md and SPECS.md for details.

Development

Install just and uv, then:

just install
just test
just lint

Build a release (requires VERSION):

VERSION=1.0.0 just build

Run a subset of tests:

just test tests/path/to/test_file.py

List all available commands:

just

📄 License

MIT