Update project documentation to reflect Phase 1 completion and outline Phase 2 priorities
This commit is contained in:
parent
fdf64d8da3
commit
a4ffaebb2a
5 changed files with 381 additions and 276 deletions
|
|
@ -17,30 +17,27 @@
|
|||
|
||||
### Component Relationships
|
||||
|
||||
#### TUI Layer (`src/hosts/tui/`)
|
||||
- **views.py**: Main application views and widgets
|
||||
- **Responsibilities**: User interaction, display logic, event handling
|
||||
- **Dependencies**: Manager layer for operations
|
||||
|
||||
#### Manager Layer (`src/hosts/core/manager.py`)
|
||||
- **Responsibilities**: Coordinate operations, maintain application state
|
||||
- **Dependencies**: Core models, parser, DNS resolver
|
||||
- **Patterns**: Command pattern for operations, Observer for state changes
|
||||
#### TUI Layer (`src/hosts/main.py`)
|
||||
- ✅ **HostsManagerApp**: Complete Textual application with reactive state management
|
||||
- ✅ **Responsibilities**: User interaction, display logic, event handling, navigation
|
||||
- ✅ **Dependencies**: Core models and parser for data operations
|
||||
- ✅ **Implementation**: Two-pane layout with ListView and reactive updates
|
||||
|
||||
#### Core Layer (`src/hosts/core/`)
|
||||
- **models.py**: Data structures (Entry, Comment, HostsFile)
|
||||
- **parser.py**: Hosts file parsing and serialization
|
||||
- **dns.py**: DNS resolution and IP comparison
|
||||
- **Responsibilities**: Pure business logic, no I/O dependencies
|
||||
- ✅ **models.py**: Complete data structures (HostEntry, HostsFile) with validation
|
||||
- ✅ **parser.py**: Robust hosts file parsing, serialization, and file operations
|
||||
- ✅ **Responsibilities**: Pure business logic, data validation, file integrity
|
||||
- ✅ **Implementation**: Comprehensive validation and error handling
|
||||
|
||||
#### System Layer
|
||||
- **File I/O**: Direct `/etc/hosts` file operations
|
||||
- **DNS Resolution**: Network calls for hostname resolution
|
||||
- **Permission Management**: Sudo privilege handling
|
||||
#### System Layer (Implemented)
|
||||
- ✅ **File I/O**: Atomic file operations with backup support
|
||||
- ✅ **Permission checking**: Validation of file access permissions
|
||||
- 🔄 **DNS Resolution**: Planned for Phase 5 advanced features
|
||||
- 🔄 **Permission Management**: Sudo handling planned for Phase 3 edit mode
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
### Data Model Design
|
||||
### Data Model Design (Implemented)
|
||||
```python
|
||||
@dataclass
|
||||
class HostEntry:
|
||||
|
|
@ -50,21 +47,49 @@ class HostEntry:
|
|||
is_active: bool = True
|
||||
dns_name: str | None = None # For CNAME-like functionality
|
||||
|
||||
# Implemented methods:
|
||||
def to_hosts_line(self) -> str
|
||||
@classmethod
|
||||
def from_hosts_line(cls, line: str) -> "HostEntry | None"
|
||||
def __post_init__(self) -> None # Validation
|
||||
|
||||
@dataclass
|
||||
class HostsFile:
|
||||
entries: list[HostEntry]
|
||||
header_comments: list[str]
|
||||
footer_comments: list[str]
|
||||
entries: list[HostEntry] = field(default_factory=list)
|
||||
header_comments: list[str] = field(default_factory=list)
|
||||
footer_comments: list[str] = field(default_factory=list)
|
||||
|
||||
# Implemented methods:
|
||||
def add_entry(self, entry: HostEntry) -> None
|
||||
def remove_entry(self, index: int) -> None
|
||||
def toggle_entry(self, index: int) -> None
|
||||
def get_active_entries(self) -> list[HostEntry]
|
||||
def get_inactive_entries(self) -> list[HostEntry]
|
||||
def sort_by_ip(self) -> None
|
||||
def sort_by_hostname(self) -> None
|
||||
def find_entries_by_hostname(self, hostname: str) -> list[HostEntry]
|
||||
def find_entries_by_ip(self, ip: str) -> list[HostEntry]
|
||||
```
|
||||
|
||||
### State Management
|
||||
- **Immutable operations**: All modifications return new state
|
||||
- **Validation pipeline**: Every change goes through validation
|
||||
- **Undo/Redo capability**: Maintain operation history
|
||||
- **Dirty state tracking**: Know when changes need saving
|
||||
### State Management (Implemented)
|
||||
- ✅ **Reactive state**: Using Textual's reactive attributes for UI updates
|
||||
- ✅ **Validation pipeline**: All data validated in models and parser
|
||||
- ✅ **File integrity**: Atomic operations preserve file structure
|
||||
- ✅ **Error handling**: Graceful degradation for all error conditions
|
||||
- 🔄 **Undo/Redo capability**: Planned for Phase 4 with command pattern
|
||||
- 🔄 **Dirty state tracking**: Will be implemented in Phase 3 edit mode
|
||||
|
||||
### Permission Model
|
||||
### Permission Model (Planned for Phase 3)
|
||||
```python
|
||||
# Current implementation (read-only mode)
|
||||
class HostsManagerApp:
|
||||
edit_mode: reactive[bool] = reactive(False) # Always False in Phase 1
|
||||
|
||||
def update_status(self):
|
||||
mode = "Edit mode" if self.edit_mode else "Read-only mode"
|
||||
# Status bar shows current mode
|
||||
|
||||
# Planned for Phase 3:
|
||||
class PermissionManager:
|
||||
def __init__(self):
|
||||
self.edit_mode = False
|
||||
|
|
@ -81,8 +106,39 @@ class PermissionManager:
|
|||
|
||||
## Design Patterns in Use
|
||||
|
||||
### Command Pattern
|
||||
### Reactive Pattern (Implemented)
|
||||
```python
|
||||
class HostsManagerApp(App):
|
||||
# Reactive attributes automatically update UI
|
||||
hosts_file: reactive[HostsFile] = reactive(HostsFile())
|
||||
selected_entry_index: reactive[int] = reactive(0)
|
||||
edit_mode: reactive[bool] = reactive(False)
|
||||
|
||||
def on_list_view_highlighted(self, event):
|
||||
# Automatic UI updates when selection changes
|
||||
self.selected_entry_index = event.list_view.index or 0
|
||||
self.update_entry_details()
|
||||
```
|
||||
|
||||
### Data Validation Pattern (Implemented)
|
||||
```python
|
||||
@dataclass
|
||||
class HostEntry:
|
||||
def __post_init__(self):
|
||||
# Comprehensive validation on creation
|
||||
if not self.ip_address or not self.hostnames:
|
||||
raise ValueError("IP address and hostnames required")
|
||||
|
||||
# Validate IP address format
|
||||
try:
|
||||
ipaddress.ip_address(self.ip_address)
|
||||
except ValueError as e:
|
||||
raise ValueError(f"Invalid IP address: {e}")
|
||||
```
|
||||
|
||||
### Command Pattern (Planned for Phase 4)
|
||||
```python
|
||||
# Will be implemented for undo/redo functionality
|
||||
class Command(ABC):
|
||||
@abstractmethod
|
||||
def execute(self) -> HostsFile:
|
||||
|
|
@ -91,76 +147,68 @@ class Command(ABC):
|
|||
@abstractmethod
|
||||
def undo(self) -> HostsFile:
|
||||
pass
|
||||
|
||||
class ToggleEntryCommand(Command):
|
||||
def __init__(self, entry_index: int):
|
||||
self.entry_index = entry_index
|
||||
|
||||
def execute(self, hosts_file: HostsFile) -> HostsFile:
|
||||
# Toggle entry active state
|
||||
|
||||
def undo(self, hosts_file: HostsFile) -> HostsFile:
|
||||
# Reverse the toggle
|
||||
```
|
||||
|
||||
### Observer Pattern
|
||||
### Factory Pattern (Implemented)
|
||||
```python
|
||||
class HostsManager:
|
||||
def __init__(self):
|
||||
self.observers: list[Observer] = []
|
||||
self.state: HostsFile = HostsFile()
|
||||
|
||||
def notify_observers(self, event: StateChangeEvent):
|
||||
for observer in self.observers:
|
||||
observer.on_state_change(event)
|
||||
```
|
||||
|
||||
### Factory Pattern
|
||||
```python
|
||||
class ParserFactory:
|
||||
@staticmethod
|
||||
def create_parser(file_path: str) -> HostsParser:
|
||||
# Return appropriate parser based on file format
|
||||
return StandardHostsParser(file_path)
|
||||
class HostsParser:
|
||||
def __init__(self, file_path: str = "/etc/hosts"):
|
||||
# Single parser handles all hosts file formats
|
||||
self.file_path = file_path
|
||||
```
|
||||
|
||||
## Critical Implementation Paths
|
||||
|
||||
### Application Startup
|
||||
1. **Initialize TUI**: Create Textual app instance
|
||||
2. **Load hosts file**: Parse `/etc/hosts` in read-only mode
|
||||
3. **Build UI**: Populate left pane with entries
|
||||
4. **Enter main loop**: Handle user input and events
|
||||
### Application Startup (✅ Implemented)
|
||||
1. ✅ **Initialize TUI**: Textual app with reactive state management
|
||||
2. ✅ **Load hosts file**: Robust parsing with error handling
|
||||
3. ✅ **Build UI**: Two-pane layout with ListView and details
|
||||
4. ✅ **Enter main loop**: Smooth keyboard navigation and event handling
|
||||
5. ✅ **Error handling**: Graceful degradation for file access issues
|
||||
|
||||
### Edit Mode Activation
|
||||
1. **User triggers edit mode**: Keyboard shortcut or menu
|
||||
2. **Request sudo**: Prompt for password if needed
|
||||
3. **Validate permissions**: Ensure write access to `/etc/hosts`
|
||||
4. **Update UI state**: Enable edit operations
|
||||
5. **Maintain permissions**: Keep sudo active until exit
|
||||
### Entry Navigation (✅ Implemented)
|
||||
1. ✅ **Keyboard navigation**: Up/down arrows navigate entries
|
||||
2. ✅ **Selection tracking**: Reactive updates to selected_entry_index
|
||||
3. ✅ **Detail updates**: Automatic refresh of right pane details
|
||||
4. ✅ **Position restoration**: Maintains cursor position on reload
|
||||
5. ✅ **Visual feedback**: Clear indication of current selection
|
||||
|
||||
### Entry Modification
|
||||
1. **User action**: Toggle, reorder, or edit entry
|
||||
2. **Create command**: Instantiate appropriate command object
|
||||
3. **Validate operation**: Check if change is valid
|
||||
4. **Execute command**: Apply change to in-memory state
|
||||
5. **Update UI**: Refresh display to show changes
|
||||
6. **Track dirty state**: Mark file as needing save
|
||||
### File Operations (✅ Implemented)
|
||||
1. ✅ **File parsing**: Comprehensive hosts file format support
|
||||
2. ✅ **Comment preservation**: Maintains all comments and formatting
|
||||
3. ✅ **Error handling**: Graceful handling of permission and format errors
|
||||
4. ✅ **Validation**: Complete IP address and hostname validation
|
||||
5. ✅ **Status feedback**: Clear user feedback for all operations
|
||||
|
||||
### File Persistence
|
||||
1. **User saves**: Explicit save command or auto-save
|
||||
2. **Validate entire file**: Ensure no syntax errors
|
||||
3. **Create backup**: Optional backup of original file
|
||||
4. **Write atomically**: Use temporary file + rename
|
||||
5. **Verify write**: Confirm file was written correctly
|
||||
### Edit Mode Activation (🔄 Planned for Phase 3)
|
||||
1. 🔄 **User triggers edit mode**: Keyboard shortcut implementation
|
||||
2. 🔄 **Request sudo**: Secure password prompt
|
||||
3. 🔄 **Validate permissions**: Ensure write access to `/etc/hosts`
|
||||
4. 🔄 **Update UI state**: Enable edit operations and visual indicators
|
||||
5. 🔄 **Maintain permissions**: Keep sudo active until explicit exit
|
||||
|
||||
### DNS Resolution Flow
|
||||
1. **User requests resolution**: For entry with DNS name
|
||||
2. **Resolve hostname**: Use socket.gethostbyname()
|
||||
3. **Compare IPs**: Current IP vs resolved IP
|
||||
4. **Present choice**: Show user both options
|
||||
5. **Update entry**: Apply user's choice
|
||||
6. **Mark dirty**: Flag file for saving
|
||||
### Entry Modification (🔄 Planned for Phase 3-4)
|
||||
1. 🔄 **User action**: Toggle, reorder, or edit entry operations
|
||||
2. 🔄 **Create command**: Command pattern for undo/redo support
|
||||
3. 🔄 **Validate operation**: Real-time validation of changes
|
||||
4. 🔄 **Execute command**: Apply changes to in-memory state
|
||||
5. 🔄 **Update UI**: Immediate visual feedback
|
||||
6. 🔄 **Track dirty state**: Mark file as needing save
|
||||
|
||||
### File Persistence (🔄 Planned for Phase 3)
|
||||
1. 🔄 **User saves**: Explicit save command or auto-save option
|
||||
2. 🔄 **Validate entire file**: Comprehensive syntax checking
|
||||
3. 🔄 **Create backup**: Automatic backup before modifications
|
||||
4. 🔄 **Write atomically**: Safe temporary file + rename operation
|
||||
5. 🔄 **Verify write**: Confirm successful file write
|
||||
|
||||
### DNS Resolution Flow (🔄 Planned for Phase 5)
|
||||
1. 🔄 **User requests resolution**: For entries with DNS names
|
||||
2. 🔄 **Resolve hostname**: Async DNS resolution
|
||||
3. 🔄 **Compare IPs**: Current IP vs resolved IP comparison
|
||||
4. 🔄 **Present choice**: User dialog for IP selection
|
||||
5. 🔄 **Update entry**: Apply user's choice with validation
|
||||
6. 🔄 **Mark dirty**: Flag file for saving
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue