mirror of
https://github.com/fosrl/olm.git
synced 2026-02-20 03:46:42 +00:00
Owen
174
dns/platform/REFACTORING_SUMMARY.md
Normal file
174
dns/platform/REFACTORING_SUMMARY.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user