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 chunks_stream;
33mod data;
34mod feeds;
35mod soc;
36mod stream;
37
38pub use bzz::{
39 CollectionEntry, collection_size, hash_collection_entries, hash_directory,
40 read_directory_entries,
41};
42pub use chunks_stream::ChunkStream;
43pub use data::ReferenceInformation;
44pub use feeds::{
45 FeedReader, FeedUpdate, FeedWriter, feed_update_chunk_reference, make_feed_identifier,
46};
47pub use soc::{SocReader, SocWriter, soc_address};
48pub use stream::{OnStreamProgressFn, StreamProgress};
49
50use std::sync::Arc;
51
52use crate::client::Inner;
53
54/// Handle exposing the file/data/chunk endpoints. Cheap to clone
55/// (holds an `Arc<Inner>`).
56#[derive(Clone, Debug)]
57pub struct FileApi {
58 pub(crate) inner: Arc<Inner>,
59}
60
61impl FileApi {
62 pub(crate) fn new(inner: Arc<Inner>) -> Self {
63 Self { inner }
64 }
65}