bee/file/mod.rs
1//! File / data / chunk / SOC / feed / collection uploads and
2//! downloads. Mirrors `pkg/file` in bee-go.
3//!
4//! Get a [`FileApi`] from [`crate::Client::file`].
5//!
6//! # Streaming vs. buffered transfers
7//!
8//! [`FileApi::download_data`] / [`FileApi::download_file`] buffer the
9//! full body into [`bytes::Bytes`] before returning — fine for ≤ a few
10//! hundred MB but will OOM on multi-GB references. For larger
11//! downloads, use [`FileApi::download_data_response`] (or
12//! `download_file_response`) which returns the raw [`reqwest::Response`]
13//! so you can drive [`reqwest::Response::bytes_stream`] yourself.
14//!
15//! Uploads accept `impl Into<Bytes>` and stream the body to Bee. The
16//! chunk-by-chunk variants ([`FileApi::stream_directory`] and
17//! [`FileApi::stream_collection_entries`]) bound peak memory at the
18//! BMT chunk size regardless of file size and report progress via a
19//! caller-supplied [`OnStreamProgressFn`].
20//!
21//! # Cancellation
22//!
23//! Dropping the future returned by any upload / download cancels the
24//! in-flight HTTP request. For [`FileApi::stream_directory`] and
25//! [`FileApi::stream_collection_entries`], chunks already accepted by
26//! the local Bee node remain in the local reserve but the manifest is
27//! not finalized — the resulting orphan chunks are eventually pruned
28//! but cost reserve space until then.
29
30mod bzz;
31mod chunk;
32mod data;
33mod feeds;
34mod soc;
35mod stream;
36
37pub use bzz::{
38 CollectionEntry, collection_size, hash_collection_entries, hash_directory,
39 read_directory_entries,
40};
41pub use data::ReferenceInformation;
42pub use feeds::{
43 FeedReader, FeedUpdate, FeedWriter, feed_update_chunk_reference, make_feed_identifier,
44};
45pub use soc::{SocReader, SocWriter, soc_address};
46pub use stream::{OnStreamProgressFn, StreamProgress};
47
48use std::sync::Arc;
49
50use crate::client::Inner;
51
52/// Handle exposing the file/data/chunk endpoints. Cheap to clone
53/// (holds an `Arc<Inner>`).
54#[derive(Clone, Debug)]
55pub struct FileApi {
56 pub(crate) inner: Arc<Inner>,
57}
58
59impl FileApi {
60 pub(crate) fn new(inner: Arc<Inner>) -> Self {
61 Self { inner }
62 }
63}