mnem_transport/
lib.rs

1//! # mnem-transport
2//!
3//! Offline transport for mnem: export a subtree of the content-addressed
4//! DAG to a CAR v1 archive, ship it anywhere (USB stick, email, `scp`,
5//! S3), import on the other side.
6//!
7//! CAR ([Content-Addressable aRchive]) is IPFS's standard bundling
8//! format: a stream of `(varint length, CID, bytes)` triples preceded
9//! by a varint-framed DAG-CBOR header that lists the root CIDs. It is
10//! streamable in both directions; this crate implements the
11//! [CAR v1] wire shape exactly.
12//!
13//! ## Shape
14//!
15//! - [`fn@export`] walks the [`Blockstore`][mnem_core::store::Blockstore]
16//!   from a root CID via the
17//!   [`Blockstore::iter_from_root`][mnem_core::store::Blockstore::iter_from_root]
18//!   default impl, writing every reachable block to a
19//!   [`std::io::Write`].
20//! - [`fn@import`] reads a CAR from a [`std::io::Read`] and inserts every
21//!   block into a target blockstore, verifying the CID on each block.
22//! - [`car`] exposes the lower-level CAR reader / writer used by the
23//!   above, for callers that need to interleave CAR parsing with other
24//!   work.
25//!
26//! In addition to the file-format half, this crate is home to the
27//! *shapes* of mnem's remote wire protocol:
28//!
29//! - [`protocol`] freezes the [`protocol::PROTOCOL_VERSION`]
30//!   integer, the [`protocol::PROTOCOL_HEADER`] HTTP
31//!   header name, and the [`protocol::Capability`]
32//!   vocabulary. PR 2 does not ship any wire code; it ships the
33//!   agreement surface so PR 3 can add verbs without a version bump.
34//! - [`remote`] defines [`remote::RemoteConfig`], the
35//!   in-memory type parsed from the `[remote.<name>]` section of
36//!   `.mnem/config.toml`.
37//! - [`have_set`] defines the [`have_set::HaveSet`] trait
38//!   and the [`have_set::BloomHaveSet`] reference
39//!   back-end used to summarise "blocks I already have" on `fetch-
40//!   blocks` / `push-blocks`.
41//!
42//! Everything in those three modules is pure data + pure functions.
43//! HTTP wiring lives in `mnem http`; the CLI glue (`mnem remote add`
44//! etc.) lives in `mnem-cli`; neither lands until PR 3.
45//!
46//! ## Constraints
47//!
48//! - WASM-clean. No tokio, no async. The entire interface is
49//!   `std::io::{Read, Write}` with `?Sized` support.
50//! - No filesystem helpers; callers open files and pass the handles.
51//!   Keeps this crate usable inside HTTP streams, pipes, etc.
52//! - Deterministic ordering: [`fn@export`] writes blocks in
53//!   `iter_from_root`'s depth-first order so the same root produces a
54//!   byte-identical CAR across runs.
55//!
56//! [Content-Addressable aRchive]: https://ipld.io/specs/transport/car/carv1/
57//! [CAR v1]: https://ipld.io/specs/transport/car/carv1/
58
59#![forbid(unsafe_code)]
60#![deny(missing_docs)]
61
62pub mod car;
63#[cfg(feature = "client")]
64pub mod client;
65pub mod error;
66pub mod export;
67pub mod have_set;
68pub mod import;
69pub mod protocol;
70pub mod remote;
71pub mod secret_token;
72
73pub use error::{ClientError, TransportError};
74pub use export::{ExportStats, export};
75pub use have_set::{BloomHaveSet, HaveSet, build_have_set};
76pub use import::{ImportStats, import};
77pub use protocol::{
78    CAPABILITIES_HEADER, Capability, CapabilitySet, PROTOCOL_HEADER, PROTOCOL_VERSION,
79    parse_capabilities, serialize_capabilities,
80};
81pub use remote::{RemoteConfig, RemoteConfigFile, RemoteSection, parse_config};
82pub use secret_token::SecretToken;
83
84#[cfg(feature = "client")]
85pub use client::{HttpRemoteClient, PushResponse, RefsResponse, RemoteClient};
86
87/// Library version (tracks the workspace package version).
88pub const VERSION: &str = env!("CARGO_PKG_VERSION");
mnem_transport/lib.rs

mnem_transport/
lib.rs
