Residential Proxy Integration

Residential Proxy Integration provides the project with the ability to map stable client-side nodes to rotating residential egress points. This system allows users to manage residential proxy vendors, create channels for client access, and maintain sticky sessions where IP rotation is handled internally by the control plane.

The integration supports multiple rotation modes, including session-based templates, API-list extraction, and Cloudflare Worker panels. It ensures that proxy traffic can be tunneled through upstream overseas proxy groups using chain dialing, while providing the client with a stable endpoint via WebSocket over TLS.

Sources: web/src/pages/residential-page.tsx:162-164, internal/store/migrations.go:343-376

Architecture and Components

The residential proxy system consists of three primary entities: Providers, Channels, and Sessions.

Residential Providers

A Provider represents a connection to a specific residential proxy vendor. It stores configuration such as the gateway host, port, credentials, and rotation logic. The system supports vendors like BestProxy and RapidProxy, as well as custom API-based or Cloudflare Worker-based integrations.
Sources: internal/store/migrations.go:347-362, web/src/lib/types.ts:601-623

Residential Channels

A Channel acts as a logical entry point for clients. It aggregates one or more Providers and defines how sessions are managed (e.g., "sticky" vs "passthrough"). Channels generate stable node names and credentials for client subscriptions, shielding the client from the underlying IP rotation of the residential provider.
Sources: internal/store/migrations.go:364-379, web/src/lib/types.ts:687-720

Residential Client Sessions

A Session tracks the allocation of a specific residential IP to a client. The system supports "lazy allocation," where an exit IP is only assigned when the client makes their first request. Sessions maintain a state including rotation counts, expiry times, and lease information to prevent concurrent IP collisions.
Sources: internal/store/migrations.go:406-417, internal/store/migrations.go:440-452

Data Flow and Session Lifecycle

The following diagram illustrates the lifecycle of a residential proxy session, from provider registration to client IP rotation.

The system prioritizes "Lazy Allocation" to avoid blocking channel creation by requesting many IPs simultaneously from a provider.
Sources: internal/store/migrations.go:532-536, internal/store/migrations.go:440-447

Technical Specifications

Supported Protocols and Rotation Modes

The system integrates with various transport protocols and vendor rotation mechanisms.

Sources: web/src/lib/types.ts:586-591, internal/store/migrations.go:454-463

Dialer Proxy Chains

Residential proxies can be chained through upstream proxy groups. This prevents residential nodes from direct exposure by tunneling egress through an overseas group. The compiler validates these chains to prevent infinite recursion at runtime.

Database Schema Highlights

The residential proxy module relies on several specialized tables in the SQLite database to maintain state.

residential_providers

• protocol: The protocol dialed by the data plane (e.g., http, socks5).
• rotation_mode: Logic for IP switching (e.g., session-template).
• upstream_proxy_group_id: Foreign key to proxy_groups for chain dialing.
  Sources: internal/store/migrations.go:347-362, internal/store/migrations.go:392-396

residential_client_sessions

• node_fingerprint: Stable identifier for the logic node.
• lease_id / lease_holder: Used for mutual exclusion when claiming IPs.
• alloc_version: Monotonically increasing version for CAS (Compare-And-Swap) operations during rotation.
  Sources: internal/store/migrations.go:440-452, internal/store/migrations.go:556-563

API Endpoints

The system exposes administrative and public (consumer-facing) endpoints.

Administrative API (/api/v1/residential/...)

Used by the management panel to configure the system.

• GET /providers: Lists all residential providers.
• POST /channels/{id}/rotate: Triggers a manual rotation of a channel's exit IP.
• POST /channels/{id}/refresh-pool: Forces a refresh of the internal exit IP pool.
  Sources: internal/api/residential.go:38-124, internal/api/residential.go:210-264

Public Control API (/ctl/{token}/...)

Used by programmatic consumers for session management.

• POST /nodes/{index}/claim: Claims a specific node for use.
• POST /nodes/{index}/next: Rotates the exit IP for the specified node.
• POST /nodes/{index}/heartbeat: Renews a session lease.
  Sources: internal/api/residential.go:303-360

Implementation Details: CF Worker Integration

For the cf-worker rotation mode, the system utilizes the "BPB-Worker-Panel" model.

1. The control plane fetches VLESS/Trojan sharing URIs from a Cloudflare Worker URL.
2. URIs are parsed for host, path, and sni.
3. The control plane acts as a config issuer, providing the client with the Worker-based subscription.
   Sources: ref/README.md:14-26, internal/api/residential.go:367-372

Conclusion

Residential Proxy Integration bridges the gap between unstable residential IP pools and static client configurations. By centralizing rotation logic, session leasing, and dialer chaining within the HX control plane, the system provides high-reliability proxy access suitable for automated scraping and browsing tasks.

Sources: internal/store/migrations.go:556-563, internal/dataplane/mihomo/compiler_residential.go:78-95