Struct Node 

pub struct Node<R> {
    pub endpoint: Endpoint,
    pub store: FsStore,
    pub registry: R,
    pub grants: GrantStore,
    /* private fields */
}

A ringdrop P2P node.

Owns an iroh QUIC Endpoint, an iroh-blobs FsStore, a RingGate that enforces ring-based access control, and the Registry that tracks ring membership.

Create a node with Node::start; shut it down cleanly with Node::shutdown so the blob store is flushed to disk before the process exits.

Fields

endpoint: Endpoint

The iroh QUIC endpoint — manages connections, NAT traversal, and relay fallback.

store: FsStore

The iroh-blobs persistent store — holds all locally imported and received blobs.

registry: R

The ring registry — tracks ring membership and permission-typed resource associations.

grants: GrantStore

The grant store — controls which peers may invoke catalog operations.

Implementations

impl<R: Registry + Clone + Send + Sync + 'static> Node<R>

pub async fn start( data_dir: impl AsRef<Path>, cfg: Config, registry: R, ) -> Result<Self>

Start a node, binding a QUIC endpoint and loading the blob store from data_dir.

The node is immediately reachable for inbound connections once this returns. The blob store is created under data_dir/blobs/ if it does not yet exist.

Errors

Returns an error if the QUIC endpoint cannot bind, or if the blob store cannot be opened or created.

pub fn node_addr(&self) -> EndpointAddr

Returns the network address of this node (relay URL + node ID).

pub async fn import_file( &self, path: impl AsRef<Path>, ) -> Result<(Hash, BlobFormat)>

Import a single file into the blob store.

The file is chunked, BLAKE3-hashed, and pinned with a named tag (the leaf filename, i.e. path.file_name()). Returns the root hash and BlobFormat::Raw.

Errors

Returns an error if the file cannot be read or the store operation fails.

pub async fn import_directory( &self, dir: impl AsRef<Path>, ) -> Result<(Hash, BlobFormat)>

Import a directory into the blob store as an iroh-blobs collection.

Each file under dir is imported individually; the resulting hashes are assembled into a HashSeq collection pinned under the directory name. Returns the collection root hash and BlobFormat::HashSeq.

Errors

Returns an error if any file cannot be read or the store operation fails.

pub async fn list_blobs( &self, peer: Option<&str>, rings: Option<Vec<String>>, ) -> Result<Vec<(Hash, BlobFormat, String)>>

List blobs in the local store as (hash, format, tag_name) triples.

When peer is supplied only blobs accessible to that peer are returned (i.e. blobs associated with at least one ring that both includes the peer and grants Permission::Read). When rings is supplied only blobs tagged with at least one of those ring names are returned (OR semantics). When both are given the filters are combined: a blob must satisfy both independently.

Errors

Returns an error if the tag store cannot be read, if peer is not a valid EndpointId encoding, or if a registry lookup fails.

pub async fn delete_blob(&self, hash: Hash) -> Result<()>

Remove a blob from the local store by deleting its named tags.

Ring tags in the registry must be removed separately by the caller before invoking this method. Disk space is reclaimed on the next GC cycle (every 30 s while the node is running).

Errors

Returns an error if no tag is found for the given hash, or if the tag deletion fails.

pub fn make_ticket( &self, hash: Hash, format: BlobFormat, name: Option<String>, ) -> ShareTicket

Build a ShareTicket for a locally-stored blob.

The ticket embeds the relay URL and node ID but omits direct IP addresses — tickets remain valid across daemon restarts and IP changes.

pub async fn catalog_connect( &self, peer_addr: EndpointAddr, ) -> Result<Vec<CatalogEntry>>

Connect to a remote node and fetch its catalog — the list of blobs the caller is allowed to download.

The remote node must have granted crate::core::grants::Privilege::BlobList to this node’s identity. Only blobs that the calling peer has iroh_rings::Permission::Read on (via ring membership) will be included.

Errors

Returns an error if the connection fails, the remote node denies access, or the response stream is malformed.

pub async fn import_path(&self, path: &Path) -> Result<(Hash, BlobFormat)>

Import a file or directory, dispatching to Node::import_file or Node::import_directory based on whether path is a file or a dir.

Errors

Returns an error if the import fails (see the individual methods for details).

pub async fn download( &self, ticket: &ShareTicket, dest: impl AsRef<Path>, ) -> Result<()>

Download the blob described by ticket and export it under dest.

If the blob is already complete in the local store the download is skipped entirely. For collections, each member blob is fetched individually before the directory is reassembled on disk.

Errors

Returns an error if the remote peer denies access, the connection cannot be established, or the export to disk fails.

pub async fn download_with_progress<F: Fn(u64, u64) + Send + Sync>( &self, ticket: &ShareTicket, dest: impl AsRef<Path>, on_progress: F, ) -> Result<()>

Like Node::download, but calls on_progress(bytes_done, total_bytes) as each chunk is received, suitable for driving a progress bar.

Errors

Returns an error under the same conditions as Node::download.

pub async fn shutdown(self) -> Result<()>

Shut down the node, flushing all pending blob-store writes to disk.

Must be called before the process exits to avoid data loss: the iroh-blobs store batches redb transactions and sync_db waits for all of them to commit.

Errors

Returns an error if the router shutdown or the blob-store flush fails.