diff --git a/PRD.md b/PRD.md index 5e790b5..dcaace9 100644 --- a/PRD.md +++ b/PRD.md @@ -172,9 +172,38 @@ - What if config file is malformed? - No documented recovery procedures + ## Resolution Tracking + + | Issue | Section | Priority | Status | Addressed By | + |-------|---------|----------|--------|-------------| + | Notification blocking monitoring | 1 | Critical | Open | Feature 007 (pending) | + | Process timeout | 1 | Critical | **Resolved** | Feature 016 | + | Missing retry logic (TCP/HTTP) | 1 | Medium | Open | — | + | Threshold config conflicts | 2 | Medium | Open | Needs config validation | + | Race condition in periodic traceroute | 2 | High | Open | Needs audit in Feature 010 code | + | Flapping detection | 2 | Medium | Open | — | + | No transaction management | 3 | High | Open | — | + | Unbounded traceroute storage | 3 | Medium | Partial | Config exists, enforcement needs audit | + | Database lock contention | 3 | Medium | Open | — | + | Missing config validation | 4 | Medium | Open | — | + | Gateway auto-detection fallback | 4 | Low | Open | — | + | ICMP vs TCP method mismatch | 5 | Medium | Open | — | + | HTTP latency thresholds | 5 | Medium | Open | Feature 009 (pending) | + | No rate limiting on concurrency | 6 | Medium | Open | — | + | Log rotation timing | 6 | Low | Partial | Feature 006 (daily rotation) | + | Memory leak in quality metrics | 6 | Low | N/A | Feature 008 not implemented | + | macOS command parsing fragility | 7 | Medium | Open | — | + | launchd service race condition | 7 | Low | Open | Feature 006 | + | Command injection risk | 8 | **Highest** | Open | Needs audit of ping/traceroute shell-out | + | openssl shell-out for certs | 8 | Medium | N/A | Feature 009 not implemented | + | No rollback strategy | 9 | Low | Open | — | + | Backup without verification | 9 | Low | Open | Feature 011 | + | Error code standards | 10 | Low | Open | — | + | Disaster recovery docs | 10 | Low | Open | — | + ## Summary of Critical Issues - 1. Highest Priority: Command injection vulnerability needs immediate audit + 1. **Highest Priority**: Command injection vulnerability needs immediate audit 2. High Priority: Database transaction safety, state machine race conditions 3. Medium Priority: Configuration validation, retry logic, method-specific thresholds 4. Low Priority: Documentation gaps, error codes, rollback strategy diff --git a/TEST.md b/TEST.md index 9dab6e0..dc44088 100644 --- a/TEST.md +++ b/TEST.md @@ -1,6 +1,31 @@ -# Manual Testing Guide +# Testing Guide -This guide covers manual testing for Feature 010 (Enhanced Culprit Tracking). +## Overview + +This guide covers automated and manual testing for Vigil. + +### Automated Tests + +```bash +cargo test # Run all unit and integration tests +cargo test -- --nocapture # Run with stdout visible +./scripts/qa.sh # Full QA: fmt, clippy, test, doc, build +VIGIL_ENV=test cargo test # Run with isolated test database +``` + +### Test Environments + +| Environment | Database Path | Usage | +|-------------|--------------|-------| +| Production | `~/Library/Application Support/ch.kapptec.vigil/monitor.db` | Live monitoring | +| Development | `.../ch.kapptec.vigil/dev/monitor.db` | `--dev` flag or `VIGIL_ENV=dev` | +| Test | `.../ch.kapptec.vigil/test/monitor.db` | `VIGIL_ENV=test` | + +--- + +## Manual Testing: Feature 010 (Enhanced Culprit Tracking) + +This section covers manual testing for Feature 010. ## 1. Setup Development Environment diff --git a/claude.md b/claude.md index 1091006..0f5ab38 100644 --- a/claude.md +++ b/claude.md @@ -20,9 +20,12 @@ This file provides context for Claude Code sessions working on this project. | 004 Hop Analysis | Done | `src/monitor/traceroute.rs` | | 005 CLI Reporting | Done | `src/cli/helpers.rs`, `status.rs`, `outages.rs`, `stats.rs` | | 006 Polish & Service | Done | `src/cli/service.rs`, log rotation in `lib.rs` | -| 009 HTTP Endpoint Monitoring | Pending | Timing breakdown, cert tracking, `vigil http`/`vigil certs` commands | +| 007 Alerts & Notifications | Pending | Desktop, webhook, command notifications | +| 008 Latency Quality Metrics | Pending | Jitter, packet loss, MOS score | +| 009 HTTP Endpoint Monitoring | Partial | Basic HTTP in 014; remaining: timing breakdown, cert tracking, `vigil http`/`vigil certs` | | 010 Enhanced Culprit Tracking | Done | `src/db.rs` (migrate_v2), `src/monitor/state.rs`, `src/cli/outage_detail.rs` | | 011 Dev Environment | Done | `config.rs` (Environment), `main.rs` (--dev flag) | +| 012 CI Pipeline Fix | Done | `.github/workflows/ci.yml` | | 013 Gateway-First Diagnosis | Done | `src/monitor/traceroute.rs`, `main.rs`, `cli/outage_detail.rs` | | 014 TCP/HTTP Connectivity | Done | `src/monitor/tcp.rs`, `src/monitor/http.rs`, `models.rs` | | 015 Version Information | Done | `build.rs`, `src/lib.rs`, `src/cli/version.rs` | @@ -87,9 +90,10 @@ route -n get default | grep gateway ## Testing ```bash -cargo test # Run all tests -cargo run -- init # Initialize config/db -cargo run -- start # Start monitoring (placeholder until 002) +cargo test # Run all tests +cargo run -- --dev init # Initialize dev config/db +cargo run -- --dev start -f # Start monitoring (dev mode, foreground) +./scripts/qa.sh # Full QA: fmt, clippy, test, doc, build ``` ## Dependencies @@ -108,12 +112,16 @@ Display: - `tabled` - Table formatting - `indicatif` - Progress bars -## Database Schema +## Database Schema (v3) ```sql outages(id, start_time, end_time, duration_secs, affected_targets, failing_hop, failing_hop_ip, notes) ping_log(id, timestamp, target, target_name, latency_ms, success) -traceroutes(id, outage_id, timestamp, target, hops, success) +traceroutes(id, outage_id, degraded_event_id, trace_trigger, gateway_reachable, + gateway_latency_ms, diagnosis, timestamp, target, hops, success) +degraded_events(id, start_time, end_time, duration_secs, escalated_to_outage_id, + affected_targets, notes) +schema_version(version, applied_at, description) ``` ## Installation diff --git a/docs/README.md b/docs/README.md index bca7024..b2cc796 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,8 +19,18 @@ Implementation is organized into sequentially numbered features: | [002](./features/002-ping-monitor.md) | Ping Monitor | Done | Continuous multi-target ping monitoring | | [003](./features/003-outage-detection.md) | Outage Detection | Done | State machine for connectivity tracking | | [004](./features/004-hop-analysis.md) | Hop Analysis | Done | Traceroute integration for fault isolation | -| [005](./features/005-cli-reporting.md) | CLI & Reporting | Pending | Status display, outage history, statistics | -| [006](./features/006-polish-service.md) | Polish & Service | Pending | Launchd, graceful shutdown, log rotation | +| [005](./features/005-cli-reporting.md) | CLI & Reporting | Done | Status display, outage history, statistics | +| [006](./features/006-polish-service.md) | Polish & Service | Done | Launchd, graceful shutdown, log rotation | +| [007](./features/007-alerts-notifications.md) | Alerts & Notifications | Pending | Desktop, webhook, command notifications | +| [008](./features/008-latency-quality-metrics.md) | Latency Quality Metrics | Pending | Jitter, packet loss, MOS score | +| [009](./features/009-http-endpoint-monitoring.md) | HTTP Endpoint Monitoring | Pending | Timing breakdown, cert tracking, HTTP CLI | +| [010](./features/010-enhanced-culprit-tracking.md) | Enhanced Culprit Tracking | Done | Periodic traceroutes, degraded events | +| [011](./features/011-dev-environment-upgrade-strategy.md) | Dev Environment & Upgrades | Done | Environment isolation, DB migrations | +| [012](./features/012-ci-pipeline-fix.md) | CI Pipeline Fix | Done | GitHub Actions fix and simplification | +| [013](./features/013-gateway-first-diagnosis.md) | Gateway-First Diagnosis | Done | Gateway ping before traceroute | +| [014](./features/014-tcp-connectivity-monitoring.md) | TCP/HTTP Connectivity | Done | TCP and HTTP monitoring methods | +| [015](./features/015-version-info.md) | Version Information | Done | Build info, schema status, JSON output | +| [016](./features/016-process-timeout.md) | Process Timeout | Done | Subprocess hard timeout, slow ping detection | ## Quick Start @@ -29,13 +39,16 @@ Implementation is organized into sequentially numbered features: vigil init # Start monitoring -vigil start +vigil start --foreground # Check status vigil status # View recent outages -vigil outages --last 24h +vigil outages -l 24h + +# View version and build info +vigil version ``` ## Problem Statement diff --git a/docs/architecture.md b/docs/architecture.md index 625a379..b474142 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -3,21 +3,27 @@ ## System Overview ``` -┌─────────────────────────────────────────────────────────────────┐ -│ Network Monitor │ -├─────────────────────────────────────────────────────────────────┤ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ -│ │ Ping Monitor │ │ Hop Analyzer │ │ Outage Detector │ │ -│ │ (continuous) │ │ (on-demand) │ │ (state machine) │ │ -│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │ -│ │ │ │ │ -│ └─────────────────┼──────────────────────┘ │ -│ ▼ │ -│ ┌───────────────┐ │ -│ │ Event Logger │ │ -│ │ (SQLite) │ │ -│ └───────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────┐ +│ Vigil Network Monitor │ +├──────────────────────────────────────────────────────────────────┤ +│ ┌───────────────────────┐ ┌──────────────────────────────────┐ │ +│ │ Connectivity Checker │ │ Outage Detector (state machine) │ │ +│ │ ┌───────┐ ┌─────┐ │ │ ONLINE → DEGRADED → OFFLINE │ │ +│ │ │ Ping │ │ TCP │ │ └──────────────┬───────────────────┘ │ +│ │ └───────┘ └─────┘ │ │ │ +│ │ ┌───────┐ │ ▼ │ +│ │ │ HTTP │ │ ┌──────────────────────────────────┐ │ +│ │ └───────┘ │ │ Hop Analyzer (gateway-first) │ │ +│ └───────────┬───────────┘ │ gateway ping → traceroute │ │ +│ │ └──────────────┬───────────────────┘ │ +│ └──────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────┐ │ +│ │ Event Logger │ │ +│ │ (SQLite v3) │ │ +│ └───────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ ``` ## Network Topology @@ -33,18 +39,26 @@ By monitoring multiple targets and running traceroute during outages, we can ide ## Components -### 1. Ping Monitor (`src/monitor/ping.rs`) +### 1. Connectivity Checker (`src/monitor/`) -- Continuously pings multiple targets at configurable intervals -- Uses macOS `ping` command via shell-out -- Parses output for latency and success/failure +Unified dispatcher (`mod.rs`) routes checks to the appropriate method: + +| Method | File | Protocol | Use Case | +|--------|------|----------|----------| +| Ping | `ping.rs` | ICMP | Traditional, may be rate-limited | +| TCP | `tcp.rs` | TCP SYN | Default — accurate for real-world connectivity | +| HTTP | `http.rs` | HTTP HEAD | Full HTTP check with response validation | + +- Continuously checks multiple targets at configurable intervals (default 2s) +- Hard process timeout (default 6s) kills hung subprocesses +- Adaptive polling: 4x faster during DEGRADED state (500ms) - Runs concurrently using tokio tasks **Targets monitored:** - Local gateway (auto-detected or configured) -- External DNS servers (8.8.8.8, 1.1.1.1) -- Custom targets (user-configured) +- External DNS servers (8.8.8.8, 1.1.1.1) via TCP:443 by default +- Custom targets (user-configured, any method) ### 2. State Machine (`src/monitor/state.rs`) @@ -68,42 +82,55 @@ Tracks connectivity state with hysteresis to avoid flapping: **Thresholds (configurable):** -- `degraded_threshold`: 3 consecutive failures → DEGRADED -- `offline_threshold`: 5 consecutive failures → OFFLINE -- `recovery_threshold`: 2 consecutive successes → ONLINE +- `degraded_threshold`: 2 consecutive failures → DEGRADED +- `offline_threshold`: 3 consecutive failures → OFFLINE +- `recovery_threshold`: 3 consecutive successes → ONLINE ### 3. Hop Analyzer (`src/monitor/traceroute.rs`) -- Triggered when entering OFFLINE state +- Gateway-first diagnosis: pings gateway before running traceroute +- Triggered when entering DEGRADED or OFFLINE state +- Periodic traceroutes during ongoing outages (configurable interval) - Runs macOS `traceroute` command - Parses output to identify failing hop -- Stores results linked to outage events +- Stores results linked to outage or degraded events +- Diagnosis output: `LocalNetworkDown`, `IspIssue`, `Healthy`, `Intermittent`, `Unknown` ### 4. Database (`src/db.rs`) -SQLite database with three tables: +SQLite database (schema v3) with five tables: -**outages** - Outage events +**outages** - Outage events (OFFLINE state) -```sql -- id, start_time, end_time, duration_secs -- affected_targets (JSON array) -- failing_hop, failing_hop_ip -- notes +``` +id, start_time, end_time, duration_secs, affected_targets (JSON), +failing_hop, failing_hop_ip, notes +``` + +**degraded_events** - Degraded state transitions (pre-outage) + +``` +id, start_time, end_time, duration_secs, escalated_to_outage_id, +affected_targets (JSON), notes ``` **ping_log** - Individual ping results (sampled) -```sql -- id, timestamp, target, target_name -- latency_ms, success +``` +id, timestamp, target, target_name, latency_ms, success ``` -**traceroutes** - Traceroute snapshots +**traceroutes** - Traceroute snapshots linked to outages or degraded events -```sql -- id, outage_id, timestamp, target -- hops (JSON array), success +``` +id, outage_id, degraded_event_id, trace_trigger, gateway_reachable, +gateway_latency_ms, diagnosis, timestamp, target, hops (JSON), success +``` + +**schema_version** - Migration tracking + +``` +version, applied_at, description ``` ### 5. Configuration (`src/config.rs`) @@ -122,26 +149,33 @@ Supports: ## Data Flow ``` -1. Ping Monitor sends pings every 1 second +1. Connectivity Checker runs checks every 2 seconds (ping/TCP/HTTP) │ ▼ 2. Results fed to State Machine │ ├── State unchanged → Log ping result │ - ├── State → OFFLINE + ├── State → DEGRADED │ │ │ ▼ - │ Trigger Hop Analyzer + │ Create DegradedEvent + run gateway-first diagnosis + │ + ├── State → OFFLINE (from DEGRADED) + │ │ + │ ▼ + │ Create Outage record + run diagnosis + │ Periodic traceroutes every N seconds + │ + ├── State → ONLINE (from DEGRADED) │ │ │ ▼ - │ Create Outage record + │ End DegradedEvent (no outage created) │ └── State → ONLINE (from OFFLINE) │ ▼ - End Outage record - (set end_time, duration) + End Outage record (set end_time, duration) ``` ## File Structure @@ -149,21 +183,27 @@ Supports: ``` src/ ├── main.rs # CLI entry point (clap) -├── lib.rs # Library root, logging init -├── config.rs # Configuration management -├── db.rs # SQLite operations -├── models.rs # Data structures +├── lib.rs # Library root, logging init, version constants +├── config.rs # Configuration management, environment support +├── db.rs # SQLite operations, migrations (v1→v3) +├── models.rs # Data structures (Target, Outage, PingResult, etc.) ├── monitor/ -│ ├── mod.rs -│ ├── ping.rs # Ping implementation -│ ├── state.rs # State machine -│ └── traceroute.rs # Traceroute implementation +│ ├── mod.rs # Unified connectivity dispatcher +│ ├── ping.rs # ICMP ping with process timeout +│ ├── tcp.rs # TCP connectivity checks +│ ├── http.rs # HTTP endpoint checks +│ ├── state.rs # State machine (ONLINE/DEGRADED/OFFLINE) +│ └── traceroute.rs # Traceroute + gateway-first diagnosis └── cli/ ├── mod.rs - ├── start.rs # Start command - ├── status.rs # Status command - ├── outages.rs # Outages command - └── stats.rs # Stats command + ├── start.rs # Start monitor daemon + ├── status.rs # Current status display + ├── outages.rs # List outages + ├── outage_detail.rs # Detailed outage view with traceroutes + ├── stats.rs # Statistics reporting + ├── service.rs # macOS launchd service management + ├── version.rs # Version and build info + └── helpers.rs # Shared CLI utilities ``` ## macOS Integration diff --git a/docs/features/001-core-infrastructure.md b/docs/features/001-core-infrastructure.md index d195e40..fcfa292 100644 --- a/docs/features/001-core-infrastructure.md +++ b/docs/features/001-core-infrastructure.md @@ -21,40 +21,52 @@ Foundation layer providing configuration management, database operations, loggin ``` Cargo.toml +build.rs # Git hash, build timestamp +scripts/qa.sh # Pre-push QA checks src/ -├── main.rs # CLI entry point -├── lib.rs # Library root + init_logging() -├── config.rs # Config struct + load/save -├── db.rs # Database struct + CRUD operations -├── models.rs # Outage, PingResult, TracerouteHop, etc. +├── main.rs # CLI entry point +├── lib.rs # Library root + init_logging() +├── config.rs # Config struct + load/save +├── db.rs # Database struct + CRUD + migrations +├── models.rs # Outage, PingResult, Target, etc. ├── monitor/ -│ ├── mod.rs # Module declarations -│ ├── ping.rs # Placeholder -│ ├── state.rs # Placeholder -│ └── traceroute.rs # Placeholder +│ ├── mod.rs # Unified connectivity dispatcher +│ ├── ping.rs # ICMP ping via shell-out +│ ├── state.rs # State machine (ONLINE/DEGRADED/OFFLINE) +│ ├── traceroute.rs # Traceroute + gateway-first diagnosis +│ ├── tcp.rs # TCP connectivity checks +│ └── http.rs # HTTP endpoint checks └── cli/ - ├── mod.rs # Module declarations - ├── start.rs # Placeholder - ├── status.rs # Placeholder - ├── outages.rs # Placeholder - └── stats.rs # Placeholder + ├── mod.rs # Module declarations + ├── start.rs # Start monitor daemon + ├── status.rs # Current status display + ├── outages.rs # List outages + ├── outage_detail.rs # Detailed outage view with traceroutes + ├── stats.rs # Statistics reporting + ├── service.rs # macOS launchd service management + ├── version.rs # Version and build info + └── helpers.rs # Shared CLI utilities ``` ## Configuration Schema ```toml [monitor] -ping_interval_ms = 1000 +ping_interval_ms = 2000 ping_timeout_ms = 2000 -degraded_threshold = 3 -offline_threshold = 5 -recovery_threshold = 2 +degraded_threshold = 2 +offline_threshold = 3 +recovery_threshold = 3 +traceroute_interval_secs = 60 +max_traceroutes_per_outage = 10 +ping_process_timeout_ms = 6000 +degraded_ping_interval_ms = 500 [targets] gateway = "192.168.1.1" # Optional, auto-detected targets = [ - { name = "Google DNS", ip = "8.8.8.8" }, - { name = "Cloudflare", ip = "1.1.1.1" }, + { name = "Google DNS", ip = "8.8.8.8", method = "tcp", port = 443 }, + { name = "Cloudflare", ip = "1.1.1.1", method = "tcp", port = 443 }, ] [database] @@ -66,7 +78,7 @@ level = "info" file = "..." # Optional ``` -## Database Schema +## Database Schema (v3) ```sql CREATE TABLE outages ( @@ -92,11 +104,32 @@ CREATE TABLE ping_log ( CREATE TABLE traceroutes ( id INTEGER PRIMARY KEY, outage_id INTEGER REFERENCES outages(id), + degraded_event_id INTEGER REFERENCES degraded_events(id), + trace_trigger TEXT DEFAULT 'state_change', + gateway_reachable INTEGER, + gateway_latency_ms REAL, + diagnosis TEXT, timestamp TEXT NOT NULL, target TEXT NOT NULL, hops TEXT NOT NULL, -- JSON array success INTEGER NOT NULL ); + +CREATE TABLE degraded_events ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + start_time TEXT NOT NULL, + end_time TEXT, + duration_secs REAL, + escalated_to_outage_id INTEGER, + affected_targets TEXT NOT NULL, + notes TEXT +); + +CREATE TABLE schema_version ( + version INTEGER PRIMARY KEY, + applied_at TEXT NOT NULL, + description TEXT +); ``` ## CLI Commands (Skeleton) diff --git a/docs/features/002-ping-monitor.md b/docs/features/002-ping-monitor.md index 8f59748..4959168 100644 --- a/docs/features/002-ping-monitor.md +++ b/docs/features/002-ping-monitor.md @@ -90,13 +90,13 @@ Use `tokio::spawn` for each target, collect results via `mpsc` channel. ## Tasks -- [ ] Implement `ping()` function with shell-out -- [ ] Parse ping output (regex or string parsing) -- [ ] Implement `PingMonitor` struct -- [ ] Add concurrent pinging with tokio -- [ ] Create result channel/stream -- [ ] Add unit tests with mock responses -- [ ] Integration test with real ping +- [x] Implement `ping()` function with shell-out +- [x] Parse ping output (regex or string parsing) +- [x] Implement `PingMonitor` struct +- [x] Add concurrent pinging with tokio +- [x] Create result channel/stream +- [x] Add unit tests with mock responses +- [x] Integration test with real ping ## Test Plan diff --git a/docs/features/003-outage-detection.md b/docs/features/003-outage-detection.md index 12b6c8f..37e33e6 100644 --- a/docs/features/003-outage-detection.md +++ b/docs/features/003-outage-detection.md @@ -143,13 +143,13 @@ fn process(&mut self, result: PingResult) -> StateEvent { ## Tasks -- [ ] Define `ConnectivityTracker` struct -- [ ] Implement per-target state tracking -- [ ] Implement state transition logic -- [ ] Implement `StateEvent` enum -- [ ] Integrate with outage creation/completion -- [ ] Add unit tests for all state transitions -- [ ] Test edge cases (rapid flapping, partial failures) +- [x] Define `ConnectivityTracker` struct +- [x] Implement per-target state tracking +- [x] Implement state transition logic +- [x] Implement `StateEvent` enum +- [x] Integrate with outage creation/completion +- [x] Add unit tests for all state transitions +- [x] Test edge cases (rapid flapping, partial failures) ## Test Plan diff --git a/docs/features/004-hop-analysis.md b/docs/features/004-hop-analysis.md index c8daa6a..c357846 100644 --- a/docs/features/004-hop-analysis.md +++ b/docs/features/004-hop-analysis.md @@ -104,14 +104,14 @@ Result: Failing hop = 2 (10.0.0.1), meaning hop 3 is unreachable. ## Tasks -- [ ] Implement `trace()` function with shell-out -- [ ] Parse traceroute output line by line -- [ ] Handle various output formats -- [ ] Implement `identify_failing_hop()` -- [ ] Integrate with outage detection (Feature 003) -- [ ] Implement `vigil trace` CLI command -- [ ] Store traceroute results in database -- [ ] Add unit tests with sample outputs +- [x] Implement `trace()` function with shell-out +- [x] Parse traceroute output line by line +- [x] Handle various output formats +- [x] Implement `identify_failing_hop()` +- [x] Integrate with outage detection (Feature 003) +- [x] Implement `vigil trace` CLI command +- [x] Store traceroute results in database +- [x] Add unit tests with sample outputs ## Test Plan diff --git a/docs/features/005-cli-reporting.md b/docs/features/005-cli-reporting.md index 4d29555..b414b4b 100644 --- a/docs/features/005-cli-reporting.md +++ b/docs/features/005-cli-reporting.md @@ -1,6 +1,6 @@ # 005 - CLI & Reporting -**Status:** Pending +**Status:** Done ## Overview @@ -148,12 +148,12 @@ pub fn run(app: &App, period: &str) -> Result<()> { ## Tasks -- [ ] Implement `parse_duration()` for "24h", "7d" format -- [ ] Implement status command -- [ ] Implement outages command with table formatting -- [ ] Implement stats command with visualizations -- [ ] Add color coding (green/yellow/red for states) -- [ ] Handle empty results gracefully +- [x] Implement `parse_duration()` for "24h", "7d" format +- [x] Implement status command +- [x] Implement outages command with table formatting +- [x] Implement stats command with visualizations +- [x] Add color coding (green/yellow/red for states) +- [x] Handle empty results gracefully - [ ] Add export functionality (CSV/JSON) ## Duration Parsing diff --git a/docs/features/006-polish-service.md b/docs/features/006-polish-service.md index 4089989..23005af 100644 --- a/docs/features/006-polish-service.md +++ b/docs/features/006-polish-service.md @@ -1,6 +1,6 @@ # 006 - Polish & Service -**Status:** Pending +**Status:** Done ## Overview @@ -238,13 +238,13 @@ struct PingAggregator { ## Tasks -- [ ] Implement service install/uninstall commands -- [ ] Generate launchd plist dynamically -- [ ] Add graceful shutdown with signal handling -- [ ] Implement log rotation -- [ ] Add periodic database cleanup -- [ ] Implement ping aggregation for storage efficiency -- [ ] Profile memory usage in long-running tests +- [x] Implement service install/uninstall commands +- [x] Generate launchd plist dynamically +- [x] Add graceful shutdown with signal handling +- [x] Implement log rotation +- [x] Add periodic database cleanup +- [x] Implement ping aggregation for storage efficiency +- [x] Profile memory usage in long-running tests - [ ] Add health check endpoint (optional) ## Test Plan diff --git a/docs/features/009-http-endpoint-monitoring.md b/docs/features/009-http-endpoint-monitoring.md index 5b83cad..1ff00c2 100644 --- a/docs/features/009-http-endpoint-monitoring.md +++ b/docs/features/009-http-endpoint-monitoring.md @@ -1,6 +1,6 @@ # 009 - HTTP Endpoint Monitoring -**Status:** Pending (basic HTTP connectivity implemented in Feature 014) +**Status:** Partial — Basic HTTP/TCP connectivity implemented in [Feature 014](./014-tcp-connectivity-monitoring.md). Remaining: timing breakdown, certificate tracking, `vigil http` and `vigil certs` CLI commands. ## Overview diff --git a/docs/features/010-enhanced-culprit-tracking.md b/docs/features/010-enhanced-culprit-tracking.md index dc3d992..8e47abf 100644 --- a/docs/features/010-enhanced-culprit-tracking.md +++ b/docs/features/010-enhanced-culprit-tracking.md @@ -295,21 +295,21 @@ pub struct TracerouteWithMeta { ## Tasks -- [ ] Add `degraded_events` table to schema -- [ ] Add columns to `traceroutes` table (`degraded_event_id`, `trace_trigger`) -- [ ] Write database migration for existing installations -- [ ] Implement `DegradedEvent` model and DB methods -- [ ] Update `StateEvent::Degraded` to include event ID -- [ ] Add `DegradedRecovered` state event -- [ ] Implement traceroute on DEGRADED state entry -- [ ] Implement periodic traceroutes during OFFLINE -- [ ] Add configuration options (`traceroute_interval`, `max_traceroutes_per_outage`) -- [ ] Update `outages` command to show full IP (no truncation) -- [ ] Add `outage ` subcommand for detailed view -- [ ] Format traceroute output with hop interpretation -- [ ] Add unit tests for new state transitions -- [ ] Add integration tests for periodic traceroutes -- [ ] Update documentation +- [x] Add `degraded_events` table to schema +- [x] Add columns to `traceroutes` table (`degraded_event_id`, `trace_trigger`) +- [x] Write database migration for existing installations +- [x] Implement `DegradedEvent` model and DB methods +- [x] Update `StateEvent::Degraded` to include event ID +- [x] Add `DegradedRecovered` state event +- [x] Implement traceroute on DEGRADED state entry +- [x] Implement periodic traceroutes during OFFLINE +- [x] Add configuration options (`traceroute_interval`, `max_traceroutes_per_outage`) +- [x] Update `outages` command to show full IP (no truncation) +- [x] Add `outage ` subcommand for detailed view +- [x] Format traceroute output with hop interpretation +- [x] Add unit tests for new state transitions +- [x] Add integration tests for periodic traceroutes +- [x] Update documentation ## Test Plan diff --git a/docs/features/012-ci-pipeline-fix.md b/docs/features/012-ci-pipeline-fix.md index cbcf9d9..b88b681 100644 --- a/docs/features/012-ci-pipeline-fix.md +++ b/docs/features/012-ci-pipeline-fix.md @@ -1,5 +1,7 @@ # Feature 012: CI Pipeline Fix +**Status:** Done + ## Problem Statement The current GitHub Actions CI pipeline has issues: @@ -181,11 +183,11 @@ Consider adding a separate release workflow that: ## Checklist -- [ ] Fix `dtolnay/rust-action` → `dtolnay/rust-toolchain` -- [ ] Remove Windows from matrix -- [ ] Replace manual cache with `Swatinem/rust-cache@v2` -- [ ] Combine lint jobs into single `check` job -- [ ] Remove or keep MSRV check (decide) -- [ ] Add job dependencies (`needs:`) -- [ ] Verify CI passes on PR -- [ ] Verify CI runtime is acceptable +- [x] Fix `dtolnay/rust-action` → `dtolnay/rust-toolchain` +- [x] Remove Windows from matrix +- [x] Replace manual cache with `Swatinem/rust-cache@v2` +- [x] Combine lint jobs into single `check` job +- [x] Remove MSRV check (not publishing to crates.io) +- [x] Add job dependencies (`needs:`) +- [x] Verify CI passes on PR +- [x] Verify CI runtime is acceptable diff --git a/docs/features/013-gateway-first-diagnosis.md b/docs/features/013-gateway-first-diagnosis.md index 44dd7eb..51779d6 100644 --- a/docs/features/013-gateway-first-diagnosis.md +++ b/docs/features/013-gateway-first-diagnosis.md @@ -278,14 +278,14 @@ ALTER TABLE traceroutes ADD COLUMN diagnosis TEXT; ## Tasks -- [ ] Add `NetworkDiagnostic` and `DiagnosisResult` to models.rs -- [ ] Add `diagnose()` method to HopAnalyzer -- [ ] Add `ping_host()` helper method -- [ ] Update monitor loop to use `diagnose()` instead of `trace()` -- [ ] Update database schema (migration v3) -- [ ] Update outage detail CLI to show diagnosis -- [ ] Update console output during monitoring -- [ ] Add tests for diagnosis logic +- [x] Add `NetworkDiagnostic` and `DiagnosisResult` to models.rs +- [x] Add `diagnose()` method to HopAnalyzer +- [x] Add `ping_host()` helper method +- [x] Update monitor loop to use `diagnose()` instead of `trace()` +- [x] Update database schema (migration v3) +- [x] Update outage detail CLI to show diagnosis +- [x] Update console output during monitoring +- [x] Add tests for diagnosis logic ## Test Plan diff --git a/docs/features/015-version-info.md b/docs/features/015-version-info.md index 0041410..a9dc585 100644 --- a/docs/features/015-version-info.md +++ b/docs/features/015-version-info.md @@ -340,16 +340,16 @@ Paths (development environment): ## Tasks -- [ ] Create `build.rs` with git hash and build time -- [ ] Add build dependencies to Cargo.toml -- [ ] Update lib.rs with GIT_HASH, BUILD_TIME constants -- [ ] Update DB_SCHEMA_VERSION to 3 -- [ ] Add `Version` command to CLI -- [ ] Create `src/cli/version.rs` module -- [ ] Add JSON output support -- [ ] Update `--version` flag to include git hash -- [ ] Add tests for version info -- [ ] Update documentation +- [x] Create `build.rs` with git hash and build time +- [x] Add build dependencies to Cargo.toml +- [x] Update lib.rs with GIT_HASH, BUILD_TIME constants +- [x] Update DB_SCHEMA_VERSION to 3 +- [x] Add `Version` command to CLI +- [x] Create `src/cli/version.rs` module +- [x] Add JSON output support +- [x] Update `--version` flag to include git hash +- [x] Add tests for version info +- [x] Update documentation ## Best Practices Followed diff --git a/docs/usage.md b/docs/usage.md index a0b26cc..120c89f 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -46,32 +46,30 @@ Edit the TOML file directly: ```toml [monitor] -ping_interval_ms = 1000 # How often to ping (ms) -ping_timeout_ms = 2000 # Ping timeout (ms) -degraded_threshold = 3 # Failures before DEGRADED state -offline_threshold = 5 # Failures before OFFLINE state -recovery_threshold = 2 # Successes to recover +ping_interval_ms = 2000 # How often to check (ms) +ping_timeout_ms = 2000 # Ping/connection timeout (ms) +degraded_threshold = 2 # Failures before DEGRADED state +offline_threshold = 3 # Failures before OFFLINE state +recovery_threshold = 3 # Successes to recover +traceroute_interval_secs = 60 # Periodic traceroute during outage +max_traceroutes_per_outage = 10 # Limit traceroutes stored per outage +ping_process_timeout_ms = 6000 # Hard subprocess timeout +degraded_ping_interval_ms = 500 # Faster polling during DEGRADED [targets] -gateway = "192.168.1.1" # Your router IP (auto-detected if omitted) - -[[targets.targets]] -name = "Google DNS" -ip = "8.8.8.8" - -[[targets.targets]] -name = "Cloudflare" -ip = "1.1.1.1" - -[[targets.targets]] -name = "Quad9" # Add custom targets -ip = "9.9.9.9" +gateway = "192.168.1.1" # Your router IP (auto-detected if omitted) +targets = [ + { name = "Google DNS", ip = "8.8.8.8", method = "tcp", port = 443 }, + { name = "Cloudflare", ip = "1.1.1.1", method = "tcp", port = 443 }, + { name = "Quad9", ip = "9.9.9.9", method = "ping" }, +] +# method: "tcp" (default, recommended), "ping" (ICMP), or "http" [database] -retention_days = 90 # How long to keep data +retention_days = 90 # How long to keep data [logging] -level = "info" # trace, debug, info, warn, error +level = "info" # trace, debug, info, warn, error ``` ## Commands @@ -108,12 +106,19 @@ Shows: vigil outages # Last 7 days -vigil outages --last 7d +vigil outages -l 7d # Last 30 days vigil outages --last 30d ``` +### View Outage Details + +```bash +# Detailed view of a specific outage with traceroute history +vigil outage 42 +``` + ### View Statistics ```bash @@ -121,7 +126,7 @@ vigil outages --last 30d vigil stats # Last week -vigil stats --period 7d +vigil stats -p 7d ``` Shows: @@ -177,12 +182,33 @@ When an outage occurs, the tool runs traceroute to identify where packets are be - **Failing Hop**: Network hop where packets were dropped - **Affected Targets**: Which monitored targets were unreachable -## Running as a Service (macOS) +### Version & Build Info + +```bash +vigil version # Human-readable build and schema info +vigil version --json # Machine-readable JSON output +``` -To run automatically at login, create a launchd plist: +### Development Mode ```bash -# Create the plist (instructions in 006-polish-service.md) +vigil --dev start -f # Isolated dev database and config +vigil --dev status # Check dev environment status +VIGIL_ENV=dev cargo run -- start # Via environment variable +``` + +## Running as a Service (macOS) + +```bash +# Install as launchd service (runs at login) +vigil service install + +# Manage the service +vigil service status # Check if running +vigil service uninstall # Remove service + +# View service logs +vigil service logs ``` ## Troubleshooting @@ -223,5 +249,5 @@ Logs are written to: View with: ```bash -tail -f "~/Library/Application Support/ch.kapptec.vigil/monitor.log" +tail -f ~/Library/Application\ Support/ch.kapptec.vigil/monitor.log ``` diff --git a/instructions.md b/instructions.md index 9f15a97..9822200 100644 --- a/instructions.md +++ b/instructions.md @@ -1,21 +1,9 @@ -# My Vigil Network Monitor +# Project History -How this project started (raw and unedited): +## Genesis -Claude instructions: +Vigil was created to solve intermittent home fiber network outages (1-60 seconds, multiple times daily). The goal: continuous monitoring with traceroute-based hop analysis to identify the culprit (local router, ISP equipment, or ISP backbone). -/model - ⎿ Set model to opus (claude-opus-4-5-20251101) +## Implementation Timeline -> make a PLAN.md: I am in a home network, with wlan or eth connection, going out to www via a home fiber router. The connection drops more than once a day, for 1 to - 60 secs, then resumes. I need a tool that monitors the connection all day and logs the outages, and checks on the hops to find the culprit of the downtime. Use Rust - to implement, call Macos tools via shell-out if needed and follwow best practices. - -⏺ I'll create a comprehensive plan for your network monitoring tool. - -> add a ./doc directory. Inside, document all features, archtitecture and useage guides if needed. in the ./docs/features write down the plan with 001-feature-x named - files. add a claude.md for your own usage. - -Ready for Feature 003 (Outage Detection) - the state machine? - -> yes start feature 003, but before, add a db migrations.sql if needed +Features were implemented sequentially from 001 (Core Infrastructure) through 016 (Process Timeout). See `docs/README.md` for the full feature index and `PLAN.md` for the original design blueprint.