Module protocol 

Wire protocol types for the Eidetica service.

The protocol uses length-prefixed JSON frames over a Unix domain socket. Each frame is a 4-byte big-endian length followed by the JSON payload.

Request shape

ServiceRequest is a flat enum holding pre-authentication lifecycle messages (TrustedLoginUser, TrustedLoginProve), the pre-auth GetInstanceMetadata query, and an AuthenticatedDb wrapper that carries every storage operation (including any user-management writes against _users). The wrapper bundles the (root_id, identity) scope so the server can validate each op against the connection’s session keyset and the target database’s auth settings. Pre-auth verification of the session pubkey happens once at login via a challenge-response handshake.

The login lifecycle is trusted in the sense that the daemon ships the user’s encrypted credentials (salt + AES-GCM ciphertext) to anyone who can connect to the socket and asks for them. This is safe in the local-socket model — filesystem permissions on the socket already bound the caller set to processes that could read the underlying DB files directly. A network transport would need a different shape (PAKE: OPAQUE/SRP) so the server doesn’t release the blob until the client proves password knowledge in a way that doesn’t leak it. The TrustedLogin* naming is a load-bearing reminder of that assumption — see § Trusted login threat model in the Service Architecture doc.

AuthenticatedDb requests carry the caller’s root_id/identity and are gated per-tree by the daemon’s permission check; clients populate these from the session established by the TrustedLogin* flow.

Structs

AuthenticatedDbRequest

Payload of an AuthenticatedDb service request.

Handshake

Handshake message sent by the client on connection.

HandshakeAck

Handshake acknowledgment sent by the server.

MergeState

Response for ComputeMergeState: lowest common ancestor + path to tips.

TransactionContext

Everything a client needs to build and sign an entry locally without further round-trips. The client owns its keys, so signing stays client-side; only the inputs Transaction::commit reads from storage before signing travel here. Heights accompany each parent so the client computes entry height without a follow-up GetEntry per parent.

Enums

DatabaseOp

Database-level operations the server runs on its local Database.

ReadScope

Which projection of the DAG an op observes. Mirrors the Database read posture: a write’s parent tips are the tips of the same projection the caller reads (see the Verification Model design doc).

ServiceRequest

Top-level request from client to server.

ServiceResponse

Response from server to client.

Constants

MAX_FRAME_SIZE

Maximum frame size: 64 MiB.

PROTOCOL_VERSION

Protocol version. Version 0 indicates an unstable protocol that may change without notice between releases.

Functions

read_frame

Read a length-prefixed JSON frame from an async reader.

write_frame

Write a length-prefixed JSON frame to an async writer.

Type Aliases

WireCrdtValue

A CRDT store’s materialized state on the wire. Concrete Store<T> typing stays client-side sugar over this; the cache path already ships serde_json bytes today, so this introduces no new representation.