Skip to main content

Crate geri_proto

Crate geri_proto 

Source
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.
  • Value is the shared data model for state, events, command arguments, and results. Géri carries values without interpreting them.

§Two protocol versions

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 leaving

The 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, Value is tagged so that integers, floats, and bytes survive the round trip.
  • CBOR, for constrained devices and high-throughput links. Value uses 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 Value encoded as plain, untagged JSON or CBOR.
ValueDeserializer
A serde Deserializer that reads from an in-memory Value.

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::accept rejected 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 Control accepts. Tagged by type on 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 Up and Down.
MAX_DEPTH
Maximum nesting depth of lists and maps accepted when decoding a Value.
PRESS
Action that fires a one-shot trigger (reboot, refresh). args is null.
SET
Action that sets an entity to a new value. args is the desired value.
VERSION
The current protocol version (4). See v4.

Functions§

valid_id
Returns whether id is a valid v3 identifier: 1 to 32 bytes of a-z, 0-9, and -.

Type Aliases§

CommandId
Hub-chosen identifier that pairs an Down::Invoke with its Up::Ack.
IntervalMs
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.