Releases · bluet/proxybroker2

🌐 Full IPv6 support — first-class across the stack

This release makes IPv6 a peer of IPv4 across detection, validation, anonymity comparison, SOCKS5 proxying, HTTP CONNECT bracketing, provider parsing, and DNS resolution.

Closes: #201 (IPv6 epic) and #214 (test infra).

Headline changes

End-to-end IPv6 — Resolver.host_is_ip, get_real_ext_ip, get_all_ip, _get_anonymity_lvl, Judge.check, Proxy(host=...), and [v6]:port provider parsing all handle IPv6 alongside IPv4.
Happy Eyeballs DNS (RFC 8305 § 3) — Resolver.resolve() races A and AAAA queries in parallel by default; explicit qtype or family falls back to the legacy single-family contract.
SOCKS5 ATYP=0x04 for IPv6 destinations (RFC 1928), with response-ATYP-driven reply parsing for dual-stack proxies that may bind a different family than the client requested.
RFC 9112/9110-compliant CONNECT bracketing — CONNECT [2001:db8::1]:443 HTTP/1.1 + Host: [2001:db8::1]; strips caller-supplied brackets so urlparse(...).netloc style inputs don't double-bracket.
RFC 5952 canonical form as the single in-process IP representation across every comparison site.
New public helpers: canonicalize_ip(s) -> str | None, find_proxy_pairs(text) -> list[tuple[str, str]].
IPv6Pattern 700-character regex deleted along with its # nosemgrep suppression — replaced by a narrow tokenizer + stdlib ipaddress validator.

Quality

+36 IPv6 tests (259 total); all 5 Python matrix cells (3.10–3.14) green.
coderabbit ✅ approved; SonarCloud Quality Gate passed; opsera scan 0 critical/high.

Follow-ups (filed)

#213 connection-layer Happy Eyeballs + DNSSEC + IDN
#215 codebase-wide type hints + mypy CI
#216 SBOM + sigstore (supply-chain hardening)
#217 cert pinning for default judge servers
#218 opt-in ECH (Encrypted Client Hello)
#219 opt-in TLS 1.3-only mode
#220 deterministic IPv6 external-IP discovery

Install

# Docker (multi-arch: amd64 + arm64)
docker pull bluet/proxybroker2:2.0.0b3
docker run --rm bluet/proxybroker2:2.0.0b3 find --types HTTP --limit 5

# pip (from GitHub)
pip install -U git+https://github.com/bluet/proxybroker2.git@v2.0.0b3

See CHANGELOG.md for the full diff.

Generated with Claude Code

🎯 Custom Proxy Provider System & Quality Pass

This release adds a user-extensible proxy provider system (the headline feature) and bundles a focused quality pass: parser bug fixes with regression tests, removal of recurring SAST false positives by fixing the underlying code (not just suppressing), modernization of %-formatting to f-strings, and isolation of the unverified-SSL bypass into a named helper.

Headline: Custom proxy providers via YAML/JSON

Drop a directory of YAML/JSON config files into your container, mount it, and proxybroker auto-loads them. No code, no PRs, no fork. Targets the Docker bind-mount workflow for entry-level / no-code users.

# /configs/my_api.yaml
type: api
url: https://my-proxy-api.example.com/v1/proxies
api_key: ${PROXY_API_KEY}
proxy_path: data.proxies

docker run -v $(pwd)/configs:/configs ghcr.io/bluet/proxybroker2 find --types HTTP --limit 10

Four provider helpers: SimpleProvider (text/CSV/JSON list endpoints with format autodetect), PaginatedProvider (numbered-page endpoints), APIProvider (JSON APIs with optional auth and dotted proxy_path), ConfigurableProvider (factory).

CLI / API

--provider-dir PATH (repeatable) on top-level and every subcommand
$PROXYBROKER_PROVIDER_DIR env fallback
/configs Docker convention (auto-loaded if directory exists)
Python: Broker(provider_dirs=[...]). Empty-list contract preserved: providers=[] means "no bundled defaults" (distinct from providers=None which means "use defaults")

Security model

YAML/JSON loader uses yaml.safe_load and never executes Python from configs. The Python file loader (load_python_providers_from_directory) is opt-in only — not wired to the CLI; users must call it from their own code if they want it.

Parser bug fixes (with regression tests)

CSV: stdlib csv module, handles quoted fields with embedded commas (e.g. "Company, Inc",80)
Text: extracts only the leading digit run after : as the port (e.g. 1.2.3.4:8080:tag no longer crashes)
JSON: no duplicate proxies for items with both ip and host keys
JSON: unwraps single-level object-wrapped responses ({"proxies": [...]}, {"data": [...]}, etc.)
Paginated: page= query param is replaced, not appended duplicate
API: proxy_path navigation handles non-dict gracefully

