Crate gregg_protocol 

gregg-protocol defines the versioned JSON wire contract shared by the greggd daemon and the gregg client.

The crate is intentionally dependency-light (only serde, serde_json, and thiserror) so it can be consumed by collectors, the HTTP server, the polling engine, and tests without dragging in larger stacks.

Schema version 1

Every snapshot carries an explicit SCHEMA_VERSION_V1 so clients can reject incompatible payloads per host without terminating the whole TUI.

Numeric values are transported as raw units — bytes for memory and swap, percentages in the closed interval 0.0..=100.0 for utilization, and milliseconds since the Unix epoch for timestamps. No human-formatted strings cross the wire.

Compatibility policy

Within schema version 1:

• Unknown additive JSON fields are ignored by default.
• Required version-1 fields remain required unless explicitly changed to optional under an additive compatibility decision.
• Capability flags control interpretation of optional metrics. A None value paired with a false capability is expected; a None value paired with a true capability indicates a missing or still-warming sample.

Examples

use gregg_protocol::{StatusSnapshot, HealthResponse, ReadinessState, SCHEMA_VERSION_V1};

let json = format!(r#"{{
    "schema_version": {sv},
    "observed_at_unix_ms": 1,
    "sample_interval_ms": 1000,
    "capabilities": {{ "cpu_iowait": false }},
    "system": {{
        "name": "mac-mini",
        "hostname": "mac-mini.local",
        "os_name": "macos",
        "os_version": "15.0",
        "kernel_name": "Darwin",
        "kernel_release": "24.0.0",
        "architecture": "arm64"
    }},
    "cpu": {{ "logical_cores": 8, "usage_pct": 12.5, "iowait_pct": null }},
    "load": {{ "one": 1.1, "five": 0.9, "fifteen": 0.6 }},
    "memory": {{ "used_bytes": 1, "total_bytes": 2, "usage_pct": 50.0 }},
    "swap": {{ "used_bytes": 0, "total_bytes": 0, "usage_pct": 0.0 }}
}}"#, sv = SCHEMA_VERSION_V1);

let snap: StatusSnapshot = serde_json::from_str(&json).expect("valid snapshot");
snap.validate().expect("snapshot validates");

let health = HealthResponse::warming();
assert_eq!(health.state, ReadinessState::Warming);

Structs

CpuMetrics

CPU utilization snapshot.

HealthResponse

Health and readiness response served by the daemon.

LoadAverage

One-, five-, and fifteen-minute load averages as reported by the operating system.

MemoryMetrics

Physical memory utilization.

MetricCapabilities

Per-metric capability flags.

StatusSnapshot

Top-level daemon snapshot returned by the status endpoint.

SwapMetrics

Swap utilization.

SystemIdentity

Stable identity fields. Each field is transported separately so the TUI can degrade by width priority without parsing a combined string.

ValidationViolation

A single protocol-invariant violation.

Enums

HealthCategory

Machine-readable category for a non-ready health response.

ReadinessState

Coarse readiness state shared between the daemon and the client.

ViolationKind

The kind of a single protocol-invariant violation.

Constants

SCHEMA_VERSION_V1

Schema major version implemented by this crate.