Supporting Infrastructure

Relevant source files

• intra/core/async.go
• intra/core/barrier.go
• intra/core/closer.go
• intra/core/dontpanic.go
• intra/core/err.go
• intra/core/hangover.go
• intra/core/volatile.go
• intra/ipn/wg/stats.go
• intra/log/log.go
• intra/log/logger.go
• intra/log/logpool.go
• intra/log/logstat.go

Purpose and Scope

This page provides an overview of the supporting infrastructure components that underpin the firestack VPN system. These are cross-cutting concerns that enable reliable operation, debugging, configuration management, and build/deployment processes.

The supporting infrastructure includes:

• Logging and observability - Multi-level logging with spam filtering, console integration, and ring buffer for recent messages.
• Panic recovery - Flight recorder and stack trace collection for crash diagnostics.
• Runtime modification - Direct manipulation of Go runtime internals for enhanced diagnostics on mobile platforms.
• Core utilities - Concurrency primitives, connection tracking, memory management, and common patterns.

For detailed information on specific subsystems:

• Logging system implementation and panic recovery: see Logging System and Panic Recovery
• Runtime modification and security: see Runtime Modification and Security
• Core utilities and concurrency primitives: see Core Utilities and Concurrency Primitives

---

System Architecture Overview

The supporting infrastructure provides foundational services used by all major subsystems (DNS, Proxy, Network Stack). The architecture follows a layered approach where low-level utilities support mid-level services (logging, configuration), which in turn support high-level features.

Code Entity Map: Infrastructure to Subsystems

The following diagram associates high-level infrastructure concepts with the specific code entities that implement them.

Diagram: Supporting Infrastructure Code Entity Map

Sources: intra/log/logger.go52-73 intra/core/dontpanic.go73-88 intra/core/barrier.go78-94 intra/core/volatile.go13-14 intra/log/logpool.go51-62

---

Logging and Observability

The logging system provides multi-level logging with spam filtering and console integration. It is implemented as a singleton log.Glogger of type simpleLogger intra/log/log.go44

Log Level Hierarchy

Level	Code	Symbol	Purpose
VVERBOSE	0	Y	Most verbose; deep tracing intra/log/logger.go178
VERBOSE	1	V	Detailed flow information intra/log/logger.go179
DEBUG	2	D	Standard debugging info intra/log/logger.go180
INFO	3	I	Normal operational messages intra/log/logger.go181
WARN	4	W	Recoverable issues/warnings intra/log/logger.go182
ERROR	5	E	Non-fatal errors intra/log/logger.go183
STACKTRACE	6	F	Crash diagnostics / Fatal errors intra/log/logger.go184
USR	7	U	Interactive logs for user prompts intra/log/logger.go185
NONE	8		Disables the logger intra/log/logger.go186

Sources: intra/log/logger.go175-187 intra/log/logger.go189-212

Architecture Components

The logging system uses a ring buffer to store the last 512 pooled message slabs (qSize) for post-mortem analysis intra/log/logger.go94 intra/log/logger.go228 and a two-level clock mechanism to prevent log spam from overwhelming the system intra/log/logger.go141-146 It also uses a dedicated sync.Pool based buffer system to minimize allocations in the hot path, utilizing LB512 and LB1024 slab sizes intra/log/logpool.go20-33

Diagram: Logging Data Flow

Sources: intra/log/logger.go75-102 intra/log/logger.go143-146 intra/log/log.go56-59 intra/log/logpool.go51-62 intra/log/logpool.go27-30

For detailed implementation of logging internals, spam filtering, and console dispatching, see Logging System and Panic Recovery.

---

Panic Recovery and Diagnostics

Firestack implements a robust panic recovery system to ensure that crashes in individual goroutines do not necessarily bring down the entire process, while still capturing critical diagnostic data.

Diagnostic Tools

• Recover / RecoverFn: Deferred functions that catch panics, log the error, and capture stack traces. RecoverFn accepts a Finally function for cleanup intra/core/dontpanic.go73-88 intra/core/dontpanic.go166-179
• Flight Recorder: Uses trace.FlightRecorder to maintain a rolling buffer of execution traces (max bytes 50 MiB), which are dumped upon a panic intra/core/dontpanic.go60-68 intra/core/dontpanic.go153-162
• Post-Mortem Context: Upon panic, the system can dump the flight recorder to the configured output file intra/core/dontpanic.go123-148 and utilizes a scratch buffer to capture the stack trace via log.C intra/core/dontpanic.go204 intra/log/log.go214-218
• Async Helpers: Utility functions like Go, Gx, and Grx wrap goroutine execution with automatic panic recovery and worker tracking intra/core/async.go31-40 intra/core/async.go111-135

For details on the recovery mechanism and post-mortem diagnostics, see Logging System and Panic Recovery.

---

Runtime Modification and Security

To improve diagnostics on restricted platforms like Android, firestack utilizes go:linkname to modify Go runtime internals.

• secureMode Override: Disables runtime.secureMode on Android to allow the runtime to produce full stack traces rather than single-line summaries during fatal throws.
• Direct Logcat Output: Critical errors can be sent directly to system logs using runtime.writeErr.
• Environment Manipulation: Directly access and modify the Go runtime's cached environment variables (GODEBUG, GOTRACEBACK).

For details on how the runtime is modified and the security implications, see Runtime Modification and Security.

---

Core Utilities and Primitives

The codebase relies on a set of high-performance utility types designed for networking and concurrency.

Memory and Connection Management

• Request Coalescing: Barrier (and KeyedBarrier) ensures that duplicate units of work (e.g., WireGuard stats collection) are suppressed, allowing multiple callers to wait for a single in-flight execution intra/core/barrier.go78-94 intra/ipn/wg/stats.go38
• Safe Resource Closure: The core/closer.go utility provides unified handling for closing various network and file resources, including TCPConn, UDPConn, and gonet adapters intra/core/closer.go132-177
• Error Handling: JoinErr and UniqErr provide mechanisms to combine multiple errors into a single multierror interface errMult intra/core/err.go31-46

Data Structures and Concurrency

• Volatile Wrappers: Volatile[T] provides a non-panicking, atomic-like wrapper around atomic.Value for safe storage of generic types with type-safety checks intra/core/volatile.go13-14 intra/core/volatile.go85-99
• Network State Tracking: Hangover tracks time-based network states, allowing subsystems to check if a specific condition (like a network outage) is still within a valid duration intra/core/hangover.go16-18 intra/core/hangover.go42-48
• Async Primitives: Race, First, and All helpers provide structured ways to manage multiple concurrent WorkCtx tasks with timeouts intra/core/async.go191-251

For a full catalog of utilities and concurrency primitives, see Core Utilities and Concurrency Primitives.

Sources: intra/core/barrier.go78-94 intra/core/closer.go132-177 intra/core/volatile.go13-14 intra/core/hangover.go16-18 intra/core/err.go95-98 intra/core/async.go191-237