Tesseras

CLI Meets Network: Publish, Fetch, and Status Commands

2026-02-15

Until now the CLI operated in isolation: create a tessera, verify it, export it, list what you have. Everything stayed on your machine. With this release, tes gains three commands that bridge the gap between local storage and the P2P network — publish, fetch, and status — by talking to a running tesd over a Unix socket.

What was built

tesseras-rpc crate — A new shared crate that both the CLI and daemon depend on. It defines the RPC protocol using MessagePack serialization with length-prefixed framing (4-byte big-endian size header, 64 MiB max). Three request types (Publish, Fetch, Status) and their corresponding responses. A sync DaemonClient handles the Unix socket connection with configurable timeouts. The protocol is deliberately simple — one request, one response, connection closed — to keep the implementation auditable.

tes publish <hash> — Publishes a tessera to the network. Accepts full hashes or short prefixes (e.g., tes publish a1b2), which are resolved against the local database. The daemon reads all tessera files from storage, packs them into a single MessagePack buffer, and hands them to the replication engine. Small tesseras (< 4 MB) are replicated as a single fragment; larger ones go through Reed-Solomon erasure coding. Output shows the short hash and fragment count:

Published tessera 9f2c4a1b (24 fragments created)
Distribution in progress — use `tes status 9f2c4a1b` to track.

tes fetch <hash> — Retrieves a tessera from the network using its full content hash. The daemon collects locally available fragments, reconstructs the original data via erasure decoding if needed, unpacks the files, and stores them in the content-addressable store. Returns the number of memories and total size fetched.

tes status <hash> — Displays the replication health of a tessera. The output maps directly to the replication engine's internal health model:

Daemon RPC listener — The daemon now binds a Unix socket (default: $XDG_RUNTIME_DIR/tesseras/daemon.sock) with proper directory permissions (0700), stale socket cleanup, and graceful shutdown. Each connection is handled in a Tokio task — the listener converts the async stream to sync I/O for the framing layer, dispatches to the RPC handler, and writes the response back.

Pack/unpack in tesseras-core — A small module that serializes a list of file entries (path + data) into a single MessagePack buffer and back. This is the bridge between the tessera's directory structure and the replication engine's opaque byte blobs.

Architecture decisions

• Unix socket over TCP: RPC between CLI and daemon happens on the same machine. Unix sockets are faster, don't need port allocation, and filesystem permissions provide access control without TLS.
• MessagePack over JSON: the same wire format used everywhere else in Tesseras. Compact, schema-less, and already a workspace dependency. A typical publish request/response round-trip is under 200 bytes.
• Sync client, async daemon: the DaemonClient uses blocking I/O because the CLI doesn't need concurrency — it sends one request and waits. The daemon listener is async (Tokio) to handle multiple connections. The framing layer works with any Read/Write impl, bridging both worlds.
• Hash prefix resolution on the client side: publish and status resolve short prefixes locally before sending the full hash to the daemon. This keeps the daemon stateless — it doesn't need access to the CLI's database.
• Default data directory alignment: the CLI default changed from ~/.tesseras to ~/.local/share/tesseras (via dirs::data_dir()) to match the daemon. A migration hint is printed when legacy data is detected.

What comes next

• DHT peer count: the status command currently reports 0 peers — wiring the actual peer count from the DHT is the next step
• tes show: display the contents of a tessera (memories, metadata) without exporting
• Streaming fetch: for large tesseras, stream fragments as they arrive rather than waiting for all of them