s5p/TASKS.md

s5p -- Tasks

Current

• Scaffold project structure

• Implement SOCKS5 server

• Implement protocol handshakes (SOCKS5, SOCKS4/4a, HTTP CONNECT)

• Implement chain builder

• CLI and config loading

• Unit tests (config, proto)

• Documentation

• Smoke test with Tor

• Containerfile + compose.yaml (Alpine)

• Graceful SIGTERM shutdown

• cProfile support (--cprofile)

• Config split (example.yaml tracked, s5p.yaml gitignored)

• Dynamic proxy source API integration

• Connection retry with proxy rotation

• Connection metrics (periodic + shutdown logging)

• Managed proxy pool (multi-source, health-tested, persistent)

• Weighted proxy selection (prefer recently-tested proxies)

• Per-proxy backoff (60s cooldown after connection failure)

• Stale proxy expiry (evict dead proxies not seen for 3 refresh cycles)

• Pool stats in periodic metrics log (pool=alive/total)

• Fast warm start (trust cached state, defer all health tests)

• Static chain health check (skip pool tests if chain unreachable)

• SIGHUP hot config reload (timeout, retries, log_level, pool config)

• Dead proxy reporting (report_url POST evicted proxies to API)

• Concurrent connection semaphore (max_connections, CLI -m)

• Async HTTP client (replace blocking urllib, parallel source fetch)

• First-hop TCP connection pool (pool_size, pool_max_idle)

• Codebase consolidation (refactor/codebase-consolidation)

  • Extract shared proxy parsing and constants to config.py
  • Consolidate health-check HTTP logic in pool
  • Remove threading from metrics (pure asyncio, no lock needed)
  • Replace ensure_future with create_task
  • Rename ambiguous variables in config loader
  • Remove legacy ProxySource layer (source.py deleted)
  • Add tests for extracted parse_api_proxies

• Instant warm start (trust cached state, defer all health tests)

• Register signal handlers before startup (fix SIGKILL on stop)

• Use k8s-file logging driver with rotation

• Built-in control API (api.py, --api, api_listen)

• Tor control port integration (NEWNYM signaling, periodic rotation)

• Replace HTTP health check with TLS handshake (round-robin targets, no httpbin dependency)

• Multi-listener with configurable proxy chaining (per-port chain depth)

• Connection rate and chain latency metrics (rate/s, p50/p95/p99)

• Per-listener latency tracking

• Dynamic health test concurrency

• Multi-Tor round-robin via tor_nodes config

• Named proxy pools with per-listener assignment (proxy_pools:, pool:)

  • mitm source filter (?mitm=0 / ?mitm=1 API query param)
  • Per-pool state files (pool-{name}.json)
  • Per-pool log prefixes (pool[name]: ...)
  • API: merged /pool with per-pool breakdown, /status pools summary
  • Backward compat: singular proxy_pool: registers as "default"

• Integration tests with mock SOCKS5 proxy (end-to-end)

• Per-destination bypass rules (CIDR, suffix, exact match)

• Weighted multi-candidate pool selection

• Onion chain-only routing (.onion skips pool hops)

• Graceful shutdown timeout (fixes cProfile data dump)

• Gitea CI workflow (lint + test + Harbor image push)

v0.3.0 Stabilization

• Version bump to 0.3.0
• Systemd service unit (config/s5p.service, make install-service)
• CLI argument parsing tests (tests/test_cli.py)
• Protocol handshake tests (tests/test_proto.py -- SOCKS5/4/HTTP)
• API reference documentation (docs/USAGE.md)
• Prometheus /metrics endpoint (OpenMetrics format)

Quick Wins

• Listener-level retry override (retries per listener)
• Pool-level proxy protocol filter (allowed_protos on proxy pool)
• Document connection pooling (pool_size/pool_max_idle in CHEATSHEET.md)

Next

• UDP ASSOCIATE support
• BIND support
• Chain randomization