Proxy Pool Management

Relevant source files

The following files were used as context for generating this wiki page:

• README_EN.md
• src/AGENTS.md
• dashboard/views/proxy/index.ts
• src/web/routes/inventory/proxy.ts
• src/web/store/config/proxy-store.ts
• src/config/load.ts
• dashboard/views/proxy/cards.ts
• test/suites/entries/smoke/parts/pool/proxy/proxy-fetch.ts

Proxy Pool Management handles the lifecycle, storage, and assignment of egress proxies within the freebuff-proxy service. It allows users to manage multiple proxy endpoints to avoid IP-based rate limiting and ensure stable connections to the upstream Freebuff API. The system supports global proxy pools, environment-based fallbacks, and internal assignment logic that binds accounts to specific proxies to maintain session stability.

Sources: README_EN.md:59-64, src/AGENTS.md:36-41, src/web/routes/inventory/proxy.ts:6-10

Architecture and Storage

The system manages proxies through a layered architecture involving the web console, a persistent JSON store, and an internal runtime allocator. Proxies are primarily stored in /data/proxies.json, which takes precedence over static configurations in config.yaml.

Data Flow for Proxy Management

The following diagram illustrates how proxy configurations move from the user interface to the network transport layer.

The diagram shows the transition from user input in the Web Console to the final network request using the allocated proxy.
Sources: src/web/store/config/proxy-store.ts:16-20, src/web/routes/inventory/proxy.ts:167-175, src/AGENTS.md:36-41

Storage Component: ProxyStore

The ProxyStore class manages the persistence of the proxy list. It ensures that only valid URLs are saved and loaded to prevent runtime crashes during egress construction.

• File Path: /data/proxies.json
• Format: Versioned JSON containing an array of proxy URLs.
• Validation: Uses sanitizeProxyList to drop illegal entries (non-strings or malformed URLs).

Sources: src/web/store/config/proxy-store.ts:21-39, src/web/store/config/proxy-store.ts:74-88

Proxy Assignment and Priority

The service uses an internal assignment strategy rather than requiring manual per-account configuration. This ensures that a single account consistently uses the same egress point, which is critical for session IP stability.

Assignment Logic

Proxies are resolved based on the following hierarchy of priority:

1. Account-Specific Proxy: Explicitly assigned proxy for a specific account.
2. Global Pool: The pool managed via the web console (/data/proxies.json).
3. Single Proxy Config: The upstream.proxy setting in config.yaml.
4. Environment Variables: Standard HTTP_PROXY or HTTPS_PROXY variables.
5. Direct Connection: Used if no other options are configured.

Sources: src/AGENTS.md:36-41, src/web/routes/inventory/proxy.ts:121-136

Internal Allocation

The AccountRuntimes component performs internal allocation using stable hashing. When the proxy pool is updated, the system invalidates existing caches and rebuilds runtimes to apply the new egress points immediately.

Sources: src/AGENTS.md:36-41, src/web/routes/inventory/proxy.ts:167-175

Connectivity Testing

The system provides an API endpoint and UI interface to verify proxy health. Testing involves two steps to ensure both general connectivity and specific upstream access.

1. Trace Test: Requests https://www.cloudflare.com/cdn-cgi/trace to retrieve the egress IP and location.
2. Upstream Probe: Requests https://codebuff.com/ to verify that the Freebuff API is reachable via the proxy.

Proxy Test Flow

The sequence diagram details the two-stage verification process for testing proxy connectivity.
Sources: src/web/routes/inventory/proxy.ts:60-108

API Reference

The following table summarizes the administrative API endpoints used for proxy management.

Endpoint	Method	Description	Admin Required
/api/proxy	GET	Lists configured proxies, effective proxies, and account-to-proxy mappings.	No
/api/proxy	POST	Saves a new list of proxies to the global pool and updates runtimes.	Yes
/api/proxy/test	POST	Executes connectivity tests for specific or configured proxies.	No

Sources: src/web/routes/inventory/proxy.ts:197-226

Configuration Parameters

Proxy settings can be influenced by environment variables and the config.yaml file, though the web console is the primary management interface.

Parameter	Source	Type	Description
FREEBUFF_PROXY_CONFIG	ENV	String	Path to the config.yaml file.
upstream.proxies	YAML / Store	Array	The global pool of proxy URLs.
upstream.proxy	YAML	String	A single fallback proxy URL.
HTTP_PROXY / HTTPS_PROXY	ENV	String	System-level fallback proxies.

Sources: src/config/load.ts:79-83, src/web/routes/inventory/proxy.ts:121-136, src/web/store/config/proxy-store.ts:16-20

Implementation Details

The core egress logic is unified to ensure that even a single proxy in the pool is correctly utilized.

// test/suites/entries/smoke/parts/pool/proxy/proxy-fetch.ts:25-30
const cfg = loadConfig()
cfg.upstream.proxies = [`http://127.0.0.1:${proxyPort}`] // Single proxy pool
// Egress is created via unified createEgress, ensuring proxy hits
const { fetch: proxyFetch } = createEgress({ config: cfg })
const res = await proxyFetch(`http://127.0.0.1:${targetPort}/hello`)

This snippet demonstrates the test case ensuring that the proxy fetch mechanism correctly routes requests through the configured proxy pool.
Sources: test/suites/entries/smoke/parts/pool/proxy/proxy-fetch.ts:20-33

Proxy Pool Management ensures that the freebuff-proxy remains resilient against IP blocks while maintaining the session integrity required by the upstream API through stable egress assignment. All day-to-day operations are accessible via the Web Console, with changes persisting to the data directory for durability across restarts.

Sources: README_EN.md:59-64, src/AGENTS.md:36-41