Proxy Groups & Routing Rules

Relevant source files

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

• internal/proxygroup/source_resolver.go
• internal/routingrules/service.go
• internal/dataplane/mihomo/compiler.go
• web/src/pages/routing-page.tsx
• web/src/lib/types.ts
• internal/api/capabilities_catalog.go

Introduction

Proxy Groups and Routing Rules define how the HX-ProxyGroup control plane organizes outbound traffic and selects nodes. Proxy Groups aggregate individual proxy nodes into logical sets using strategies like load balancing or latency testing. Routing Rules determine which traffic uses specific Proxy Groups, a DIRECT connection, or is REJECTED based on destination criteria such as domains or IP ranges.

The system acts as a management layer for a Mihomo data plane. It translates high-level configurations into a structured YAML configuration that Mihomo uses for traffic forwarding. This architecture separates the administrative control plane from the actual network data path.

Sources: AGENTS.md:10-14, internal/dataplane/mihomo/compiler.go:210-218, web/src/pages/routing-page.tsx:69-75

Proxy Groups

Proxy Groups are logical containers that manage a set of "members," which can be physical nodes, other groups, or a DIRECT exit. Each group follows a specific selection strategy to choose an active member for a connection.

Group Strategies

The system supports several selection strategies that govern how members within a group are utilized.

Strategy	Description
manual	Requires manual selection of a specific member (translated to Mihomo select).
url-test	Periodically tests members and selects the one with the lowest latency.
fallback	Uses the first available healthy member in the list.
round-robin	Distributes traffic across members sequentially.
consistent-hashing	Uses hashing to ensure the same destination consistently uses the same member.
sticky-sessions	Maintains session persistence for a specific client/destination pair.

Sources: web/src/lib/types.ts:167, internal/dataplane/mihomo/compiler.go:429-446, web/src/pages/routing-page.tsx:23-26

Member Resolution Pipeline

The source_resolver manages how dynamic members are added to a group. It uses a SourceSpec to filter nodes from subscriptions based on criteria like protocol, region, or latency.

The resolution process ensures that explicitly pinned nodes always appear first, followed by dynamically selected nodes that meet all filter requirements.

Sources: internal/proxygroup/source_resolver.go:27-40, internal/proxygroup/source_resolver.go:72-104

Dialer Chains

Proxy Groups can be chained by setting a dialer_proxy_group_id. This forces all traffic leaving a group to be tunneled through another specified group. The compiler validates these chains to ensure they remain acyclic and do not cause infinite recursion in the data plane.

Sources: internal/dataplane/mihomo/compiler.go:402-409, internal/dataplane/mihomo/compiler_residential.go:12-25

Routing Rules

Routing Rules map network traffic destinations to specific actions. These rules are organized into RuleSets which have a priority for evaluation order.

Rule Matching Types

The system supports various matching criteria for network traffic:

• Domain-based: domain, domain_suffix, domain_keyword, and geosite.
• IP-based: ip_cidr and geoip.
• System-based: process_name.
• Network-based: network (TCP/UDP) and dst_port.

Sources: internal/routingrules/service.go:230-244, web/src/pages/rules-page.tsx:13-18

Routing Actions

When a rule matches, one of three actions is performed:

1. DIRECT: Traffic bypasses proxies and uses the local server's network.
2. REJECT: Traffic is blocked.
3. Proxy Group: Traffic is forwarded to a specific Proxy Group.

Sources: internal/routingrules/service.go:37-41, web/src/lib/types.ts:153-156

Execution Logic

The Routing Rule system utilizes a priority-based execution flow. Rules with higher priority values are evaluated first.

Data Plane Compilation

The Compiler translates the internal domain models (Proxy Groups, Listeners, Routing Rules) into the Mihomo YAML format.

Compilation Process

1. Load State: Fetch Proxy Groups, Listeners, and Routing Rules from the repository.
2. Sort by Dependency: Order Proxy Groups so that dialer-proxies are defined before the groups that use them.
3. Compile Groups: Resolve members and apply strategies.
4. Compile Listeners: Configure inbound ports (HTTP, SOCKS5, VLESS, etc.) and map them to groups.
5. Compile Rules: Generate the final rule list, including special IN-NAME rules for multi-service support.

Sources: internal/dataplane/mihomo/compiler.go:81-125, internal/dataplane/mihomo/compiler.go:368-386

Shared Inbound Mode

The system supports a shared mode where multiple services share a single port. In this mode, the compiler generates AND rules that combine IN-NAME (the listener) and IN-USER (the authenticated user) to route traffic to the correct group.

// Example of a compiled rule for shared inbounds
"AND,((IN-NAME,hx-in-service1),(IN-USER,user-a)),hk-proxy-group"

Sources: internal/dataplane/mihomo/compiler.go:200-208, internal/dataplane/mihomo/compiler_residential.go:128-135, web/src/lib/types.ts:130-141

API Integration

The management API provides endpoints for programmatic control of groups and rules.

Endpoint	Method	Description
/api/v1/proxy-groups	GET/POST	List or create proxy groups.
/api/v1/proxy-services	POST	Atomically creates a group and a listener.
/api/v1/routing-rules	GET/PUT	Retrieve or replace the global routing configuration.

Sources: internal/api/capabilities_catalog.go:50-100, internal/api/routing_rules.go:10-31

Conclusion

The Proxy Groups and Routing Rules modules form the core of the HX-ProxyGroup control plane logic. By utilizing a resolution pipeline for nodes and a priority-based routing engine, the system enables complex network topologies while maintaining strict validation against cycles and misconfigurations. This configuration is ultimately compiled into a standardized format for execution by the underlying data plane.