add host status checks and states + test/docs updates (#27)

Author: kylerisse

README.md

@@ -9,6 +9,7 @@
 ## Features
 
 - **Extensible Check System**: Modular check types (ping, with more planned) via a Registry/Factory pattern.
+- **Host Status Aggregation**: Each host has an aggregate status (`up`, `down`, `degraded`, `unknown`) computed from all its checks. A check must be alive and have reported within the last 5 minutes to count as healthy.
 - **Ping Monitoring**: Sends ICMP Echo Requests to check host availability.
 - **Latency Logging**: Uses RRD to store latency data over time.
 - **Graphs Generation**: Generates historical latency graphs (15 minutes, 4 hours, 8 hours, etc.) for each host.
@@ -101,6 +102,58 @@ Ensure the following are installed:
 - **Port** (`--port`): Port on which the API and front-end are served.
 - **Logging Level** (`--log-level`): Set the verbosity of logs (e.g., `debug`, `info`, `warn`, `error`, `fatal`, `panic`).
 
+## Host Status
+
+Each host has an aggregate status derived from all its enabled checks:
+
+| Status       | Color  | Meaning                                                      |
+| ------------ | ------ | ------------------------------------------------------------ |
+| **up**       | Green  | All checks are alive and reported within the last 5 minutes. |
+| **degraded** | Yellow | Some checks are healthy, others are down or stale.           |
+| **down**     | Red    | All checks are down (but at least one has reported before).  |
+| **unknown**  | Gray   | No checks configured, or no check has ever reported.         |
+
+A check result is considered **stale** if its last successful RRD update is older than 5 minutes. Stale checks are treated the same as down checks for the purpose of host status aggregation.
+
+## API
+
+### `GET /api`
+
+Returns JSON with the status of all hosts:
+
+```json
+{
+	"google": {
+		"address": "8.8.8.8",
+		"status": "up",
+		"checks": {
+			"ping": {
+				"alive": true,
+				"metrics": {
+					"latency_us": 12345
+				},
+				"lastupdate": 1700000000
+			}
+		}
+	},
+	"router": {
+		"status": "unknown",
+		"checks": {}
+	}
+}
+```
+
+The `status` field is one of `up`, `down`, `degraded`, or `unknown` (see [Host Status](#host-status) above).
+
+### `GET /metrics`
+
+Exposes Prometheus-formatted metrics:
+
+```
+check_alive{host="google", address="8.8.8.8", check="ping"} 1
+check_metric{host="google", address="8.8.8.8", check="ping", metric="latency_us"} 12345
+```
+
 ## Data Directory Layout
 
 RRD files and graph images are organized into per-host subdirectories:

pkg/rrd/helpers.go

@@ -1,8 +1,12 @@
 package rrd
 
+// Standard colors for RRD graph elements.
 const RED = "FF0000"
 const GREEN = "00FF00"
 
+// expandTimeLength converts a short time duration code (e.g. "15m", "1h", "4d")
+// into a human-readable string for use in graph titles and comments.
+// Returns the input unchanged if it does not match a known code.
 func expandTimeLength(timeLength string) string {
 	switch timeLength {
 	case "15m":