Refactor code structure for improved readability and maintainability
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
# Package Contracts: dns-helper
|
||||
|
||||
**Feature Branch**: `001-safety-reliability-refactor`
|
||||
**Date**: 2026-03-03
|
||||
|
||||
## Package: `resolver`
|
||||
|
||||
Handles DNS name resolution against a user-specified DNS server.
|
||||
|
||||
### Interface
|
||||
|
||||
```go
|
||||
// Resolver performs DNS lookups against a specific server.
|
||||
type Resolver interface {
|
||||
// LookupIP resolves a hostname to a list of IPv4 addresses using the
|
||||
// specified DNS server. Follows CNAME chains up to a maximum depth.
|
||||
// Returns deduplicated IPs. Returns an error if the hostname cannot
|
||||
// be resolved (NXDOMAIN, timeout, server unreachable, etc.).
|
||||
LookupIP(hostname, server string) ([]string, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Behavior Contract
|
||||
|
||||
- Queries are sent over UDP to `<server>:53`.
|
||||
- The `hostname` is automatically converted to FQDN (trailing dot appended if missing).
|
||||
- An A query is sent first. If A records are returned, they are collected.
|
||||
- If only CNAME records are returned (no A records in the answer), the CNAME target is resolved recursively.
|
||||
- CNAME chain depth is limited to 10 levels. Exceeding this returns an error.
|
||||
- Results are deduplicated before return.
|
||||
- Timeout: 5 seconds per query.
|
||||
- On NXDOMAIN: returns `error` with descriptive message.
|
||||
- On server unreachable/timeout: returns `error` with descriptive message.
|
||||
- Response ID must match query ID; mismatches are treated as errors.
|
||||
- Truncated responses (TC flag set) are treated as errors (no TCP fallback for simplicity).
|
||||
|
||||
---
|
||||
|
||||
## Package: `hostfile`
|
||||
|
||||
Manages reading, parsing, modifying, and atomically writing the hosts file.
|
||||
|
||||
### Interface
|
||||
|
||||
```go
|
||||
// Manager handles hosts file operations.
|
||||
type Manager interface {
|
||||
// Read reads and parses the hosts file at the given path.
|
||||
// Returns an error if the file cannot be read or the managed block is corrupt.
|
||||
Read(path string) (*HostsFile, error)
|
||||
|
||||
// Write atomically writes the hosts file content to the given path.
|
||||
// Creates a backup before writing. Uses temp-file-and-rename pattern.
|
||||
// backupDir is the directory for the backup file (typically the exe directory).
|
||||
Write(hf *HostsFile, backupDir string) error
|
||||
}
|
||||
|
||||
// HostsFile represents the parsed content of a hosts file.
|
||||
type HostsFile struct {
|
||||
Path string
|
||||
OriginalContent []string
|
||||
PrefixContent []string
|
||||
ManagedContent []string
|
||||
PostfixContent []string
|
||||
HasManagedBlock bool
|
||||
}
|
||||
```
|
||||
|
||||
### Sub-package: Managed Block Operations
|
||||
|
||||
```go
|
||||
// AddEntries adds DNS entries to the managed content, removing any
|
||||
// existing entries for the same hostnames first. Returns updated content.
|
||||
func AddEntries(existing []string, entries []DNSEntry) []string
|
||||
|
||||
// RemoveByHostname removes all managed entries matching any of the
|
||||
// specified hostnames. Returns updated content.
|
||||
func RemoveByHostname(existing []string, hostnames []string) []string
|
||||
|
||||
// RemoveAll returns an empty slice (clears all managed entries).
|
||||
func RemoveAll() []string
|
||||
```
|
||||
|
||||
### Behavior Contract — Read
|
||||
|
||||
- Opens the file at `path` and reads all lines.
|
||||
- Scans for start marker (`# DNSHelper <<-> START CONFIG`) and end marker (`# DNSHelper <->> END CONFIG`).
|
||||
- If neither marker found: `HasManagedBlock = false`, all content goes to `PrefixContent`.
|
||||
- If both markers found in correct order: splits content into Prefix, Managed, Postfix.
|
||||
- **Corruption detection** (returns error):
|
||||
- Start marker without end marker.
|
||||
- End marker without start marker.
|
||||
- End marker before start marker.
|
||||
- Duplicate start or end markers.
|
||||
- Uses sentinel values (not zero-index) for marker detection.
|
||||
|
||||
### Behavior Contract — Write
|
||||
|
||||
1. Creates backup: copies current hosts file to `<backupDir>/hosts.bak.<YYYYMMDD>-<4hex>`.
|
||||
2. Assembles full file content: prefix + (managed block if non-empty) + postfix.
|
||||
3. Compares assembled content with original — skips write if identical.
|
||||
4. Creates temp file in same directory as hosts file: `.dns-helper-tmp-*`.
|
||||
5. Writes content to temp file.
|
||||
6. Sets temp file permissions to match original hosts file permissions.
|
||||
7. Calls `Sync()` on temp file.
|
||||
8. Closes temp file.
|
||||
9. Calls `os.Rename(temp, hostsPath)`.
|
||||
10. On rename success: deletes backup, returns nil.
|
||||
11. On rename failure (including Windows retry 2-3x with 200ms delay): cleans up temp file, returns error. Backup is cleaned up after confirming original is intact.
|
||||
|
||||
---
|
||||
|
||||
## Package: `platform`
|
||||
|
||||
Provides platform-specific hosts file location.
|
||||
|
||||
### Interface
|
||||
|
||||
```go
|
||||
// GetHostsFilePath returns the absolute path to the system hosts file.
|
||||
// Returns an error if the file does not exist or cannot be accessed.
|
||||
func GetHostsFilePath() (string, error)
|
||||
```
|
||||
|
||||
### Platform Implementations
|
||||
|
||||
| Platform | Path | Detection |
|
||||
|----------|------|-----------|
|
||||
| Windows | `%SystemRoot%\System32\drivers\etc\hosts` (fallback: `C:\Windows\...`) | `os.LookupEnv("SystemRoot")` |
|
||||
| Linux | `/etc/hosts` | Hardcoded |
|
||||
| macOS | `/etc/hosts` | Hardcoded |
|
||||
|
||||
### Behavior Contract
|
||||
|
||||
- Returns error to caller on file-not-found or access error.
|
||||
- **Must NOT** call `os.Exit()`, `log.Fatal()`, or any process-terminating function.
|
||||
- Error messages include the path that was checked.
|
||||
|
||||
---
|
||||
|
||||
## Package: `lockfile`
|
||||
|
||||
Serializes concurrent access to the hosts file.
|
||||
|
||||
### Interface
|
||||
|
||||
```go
|
||||
// Lock represents an acquired lock.
|
||||
type Lock interface {
|
||||
// Release deletes the lock file. Safe to call multiple times.
|
||||
Release() error
|
||||
}
|
||||
|
||||
// Acquire attempts to acquire a lock file in the specified directory.
|
||||
// Retries for up to maxWait on contention. Breaks stale locks older
|
||||
// than staleTimeout. Returns an error if the lock cannot be acquired.
|
||||
func Acquire(dir string) (Lock, error)
|
||||
```
|
||||
|
||||
### Behavior Contract
|
||||
|
||||
- Lock file path: `<dir>/.dns-helper.lock`.
|
||||
- Created atomically via `os.OpenFile` with `O_CREATE|O_EXCL`.
|
||||
- PID written to lock file for debugging (not used for staleness).
|
||||
- Staleness: lock file with `ModTime` older than 2 minutes is considered stale and removed.
|
||||
- Retry: up to 2 seconds total, 200ms between attempts.
|
||||
- Release: `os.Remove(lockPath)`. Idempotent (no error if already deleted).
|
||||
- Lock acquired **after** DNS resolution, released **after** file write (or on error).
|
||||
Reference in New Issue
Block a user