proxyflare 0.1.2

Cloudflare Workers Proxy Management CLI

Proxyflare

English | Русский

---

CLI utility for managing proxy servers based on Cloudflare Workers

📋 Description

Proxyflare is a modern CLI utility for creating and managing proxy workers on the Cloudflare Workers platform. The project is a complete rewrite of the existing flareprox.py script, utilizing best practices for Python and Rust development.

Key Features

• Multi-platform: Support for workers written in TypeScript, Python, JavaScript, and Rust (WASM).
• Parallel Deployment: Quickly create dozens of workers simultaneously.
• Flexible Routing: Route targets via query parameters, headers, or URL path.
• Local Client: Built-in tools for testing and interacting with the worker pool.
• Artifact Management: Automatic compilation of Rust workers and resource copying.

---

⚖️ Comparison with Original flareprox

[!NOTE] The Proxyflare project is inspired by the flareprox utility, but offers several significant architectural improvements:

Feature	flareprox (Original)	Proxyflare
Worker Languages	JavaScript only	TypeScript, JavaScript, Python, Rust (WASM)
Architecture	Monolithic Python script (~300 lines)	Modular CLI application (Typer, Rich, Pydantic)
Client Interface	Returns raw URLs	Built-in custom httpx Transport for automatic transparent proxying and ProxyManager for pool management
Testing	None	Full Unit coverage and integration tests with wrangler dev + E2E
Worker Management	Synchronous creation	Parallel creation, deletion, and pool listing (batch operations)
Artifact Build	JS hardcoded inside Python	Separated into individual files, Automatic dynamic Rust build via cargo/worker-build

---

⚡ Worker Performance Benchmark

Stress testing results (1000 requests with concurrency: 50 via Cloudflare) for each worker type:

Worker Type	Latency (avg)	Max Latency	Requests per Second (RPS)
TypeScript	~305 ms	~2134 ms	~133 RPS
JS	~489 ms	~2189 ms	~89 RPS
Rust (WASM)	~510 ms	~2314 ms	~85 RPS
Python	~621 ms	~2802 ms	~71 RPS

ℹ️ Benchmark was conducted remotely via deployed workers.
ℹ️ Results may vary depending on your region and network load.

🏠 Local Benchmark

Testing results conducted locally via wrangler dev (500 requests, concurrency: 20):

Worker Type	Latency (avg)	Max Latency	Requests per Second (RPS)
Rust (WASM)	~295 ms	~1742 ms	~65 RPS
TypeScript	~307 ms	~1559 ms	~60 RPS
Python	~317 ms	~1681 ms	~59 RPS
JavaScript	~373 ms	~1752 ms	~48 RPS

ℹ️ Local benchmark includes overhead from wrangler dev and proxying to httpbin.org.

---

🏗️ Architecture and Workflow

CLI Utility

1. Configuration: Manage Cloudflare settings via .env or system variables.
2. Worker Management:
   • config verify: Verify API token and access permissions.
   • config show: View current configuration.
   • create: Parallel deployment of workers.
   • list: List all workers with the proxyflare prefix.
   • delete: Delete workers by name or mask.
   • test: Test proxy functionality via the local client.

Client Library (README)

1. Manager: Manage the list of active workers and select a random node.
2. Transport: Custom transport for httpx to transparently proxy requests through workers.

Workers (Proxy)

1. Compatibility: Header stripping (Cloudflare-specific, Host) for correct proxying.
2. CORS: Built-in CORS support (Access-Control-Allow-Origin: *).
3. Performance: Optimized Rust worker for high-load tasks.

Tech Stack

Python Stack

• Python 3.12+
• UV - for dependency management
• Cloudflare SDK - API interaction
• Typer & Rich - modern CLI interface
• Pydantic V2 - data models and settings
• Loguru - structured logging
• Tenacity - resilient network operations

Rust Stack

• Rust & Cargo — compilation of high-performance workers
• worker-rs — Cloudflare Workers SDK for Rust

---

📦 Project Structure

proxyflare/
├── src/
│   └── proxyflare/
│       ├── cli/                 # CLI interface and commands
│       ├── client/              # Client library (httpx transport)
│       ├── models/              # Pydantic models (Config, Results)
│       ├── services/            # Business logic (WorkerService, Tester)
│       ├── workers/             # Worker sources (py, js, rs)
│       └── utils/               # Utilities (artifacts, markers)
│
└── tests/                       # Full test coverage (Unit, Integration, E2E)

---

🛠️ Installation and Usage

Requirements

• Python 3.12+
• Rust (cargo) (for compiling WASM artifacts, the worker-build plugin gets installed automatically)
• Node.js (npm/npx) (for running local tests via wrangler dev)

Cloudflare API Token Setup

To use Proxyflare, you need to provide a custom Cloudflare API token. Create a custom token in your Cloudflare dashboard (My Profile -> API Tokens -> Create Token -> Custom Token) with the following four specific permissions:

1. User -> API Tokens -> Read
2. Account -> Workers Scripts -> Edit
3. Account -> Account Settings -> Read
4. Zone -> Workers Routes -> Edit

[!WARNING] Do not restrict the token to specific zones in "Zone Resources" or "Account Resources". Set them to Include -> All accounts and Include -> All zones, otherwise the verify endpoint will return an 1000 Invalid API Token error.

Set the token and your Account ID as environment variables (e.g., in a .env file):

PROXYFLARE_API_TOKEN="your_custom_token"
PROXYFLARE_ACCOUNT_ID="your_account_id"

Installation

The easiest way to install Proxyflare is via pip (or uv pip):

pip install proxyflare

After installation, you can verify your configuration with the built-in command:

proxyflare config verify

Build from Source (For Development)

The project uses a custom hatchling build hook, which automatically compiles Rust workers upon package installation. It is recommended to use uv for fast dependency management and utility building:

# Install project dependencies
uv sync

# Install as a system utility tool
uv tool install .

# Install package in development mode (triggers Rust worker build)
uv pip install -e .

Development and Testing

1. Unit tests (Fast, local):

uv run pytest tests/unit

2. Integration tests (Local wrangler):

uv run pytest tests/integration

3. E2E tests (Remote Cloudflare):

uv run pytest tests/remote/test_e2e.py

---

📝 License

MIT

---

Status: 🟢 Stable version (Core Ready) | Current version: 0.1.1