Add comprehensive documentation to CLI components and core functionality

This commit extends the documentation effort by adding detailed explanatory
comments to key CLI components and core functionality throughout the cmd/
directory. The changes focus on explaining WHY certain logic is needed,
not just WHAT the code does, improving code maintainability and helping
developers understand complex business decisions.

Key improvements:
- Main entry points: Document CLI initialization, logging setup, and cache
  configuration with reasoning for design decisions
- DNS proxy core: Explain DNS proxy constants, data structures, and core
  processing pipeline for handling DNS queries
- Service management: Document service command structure, configuration
  patterns, and platform-specific service handling
- Logging infrastructure: Explain log buffer management, level encoders,
  and log formatting decisions for different use cases
- Metrics and monitoring: Document Prometheus metrics structure, HTTP
  endpoints, and conditional metric collection for performance
- Network handling: Explain Linux-specific network interface filtering,
  virtual interface detection, and DNS configuration management
- Hostname validation: Document RFC1123 compliance and DNS naming
  standards for system compatibility
- Mobile integration: Explain HTTP retry logic, fallback mechanisms, and
  mobile platform integration patterns
- Connection management: Document connection wrapper design to prevent
  log pollution during process lifecycle

Technical details:
- Added explanatory comments to 11 additional files in cmd/cli/
- Maintained consistent documentation style and format
- Preserved all existing functionality while improving code clarity
- Enhanced understanding of complex business logic and platform-specific
  behavior

These comments help future developers understand the reasoning behind
complex decisions, making the codebase more maintainable and reducing
the risk of incorrect modifications during maintenance.

cmd/cli/main.go

@@ -13,6 +13,8 @@ import (
 	"github.com/Control-D-Inc/ctrld"
 )
 
