Phoneline

Command line tool that wraps the system ping, streams live latency metrics, logs long-running sessions, and offers an interactive TUI with colorized ASCII graphs and failure tracking.

Implementation Approach

Phoneline will be implemented as a Go CLI that wraps the system ping binary instead of issuing raw ICMP packets. The tool will:

• Invoke ping with platform-appropriate flags via os/exec and stream its output.
• Use kong for command-line parsing and configuration handling.
• Parse response lines to capture latency measurements and success/failure counts.
• Aggregate stats in-process (rolling averages, error rate, uptime) and present them in the CLI.
• Handle OS-specific differences in ping syntax/output, falling back to sane defaults when possible.
• Persist aggregated stats to a rotating on-disk file so the tool can run for extended periods.

This approach keeps the codebase small and avoids raw-socket privileges while still giving us live metrics with minimal complexity.

Getting Started

Prerequisites

• Go 1.24 or newer.
• Access to the system ping binary (/sbin/ping, /usr/bin/ping, etc.).
• Optional: golangci-lint if you want the lint target to perform extra checks.

Build

go build ./...
# or, using the Makefile
GOFLAGS="-mod=readonly" make build

The primary binary is produced at cmd/phoneline/phoneline when running go build ./....

Test

go test ./...
# or with the Makefile
make test

Run

Phoneline defaults to the run command, so you can omit it when just supplying a target.

go run ./cmd/phoneline --target example.com
# positional target
go run ./cmd/phoneline example.com
# quiet mode with 2s interval
go run ./cmd/phoneline -q -i 2s example.com
# append stats to a rolling log
go run ./cmd/phoneline --log-file ./logs/phoneline.log example.com
# serve the web dashboard on port 8080
go run ./cmd/phoneline --http-port 8080 example.com
# interactive TUI with ASCII graph
go run ./cmd/phoneline tui example.com

Once built, you can run the compiled binary directly:

./phoneline example.com
# equivalent explicit form
./phoneline run example.com
# with logging
./phoneline --log-file /var/log/phoneline.log --log-max 2097152 example.com
# with web dashboard
./phoneline --http-port 8080 example.com
# interactive TUI
./phoneline tui example.com

Use --help to see all flags (provided by kong).

Features & Acceptance Criteria

• Continuous ping execution

  • CLI accepts target host via --target or positional arg.
  • Starting the tool spawns system ping and streams results until interrupted.
  • Ctrl+C stops both Phoneline and the ping subprocess cleanly.

• Live latency reporting

  • Each successful ping updates displayed latency in milliseconds.
  • Display refreshes without piling up duplicate lines in the terminal.

• Aggregate statistics

  • Running totals for sent/received packets and failure rate update in real time.
  • Rolling average latency, min, and max appear alongside counts.

• Configurable output options

  • CLI flag to toggle quiet mode (latency only) or detailed stats.
  • CLI flag/select to set ping interval, passed through to ping command.
  • Invalid flag combinations produce helpful errors from kong.

• Cross-platform baseline

  • Works on macOS and Linux without requiring root.
  • Detects unsupported platforms (e.g. Windows) and exits with message.

• Observability & exit codes

  • Emits structured log-style lines when ping exits unexpectedly.
  • Phoneline exits non-zero if no successful pings were recorded during the session.

• Durable stats logging

  • CLI flag to specify an output file path for rolling stats snapshots.
  • Tool appends timestamped stats updates without truncating existing logs.
  • If the file is not writable, Phoneline reports an error and exits before starting the ping loop.

• Interactive TUI

  • Dedicated CLI subcommand renders a terminal UI with rolling stats and ASCII latency graph.
  • TUI uses bubbletea for interactive rendering if native terminal drawing becomes complex.
  • Graph updates without flicker and works in standard 80x24 terminals.
  • Users can press h to reveal the ASCII graph legend, showing the color gradient (cool → warm → bright green) and bright red x failure markers.
  • Press q to exit the TUI.

• Web dashboard (planned)

  • run command accepts --http-port to start an HTTP server alongside the CLI output.
  • Dashboard mirrors the TUI stats and latency graph using HTMX to stream incremental updates (SSE or periodic polling fallback).
  • Dashboard stays responsive without JavaScript frameworks; works in modern browsers.
  • Graceful shutdown ties dashboard lifecycle to the main process.