olm/dns/platform/REFACTORING_SUMMARY.md

# DNS Platform Module Refactoring Summary

## Changes Made

Successfully refactored the DNS platform directory from a NetBird-derived codebase into a standalone, simplified DNS override module.

### Files Created

**Core Interface & Types:**
- `types.go` - DNSConfigurator interface and shared types (DNSConfig, DNSState)

**Platform Implementations:**
- `darwin.go` - macOS DNS configurator using scutil (replaces host_darwin.go)
- `windows.go` - Windows DNS configurator using registry (replaces host_windows.go)
- `file.go` - Linux/Unix file-based configurator (replaces file_unix.go + file_parser_unix.go + file_repair_unix.go)
- `networkmanager.go` - NetworkManager D-Bus configurator (replaces network_manager_unix.go)
- `systemd.go` - systemd-resolved D-Bus configurator (replaces systemd_linux.go)
- `resolvconf.go` - resolvconf utility configurator (replaces resolvconf_unix.go)

**Detection & Helpers:**
- `detect_unix.go` - Automatic detection for Linux/FreeBSD
- `detect_darwin.go` - Automatic detection for macOS
- `detect_windows.go` - Automatic detection for Windows

**Documentation:**
- `README.md` - Comprehensive module documentation
- `examples/example_usage.go` - Usage examples for all platforms

### Files Removed

**Old NetBird-specific files:**
- `dbus_unix.go` - D-Bus utilities (functionality moved into platform-specific files)
- `file_parser_unix.go` - resolv.conf parser (simplified and integrated into file.go)
- `file_repair_unix.go` - File watching/repair (removed - out of scope)
- `file_unix.go` - Old file configurator (replaced by file.go)
- `host_darwin.go` - Old macOS configurator (replaced by darwin.go)
- `host_unix.go` - Old Unix manager factory (replaced by detect_unix.go)
- `host_windows.go` - Old Windows configurator (replaced by windows.go)
- `network_manager_unix.go` - Old NetworkManager (replaced by networkmanager.go)
- `resolvconf_unix.go` - Old resolvconf (replaced by resolvconf.go)
- `systemd_linux.go` - Old systemd-resolved (replaced by systemd.go)
- `unclean_shutdown_*.go` - Unclean shutdown detection (removed - out of scope)

### Key Architectural Changes

1. **Removed Build Tags for Platform Selection**
   - Old: Used `//go:build` tags at top of files to compile different code per platform
   - New: Named structs differently per platform (e.g., `DarwinDNSConfigurator`, `WindowsDNSConfigurator`)
   - Build tags kept only where necessary for cross-platform library imports

2. **Simplified Interface**
   - Removed complex domain routing, search domains, and port customization
   - Focused on core functionality: Set DNS, Get DNS, Restore DNS
   - Removed state manager dependencies

3. **Removed External Dependencies**
   - Removed: statemanager, NetBird-specific types, logging libraries
   - Kept only: D-Bus (for Linux), x/sys (for Windows registry and Unix syscalls)
   - Uses standard library where possible

4. **Standalone Operation**
   - No longer depends on NetBird types (HostDNSConfig, etc.)
   - Uses standard library types (net/netip.Addr)
   - Self-contained backup/restore logic

5. **Improved Code Organization**
   - Each platform has its own clearly-named file
   - Detection logic separated into detect_*.go files
   - Shared types in types.go
   - Examples in dedicated examples/ directory

### Feature Comparison

**Removed (out of scope for basic DNS override):**
- Search domain management
- Match-only domains
- DNS port customization (except where natively supported)
- File watching and auto-repair
- Unclean shutdown detection
- State persistence
- Integration with external state managers

**Retained (core DNS functionality):**
- Setting DNS servers
- Getting current DNS servers
- Restoring original DNS servers
- Automatic platform detection
- DNS cache flushing
- Backup and restore of original configuration

### Platform-Specific Notes

**macOS (Darwin):**
- Simplified to focus on DNS server override using scutil
- Removed complex domain routing and local DNS setup
- Removed GPO and state management
- Kept DNS cache flushing

**Windows:**
- Simplified registry manipulation to just NameServer key
- Removed NRPT (Name Resolution Policy Table) support
- Removed DNS registration and WINS management
- Kept DNS cache flushing

**Linux - File-based:**
- Direct /etc/resolv.conf manipulation with backup
- Removed file watching and auto-repair
- Removed complex search domain merging logic
- Simple nameserver-only configuration

**Linux - systemd-resolved:**
- D-Bus API for per-link DNS configuration
- Simplified to just DNS server setting
- Uses Revert method for restoration

**Linux - NetworkManager:**
- D-Bus API for connection settings modification
- Simplified to IPv4 DNS only
- Removed search/match domain complexity

**Linux - resolvconf:**
- Uses resolvconf utility (openresolv or Debian resolvconf)
- Interface-specific configuration
- Simple nameserver configuration

### Usage Pattern

```go
// Automatic detection
configurator, err := platform.DetectBestConfigurator("eth0")

// Set DNS
original, err := configurator.SetDNS([]netip.Addr{
    netip.MustParseAddr("8.8.8.8"),
})

// Restore
defer configurator.RestoreDNS()
```

### Maintenance Notes

- Each platform implementation is independent
- No shared state between configurators
- Backups are file-based or in-memory only
- No external database or state management required
- Configurators can be tested independently

## Migration Guide

If you were using the old code:

1. Replace `HostDNSConfig` with simple `[]netip.Addr` for DNS servers
2. Replace `newHostManager()` with `platform.DetectBestConfigurator()`
3. Replace `applyDNSConfig()` with `SetDNS()`
4. Replace `restoreHostDNS()` with `RestoreDNS()`
5. Remove state manager dependencies
6. Remove search domain configuration (can be added back if needed)

## Dependencies

Required:
- `github.com/godbus/dbus/v5` - For Linux D-Bus configurators
- `golang.org/x/sys` - For Windows registry and Unix syscalls
- Standard library

## Testing Recommendations

Each configurator should be tested on its target platform:
- macOS: Test darwin.go with scutil
- Windows: Test windows.go with actual interface GUID
- Linux: Test all variants (file, systemd, networkmanager, resolvconf)
- Verify backup/restore functionality
- Test with invalid input (empty servers, bad interface names)