+// Global variables for CLI configuration and state management
+// These are used across multiple commands and need to persist throughout the application lifecycle
 var (
 	configPath        string
 	configBase64      string
@@ -46,6 +48,8 @@ var (
 	noConfigStart      bool
 )
 
+// Flag name constants for consistent reference across the codebase
+// Using constants prevents typos and makes refactoring easier
 const (
 	cdUidFlagName          = "cd"
 	cdOrgFlagName          = "cd-org"
@@ -53,11 +57,15 @@ const (
 	nextdnsFlagName        = "nextdns"
 )
 
+// init initializes the default logger before any CLI commands are executed
+// This ensures logging is available even during early initialization phases
 func init() {
 	l := zap.NewNop()
 	mainLog.Store(&ctrld.Logger{Logger: l})
 }
 
+// Main is the entry point for the CLI application
+// It initializes configuration, sets up the CLI structure, and executes the root command
 func Main() {
 	ctrld.InitConfig(v, "ctrld")
 	rootCmd := initCLI()
@@ -67,6 +75,8 @@ func Main() {
 	}
 }
 
+// normalizeLogFilePath converts relative log file paths to absolute paths
+// This ensures log files are created in predictable locations regardless of working directory
 func normalizeLogFilePath(logFilePath string) string {
 	if logFilePath == "" || filepath.IsAbs(logFilePath) || service.Interactive() {
 		return logFilePath
@@ -82,18 +92,19 @@ func normalizeLogFilePath(logFilePath string) string {
 }
 
 // initConsoleLogging initializes console logging, then storing to mainLog.
+// This sets up human-readable logging output for interactive use
 func initConsoleLogging() {
 	consoleWriterLevel = ctrld.NoticeLevel
 	switch {
 	case silent:
-		// For silent mode, use a no-op logger
+		// For silent mode, use a no-op logger to suppress all output
 		l := zap.NewNop()
 		mainLog.Store(&ctrld.Logger{Logger: l})
 	case verbose == 1:
-		// Info level
+		// Info level provides basic operational information
 		consoleWriterLevel = zapcore.InfoLevel
 	case verbose > 1:
-		// Debug level
+		// Debug level provides detailed diagnostic information
 		consoleWriterLevel = zapcore.DebugLevel
 	}
 	consoleWriter = newHumanReadableZapCore(os.Stdout, consoleWriterLevel)
@@ -105,6 +116,7 @@ func initConsoleLogging() {
 // to be used for all interactive commands.
 //
 // Current log file config will also be ignored.
+// This prevents log file conflicts during interactive command execution
 func initInteractiveLogging() {
 	old := cfg.Service.LogPath
 	cfg.Service.LogPath = ""
@@ -122,19 +134,23 @@ func initLoggingWithBackup(doBackup bool) []zapcore.Core {
 	var writers []io.Writer
 	if logFilePath := normalizeLogFilePath(cfg.Service.LogPath); logFilePath != "" {
 		// Create parent directory if necessary.
+		// This ensures log files can be created even if the directory doesn't exist
 		if err := os.MkdirAll(filepath.Dir(logFilePath), 0750); err != nil {
 			mainLog.Load().Error().Msgf("failed to create log path: %v", err)
 			os.Exit(1)
 		}
 
 		// Default open log file in append mode.
+		// This preserves existing log entries across restarts
 		flags := os.O_CREATE | os.O_RDWR | os.O_APPEND
 		if doBackup {
 			// Backup old log file with .1 suffix.
+			// This prevents log file corruption during rotation
 			if err := os.Rename(logFilePath, logFilePath+oldLogSuffix); err != nil && !os.IsNotExist(err) {
 				mainLog.Load().Error().Msgf("could not backup old log file: %v", err)
 			} else {
 				// Backup was created, set flags for truncating old log file.
+				// This ensures a clean start for the new log file
 				flags = os.O_CREATE | os.O_RDWR
 			}
 		}
@@ -147,14 +163,16 @@ func initLoggingWithBackup(doBackup bool) []zapcore.Core {
 	}
 
 	// Create zap cores for different writers
+	// Multiple cores allow logging to both console and file simultaneously
 	var cores []zapcore.Core
 	cores = append(cores, consoleWriter)
 
-	// Determine log level
+	// Determine log level based on verbosity and configuration
+	// This provides flexible logging control for different use cases
 	logLevel := cfg.Service.LogLevel
 	switch {
 	case silent:
-		// For silent mode, use a no-op logger
+		// For silent mode, use a no-op logger to suppress all output
 		l := zap.NewNop()
 		mainLog.Store(&ctrld.Logger{Logger: l})
 		return cores
@@ -164,7 +182,8 @@ func initLoggingWithBackup(doBackup bool) []zapcore.Core {
 		logLevel = "debug"
 	}
 
-	// Parse log level
+	// Parse log level string to zapcore.Level
+	// This provides human-readable log level configuration
 	var level zapcore.Level
 	switch logLevel {
 	case "debug":
@@ -183,12 +202,14 @@ func initLoggingWithBackup(doBackup bool) []zapcore.Core {
 
 	consoleWriter.Enabled(level)
 	// Add cores for all writers
+	// This enables multi-destination logging (console + file)
 	for _, writer := range writers {
 		core := newMachineFriendlyZapCore(writer, level)
 		cores = append(cores, core)
 	}
 
 	// Create a multi-core logger
+	// This allows simultaneous logging to multiple destinations
 	multiCore := zapcore.NewTee(cores...)
 	logger := zap.New(multiCore)
 	mainLog.Store(&ctrld.Logger{Logger: logger})
@@ -196,11 +217,14 @@ func initLoggingWithBackup(doBackup bool) []zapcore.Core {
 	return cores
 }
 
+// initCache initializes DNS cache configuration
+// This improves performance by caching frequently requested DNS responses
 func initCache() {
 	if !cfg.Service.CacheEnable {
 		return
 	}
 	if cfg.Service.CacheSize == 0 {
+		// Default cache size provides good balance between memory usage and performance
 		cfg.Service.CacheSize = 4096
 	}
 }