Expand description
Wire contract for Géri, a self-declaring telemetry, command, and tamper-evident event log protocol.
This crate defines what travels on the wire and nothing else: no I/O, no
storage, no transport. It is #![no_std] (it needs only alloc), so the same
types compile for a microcontroller, a Linux daemon, a browser, or a hub.
The normative description of the protocol is SPEC.md.
§Concepts
- A source is the origin of data: a device, an app, a service, or an adapter in front of one. It declares its entities, the addressable parts it exposes.
- An entity may declare a
Control, which tells a hub how it can be changed and how risky that is. Hubs validate every command against it. Valueis the shared data model for state, events, command arguments, and results. Géri carries values without interpreting them.
§Two protocol versions
- v4 (
v4,VERSION) is the current, batch-oriented HTTP contract: sources submitv4::Batches ofv4::Records and get av4::Receiptonly after durable commit. Operators issue commands that sources claim. - v3 (
Up,Down,LEGACY_VERSION) is the streaming form for long-lived connections:
Source Hub
|--- Hello --------------------->| Who I am, what I offer
|--- State --------------------->| My current values
|--- Event --------------------->| Something happened
|<-- Pace -----------------------| Report state at this interval
|<-- Invoke ---------------------| Do this action with these args
|--- Ack ----------------------->| Final outcome of a command
|--- Bye ----------------------->| I am leavingThe first v3 message must be Hello. A receiver checks v and does not process
messages of a version it does not support. Unknown messages decode to
Up::Unknown / Down::Unknown and may be ignored; unknown payload content is
carried through unchanged.
§Encodings
Every type serializes with serde to two equivalent encodings:
- JSON, for humans, webhooks, and browsers. In v3,
Valueis tagged so that integers, floats, and bytes survive the round trip. - CBOR, for constrained devices and high-throughput links.
Valueuses native CBOR types.
The message envelope is the same in both, e.g. {"t": "state", ...}. On a
WebSocket, text frames carry JSON and binary frames carry CBOR.
§Example
Build a v4 batch with one state record and encode it as JSON:
use geri_proto::v4::{Batch, Record, RecordKind, VERSION};
let batch = Batch {
v: VERSION,
records: vec![Record {
source_id: "router".into(),
entity_id: "cpu".into(),
record_id: "router-1".into(),
sequence: 1,
kind: RecordKind::State,
event_time_ms: None,
content_type: "application/json".into(),
data: Some(serde_json::json!({ "pct": 12.5 })),
indexed: None,
blob: None,
}],
};
let json = serde_json::to_string(&batch).unwrap();
assert!(json.starts_with(r#"{"v":4,"records":[{"source_id":"router""#));Declare a v3 node with a dimmable light and a reboot button:
use geri_proto::{Danger, Entity, LEGACY_VERSION, Shape, Up, Visibility};
let hello = Up::Hello {
v: LEGACY_VERSION,
label: "Living room".into(),
pace_ms: None,
entities: vec![
Entity::new("light").label("Light").control(Shape::range(0.0, 100.0), Danger::Safe),
Entity::new("reboot").control(Shape::Trigger, Danger::Destructive),
],
visibility: Visibility::Public,
};
let json = serde_json::to_value(&hello).unwrap();
assert_eq!(json["t"], "hello");
assert_eq!(json["entities"][1]["control"]["shape"]["type"], "trigger");§Limits
Message size, entity counts, data depth, and traffic limits are chosen by the
receiver, not by this crate; see geri-core and v4::Limits. The only limit
enforced here is MAX_DEPTH for nested values.
Modules§
- mqtt
- MQTT topic scheme for v3 nodes on a broker.
- v4
- The Géri v4 wire contract: batch ingestion, receipts, queries, commands, and signed digests over HTTP.
Structs§
- Control
- Declares that an entity can be changed, in what form, and how risky it is.
- Entity
- An addressable part of a v3 node, as declared in
Up::Hello. - Item
- One occurrence in a v3 event stream, sent with
Up::Event. - Plain
- A
Valueencoded as plain, untagged JSON or CBOR. - Value
Deserializer - A serde
Deserializerthat reads from an in-memoryValue.
Enums§
- Bye
- Why a node sent
Up::Bye. Lets a hub tell a planned absence from a failure. - Danger
- How risky a control is to use. Ordered from least to most risky.
- Down
- A v3 message from the hub to a source.
- Invalid
- Why
Shape::acceptrejected a command’s arguments. - Outcome
- Final result of a command, sent with
Up::Ack. - Scope
- Visibility of a single v3 entity.
- Shape
- The input a
Controlaccepts. Tagged bytypeon the wire. - Up
- A v3 message from a source to the hub.
- Value
- The data model for state, events, command arguments, and results.
- Visibility
- Visibility of a whole v3 node, declared in
Up::Hello.
Constants§
- LEGACY_
VERSION - The streaming protocol version (3) used by
UpandDown. - MAX_
DEPTH - Maximum nesting depth of lists and maps accepted when decoding a
Value. - PRESS
- Action that fires a one-shot trigger (reboot, refresh).
argsis null. - SET
- Action that sets an entity to a new value.
argsis the desired value. - VERSION
- The current protocol version (4). See
v4.
Functions§
- valid_
id - Returns whether
idis a valid v3 identifier: 1 to 32 bytes ofa-z,0-9, and-.
Type Aliases§
- Command
Id - Hub-chosen identifier that pairs an
Down::Invokewith itsUp::Ack. - Interval
Ms - A reporting interval in milliseconds. Zero is not a valid interval.
- Name
- Name of an entity, event stream, or action. See
valid_id. - NodeId
- Identity of a v3 node, established by the transport. See
valid_id. - Timestamp
- Milliseconds since the Unix epoch (UTC).
- Values
- Current values of a node, keyed by entity name.