ansible-proxy-chain/openspec/specs/proxy-rules/spec.md

ADDED Requirements

Requirement: Reference Surge client config documents the chained proxy setup

The project SHALL include a reference Surge client configuration file showing how to configure the relay (Shadowsocks) and landing (Trojan) proxies with underlying-proxy chaining.

Scenario: Chain proxy definition

• WHEN a user reads the reference Surge config
• THEN it defines a Shadowsocks proxy pointing to the relay server
• THEN it defines a Trojan proxy pointing to the landing server with underlying-proxy set to the relay SS proxy
• THEN it defines a direct Trojan proxy to the landing server without underlying-proxy

Requirement: Surge rules use Sukka's ruleset for AI services

The reference Surge configuration SHALL use rulesets from ruleset.skk.moe (https://github.com/SukkaW/Surge) for AI service routing, not self-maintained domain lists.

Scenario: AI traffic routed through chained landing proxy

• WHEN a client request matches Sukka's AI ruleset (e.g., RULE-SET,https://ruleset.skk.moe/List/non_ip/ai.conf)
• THEN the Surge rule directs it through the chained landing proxy
• THEN traffic exits from the landing server's local IP

Requirement: Surge rules use Sukka's ruleset for streaming services

The reference Surge configuration SHALL use rulesets from ruleset.skk.moe for streaming service routing, selecting the appropriate regional ruleset.

Scenario: Streaming traffic routed through chained landing proxy

• WHEN a client request matches Sukka's streaming ruleset (e.g., RULE-SET,https://ruleset.skk.moe/List/non_ip/stream_us.conf)
• THEN the Surge rule directs it through the chained landing proxy
• THEN traffic exits from the landing server's local IP

Requirement: Rule ordering follows Sukka's prescribed order

The reference Surge configuration SHALL place DOMAIN-SET and non_ip rules before all IP-based rules, as required by Sukka's ruleset documentation.

Scenario: Correct rule ordering

• WHEN the Surge config is loaded
• THEN all DOMAIN-SET and non_ip RULE-SET entries appear before any ip RULE-SET entries

Requirement: Default traffic routes through the relay only

The reference Surge configuration SHALL route all traffic not matching any specific ruleset through the relay Shadowsocks proxy directly.

Scenario: Non-matched domain goes through relay

• WHEN a client request does not match any ruleset
• THEN the Surge FINAL rule directs it through the relay SS proxy
• THEN traffic exits from the relay server's IP

Requirement: Surge rules route China domains to DIRECT

The reference Surge configuration SHALL use Sukka's China domain rulesets to route China-destined domain traffic to DIRECT, bypassing all proxies.

Scenario: China domain hits DIRECT

• WHEN a client request matches Sukka's China domain ruleset (e.g., DOMAIN-SET,https://ruleset.skk.moe/List/domainset/cn.conf)
• THEN Surge routes it via DIRECT policy
• THEN the traffic connects without going through any proxy

Requirement: Surge rules route China IPs to DIRECT

The reference Surge configuration SHALL use Sukka's China IP ruleset to route China IP CIDR traffic to DIRECT.

Scenario: China IP hits DIRECT

• WHEN a client request resolves to a China IP matching Sukka's China IP ruleset (e.g., RULE-SET,https://ruleset.skk.moe/List/ip/domestic.conf)
• THEN Surge routes it via DIRECT policy

Requirement: China rules are placed after service-specific rules

The China direct rules SHALL be placed after AI and streaming service rules in the Surge configuration, so that AI/streaming traffic still routes through the chain even if the destination IP is in China.

Scenario: AI service with China CDN still goes through chain

• WHEN a request to an AI service domain matches the AI ruleset
• AND the destination IP happens to be in a China range
• THEN the AI ruleset matches first (higher priority) and routes through Chain
• THEN the China IP rule does not override the AI routing

Requirement: China domain rules appear before China IP rules

The China DOMAIN-SET and non_ip rules SHALL appear before the China ip rules, following Sukka's prescribed ordering to maintain DNS protection.

Scenario: Correct ordering within China rules

• WHEN the Surge config is loaded
• THEN China DOMAIN-SET and non_ip entries appear before any China ip entries

Requirement: No self-maintained domain lists

The project SHALL NOT maintain its own domain lists for AI or streaming services. All domain/rule matching SHALL be delegated to Sukka's externally maintained rulesets.

Scenario: No local domain list files

• WHEN the project repository is inspected
• THEN there are no manually curated domain list files for proxy routing