Quality pass

Judge.is_working is now a @property (was a plain attribute) — removes 5 recurring SAST false positives
Unverified-SSL context construction extracted to _make_unverified_ssl_context_for_proxy_testing() helper
Eighteen %-formatting calls modernized to f-strings (silently accumulating because pre-commit hook was missing --unsafe-fixes; now fixed)
aiodns.DNSResolver() lazy-init for Python 3.14 compatibility
Dockerfile pinned to specific SHA256 digest of python:3.14-slim

Removed

proxybroker.utils.update_geoip_db() body. The function attempted to download from geolite.maxmind.com which has been NXDOMAIN since 2019-12-30 (MaxMind retired the unauthenticated endpoint, license key now required). Now raises RuntimeError linking to the tracking issue. Bundled GeoLite2 databases continue to work for runtime IP lookups.

Python support

3.10–3.14 (added 3.14, default in CI/Docker).

Tracked follow-ups for next releases

#200 — GeoIP database replacement strategy (DB-IP, IPLocate, license-key MaxMind, etc.)
#201 — IPv6 regex → stdlib ipaddress (eliminates ReDoS suppression)
#202 — Cognitive-complexity refactor in parsers (SonarCloud S3776)
#203 — argparse.FileType and asyncio.get_event_loop() deprecation migrations

Full changelog: https://github.com/bluet/proxybroker2/blob/v2.0.0b2/CHANGELOG.md
PR: #199

🎉 Major Milestone: ProxyBroker2 is Production-Ready!

This beta release represents a complete modernization and stabilization of ProxyBroker, making it ready for production use with zero critical bugs and comprehensive test coverage.

✨ Key Highlights

🔧 Critical Bug Fixes

✅ Fixed ProxyPool heap corruption - Proper min-heap maintenance with avg_resp_time priority
✅ Added timeout/retry limits - Prevents infinite loops in proxy import operations
✅ Deterministic protocol selection - Clear priority order (SOCKS5 → SOCKS4 → CONNECT → HTTPS → HTTP)
✅ Signal handler cleanup - Proper memory management prevents leaks
✅ Modern SSL handling - Uses asyncio.start_tls() instead of deprecated patterns
✅ Exception chaining - Proper error propagation with raise ... from err

🚀 Production-Ready Status

Zero critical bugs - All signal handler leaks, deadlocks, and heap corruption fixed
100% test suite pass rate - All 131 tests passing with comprehensive coverage
Python 3.10-3.13 support - Full compatibility with latest Python versions
Modern async patterns - Updated from deprecated asyncio patterns

🛠️ API Improvements

Proxy.types setter - Direct assignment and update operations with type validation
Cache invalidation - Schemes properly refresh when types change
Async context managers - Server lifecycle management
Resource cleanup - Comprehensive connection and SSL cleanup

🧪 Modern Testing Philosophy

Behavior-focused tests - Contract-based testing protects APIs during refactoring
131 passing tests - Comprehensive coverage across all components
Mock infrastructure - Realistic testing without external dependencies
Integration tests - End-to-end workflow validation

🔄 Updated Dependencies (May 2025)

aiohttp 3.10.11 → 3.12.0 (asyncio deprecation fixes)
aiodns 3.1.1 → 3.4.0 (DNS resolution improvements)
attrs 22.1.0 → 25.3.0 (Python 3.10+ optimizations)
pytest 7.1.2 → 8.3.5 (modern testing framework)

📚 Enhanced Documentation

Updated architecture guide with clear component explanations
Modern toolchain documentation (ruff, pytest, poetry)
Migration guide for smooth transition from v1.x
Auto-generated API reference from high-quality docstrings

🎯 Perfect for Production Use

Web Scraping & Automation

import asyncio
from proxybroker import Broker

async def main():
    proxies = asyncio.Queue()
    broker = Broker(proxies)
    await broker.find(types=['HTTP', 'HTTPS'], limit=10)

asyncio.run(main())

Proxy Server Deployment

import asyncio
from proxybroker import Broker

async def main():
    proxies = asyncio.Queue()  
    broker = Broker(proxies)
    await broker.serve(host='127.0.0.1', port=8888, types=['HTTP', 'HTTPS'])

asyncio.run(main())

🔄 Migration from v1.x

ProxyBroker2 maintains API compatibility while adding modern features:

All existing code continues to work
New type validation provides better error messages
Enhanced async patterns improve performance
Modern Python 3.10+ support

📦 Installation

# Install from GitHub (recommended)
pip install git+https://github.com/bluet/proxybroker2.git

# Or with Poetry
poetry add git+https://github.com/bluet/proxybroker2.git

🤝 Contributing

ProxyBroker2 is ready for community contributions! See CONTRIBUTING.md for guidelines.

