Changelog

All notable changes to ProxyWhirl are documented here. This project uses Conventional Commits and Semantic Versioning.

Unreleased

Added

  • Source curator agent – automated proxy source curation with .claude config integration

  • BootstrapConfig model – structured configuration for lazy proxy bootstrap

  • Proxy source curation – audit counts, hardened CI validation for proxy sources

Fixed

  • Test flakiness in performance strategy (increased iterations)

  • Mock return type for bootstrap candidates unpacking

Changed

  • Simplified strategy demo examples, merged retry cells, renamed pool variables

0.3.0 (2026-02-16)

Added

  • Source curator agent and skill for automated proxy source management

  • Security hardening – credential handling, SSRF protection, API error responses

  • Docs overhaul – enhanced content, cross-links, visual polish across all pages

  • Web navbar – shared navigation between SPA and Sphinx docs

  • Tabbed code examples on web dashboard

  • Flag emoji next to country codes in proxy table

  • Analytics dashboard with exotic visualizations

  • CLI sources audit command for broken source detection

  • CLI --revalidate flag to re-check existing DB proxies

  • Normalized proxy schema across all sources

  • Cost-aware strategy (CostAwareStrategy) for budget-optimized selection

  • Composite strategy (CompositeStrategy) for chaining filters and selectors

  • MCP server for AI assistant integration (Claude, GPT)

  • Rate limiting API – token bucket algorithm with per-proxy and global limits

  • Session persistence strategy with sticky sessions and TTL

  • Geo-targeted strategy with region-aware routing

  • Performance-based strategy with EMA latency scoring

  • Multi-tier caching (L1/L2/L3) with Fernet encryption on L2/L3

  • Circuit breakers (CircuitBreaker, AsyncCircuitBreaker) with auto-recovery

Fixed

  • CDN cache strategy simplified for web data hooks

  • Interface parity finalized with docs references

  • Strategy count corrected from 8 to 9 across all assets

  • Linkcheck CI failure from false-positive sources.py URL

  • Docs and CLI aligned with codebase; config init validation bugs resolved

  • Pruned 55 dead/stale/duplicate sources, added 7 new active repos

  • Web health visualizations replaced with meaningful metrics

  • Exports now only include healthy proxies

  • Table column alignment and globe missing data on web dashboard

  • CI: compact database to stay under GitHub 100 MB file limit

  • Response time field name corrected in CLI revalidation

  • GeonodeParser added for proper API response handling

  • Failed proxies marked as DEAD instead of deleted during revalidation

0.1.2 (2026-02-14)

Added

  • Source curator script for proxy source list management

  • Shared navbar between SPA and Sphinx docs

  • Tabbed code examples on landing page

Fixed

  • Docs linkcheck CI failure

  • Docs and CLI alignment with codebase

  • Config init validation bugs

  • Web: serve Sphinx docs at /docs/ instead of SPA fallback

  • Exports: only include healthy proxies in lists and web UI

0.1.1 (2026-01-14)

Fixed

  • Skip TestAuthMiddleware when FastMCP not installed or on Python <3.10

  • CI failures resolved (lint, docs, flaky tests)

  • Flaky integration tests stabilized

  • Benchmarks and extras tests skipped on feature branches

  • README stats workflow timeout and coverage tracking

Changed

  • Major codebase restructuring for v0.1.0 release

  • CI coverage uses artifact instead of re-running tests

0.1.0 (2026-01-10)

Initial release.

Added

  • ProxyWhirl sync client and AsyncProxyWhirl async client

  • 9 rotation strategies: round-robin, random, weighted, least-used, performance-based, session persistence, geo-targeted, cost-aware, composite

  • RotationStrategy protocol with StrategyRegistry plugin architecture

  • ProxyFetcher and ProxyValidator with JSON, CSV, PlainText, and HTMLTable parsers

  • Hundreds of built-in proxy sources (ALL_SOURCES, RECOMMENDED_SOURCES)

  • Multi-tier cache (CacheManager): L1 in-memory, L2 encrypted disk, L3 SQLite

  • Circuit breakers with three-state machine (CLOSED/OPEN/HALF_OPEN)

  • RetryExecutor with exponential and linear backoff strategies

  • RateLimiter with token bucket algorithm

  • FastAPI REST API (/api/v1/*) with OpenAPI docs

  • Typer CLI with 9+ commands

  • MCP server for AI assistant integration

  • SQLite persistence with Fernet encryption

  • Textual TUI dashboard

  • Playwright-based BrowserRenderer for JS-rendered sources

  • TOML configuration with environment variable overrides

  • ProxyWhirlError exception hierarchy with error codes and URL redaction

  • ReDoS-safe regex utilities

  • IP geolocation enrichment

  • Comprehensive test suite: unit, integration, property-based, contract, benchmarks