### start Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/fn.start.html The entry point of the get response machine. ```APIDOC ## start iroh_blobs::get::fsm ### Description The entry point of the get response machine. ### Signature ```rust pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial ``` ``` -------------------------------- ### Setup iroh-blobs with iroh Source: https://docs.rs/iroh-blobs/latest/index.html This example demonstrates how to set up an iroh endpoint and a Router to handle iroh-blobs protocol using an in-memory store. It shows how to add data, create a BlobTicket, and serve it. ```rust use iroh::{protocol::Router, Endpoint, endpoint::presets}; use iroh_blobs::{store::mem::MemStore, BlobsProtocol, ticket::BlobTicket}; #[tokio::main] async fn main() -> anyhow::Result<()> { // create an iroh endpoint that includes the standard address lookup mechanisms // we've built at number0 let endpoint = Endpoint::bind(presets::N0).await?; // create a protocol handler using an in-memory blob store. let store = MemStore::new(); let tag = store.add_slice(b"Hello world").await?; let _ = endpoint.online().await; let addr = endpoint.addr(); let ticket = BlobTicket::new(addr, tag.hash, tag.format); // build the router let blobs = BlobsProtocol::new(&store, None); let router = Router::builder(endpoint) .accept(iroh_blobs::ALPN, blobs) .spawn(); println!("We are now serving {}", ticket); // wait for control-c tokio::signal::ctrl_c().await; // clean shutdown of router and store router.shutdown().await?; Ok(()) } ``` -------------------------------- ### Start a get response machine Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html Initiates the get response finite state machine with a connection, a GetRequest, and request counters. This is the entry point for retrieving data. ```rust pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial { AtInitial::new(connection, request, counters) } ``` -------------------------------- ### AtInitial::new Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html Creates a new `AtInitial` state for initiating a get response. This is the starting point for the get operation. ```APIDOC ## `AtInitial::new` ### Description Creates a new `AtInitial` state for initiating a get response. This is the starting point for the get operation. ### Method `AtInitial::new` ### Parameters - `connection` (Connection) - An existing connection to use for the request. - `request` (GetRequest) - The request to be sent. - `counters` (RequestCounters) - Counters for tracking request metrics. ``` -------------------------------- ### Example Searches in iroh_blobs Store Tests Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/test.rs.html?search= Demonstrates example search queries used in the iroh_blobs store tests. These examples show common patterns for searching within the store. ```rust 1//! Test harness for store implementations. ``` ```rust * std::vec ``` ```rust * u32 -> bool ``` ```rust * Option, (T -> U) -> Option ``` -------------------------------- ### Start Function Signature Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/fn.start.html This is the function signature for the `start` function, which serves as the entry point for the get response state machine. It takes a connection, a GetRequest, and RequestCounters as input and returns a state of type AtInitial. ```rust pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial ``` -------------------------------- ### Setup iroh-blobs with iroh Endpoint Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/index.html Sets up an iroh endpoint and a BlobsProtocol handler using an in-memory store. This example demonstrates how to bind an endpoint, add data to the store, create a BlobTicket, and configure the router to accept the iroh_blobs protocol. ```rust use iroh::{protocol::Router, Endpoint, endpoint::presets}; use iroh_blobs::{store::mem::MemStore, BlobsProtocol, ticket::BlobTicket}; #[tokio::main] async fn main() -> anyhow::Result<()> { // create an iroh endpoint that includes the standard address lookup mechanisms // we've built at number0 let endpoint = Endpoint::bind(presets::N0).await?; // create a protocol handler using an in-memory blob store. let store = MemStore::new(); let tag = store.add_slice(b"Hello world").await?; let _ = endpoint.online().await; let addr = endpoint.addr(); let ticket = BlobTicket::new(addr, tag.hash, tag.format); // build the router let blobs = BlobsProtocol::new(&store, None); let router = Router::builder(endpoint) .accept(iroh_blobs::ALPN, blobs) .spawn(); println!("We are now serving {}", ticket); // wait for control-c tokio::signal::ctrl_c().await; // clean shutdown of router and store router.shutdown().await?; Ok(()) } ``` -------------------------------- ### Initialize Get Response FSM Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search= Starts the finite state machine for handling get responses. Requires an active connection, a `GetRequest`, and initial counters. ```rust /// The entry point of the get response machine pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial { AtInitial::new(connection, request, counters) } ``` -------------------------------- ### Initialize Get Response State Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search= Creates a new `AtInitial` state for a get response. This is the starting point before opening a connection. ```rust pub fn new(connection: Connection, request: GetRequest, counters: RequestCounters) -> Self { Self { connection, request, counters, } } ``` -------------------------------- ### fsm::start Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html The entry point of the get response machine. Initiates the process of getting data from a peer with a given connection and request. ```APIDOC ## fsm::start ### Description This function is the entry point for the get response finite state machine. It starts the process of retrieving data from a peer using the provided connection and a `GetRequest`. ### Method ```rust pub fn start(connection: Connection, request: GetRequest, counters: RequestCounters) -> AtInitial ``` ### Parameters - `connection` (Connection): The established connection to the peer. - `request` (GetRequest): The description of the data to retrieve. - `counters` (RequestCounters): Counters to track request statistics. ``` -------------------------------- ### Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/protocol/builder/struct.GetRequestBuilder.html?search= Examples of how to structure search queries for the Iroh Blobs protocol builder. ```APIDOC ## Search Examples This section provides examples of search queries that can be used within the Iroh Blobs protocol builder. ### Example Searches * `std::vec` * `u32 -> bool` * `Option, (T -> U) -> Option` ``` -------------------------------- ### DownloadRequest Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.DownloadRequest.html?search= Examples of how to perform searches for download requests. These demonstrate different query patterns. ```APIDOC ## Search Examples ### Description Provides examples of search queries for download requests. ### Query Patterns - **Simple Type Search:** - `std::vec` - **Type Conversion Search:** - `u32 -> bool` - **Generic Type Transformation Search:** - `Option, (T -> U) -> Option` ``` -------------------------------- ### Batch Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/blobs/struct.Batch.html?search= Examples of how to perform searches within batches. ```APIDOC ## Batch Search Examples ### Description Provides examples of search queries that can be performed on batches. ### Example Searches - `std::vec` - `u32 -> bool` - `Option, (T -> U) -> Option` ``` -------------------------------- ### fsm::start_get_many Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html Starts the get response machine with a `GetManyRequest`. This is an alternative entry point for retrieving multiple pieces of data. ```APIDOC ## fsm::start_get_many ### Description Initiates the get response machine using a `GetManyRequest` to fetch multiple data items. This function handles opening a bidirectional connection and sending the initial request. ### Method ```rust pub async fn start_get_many(connection: Connection, request: GetManyRequest, counters: RequestCounters) -> std::result::Result, GetError> ``` ### Parameters - `connection` (Connection): The established connection to the peer. - `request` (GetManyRequest): The request specifying multiple data items to retrieve. - `counters` (RequestCounters): Counters to track request statistics. ### Returns A `std::result::Result` which can contain either `AtStartChild` or `AtClosing` upon success, or a `GetError` if an error occurs during the process. ``` -------------------------------- ### ConnectionPool Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/util/connection_pool/struct.ConnectionPool.html?search= Examples of how to perform searches within the ConnectionPool. ```APIDOC ## ConnectionPool Search ### Description Provides examples of search queries that can be used within the ConnectionPool. ### Example Searches - `std::vec` - `u32 -> bool` - `Option, (T -> U) -> Option` ``` -------------------------------- ### RequestMode Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/provider/events/enum.RequestMode.html?search= Examples demonstrating how to search for RequestMode values. These examples illustrate common search patterns. ```APIDOC ## RequestMode Search ### Description Provides examples of how to search for specific RequestMode values or patterns. ### Example Searches - `std::vec` - `u32 -> bool` - `Option, (T -> U) -> Option` ``` -------------------------------- ### ConnectMode Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/provider/events/enum.ConnectMode.html?search= Examples of how to search for ConnectMode enums. ```APIDOC ## Example Searches - std::vec - u32 -> bool - Option, (T -> U) -> Option ``` -------------------------------- ### AtInitial Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search=u32+-%3E+bool Represents the initial state of a get response. It holds the connection, the get request, and request counters. The `next` method is used to initiate the bidi stream for the get response. ```APIDOC ## AtInitial ### Description Represents the initial state of a get response. It holds the connection, the get request, and request counters. The `next` method is used to initiate the bidi stream for the get response. ### Methods #### `new(connection: Connection, request: GetRequest, counters: RequestCounters) -> Self` Creates a new `AtInitial` state. - **connection** (Connection) - An existing connection. - **request** (GetRequest) - The request to be sent. - **counters** (RequestCounters) - Counters for the request. #### `async next(self) -> Result` Initiates a new bidi stream to use for the get response. This transitions the state to `AtConnected`. ### Errors - `InitialNextError::Open`: An error occurred while opening the connection. ``` -------------------------------- ### iroh_blobs::get::fsm::start Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search= Initiates the state machine for handling GET responses. This is the entry point for the low-level API to get data from a peer. ```APIDOC ## iroh_blobs::get::fsm::start ### Description Initiates the state machine for handling GET responses. This is the entry point for the low-level API to get data from a peer. ### Signature ```rust pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial ``` ### Parameters * `connection`: An established `Connection` object to the peer. * `request`: A `GetRequest` object specifying the data to retrieve. * `counters`: `RequestCounters` to track statistics for the request. ``` -------------------------------- ### start_get_many Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/fn.start_get_many.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Initiates a get many request. This is the entry point for the get many operation within the state machine. ```APIDOC ## start_get_many ### Description Starts a get many request. This function is the initial step in the state machine for handling multiple blob retrieval requests. ### Function Signature ```rust pub async fn start_get_many( connection: Connection, request: GetManyRequest, counters: RequestCounters, ) -> Result, GetError> ``` ### Parameters * `connection` (Connection) - Represents the connection to be used for the request. * `request` (GetManyRequest) - The specific request details for retrieving multiple blobs. * `counters` (RequestCounters) - Counters to track metrics related to the request. ### Returns A `Result` which can be: * `Ok(Result)` - Indicates the operation started successfully, returning either `AtStartChild` or `AtClosing` state. * `Err(GetError)` - Indicates an error occurred during the initiation of the get many request. ``` -------------------------------- ### Initiate Download with Options Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html Starts a download process using a DownloadOptions struct for detailed configuration. This allows for more control over the download behavior. ```rust pub fn download_with_opts(&self, options: DownloadOptions) -> DownloadProgress ``` -------------------------------- ### ThrottleMode Search Examples Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/provider/events/enum.ThrottleMode.html?search= Demonstrates different ways to search for ThrottleMode enums. These examples cover basic searches, type conversions, and generic function patterns. ```APIDOC ## ThrottleMode Search Operations ### Description Provides examples of how to search and filter ThrottleMode enums using various patterns. ### Example Searches - **Basic Search:** `std::vec` - **Type Conversion Search:** `u32 -> bool` - **Generic Function Pattern Search:** `Option, (T -> U) -> Option` ``` -------------------------------- ### Initiate Download with Options Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search= The `download_with_opts` method allows initiating a download with specific `DownloadOptions`, including the request, providers, and split strategy. It returns a `DownloadProgress` handle. ```rust pub fn download_with_opts(&self, options: DownloadOptions) -> DownloadProgress { let fut = self.client.server_streaming(options, 32); DownloadProgress::new(Box::pin(fut)) } ``` -------------------------------- ### Initiate a Download with Options Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Starts a download request with explicit DownloadOptions, allowing for custom strategies. Use this when you need to specify the SplitStrategy or other advanced options. ```rust pub fn download_with_opts(&self, options: DownloadOptions) -> DownloadProgress { let fut = self.client.server_streaming(options, 32); DownloadProgress::new(Box::pin(fut)) } ``` -------------------------------- ### Initiate Download Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html Starts a download process for a given request and content discovery provider. Returns a DownloadProgress handle. ```rust pub fn download( &self, request: impl SupportedRequest, providers: impl ContentDiscovery, ) -> DownloadProgress ``` -------------------------------- ### Initiate a Download Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search= The `download` method starts a new download using provided `SupportedRequest` and `ContentDiscovery` providers. It defaults to `SplitStrategy::None`. ```rust pub fn download( &self, request: impl SupportedRequest, providers: impl ContentDiscovery, ) -> DownloadProgress { let request = request.into_request(); let providers = Arc::new(providers); self.download_with_opts(DownloadOptions { request, providers, strategy: SplitStrategy::None, }) } ``` -------------------------------- ### Start Get Many Request Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/fn.start_get_many.html?search= Initiates a get many request with the provided connection, request details, and counters. This function is a precursor to a state machine implementation. ```rust pub async fn start_get_many( connection: Connection, request: GetManyRequest, counters: RequestCounters, ) -> Result, GetError> ``` -------------------------------- ### Read Collection from FSM (Start Root) Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/format/collection/struct.Collection.html?search= Reads a collection from a get FSM starting at the root. Returns the FSM state for the next child blob, the links array, and the collection itself. ```rust pub async fn read_fsm( fsm_at_start_root: AtStartRoot, ) -> Result<(EndBlobNext, HashSeq, Collection)> ``` -------------------------------- ### Start Get Many Request Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search= Initiates a 'get many' request. This function opens a bidirectional stream, serializes the request, and returns a result that can be either an `AtStartChild` or `AtClosing` state, or a `GetError`. ```rust /// Start with a get many request. Todo: turn this into distinct states. pub async fn start_get_many( connection: Connection, request: GetManyRequest, counters: RequestCounters, ) -> std::result::Result, GetError> { let start = Instant::now(); let (mut writer, reader) = connection .open_bi() .await .map_err(|e| e!(InitialNextError::Open, e.into()))?; let request = Request::GetMany(request); let request_bytes = postcard::to_stdvec(&request) ``` -------------------------------- ### Get Current Stream Position Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/util/connection_pool/type.OnConnected.html?search= Returns the current position within the stream, measured from the start. ```rust fn stream_position(&mut self) -> Result ``` -------------------------------- ### AtInitial::new Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/struct.AtInitial.html?search=std%3A%3Avec Creates a new instance of the AtInitial state for the get response machine. It takes an existing connection, the get request details, and request counters as arguments. ```APIDOC ## AtInitial::new ### Description Create a new get response. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Method Signature `pub fn new(connection: Connection, request: GetRequest, counters: RequestCounters) -> Self` ### Parameters * **connection** (Connection) - An existing connection. * **request** (GetRequest) - The request to be sent. * **counters** (RequestCounters) - Request counters. ``` -------------------------------- ### Start a get many response machine Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html Initiates the get response machine with a GetManyRequest. This function opens a bidirectional stream, serializes the request, and returns a result that can be either an initial state or an error. ```rust pub async fn start_get_many( connection: Connection, request: GetManyRequest, counters: RequestCounters, ) -> std::result::Result, GetError> { let start = Instant::now(); let (mut writer, reader) = connection .open_bi() .await .map_err(|e| e!(InitialNextError::Open, e.into()))?; let request = Request::GetMany(request); let request_bytes = postcard::to_stdvec(&request) ``` -------------------------------- ### Create Downloader with Options Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html Initializes a new Downloader instance with a Store, Endpoint, and specific pool options. Use this for custom download configurations. ```rust pub fn new_with_opts( store: &Store, endpoint: &Endpoint, pool_options: Options, ) -> Self ``` -------------------------------- ### Example Search Queries Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/remote/struct.PushProgress.html?search= Demonstrates common search query patterns for types, type conversions, and function signatures. ```text std::vec ``` ```text u32 -> bool ``` ```text Option, (T -> U) -> Option ``` -------------------------------- ### Initiate a Download Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Starts a download request with specified content providers. This method abstracts away the SplitStrategy and uses None by default. Use this for simple download initiation. ```rust pub fn download( &self, request: impl SupportedRequest, providers: impl ContentDiscovery, ) -> DownloadProgress { let request = request.into_request(); let providers = Arc::new(providers); self.download_with_opts(DownloadOptions { request, providers, strategy: SplitStrategy::None, }) } ``` -------------------------------- ### Handle Get Request Received Notify Event Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider/events.rs.html?search=std%3A%3Avec Processes a `GetRequestReceivedNotify` message and starts logging request events. ```rust ProviderMessage::GetRequestReceivedNotify(msg) => { trace!(%connection_id, %request_id, "{:?}", msg.inner); log_request_events(msg.rx, msg.inner.connection_id, msg.inner.request_id); } ``` -------------------------------- ### Handle Get Many Request Received Notify Event Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider/events.rs.html?search=std%3A%3Avec Processes a `GetManyRequestReceivedNotify` message and starts logging request events. ```rust ProviderMessage::GetManyRequestReceivedNotify(msg) => { trace!(%connection_id, %request_id, "{:?}", msg.inner); log_request_events(msg.rx, msg.inner.connection_id, msg.inner.request_id); } ``` -------------------------------- ### Example Usage of BlobsProtocol Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/net_protocol.rs.html?search= Demonstrates setting up an iroh endpoint, creating a `BlobsProtocol` handler with a store, and adding it to a router to make data globally available via a ticket. ```rust use iroh::{protocol::Router, Endpoint, endpoint::presets}; use iroh_blobs::{store, ticket::BlobTicket, BlobsProtocol}; // create a store let store = store::fs::FsStore::load("blobs").await?; // add some data let t = store.add_slice(b"hello world").await?; // create an iroh endpoint let endpoint = Endpoint::bind(presets::N0).await?; endpoint.online().await; let addr = endpoint.addr(); // create a blobs protocol handler let blobs = BlobsProtocol::new(&store, None); // create a router and add the blobs protocol handler let router = Router::builder(endpoint) .accept(iroh_blobs::ALPN, blobs) .spawn(); // this data is now globally available using the ticket let ticket = BlobTicket::new(addr, t.hash, t.format); println!("ticket: {}", ticket); // wait for control-c to exit tokio::signal::ctrl_c().await?; ``` -------------------------------- ### fsm::start Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Initiates the get response finite state machine with a connection, a GetRequest, and request counters. ```APIDOC ## fsm::start ### Description Starts the finite state machine for handling GET responses. This is the entry point for initiating a data retrieval operation. ### Signature ```rust pub fn start( connection: Connection, request: GetRequest, counters: RequestCounters, ) -> AtInitial ``` ### Parameters * `connection`: An active connection object to the peer. * `request`: A `GetRequest` struct describing the data to be fetched. * `counters`: `RequestCounters` to track statistics about the request. ### Returns An `AtInitial` state, representing the initial state of the FSM. ``` -------------------------------- ### Handle Get Request Received Event Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider/events.rs.html?search=std%3A%3Avec Processes a `GetRequestReceived` message, sends an acknowledgment, and starts logging request events. ```rust ProviderMessage::GetRequestReceived(msg) => { trace!(%connection_id, %request_id, "{:?}", msg.inner); msg.tx.send(Ok(())).await.ok(); log_request_events(msg.rx, msg.inner.connection_id, msg.inner.request_id); } ``` -------------------------------- ### Handle Get Many Request Received Event Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider/events.rs.html?search=std%3A%3Avec Processes a `GetManyRequestReceived` message, sends an acknowledgment, and starts logging request events. ```rust ProviderMessage::GetManyRequestReceived(msg) => { trace!(%connection_id, %request_id, "{:?}", msg.inner); msg.tx.send(Ok(())).await.ok(); log_request_events(msg.rx, msg.inner.connection_id, msg.inner.request_id); } ``` -------------------------------- ### Example: Product of Parsed Numbers from Strings Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/type.ExportBaoResult.html This example shows how to use the `product` method to multiply numbers parsed from a vector of strings. It demonstrates both a successful multiplication and a case where parsing fails, resulting in an `Err`. ```rust let nums = vec!["5", "10", "1", "2"]; let total: Result = nums.iter().map(|w| w.parse::()).product(); assert_eq!(total, Ok(100)); let nums = vec!["5", "10", "one", "2"]; let total: Result = nums.iter().map(|w| w.parse::()).product(); assert!(total.is_err()); ``` -------------------------------- ### DownloadRequest::new Constructor Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/type.DownloadOptions.html Shows how to create a new DownloadRequest instance, which is aliased as DownloadOptions. ```APIDOC ### impl DownloadRequest #### pub fn new( request: impl SupportedRequest, providers: impl ContentDiscovery, strategy: SplitStrategy, ) -> Self Creates a new `DownloadRequest`. ``` -------------------------------- ### RangeSpec wire format: Chunks from 64 onwards Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/protocol/range_spec.rs.html Example of the wire format for a RangeSpec representing chunks starting from chunk 64. ```rust ( RangeSpec::new(ChunkRanges::chunks(64..)), r" 01 # length prefix - 1 element 40 # span width - 64. everything starting from 64 is included ", ), ``` -------------------------------- ### Example Search Queries Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/type.RequestResult.html?search= Demonstrates common patterns for search queries. ```text Example searches: * std::vec * u32 -> bool * Option, (T -> U) -> Option ``` -------------------------------- ### Read Collection from FSM Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/format/collection/struct.Collection.html Reads a collection from a get FSM. Returns the FSM at the start of the first child blob, the links array, and the collection itself. ```rust pub async fn read_fsm( fsm_at_start_root: AtStartRoot, ) -> Result<(EndBlobNext, HashSeq, Collection)> ``` -------------------------------- ### Downloader Initialization with Options Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a new Downloader instance with specified connection pool options. Use this to configure the underlying connection pool for the downloader. ```rust pub fn new_with_opts( store: &Store, endpoint: &Endpoint, pool_options: crate::util::connection_pool::Options, ) -> Self { let (tx, rx) = tokio::sync::mpsc::channel::(32); let actor = DownloaderActor::new_with_opts(store.clone(), endpoint.clone(), pool_options); n0_future::task::spawn(actor.run(rx)); Self { client: tx.into() } } ``` -------------------------------- ### Collection read_fsm Method Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/format/collection.rs.html?search=std%3A%3Avec Reads a collection from a get FSM. It parses the links and returns the FSM at the start of the next child, the parsed `HashSeq`, and the `Collection`. ```rust pub async fn read_fsm( fsm_at_start_root: fsm::AtStartRoot, ) -> Result<(fsm::EndBlobNext, HashSeq, Collection)> { let (next, links) = { let curr = fsm_at_start_root.next(); let (curr, data) = curr.concatenate_into_vec().await?; let links = HashSeq::new(data.into()) .ok_or_else(|| n0_error::anyerr!("links could not be parsed"))?; (curr.next(), links) }; let fsm::EndBlobNext::MoreChildren(at_meta) = next else { n0_error::bail_any!("expected meta"); }; } ``` -------------------------------- ### AtStartRoot Struct Definition Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/struct.AtStartRoot.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Defines the AtStartRoot struct, which holds the state for the get response when starting to read a collection. It is generic over R, which must implement RecvStream. ```rust pub struct AtStartRoot { /* private fields */ } ``` -------------------------------- ### Collection::read_fsm Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/format/collection/struct.Collection.html?search=u32+-%3E+bool Reads a collection from a get FSM (Finite State Machine). It returns the FSM at the start of the first child blob (if any), the links array, and the collection itself. ```APIDOC ## Collection::read_fsm ### Description Read the collection from a get fsm. Returns the fsm at the start of the first child blob (if any), the links array, and the collection. ### Signature ```rust pub async fn read_fsm( fsm_at_start_root: AtStartRoot, ) -> Result<(EndBlobNext, HashSeq, Collection)> ``` ``` -------------------------------- ### Download Single Blob with Options Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html?search= Demonstrates downloading a single blob using `download_with_opts`. This example sets up two nodes, adds large slices to them, and then uses the `Downloader` to retrieve a `HashSeq` that references these slices. It utilizes `DownloadOptions` to specify the request, sources, and `SplitStrategy`. ```rust #[tokio::test] async fn downloader_get_smoke() -> TestResult<()> { // tracing_subscriber::fmt::try_init().ok(); let testdir = tempfile::tempdir()?; let (r1, store1, _, _) = node_test_setup_fs(testdir.path().join("a")).await?; let (r2, store2, _, _) = node_test_setup_fs(testdir.path().join("b")).await?; let (r3, store3, _, sp3) = node_test_setup_fs(testdir.path().join("c")).await?; let tt1 = store1.add_slice(vec![1; 10000000]).await?; let tt2 = store2.add_slice(vec![2; 10000000]).await?; let hs = [tt1.hash, tt2.hash].into_iter().collect::(); let root = store1 .add_bytes_with_opts(AddBytesOptions { data: hs.clone().into(), format: crate::BlobFormat::HashSeq, }) .await?; let node1_addr = r1.endpoint().addr(); let node1_id = node1_addr.id; let node2_addr = r2.endpoint().addr(); let node2_id = node2_addr.id; let swarm = Downloader::new(&store3, r3.endpoint()); sp3.add_endpoint_info(node1_addr.clone()); sp3.add_endpoint_info(node2_addr.clone()); let request = GetRequest::builder() .root(ChunkRanges::all()) .next(ChunkRanges::all()) .next(ChunkRanges::all()) .build(root.hash); if true { let mut progress = swarm .download_with_opts(DownloadOptions::new( request, [node1_id, node2_id], SplitStrategy::Split, )) .stream() .await?; while progress.next().await.is_some() {} } if false { let conn = r3.endpoint().connect(node1_addr, crate::ALPN).await?; let remote = store3.remote(); let _rh = remote .execute_get( conn.clone(), GetRequest::builder() .root(ChunkRanges::all()) .build(root.hash), ) .await?; let h1 = remote.execute_get( conn.clone(), GetRequest::builder() .child(0, ChunkRanges::all()) ``` -------------------------------- ### Possible Next States After Handshake Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search=u32+-%3E+bool Enumerates the possible states the get response machine can transition to after the handshake is sent. This includes starting with a root collection, a child, or if the request is empty. ```rust pub enum ConnectedNext { /// First response is either a collection or a single blob StartRoot(AtStartRoot), /// First response is a child StartChild(AtStartChild), /// Request is empty Closing(AtClosing), } ``` -------------------------------- ### Initialize and Test FsStore Batch Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/fs.rs.html?search=u32+-%3E+bool Sets up an FsStore in a temporary directory and runs the test_batch function. ```rust #[tokio::test] async fn test_batch_fs() -> TestResult<()> { tracing_subscriber::fmt::try_init().ok(); let testdir = tempfile::tempdir()?; let db_dir = testdir.path().join("db"); let store = FsStore::load(db_dir).await?; test_batch(&store).await } ``` -------------------------------- ### AtInitial::next Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/struct.AtInitial.html Initiates a new bidi stream to use for the get response. ```APIDOC ## AtInitial::next ### Description Initiate a new bidi stream to use for the get response ### Signature ```rust pub async fn next(self) -> Result ``` ``` -------------------------------- ### Collection::read_fsm Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/format/collection/struct.Collection.html?search= Reads a collection from a get FSM (Finite State Machine). It returns the FSM state at the start of the first child blob, the links array, and the collection itself. This is useful for incrementally reading collection data. ```APIDOC ## Collection::read_fsm ### Description Reads the collection from a get fsm. Returns the fsm at the start of the first child blob (if any), the links array, and the collection. ### Method ```rust pub async fn read_fsm( fsm_at_start_root: AtStartRoot, ) -> Result<(EndBlobNext, HashSeq, Collection)> ``` ### Parameters #### Path Parameters * `fsm_at_start_root` (AtStartRoot) - The FSM state at the start of the root blob. ### Returns A `Result` containing a tuple: `(EndBlobNext, HashSeq, Collection)` on success, or an error. * `EndBlobNext`: The FSM state at the start of the next blob (if any). * `HashSeq`: The sequence of hashes representing the collection's links. * `Collection`: The deserialized collection object. ``` -------------------------------- ### Create Downloader with Store and Endpoint Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html Initializes a new Downloader instance using a provided Store and Endpoint. This is the basic constructor. ```rust pub fn new(store: &Store, endpoint: &Endpoint) -> Self ``` -------------------------------- ### CompleteStorage::new Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/store/mem/struct.CompleteStorage.html Initializes a new CompleteStorage instance with the provided data and outboard. ```APIDOC ## CompleteStorage::new ### Description Initializes a new CompleteStorage instance with the provided data and outboard. ### Signature ```rust pub fn new(data: Bytes, outboard: Bytes) -> Self ``` ### Parameters * `data` (Bytes) - The main data to be stored. * `outboard` (Bytes) - Additional outboard data. ``` -------------------------------- ### Initialize Get Request State Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search=u32+-%3E+bool Use this to create the initial state for a get request. It requires an active connection, the get request details, and request counters. ```rust pub struct AtInitial { connection: Connection, request: GetRequest, counters: RequestCounters, } impl AtInitial { /// Create a new get response /// /// `connection` is an existing connection /// `request` is the request to be sent pub fn new(connection: Connection, request: GetRequest, counters: RequestCounters) -> Self { Self { connection, request, counters, } } /// Initiate a new bidi stream to use for the get response pub async fn next(self) -> Result { let start = Instant::now(); let (writer, reader) = self .connection .open_bi() .await .map_err(|e| e!(InitialNextError::Open, e.into()))?; Ok(AtConnected { start, reader, writer, request: self.request, counters: self.counters, }) } } ``` -------------------------------- ### Downloader NewWithOpts Constructor Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html Creates a new `Downloader` instance with customizable connection pool options. ```rust pub fn new_with_opts( store: &Store, endpoint: &Endpoint, pool_options: crate::util::connection_pool::Options, ) -> Self { let (tx, rx) = tokio::sync::mpsc::channel::(32); let actor = DownloaderActor::new_with_opts(store.clone(), endpoint.clone(), pool_options); n0_future::task::spawn(actor.run(rx)); Self { client: tx.into() } } ``` -------------------------------- ### Options::new Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/store/fs/options/struct.Options.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates new Options with the given root path and default settings for all other options. ```APIDOC ## `new` Method ### Description Create new optinos with the given root path and everything else default. ### Signature ```rust pub fn new(root: &Path) -> Self ``` ``` -------------------------------- ### Create Options with default values Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/fs/options.rs.html?search=std%3A%3Avec Initializes `Options` with default path, inline, and batch settings, and no garbage collection configuration. ```rust pub fn new(root: &Path) -> Self { Self { path: PathOptions::new(root), inline: InlineOptions::default(), batch: BatchOptions::default(), gc: None, } } ``` -------------------------------- ### Get Struct Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/fs/meta/proto.rs.html Represents a request to get the entry state for a specific hash. ```APIDOC /// Get the entry state for a hash. /// /// This will read from the blobs table and enrich the result with the content /// of the inline data and inline outboard tables if necessary. pub struct Get { pub hash: Hash, pub tx: oneshot::Sender, pub span: Span, } impl fmt::Debug for Get ``` -------------------------------- ### Using expect with a recommended message style for environment variables Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/type.ExportBaoResult.html?search=u32+-%3E+bool This example demonstrates the recommended usage of `expect` for environment variables, emphasizing the 'should' phrasing to indicate expected conditions. ```rust let path = std::env::var("IMPORTANT_PATH") .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); ``` -------------------------------- ### init Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/enum.FiniteRequest.html?search=u32+-%3E+bool Initializes a with the given initializer. ```APIDOC ## unsafe fn init(init: ::Init) -> usize ### Description Initializes a with the given initializer. ### Signature ```rust unsafe fn init(init: ::Init) -> usize ``` ``` -------------------------------- ### Example Searches Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/type.ExportBaoResult.html?search= These are example search queries demonstrating different patterns for searching within the API. They include searching for specific types like std::vec, type conversions like u32 -> bool, and generic transformations like Option, (T -> U) -> Option. ```text * std::vec * u32 -> bool * Option, (T -> U) -> Option ``` -------------------------------- ### Handle Finite and Infinite Get Requests Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/api/downloader.rs.html Processes incoming `FiniteRequest`s, distinguishing between `Get` and `GetMany`. For `Get` requests, it determines the number of chunks and generates `GetRequest`s for each range. For `GetMany`, it creates `GetRequest`s for each hash and its corresponding ranges. ```rust Ok(match request { FiniteRequest::Get(req) => { let Some(_first) = req.ranges.iter_infinite().next() else { return Ok(Box::new(std::iter::empty())); }; let first = GetRequest::blob(req.hash); execute_get(pool, Arc::new(first), providers, store, progress).await?; let size = store.observe(req.hash).await?.size(); n0_error::ensure_any!(size % 32 == 0, "Size is not a multiple of 32"); let n = size / 32; Box::new( req.ranges .iter_infinite() .take(n as usize + 1) .enumerate() .filter_map(|(i, ranges)| { if i != 0 && !ranges.is_empty() { Some( GetRequest::builder() .offset(i as u64, ranges.clone()) .build(req.hash), ) } else { None } }), ) } FiniteRequest::GetMany(req) => Box::new( req.hashes .iter() .enumerate() .map(|(i, hash)| GetRequest::blob_ranges(*hash, req.ranges[i as u64].clone())), ), }) } ``` -------------------------------- ### Options: New with Default Settings Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/fs/options.rs.html?search=u32+-%3E+bool Creates new file store options with default inline and batch settings, and no garbage collection, based on a root path. ```rust pub fn new(root: &Path) -> Self { Self { path: PathOptions::new(root), inline: InlineOptions::default(), batch: BatchOptions::default(), gc: None, } } ``` -------------------------------- ### Get Request Tracker Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/provider/struct.StreamPair.html Asynchronously retrieves a RequestTracker for a 'get' request. It takes a closure that returns a GetRequest. ```rust pub async fn get_request( &self, f: impl FnOnce() -> GetRequest, ) -> Result ``` -------------------------------- ### Downloader::new_with_opts Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html Creates a new Downloader instance with specified store, endpoint, and options. ```APIDOC ## Downloader::new_with_opts ### Description Creates a new Downloader instance with specified store, endpoint, and options. ### Signature ```rust pub fn new_with_opts( store: &Store, endpoint: &Endpoint, pool_options: Options, ) -> Self ``` ### Parameters * **store**: A reference to the `Store`. * **endpoint**: A reference to the `Endpoint`. * **pool_options**: The `Options` for the downloader's pool. ``` -------------------------------- ### Provider Get Request Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider.rs.html Initiates a 'get' request, passing a closure that creates the request to the event system for processing. ```rust pub async fn get_request( &self, f: impl FnOnce() -> GetRequest, ) -> Result { self.events .request(f, self.connection_id, self.reader.id()) .await } ``` -------------------------------- ### Initialize Iroh Blobs Metadata Database Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/store/fs/meta.rs.html?search= Creates or opens the metadata database. Handles potential upgrade requirements and initializes tables if the database is new. Returns an error if migration from an older redb version is required. ```rust pub fn new( db_path: PathBuf, cmds: tokio::sync::mpsc::Receiver, mut ds: DeleteHandle, options: BatchOptions, ) -> Result { debug!("creating or opening meta database at {}", db_path.display()); let db = match redb::Database::create(db_path) { Ok(db) => db, Err(DatabaseError::UpgradeRequired(v)) => { return Err(anyerr!( "migration from redb v{v} no longer supported; \\ upgrade with an older redb version first" ) .into()); } Err(err) => return Err(err.into()), }; let tx = db.begin_write()?; let ftx = ds.begin_write(); Tables::new(&tx, &ftx)?; tx.commit()?; drop(ftx); let cmds = PeekableReceiver::new(cmds); Ok(Self { db, cmds, ds, options, protected: Default::default(), }) } ``` -------------------------------- ### Open Connection for Get Response Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/get.rs.html?search= Opens a bidirectional stream for the get response. This transitions the state from `AtInitial` to `AtConnected`. ```rust pub async fn next(self) -> Result { let start = Instant::now(); let (writer, reader) = self .connection .open_bi() .await .map_err(|e| e!(InitialNextError::Open, e.into()))?; Ok(AtConnected { start, reader, writer, request: self.request, counters: self.counters, }) } ``` -------------------------------- ### get::Stats::equivalent Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/provider/struct.StreamPair.html?search=u32+-%3E+bool Checks if get::Stats is equivalent to another type `K` where `u32` matches `K`. ```APIDOC ## iroh_blobs::get::Stats::equivalent ### Description Checks if get::Stats is equivalent to another type `K` where `u32` matches `K`. ### Method `equivalent` ### Signature `&self, &K -> bool` where `u32` matches `K` ``` -------------------------------- ### Downloader::new_with_opts Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.Downloader.html?search=u32+-%3E+bool Creates a new Downloader instance with specified options. ```APIDOC ## Downloader::new_with_opts ### Description Creates a new Downloader instance with the provided store, endpoint, and pool options. ### Signature `pub fn new_with_opts(store: &Store, endpoint: &Endpoint, pool_options: Options) -> Self` ### Parameters * `store`: A reference to the `Store`. * `endpoint`: A reference to the `Endpoint`. * `pool_options`: The `Options` for the download pool. ### Returns A new `Downloader` instance. ``` -------------------------------- ### Finish Get Response Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/struct.AtBlobContent.html Immediately finishes the get response without reading any further content. Transitions the state to AtClosing. ```rust pub fn finish(self) -> AtClosing ``` -------------------------------- ### load Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/format/collection.rs.html?search= Creates a new collection from a hash sequence and metadata stored in a `SimpleStore`. ```APIDOC ## load ### Description Create a new collection from a hash sequence and metadata. ### Parameters #### Path Parameters - `root` (Hash) - The root hash of the collection. - `store` (&impl SimpleStore) - The store to load the collection from. ### Returns - `Result` - The loaded collection. ### Example ```rust let collection = Collection::load(root, &store).await?; ``` ``` -------------------------------- ### start_get_many Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/get/fsm/fn.start_get_many.html?search= Initiates a get many request. This function is part of the state machine for handling 'get many' operations. ```APIDOC ## start_get_many ### Description Starts with a get many request. Todo: turn this into distinct states. ### Signature ```rust pub async fn start_get_many( connection: Connection, request: GetManyRequest, counters: RequestCounters, ) -> Result, GetError> ``` ### Parameters * `connection`: Connection - The connection to use for the request. * `request`: GetManyRequest - The details of the get many request. * `counters`: RequestCounters - Counters to track request metrics. ### Returns * `Result, GetError>` - On success, returns a nested Result indicating the initial state or closing state of the operation. On failure, returns a GetError. ``` -------------------------------- ### WriterContext Transfer Started Notification Source: https://docs.rs/iroh-blobs/latest/src/iroh_blobs/provider.rs.html Notifies the writer context that a transfer has started. It reports the transfer details to the tracker. ```rust async fn send_transfer_started(&mut self, index: u64, hash: &Hash, size: u64) { self.tracker.transfer_started(index, hash, size).await.ok(); } ``` -------------------------------- ### Remote::execute_get_with_opts Source: https://docs.rs/iroh-blobs/latest/iroh_blobs/api/remote/struct.Remote.html?search= Executes a get request with options over a given connection, returning a progress tracker. ```APIDOC ## Remote::execute_get_with_opts ### Description Executes a get request with options over a given connection, returning a progress tracker. This provides more control over the data retrieval process. ### Method `fn` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response - **GetProgress**: An object that tracks the progress of the get operation. ### Response Example None ```