Ready to use ProxyBroker2 in production? This beta release provides a stable, thoroughly tested foundation for your proxy needs.

🤖 Generated with Claude Code

@hms5232

What's Changed

run script in venv through Poetry by @hms5232 in #92
Add coverage test by @afunTW in #96
Remove deprecation warnings/Add support for python 3.10 by @ziloka in #94
use setup-python built-in cache functionality by @hms5232 in #97
instructions to compile proxybroker to shared executable for Major platforms (Windows, Linux, and MacOS) by @ziloka in #95
fix README.md by @bluet in #100

New Contributors

@hms5232 made their first contribution in #92

Full Changelog: v2.0.0-alpha3...v2.0.0-alpha4

@ziloka

What's Changed

Update for python 3.10 by @ziloka in #88
docs: add ziloka as a contributor for code by @allcontributors in #90
build/use poetry by @a5r0n in #86

New Contributors

@ziloka made their first contribution in #88
@a5r0n made their first contribution in #86

Full Changelog: v2.0.0-alpha...v2.0.0-alpha3

@bluet

What's Changed

1 send proxy info back to client in http header by @bluet in #2
Bump attrs from 19.1.0 to 19.3.0 by @dependabot-preview in #6
WIP: ADD: using pre-commit for code quality by @afunTW in #4
Adding optional SIGINT handler. It raises RuntimeError when run on a … by @quancore in #9
[Snyk] Security upgrade pyyaml from 5.3.1 to 5.4 by @bluet in #18
[Snyk] Security upgrade py from 1.8.1 to 1.10.0 by @bluet in #19
External ip by @quancore in #11
lock python version to 3.6 in Dockerfile by @vincentinttsh in #29
Don't lock python packages black version in dev-py36.txt by @vincentinttsh in #30
Bump py from 1.8.1 to 1.10.0 by @dependabot in #63
Bump pyyaml from 5.3.1 to 5.4 by @dependabot in #64
[Snyk] Security upgrade python from 3.6-alpine to 3.8.13-alpine by @bluet in #60
add output format: text by @bluet in #65
docs: add ivaano as a contributor for code by @allcontributors in #72
docs: add synchronizing as a contributor for ideas by @allcontributors in #70
docs: add vincentinttsh as a contributor for code, review by @allcontributors in #69
docs: add quancore as a contributor for code by @allcontributors in #68
docs: add afunTW as a contributor for code, ideas, review by @allcontributors in #67
build(deps-dev): bump pycares from 3.1.1 to 4.2.0 by @dependabot in #78
Feature/update GitHub action by @afunTW in #79
Separate the linter and test check by @afunTW in #80
docs: add a5r0n as a contributor for code by @allcontributors in #66
fix: tests and styles by @bluet in #74
Deprecate py36 py37 support by @afunTW in #81
[Snyk] Security upgrade python from 3.6-alpine to 3.10-alpine by @snyk-bot in #55

New Contributors

@bluet made their first contribution in #2
@dependabot-preview made their first contribution in #6
@afunTW made their first contribution in #4
@quancore made their first contribution in #9
@vincentinttsh made their first contribution in #29
@dependabot made their first contribution in #63
@allcontributors made their first contribution in #72
@snyk-bot made their first contribution in #55

Full Changelog: https://github.com/bluet/proxybroker2/commits/v2.0.0-alpha

Uh oh!

Releases: bluet/proxybroker2

Release list

v2.0.0b3 — Full IPv6 support

🌐 Full IPv6 support — first-class across the stack

Headline changes

Quality

Follow-ups (filed)

Install

Uh oh!

v2.0.0b2 — Custom Provider System & Quality Pass

🎯 Custom Proxy Provider System & Quality Pass

Headline: Custom proxy providers via YAML/JSON

CLI / API

Security model

Parser bug fixes (with regression tests)

Quality pass

Removed

Python support

Tracked follow-ups for next releases

Uh oh!

ProxyBroker2 v2.0.0b1 - Production Ready Beta 🚀

🎉 Major Milestone: ProxyBroker2 is Production-Ready!

✨ Key Highlights

🔧 Critical Bug Fixes

🚀 Production-Ready Status

🛠️ API Improvements

🧪 Modern Testing Philosophy

🔄 Updated Dependencies (May 2025)

📚 Enhanced Documentation

🎯 Perfect for Production Use

Web Scraping & Automation

Proxy Server Deployment

🔄 Migration from v1.x

📦 Installation

🤝 Contributing

Uh oh!

v2.0.0-alpha4

What's Changed

New Contributors

Contributors

Uh oh!

v2.0.0-alpha3

What's Changed

New Contributors

Contributors

Uh oh!

v2.0.0-alpha

What's Changed

New Contributors

Contributors

Uh oh!