7.5 KiB
7.5 KiB
02. ucode Backend Module Reference
Tachyon's backend is modularized under tachyon/files/usr/lib/tachyon/. Modules are loaded dynamically via ucode's require() or executed directly via ucode -L <lib_dir> <module> <command>.
1. Core Subsystem (core/)
| Module | Key Functions & Responsibilities |
|---|---|
constants.uc |
Central repository of paths, default ports, mark values, version detection (detect_installed_version()), commit SHA resolver (detect_installed_commit_sha()), UCI config names. |
common.uc |
String manipulation (trim, split_lines), file helpers (read_file, write_atomic), logging formatters (log_info, log_error, log_debug). |
helpers.uc |
Process management (popen_read, system_exec), CIDR formatting, MAC address validators, integer conversions with safety fallbacks. |
ip.uc |
IP v4/v6 parser, subnet containment (ip_in_subnet), CIDR validator, loopback & private IP range detection. |
url.uc |
RFC 3986 URL parser, extraction of scheme, host, port, path, query params, hash fragment, safe URL encoding/decoding. |
uci.uc |
High-level wrapper over OpenWrt libuci: get_section, set_option, add_section, delete_section, atomic commit with lock. |
packages.uc |
Package manager abstraction: detects opkg vs apk (OpenWrt 25.x+), checks installed packages, versions, and dependencies. |
events.uc |
Internal event bus mechanism: publish/subscribe for service state transitions and notification dispatching. |
2. Service Management Subsystem (service/)
| Module | Key Functions & Responsibilities |
|---|---|
lifecycle.uc |
Service start, stop, restart, enable, disable. Coordinates teardown order (nftables -> singbox -> zapret -> dnsmasq) to prevent routing deadlocks. |
state.uc |
Comprehensive runtime state reader (get_runtime_state()): active proxy server, watchdog status, interface health, uptime, memory consumption. |
reload.uc |
Hot-reload planner (plan_reload()): inspects what changed in UCI and applies the minimal necessary restart (e.g. soft-reload sing-box vs full nftables rebuild). |
reset.uc |
Factory reset routines: wipes /etc/config/tachyon, cleans up temporary caches, restores default templates. |
watchdog.uc |
Autonomous supervisor loop: checks sing-box process, memory thresholds (OOM guard), DNS resolution, loop-restart mitigation (safe_proxy_restart). |
snapshot.uc |
Assembles a structured system snapshot JSON for AI Doctor and external diagnostics. |
agent_api.uc |
CGI handler for /cgi-bin/tachyon-agent/: handles routing, Bearer authentication validation, endpoint dispatch, JSON serialization. |
agent_mcp.uc |
Model Context Protocol (MCP) tool schema and handlers for integration with MCP clients (Cursor, Claude Desktop). |
telegram.uc |
Telegram Bot daemon: polling loop (getUpdates), command dispatcher (/doctor, /ai_doctor, /fix, /restart, /status), inline keyboards. |
warp_generator.uc |
Cloudflare WARP account generator & key exchange for auto-provisioning WireGuard outbounds. |
event_controller.uc |
Coordinates async background job workers, PID tracking, lock files, and log ring-buffer management. |
3. Diagnostics & AI Subsystem (diagnostics/)
| Module | Key Functions & Responsibilities |
|---|---|
runtime.uc |
Local Rule Doctor & AI Doctor engine: runs 10+ local heuristic checks, detects NTP desync, conntrack overflow, MTU issues, bootstrap DNS deadlock; applies 13+ quick fix codes (apply_quick_fix()), executes emergency internet restoration (restore_native_internet()). |
service_check.uc |
Health probes: tests sing-box TCP/UDP proxying, DNS response latency, WAN internet connectivity, gateway reachability. |
status.uc |
Detailed diagnostics status assembler for LuCI Diagnostic tab and CLI tachyon doctor. |
4. sing-box Subsystem (singbox/)
| Module | Key Functions & Responsibilities |
|---|---|
generator.uc |
Master sing-box JSON configuration compiler (/tmp/tachyon/sing-box.json): binds inbounds, outbounds, routing rules, DNS, experimental. |
generator_outbounds.uc |
Compiles VLESS (Reality/gRPC/WS), VMess, Shadowsocks, Trojan, Hysteria2, WireGuard, Direct, and Block outbounds. |
generator_routes.uc |
Compiles routing rules: domain matchers, IP CIDR matchers, GeoIP rules, client MAC/IP matchers, detour assignments. |
dns.uc |
Compiles sing-box DNS configuration: local DNS, remote DoH/DoT/UDP DNS, fakeip/direct resolution rules. |
dns_failover.uc |
High-availability DNS failover logic: switches between primary and secondary bootstrap DNS upon timeouts. |
dns_prefetch.uc |
Domain pre-fetching & cache warming for frequently accessed sites. |
dns_presets.uc |
Built-in DNS presets (Cloudflare, Google, AdGuard, Quad9, OpenDNS, Custom DoH). |
priority.uc |
Outbound group priority manager: auto-failover, fallback groups, URL-test latency sorting. |
route.uc |
Low-level sing-box route rule builder & selector logic. |
rulesets.uc |
Rule-set binary (.srs) and JSON ruleset compiler and parser. |
servers.uc |
Server node parser, validator, and URI serializer (VLESS, VMess, SS, Trojan, H2). |
subscription.uc |
Subscriptions processor: download, base64 decoding, node deduplication, format normalizer. |
urltest.uc |
RTT ping & latency testing worker: measures real response times across proxy servers. |
5. Providers & DPI Bypass Subsystem (providers/)
| Module | Key Functions & Responsibilities |
|---|---|
zapret/runtime.uc |
Manages Zapret v1 (nfqws) process arguments, queue numbers, NFQueue bindings, daemon start/stop. |
zapret2/runtime.uc |
Manages Zapret v2 (nfqws2) advanced multi-vector desync arguments (--dpi-desync=multisplit, --dpi-desync-seqovl). |
byedpi/runtime.uc |
Manages ByeDPI (ciadpi) SOCKS5 proxy daemon, port allocation, payload split parameters. |
nfqueue/runtime.uc |
Kernel NFQueue allocation table, prevents queue ID collisions between Zapret v1 and v2. |
rules.uc |
Maps UCI routing rules to specific provider action handlers (`action = zapret |
status.uc |
Real-time process inspection and health monitoring of all active DPI bypass daemons. |
6. Networking & Firewall Subsystem (nft/, dns/)
| Module | Key Functions & Responsibilities |
|---|---|
nft/apply.uc |
Generates and commits nftables ruleset (inet TachyonTable): prerouting, output, divert chains, marks, fwmark, bypass sets. |
dns/apply.uc |
Coordinates DNS interception: configures dnsmasq forwarders, port redirection (127.0.0.1:5353), ipset / nftset auto-population. |
7. Configuration & Components Subsystem (config/, components/, subscription/)
| Module | Key Functions & Responsibilities |
|---|---|
config/validator.uc |
Strict UCI schema validation: validates IP addresses, ports, UUIDs, private keys, domain names, action modes. |
config/migration.uc |
Automatic migration engine: migrates configurations from legacy Forkop, Podkop Plus, and Podkop configs without data loss. |
components/updater.uc |
Background component installer/updater: handles downloading, unpacking, installing, and version checking of binaries. |
components/hosts.uc |
Remote hosts lists ingestor: fetches blocklists, merges into unified combined.txt, handles GitHub mirror failovers. |
subscription/cache.uc |
Atomic subscription cache store, prevents redundant network downloads. |
subscription/parser.uc |
Universal proxy URI parser: parses vless://, vmess://, ss://, trojan://, hysteria2://, wireguard://. |