hale 0.1.27

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
133
134
135
136

# 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?"*

**hale** uses concurrent TCP probing across six major global networks (Google, AWS, Azure, Cloudflare, Quad9, OpenDNS) to provide an at-a-glance health assessment without requiring root/sudo privileges.

![hale TUI interface](docs/screenshot.png)

## Quick Start

### Installation

```bash
cargo install hale
```

### Basic Usage

**Interactive TUI (default):**
```bash
hale
```
Full-screen dashboard for continuous monitoring with real-time status, per-provider history, and 5m/1h connection overviews. Press `q`, `ESC`, or `Ctrl+C` to exit.

**CLI mode:**
```bash
# Quick check
hale --check

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

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

**Exit Codes:**
*   `0`: Connection is **OK**
*   `1`: Connection is **Slow** or **Disconnected**

## Key Features

*   **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

## How It Works

### 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

### 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

## 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.

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/adamatan/hale.git
cd hale

# Build the release binary
cargo build --release

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

### 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.