CLI Reference: Serve (Proxy Server)
Relevant source files
The following files were used as context for generating this wiki page:
The serve command launches a local proxy server that distributes incoming client requests to a pool of discovered and validated external proxies. It automates proxy rotation, handles failovers, and provides a centralized endpoint for applications to access public proxy networks.
This system operates asynchronously, concurrently finding new proxies while serving existing requests. It supports HTTP, HTTPS, and SOCKS protocols, and allows for fine-grained filtering based on anonymity levels, response times, and geographical locations.
Sources: README.md:14-20, CLAUDE.md:55-59, proxybroker/cli.py:84-92
Architecture and Data Flow
The serve command initializes a Broker instance which orchestrates three primary components: the Provider tasks, the Checker, and the Server. The Server utilizes a ProxyPool to manage the lifecycle of proxies used for rotation.
The diagram shows the flow from CLI initialization to the selection of a validated proxy for an external request.
Sources: CLAUDE.md:62-85, proxybroker/server.py
ProxyPool Management
The ProxyPool maintains a priority queue (min-heap) of proxies based on their average response time (avg_resp_time). It categorizes proxies into two stages:
- Newcomers: Proxies with fewer than the required minimum requests (
min_req_proxy) are stored in a separate list to gain initial statistics. - Main Pool: Proven proxies that meet quality thresholds (error rate and response time) are moved to the heap for active rotation.
Sources: CLAUDE.md:67-71, proxybroker/server.py:35-100, tests/test_server.py:185-210
Configuration Options
The serve command accepts parameters to configure both the local server listener and the background proxy discovery process.
Server Listener Settings
These options define how the local proxy server accepts connections.
| Option | Type | Default | Description |
|---|---|---|---|
--host | String | 127.0.0.1 | The IP address the local server binds to. |
--port | Integer | 8888 | The port the local server listens on. |
--backlog | Integer | 100 | Maximum number of queued connections for the listener. |
Sources: proxybroker/cli.py:195-201, proxybroker/cli.py:260-262
Proxy Selection and Rotation Strategy
These settings control how the ProxyPool selects and maintains external proxies.
| Option | Type | Default | Description |
|---|---|---|---|
--strategy | String | best | Strategy for picking a proxy (currently only best is supported). |
--min-queue | Integer | 5 | Minimum proxies required in the pool before selection begins. |
--min-req-proxy | Integer | 5 | Minimum requests a proxy must handle before quality evaluation. |
--max-error-rate | Float | 0.5 | Maximum allowed error rate (e.g., 0.5 for 50%). |
--max-resp-time | Integer | 8 | Maximum allowed average response time in seconds. |
--prefer-connect | Flag | False | Prefers the CONNECT method for requests when possible. |
Sources: proxybroker/cli.py:208-245, proxybroker/server.py:35-55
Discovery and Filtering
The server continues to find proxies in the background using these filters.
| Option | Type | Required | Description |
|---|---|---|---|
--types | List | Yes | Protocols to check (HTTP, HTTPS, SOCKS4, SOCKS5, etc.). |
--lvl | List | No | Anonymity levels (Transparent, Anonymous, High). |
--countries | List | No | ISO country codes for proxy location filtering. |
--limit | Integer | 100 | Maximum number of working proxies to maintain in the pool. |
Sources: proxybroker/cli.py:148-160, proxybroker/cli.py:250-258
Control API
The running proxy server exposes a special internal host, proxycontrol, which allows clients to interact with the server's state via HTTP requests.
The sequence diagram illustrates how a client uses the proxycontrol API to query history or remove a failing proxy.
Sources: README.md:245-285, tests/test_server.py:145-155
API Endpoints
- Get Proxy Info:
GET http://proxycontrol/api/history/url:<target_url>
Returns the IP and port of the proxy used for a specific request. For HTTPS, only the hostname is available. - Remove Proxy:
GET http://proxycontrol/api/remove/<PROXY_IP>:<PROXY_PORT>
Manually removes a specific proxy from the active pool.
Sources: README.md:245-285
Usage Examples
Basic Rotating Server
Start a server on the default port (8888) using high-anonymity HTTP and HTTPS proxies:
python -m proxybroker serve --host 127.0.0.1 --port 8888 --types HTTP HTTPS --lvl High
Sources: README.md:135-140
Custom Quality Thresholds
Start a server that only uses proxies with a response time under 5 seconds and an error rate below 30%:
python -m proxybroker serve --types HTTP --max-resp-time 5 --max-error-rate 0.3 --min-queue 10
Sources: proxybroker/cli.py:225-240, tests/test_server.py:160-175
Summary
The serve command provides a robust, asynchronous proxy server capable of managing a rotating pool of public proxies. By leveraging the ProxyPool's priority-based selection and the proxycontrol API, you can integrate high-quality, validated proxies into your applications with minimal configuration. The system ensures that only proxies meeting specific performance and anonymity criteria are utilized, automatically handling the discovery and replacement of failing nodes.
Sources: CLAUDE.md:55-59, README.md:14-20