How fossabot/clash works
Step 1: Identify the project type and purpose
• Clash is a rule-based network proxy service written in Go.
• It exposes HTTP/HTTPS and SOCKS5 listeners, applies user-defined rules (domain suffix/keyword, GeoIP, final), selects a proxy or “direct/reject” action, and can chain or benchmark proxies (url-test).
• It also provides a RESTful external-controller API for dynamic control.
Step 2: Analyze the file structure
• Top level: main.go (entry), Makefile/Dockerfile for build & deploy, .travis.yml for CI, Gopkg.* for Go deps.
• adapters/: implementations of outbound strategies (direct, reject, shadowsocks, url-test).
• constant/: shared constants (adapter names, address types, rule types, traffic metrics).
• hub/: core orchestrator—reads config, holds global state (proxy definitions, groups, rulesets), runs external-controller server.
• proxy/: inbound servers
• proxy/http/: HTTP(S) proxy (CONNECT & standard requests)
• proxy/socks/: SOCKS5 proxy (TCP/UDP)
• rules/: rule matcher implementations (domain-suffix, domain-keyword, geoip, ipcidr, final).
• tunnel/: connection logic to upstream (builds actual TCP connections, logs, error handling).
• observable/: event bus for publishing/subscribing metrics & url-test results.
• docs/: documentation, LICENSE, README.md.
Step 3: Examine README for additional insights
• Features: HTTP/HTTPS, SOCKS, Surge-style config, GeoIP support.
• Configuration: INI file defines ports, proxies, proxy groups, rules.
• External controller: REST API on a configurable port for live control (via hub/server.go).
• Docker support via docker-compose.
a. Main components
• Clients (any HTTP/SOCKS5-capable application)
• HTTP Proxy Server (proxy/http/)
• SOCKS Proxy Server (proxy/socks/)
• Rule Engine (rules/ + constant/)
• Hub – Config Manager & REST API Controller (hub/)
• Adapter Factory & Pool (adapters/)
• Tunnel Manager (tunnel/)
• Observable/EventBus (observable/)
• GeoIP Database (data file loaded by rules/geoip.go)
b. Relationships & interactions
1. Client → HTTP/SOCKS listener
2. Listener → Rule Engine: “Which adapter?”
3. Rule Engine queries Hub for configured proxies/groups
4. Hub.AdapterFactory ↔ adapters/: instantiate or select an adapter (direct, reject, shadowsocks, url-test)
5. Adapter → Tunnel Manager: Dial upstream (could be direct host or another proxy)
6. Tunnel → External Network or next-hop proxy
7. Responses flow back along the same path in reverse
8. Observable:
• Adapters and Tunnel publish metrics (latency, failures)
• url-test adapter subscribes to schedule active benchmarks
9. External Controller (REST API) ↔ Hub: dynamic config reload, status queries
c. Architectural patterns & design principles
• Strategy Pattern: adapters implement a common interface for outbound connections
• Observer Pattern: observable package for metrics, url-test scheduling
• Factory Pattern: hub constructs adapters based on config.toml
• Modular design: strict separation between ingress (proxy servers), processing (rules, hub), egress (adapters, tunnel), and monitoring (observable)
d. Significant technologies/frameworks
• Go 1.10+ (net/http, net package)
• go-shadowsocks2 for Shadowsocks adapter
• INI parser for config
• Docker & docker-compose for containerization
• Travis CI for continuous integration
• External daemons (pm2, supervisor) for process management
• Two parallel ingress paths: HTTP and SOCKS listeners.
• Centralize rule evaluation before selecting an outbound adapter.
• External-controller API connecting to the Hub for runtime changes.
Step 6: Diagramming guidelines
• Request flow (Client → Listener → Rule Engine → Adapter → Tunnel → Network)
• Control flow (External Controller → Hub; Observable ↔ Adapters)