diff options
Diffstat (limited to 'news/cli-daemon-rpc/index.html')
| -rw-r--r-- | news/cli-daemon-rpc/index.html | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/news/cli-daemon-rpc/index.html b/news/cli-daemon-rpc/index.html new file mode 100644 index 0000000..a1ca0c1 --- /dev/null +++ b/news/cli-daemon-rpc/index.html @@ -0,0 +1,142 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>CLI Meets Network: Publish, Fetch, and Status Commands — Tesseras</title> + <meta name="description" content="The tesseras CLI can now publish tesseras to the network, fetch them from peers, and monitor replication status — all through a new Unix socket RPC bridge to the daemon."> + <!-- Open Graph --> + <meta property="og:type" content="article"> + <meta property="og:title" content="CLI Meets Network: Publish, Fetch, and Status Commands"> + <meta property="og:description" content="The tesseras CLI can now publish tesseras to the network, fetch them from peers, and monitor replication status — all through a new Unix socket RPC bridge to the daemon."> + <meta property="og:image" content="https://tesseras.net/images/social.jpg"> + <meta property="og:image:width" content="1200"> + <meta property="og:image:height" content="630"> + <meta property="og:site_name" content="Tesseras"> + <!-- Twitter Card --> + <meta name="twitter:card" content="summary_large_image"> + <meta name="twitter:title" content="CLI Meets Network: Publish, Fetch, and Status Commands"> + <meta name="twitter:description" content="The tesseras CLI can now publish tesseras to the network, fetch them from peers, and monitor replication status — all through a new Unix socket RPC bridge to the daemon."> + <meta name="twitter:image" content="https://tesseras.net/images/social.jpg"> + <link rel="stylesheet" href="https://tesseras.net/style.css?h=21f0f32121928ee5c690"> + + + <link rel="alternate" type="application/atom+xml" title="Tesseras" href="https://tesseras.net/atom.xml"> + + + <link rel="icon" type="image/png" sizes="32x32" href="https://tesseras.net/images/favicon.png?h=be4e123a23393b1a027d"> + +</head> +<body> + <header> + <h1> + <a href="https://tesseras.net/"> + <img src="https://tesseras.net/images/logo-64.png?h=c1b8d0c4c5f93b49d40b" alt="Tesseras" width="40" height="40" class="logo"> + Tesseras + </a> + </h1> + <nav> + + <a href="https://tesseras.net/about/">About</a> + <a href="https://tesseras.net/news/">News</a> + <a href="https://tesseras.net/releases/">Releases</a> + <a href="https://tesseras.net/faq/">FAQ</a> + <a href="https://tesseras.net/subscriptions/">Subscriptions</a> + <a href="https://tesseras.net/contact/">Contact</a> + + </nav> + <nav class="lang-switch"> + + <strong>English</strong> | <a href="/pt-br/news/cli-daemon-rpc/">Português</a> + + </nav> + </header> + + <main> + +<article> + <h2>CLI Meets Network: Publish, Fetch, and Status Commands</h2> + <p class="news-date">2026-02-15</p> + <p>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, <code>tes</code> +gains three commands that bridge the gap between local storage and the P2P +network — <code>publish</code>, <code>fetch</code>, and <code>status</code> — by talking to a running <code>tesd</code> over +a Unix socket.</p> +<h2 id="what-was-built">What was built</h2> +<p><strong><code>tesseras-rpc</code> crate</strong> — 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 (<code>Publish</code>, <code>Fetch</code>, <code>Status</code>) and their corresponding responses. +A sync <code>DaemonClient</code> handles the Unix socket connection with configurable +timeouts. The protocol is deliberately simple — one request, one response, +connection closed — to keep the implementation auditable.</p> +<p><strong><code>tes publish <hash></code></strong> — Publishes a tessera to the network. Accepts full +hashes or short prefixes (e.g., <code>tes publish a1b2</code>), 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:</p> +<pre><code>Published tessera 9f2c4a1b (24 fragments created) +Distribution in progress — use `tes status 9f2c4a1b` to track. +</code></pre> +<p><strong><code>tes fetch <hash></code></strong> — 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.</p> +<p><strong><code>tes status <hash></code></strong> — Displays the replication health of a tessera. The +output maps directly to the replication engine's internal health model:</p> +<table><thead><tr><th>State</th><th>Meaning</th></tr></thead><tbody> +<tr><td>Local</td><td>Not yet published — exists only on your machine</td></tr> +<tr><td>Publishing</td><td>Fragments being distributed, critical redundancy</td></tr> +<tr><td>Replicated</td><td>Distributed but below target redundancy</td></tr> +<tr><td>Healthy</td><td>Full redundancy achieved</td></tr> +</tbody></table> +<p><strong>Daemon RPC listener</strong> — The daemon now binds a Unix socket (default: +<code>$XDG_RUNTIME_DIR/tesseras/daemon.sock</code>) 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.</p> +<p><strong>Pack/unpack in <code>tesseras-core</code></strong> — 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.</p> +<h2 id="architecture-decisions">Architecture decisions</h2> +<ul> +<li><strong>Unix socket over TCP</strong>: 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.</li> +<li><strong>MessagePack over JSON</strong>: 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.</li> +<li><strong>Sync client, async daemon</strong>: the <code>DaemonClient</code> 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 <code>Read</code>/<code>Write</code> impl, bridging both worlds.</li> +<li><strong>Hash prefix resolution on the client side</strong>: <code>publish</code> and <code>status</code> 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.</li> +<li><strong>Default data directory alignment</strong>: the CLI default changed from +<code>~/.tesseras</code> to <code>~/.local/share/tesseras</code> (via <code>dirs::data_dir()</code>) to match +the daemon. A migration hint is printed when legacy data is detected.</li> +</ul> +<h2 id="what-comes-next">What comes next</h2> +<ul> +<li><strong>DHT peer count</strong>: the <code>status</code> command currently reports 0 peers — wiring +the actual peer count from the DHT is the next step</li> +<li><strong><code>tes show</code></strong>: display the contents of a tessera (memories, metadata) without +exporting</li> +<li><strong>Streaming fetch</strong>: for large tesseras, stream fragments as they arrive +rather than waiting for all of them</li> +</ul> + +</article> + + </main> + + <footer> + <p>© 2026 Tesseras Project. <a href="/atom.xml">News Feed</a> · <a href="https://git.sr.ht/~ijanc/tesseras">Source</a></p> + </footer> +</body> +</html> |