Crate efema_proto 

The wire format of efema: what a client and a relay say to each other.

efema is a sync relay for local-first apps. A device writes its changes as a batch of opaque entries into a named stream; the relay gives each entry the next position and keeps it; every other device reads what came after its cursor. The relay never looks inside an entry - it cannot tell a note from a password, and merging is left to the app.

This crate is that conversation and nothing else: the messages, their CBOR encoding, the stream’s names and identities, the cursor and the hash chain that makes a cursor checkable. The relay (efema-server) and the client library both build on it, so the two cannot drift apart: there is one definition of each message, and it lives here.

The pieces

• StreamName - the name a stream is addressed by, in the URL.
• StreamId - which incarnation of that name: a fresh random value when the stream is created, so a cursor from a stream that was wiped and started again is recognised as foreign instead of silently reused.
• Epoch - a number the app raises when it changes the format of what it writes. The relay only compares epochs; it never knows what they mean.
• Hash and chain - every entry is linked to the one before it, so a cursor names not just a position but the history up to it.
• Cursor - where a reader stands: stream, position and the hash there.
• wire - the request and response bodies, encoded as CBOR.

use efema_proto::{chain, Epoch, StreamId};

let stream = StreamId::from_bytes([7; 16]);
let start = chain::genesis(&stream);
let first = chain::link(&start, 1, Epoch(1), b"sealed bytes");
// The same history always gives the same hash...
assert_eq!(first, chain::link(&start, 1, Epoch(1), b"sealed bytes"));
// ...and a different one never does.
assert_ne!(first, chain::link(&start, 1, Epoch(2), b"sealed bytes"));

Modules

chain

The hash chain that links every entry of a stream to the one before it.

limits

What a request may carry and a response may hold, in protocol version 1.

wire

The bodies of requests and responses, and their CBOR encoding.

Structs

Cursor

A reader’s place in a stream: which stream, how far, and what the history up to there was.

Epoch

The version of the format an app writes into a stream.

Hash

A link in a stream’s hash chain: SHA-256 over the previous link and the entry at this position (see crate::chain).

ParseCursorError

Why a text is not a cursor.

ParseIdError

Why a text is not an identity or a hash.

StreamId

Which incarnation of a stream name this is.

StreamName

The name of a stream: what goes into the URL, and what a person reads in the relay’s listing.

Enums

InvalidName

Why a text is not a stream name.

Constants

API_PREFIX

The path every endpoint of protocol version 1 lives under.

MAX_NAME_LEN

The longest name a stream may have, in bytes.

MEDIA_TYPE

The media type of every request and response body in protocol version 1.