This glossary defines codebase-specific terms, abbreviations, and domain concepts used within the Firestack repository. It serves as a technical reference for engineers to map high-level concepts to their respective implementations in the Go source code.
A system within the DNS resolver that performs transparent IP address translation. It maps "fake" IP addresses (generated via consistent hashing) to real destination IPs. This allows the system to track domain-to-IP mappings even when the underlying network or proxy requires specific IP families (e.g., NAT64).
Gateway interface in intra/dnsx/alg.go92-113translate function intra/dnsx/alg.go102 and X (un-map) function intra/dnsx/alg.go94The central orchestrator for all outbound network traffic. It manages a registry of proxy implementations (WireGuard, SOCKS5, HTTP, etc.) and determines which proxy should handle a specific flow based on user settings or automatic health selection.
proxifier struct (internal) and Proxies interface in intra/ipn/proxies.go170-191ProxyTo (used to select a proxy for a specific UID/destination) defined in the Proxies interface intra/ipn/proxies.go203-205An anti-censorship technique used to bypass Deep Packet Inspection (DPI). It involves sending "fake" or overlapping TCP segments with manipulated TTLs or sequence numbers to confuse middleboxes while remaining valid for the end host.
overwriteSplitter in intra/dialers/split_and_desync.go21-45DesyncTCP and DesyncTLS functions in intra/dialers/split_and_desync.go50 and intra/dialers/split_and_desync.go61| Term | Definition | Code Pointer |
|---|---|---|
| DoH | DNS over HTTPS transport. | intra/dnsx/transport.go36 |
| ODoH | Oblivious DNS over HTTPS (DoH via a relay). | intra/dnsx/transport.go40 |
| DNS53 | Standard DNS over UDP/TCP on port 53. | intra/dnsx/transport.go38 |
| Caching Transport | A decorator that adds bucketed caching and request coalescing to any DNS transport. | intra/dnsx/cacher.go92-106 |
| Hangover | A mechanism to track transport failures and temporarily stop queries if the network is down. | intra/dnsx/cacher.go105 |
| Barrier | A concurrency primitive used to coalesce multiple identical DNS queries into a single upstream request. | intra/dnsx/cacher.go104 |
This diagram shows how a "Natural Language" DNS query maps to specific code entities and transport selection.
Title: "DNS Query Resolution Path"
Sources: intra/dnsx/transport.go181-182 intra/dnsx/cacher.go114-145 intra/dnsx/cacher.go236 intra/dnsx/transport.go221-233
Proxies transition through various states monitored by the Auto proxy and proxifier.
The wgtun component bridges the gVisor network stack with the wireguard-go device. It handles the lifecycle of the virtual TUN interface.
channel.Endpoint (gVisor link layer) intra/ipn/wgproxy.go114 and device.Device (WireGuard core) intra/ipn/wgproxy.go183The system uses protocol-specific handlers to manage flows from the gVisor stack.
muxTable intra/udp.go44-47This diagram bridges the concept of "Proxying a Connection" to the internal code entities that handle the data.
Title: "Connection Proxying Logic"
Sources: intra/tcp.go237 intra/ipn/proxies.go203-205 intra/ipn/wgproxy.go182-186 intra/ipn/wgproxy.go211-215
| Abbreviation | Meaning | Context / Code Pointer |
|---|---|---|
| EIM / EIF | Endpoint Independent Mapping / Filtering | Used in UDP Muxer for NAT traversal. intra/udp.go46 |
| GRO / GSO | Generic Receive/Segment Offload | Performance optimizations for UDP/WireGuard. intra/ipn/wgproxy.go119 |
| RPN | Rethink Private Network | Internal proxy variant for specific region/country routing. intra/ipn/proxies.go55 |
| SMM | Socket Summary | Data structure for logging flow statistics. intra/listener.go31-50 |
| UID | User ID | Linux/Android User ID used for per-app routing rules. intra/tcp.go135 |
| NAT-PT | NAT-Protocol Translation | Mechanism for IPv4-IPv6 translation (DNS64/NAT64). intra/dnsx/transport.go175 |
A wrapper for atomic-like access to complex types that cannot be handled by standard sync/atomic primitives.
core.Volatile[T] used extensively for settings and state intra/ipn/wgproxy.go138A synchronization primitive that ensures only one execution of a task happens for a given key within a specific time window. Used for caching expensive operations and request coalescing.
A specialized connection wrapper that can replay initial writes (via a tee buffer) to support transparent retries with different anti-censorship strategies.
retrier struct in intra/dialers/retrier.go73-117calcTimeout intra/dialers/retrier.go134-142 and DialAny intra/dialers/retrier.go198-210Handles interactions with regional server infrastructure and account session management.
addRpnProxy intra/ipn/proxy.go90-127 and removeRpnProxy intra/ipn/proxy.go66-87An extension to the WireGuard protocol that adds noise and header manipulation to bypass protocol detection.
Amnezia struct in intra/ipn/wgproxy.go101 and pointer in wgtun intra/ipn/wgproxy.go142The leveled logging system that supports backpressure, console dispatching, and spam suppression.
Logger interface and simpleLogger implementation in intra/log/logger.go52-102clock based spam suppression intra/log/logger.go143-146 and ring buffer for recent logs intra/log/logger.go227-233A structure that captures metadata about a network flow (TCP/UDP/ICMP), including UID, process ID, destination, and data usage.
FlowSummary struct in intra/listener.go31-50tcpHandler intra/tcp.go136 and udpHandler intra/udp.go96Thread-safe maps with expiration logic. ExpMap is used for tracking firewall policies, while Sieve is used for caching dialer-to-IP pins.
ExpMap in intra/common.go113 and Sieve in intra/dialers/retrier.go68A utility for tracking active connections, mapping internal connection IDs to their respective local and remote addresses.
core.ConnMapper in intra/common.go90Sources:
Refresh this wiki