hale 0.1.22

Instant network connection quality monitor
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# hale

[![CI](https://github.com/adamatan/hale/actions/workflows/test_and_release.yml/badge.svg)](https://github.com/adamatan/hale/actions/workflows/test_and_release.yml)

**hale** is a lightweight, high-precision network connection quality monitor. It answers the critical question: *"Is my internet connection OK right now?"*

Unlike standard ping tools, **hale** uses concurrent TCP probing across six major global networks to provide an at-a-glance health assessment without requiring root/sudo privileges.

## Vision & Purpose

It's often difficult to tell if internet slowness is caused by your own connection, a specific website, or a wider outage. **hale** provides immediate clarity through:
*   **Immediate clarity**: Big, obvious status indicators (OK/Slow/Disconnected).
*   **Context-aware feedback**: Descriptive explanations when issues are detected.
*   **High-precision monitoring**: Optimized for detecting micro-dropouts and stability issues that standard tools miss.

## Key Features

*   **Dual Mode Operation**: 
    *   **TUI (Default)**: A rich, real-time dashboard with historical status bars and per-provider metrics.
    *   **CLI (`--check`)**: A one-shot diagnostic tool with proper exit codes for scripts and automation.
*   **Intelligent Analysis**:
    *   **Multi-Provider Probing**: Simultaneously monitors Google, AWS, Azure, Cloudflare, Quad9, and OpenDNS.
    *   **Majority Voting**: Uses a 4/6 threshold to filter out localized network noise or single-provider outages.
    *   **High Frequency**: 500ms update interval for immediate detection of micro-dropouts.
*   **Historical Visibility**:
    *   Per-provider status history bars.
    *   5-minute and 1-hour aggregate connection overviews.
    *   Automatic downtime tracking and duration calculation.
*   **Lean & Safe**:
    *   **Resource Efficient**: Memory footprint < 5MB, CPU usage < 1%.
    *   **Zero Configuration**: Works out of the box with sensible defaults.
    *   **Terminal Safety**: Implements panic hooks to ensure your terminal is always restored to its original state.

## Installation

Ensure you have the Rust toolchain installed, then:

```bash
# Build the release binary
cargo build --release

# The binary is now available at
./target/release/hale
```

## Usage

### Terminal User Interface (Interactive)
The default mode provides a full-screen dashboard for continuous monitoring.

```bash
hale
```
*   **Top Banner**: Real-time status, average latency, and uptime timer.
*   **Targets**: Live latency and status history for each of the 6 providers.
*   **Overview**: 5m and 1h sliding windows of your overall connection health.
*   **Exit**: Press `q`, `ESC`, or `Ctrl+C`.

### Command Line Interface (One-shot)
Ideal for quick checks or integration into other tools and scripts.

```bash
# Basic check
hale --check

# Verbose output with timestamps
hale --check --verbose

# Machine-readable JSON output
hale --check --format json
```

### Exit Codes
The CLI mode returns standard Unix exit codes:
*   `0`: Connection is **OK**.
*   `1`: Connection is **Slow** or **Disconnected**.

## Architecture & Tech Stack

### Technology Stack
*   **Language**: Rust (2021 Edition)
*   **Async Runtime**: `tokio` (v1) for concurrent non-blocking probing.
*   **TUI Framework**: `ratatui` with `crossterm` backend.
*   **CLI Parsing**: `clap` (v4) with derive macros.

### Module Structure
*   **Monitor**: Handles concurrent TCP (port 443) handshake probing.
*   **Analysis**: Aggregates raw data and applies majority voting for stability.
*   **UI**: Renders the interactive TUI and formatted CLI outputs.
*   **Utils**: Provides session logging with automatic downtime calculation.

### Monitoring Targets
Hale monitors the entry points of the world's most critical internet infrastructure:
1.  **Google**: `8.8.8.8`
2.  **AWS**: `s3.amazonaws.com`
3.  **Azure**: `portal.azure.com`
4.  **Cloudflare**: `1.1.1.1`
5.  **Quad9**: `9.9.9.9`
6.  **OpenDNS**: `208.67.222.222`

### Status Thresholds
*   **OK**: Latency < 100ms.
*   **Slow**: Latency 100-300ms.
*   **Disconnected**: Latency > 300ms or majority (4/6) timeout.

## Logging
Hale automatically creates a detailed session log at:
`/tmp/hale-{timestamp}.log`

This log records every status change and precisely calculates how long each network incident lasted.

## Testing
Hale includes a comprehensive suite of unit tests covering its analysis engine and probing logic.

```bash
cargo test
```

## Release Process

This project uses an automated release workflow powered by [release-plz](https://github.com/MarcoIeni/release-plz).

*   **Trigger**: Pushing to the `main` branch.
*   **Versioning**: Determined automatically based on [Conventional Commits](https://www.conventionalcommits.org/).
    *   `fix:` -> Patch bump.
    *   `feat:` -> Minor bump.
    *   `BREAKING CHANGE:` -> Major bump.
*   **Publishing**: Automatically publishes to [crates.io](https://crates.io/crates/hale) and creates a GitHub release/tag.

## License
This project is licensed under the MIT License - see the LICENSE file for details.