iroh_blobs/rpc/proto/
blobs.rs

1//! RPC requests and responses for the blob service.
2use std::path::PathBuf;
3
4use bytes::Bytes;
5use nested_enum_utils::enum_conversions;
6use quic_rpc_derive::rpc_requests;
7use serde::{Deserialize, Serialize};
8
9use super::{RpcError, RpcResult, RpcService};
10use crate::{
11    export::ExportProgress,
12    format::collection::Collection,
13    get::db::DownloadProgress,
14    net_protocol::{BatchId, BlobDownloadRequest},
15    provider::{AddProgress, BatchAddPathProgress},
16    rpc::client::blobs::{BlobInfo, BlobStatus, IncompleteBlobInfo, ReadAtLen, WrapOption},
17    store::{
18        BaoBlobSize, ConsistencyCheckProgress, ExportFormat, ExportMode, ImportMode,
19        ValidateProgress,
20    },
21    util::SetTagOption,
22    BlobFormat, Hash, HashAndFormat, Tag,
23};
24
25#[allow(missing_docs)]
26#[derive(strum::Display, Debug, Serialize, Deserialize)]
27#[enum_conversions(super::Request)]
28#[rpc_requests(RpcService)]
29pub enum Request {
30    #[server_streaming(response = RpcResult<ReadAtResponse>)]
31    ReadAt(ReadAtRequest),
32    #[bidi_streaming(update = AddStreamUpdate, response = AddStreamResponse)]
33    AddStream(AddStreamRequest),
34    AddStreamUpdate(AddStreamUpdate),
35    #[server_streaming(response = AddPathResponse)]
36    AddPath(AddPathRequest),
37    #[server_streaming(response = DownloadResponse)]
38    Download(BlobDownloadRequest),
39    #[server_streaming(response = ExportResponse)]
40    Export(ExportRequest),
41    #[server_streaming(response = RpcResult<BlobInfo>)]
42    List(ListRequest),
43    #[server_streaming(response = RpcResult<IncompleteBlobInfo>)]
44    ListIncomplete(ListIncompleteRequest),
45    #[rpc(response = RpcResult<()>)]
46    Delete(DeleteRequest),
47    #[server_streaming(response = ValidateProgress)]
48    Validate(ValidateRequest),
49    #[server_streaming(response = ConsistencyCheckProgress)]
50    Fsck(ConsistencyCheckRequest),
51    #[rpc(response = RpcResult<CreateCollectionResponse>)]
52    CreateCollection(CreateCollectionRequest),
53    #[rpc(response = RpcResult<BlobStatusResponse>)]
54    BlobStatus(BlobStatusRequest),
55
56    #[bidi_streaming(update = BatchUpdate, response = BatchCreateResponse)]
57    BatchCreate(BatchCreateRequest),
58    BatchUpdate(BatchUpdate),
59    #[bidi_streaming(update = BatchAddStreamUpdate, response = BatchAddStreamResponse)]
60    BatchAddStream(BatchAddStreamRequest),
61    BatchAddStreamUpdate(BatchAddStreamUpdate),
62    #[server_streaming(response = BatchAddPathResponse)]
63    BatchAddPath(BatchAddPathRequest),
64    #[rpc(response = RpcResult<()>)]
65    BatchCreateTempTag(BatchCreateTempTagRequest),
66}
67
68#[allow(missing_docs)]
69#[derive(strum::Display, Debug, Serialize, Deserialize)]
70#[enum_conversions(super::Response)]
71pub enum Response {
72    ReadAt(RpcResult<ReadAtResponse>),
73    AddStream(AddStreamResponse),
74    AddPath(AddPathResponse),
75    List(RpcResult<BlobInfo>),
76    ListIncomplete(RpcResult<IncompleteBlobInfo>),
77    Download(DownloadResponse),
78    Fsck(ConsistencyCheckProgress),
79    Export(ExportResponse),
80    Validate(ValidateProgress),
81    CreateCollection(RpcResult<CreateCollectionResponse>),
82    BlobStatus(RpcResult<BlobStatusResponse>),
83    BatchCreate(BatchCreateResponse),
84    BatchAddStream(BatchAddStreamResponse),
85    BatchAddPath(BatchAddPathResponse),
86}
87
88/// A request to the node to provide the data at the given path
89///
90/// Will produce a stream of [`AddProgress`] messages.
91#[derive(Debug, Serialize, Deserialize)]
92pub struct AddPathRequest {
93    /// The path to the data to provide.
94    ///
95    /// This should be an absolute path valid for the file system on which
96    /// the node runs. Usually the cli will run on the same machine as the
97    /// node, so this should be an absolute path on the cli machine.
98    pub path: PathBuf,
99    /// True if the provider can assume that the data will not change, so it
100    /// can be shared in place.
101    pub in_place: bool,
102    /// Tag to tag the data with.
103    pub tag: SetTagOption,
104    /// Whether to wrap the added data in a collection
105    pub wrap: WrapOption,
106}
107
108/// Wrapper around [`AddProgress`].
109#[derive(Debug, Serialize, Deserialize, derive_more::Into)]
110pub struct AddPathResponse(pub AddProgress);
111
112/// Progress response for [`BlobDownloadRequest`]
113#[derive(Debug, Clone, Serialize, Deserialize, derive_more::From, derive_more::Into)]
114pub struct DownloadResponse(pub DownloadProgress);
115
116/// A request to the node to download and share the data specified by the hash.
117#[derive(Debug, Clone, Serialize, Deserialize)]
118pub struct ExportRequest {
119    /// The hash of the blob to export.
120    pub hash: Hash,
121    /// The filepath to where the data should be saved
122    ///
123    /// This should be an absolute path valid for the file system on which
124    /// the node runs.
125    pub path: PathBuf,
126    /// Set to [`ExportFormat::Collection`] if the `hash` refers to a [`Collection`] and you want
127    /// to export all children of the collection into individual files.
128    pub format: ExportFormat,
129    /// The mode of exporting.
130    ///
131    /// The default is [`ExportMode::Copy`]. See [`ExportMode`] for details.
132    pub mode: ExportMode,
133}
134
135/// Progress response for [`ExportRequest`]
136#[derive(Debug, Clone, Serialize, Deserialize, derive_more::From, derive_more::Into)]
137pub struct ExportResponse(pub ExportProgress);
138
139/// A request to the node to validate the integrity of all provided data
140#[derive(Debug, Serialize, Deserialize)]
141pub struct ConsistencyCheckRequest {
142    /// repair the store by dropping inconsistent blobs
143    pub repair: bool,
144}
145
146/// A request to the node to validate the integrity of all provided data
147#[derive(Debug, Serialize, Deserialize)]
148pub struct ValidateRequest {
149    /// repair the store by downgrading blobs from complete to partial
150    pub repair: bool,
151}
152
153/// List all blobs, including collections
154#[derive(Debug, Serialize, Deserialize)]
155pub struct ListRequest;
156
157/// List all blobs, including collections
158#[derive(Debug, Serialize, Deserialize)]
159pub struct ListIncompleteRequest;
160
161/// Get the bytes for a hash
162#[derive(Serialize, Deserialize, Debug)]
163pub struct ReadAtRequest {
164    /// Hash to get bytes for
165    pub hash: Hash,
166    /// Offset to start reading at
167    pub offset: u64,
168    /// Length of the data to get
169    pub len: ReadAtLen,
170}
171
172/// Response to [`ReadAtRequest`]
173#[derive(Serialize, Deserialize, Debug)]
174pub enum ReadAtResponse {
175    /// The entry header.
176    Entry {
177        /// The size of the blob
178        size: BaoBlobSize,
179        /// Whether the blob is complete
180        is_complete: bool,
181    },
182    /// Chunks of entry data.
183    Data {
184        /// The data chunk
185        chunk: Bytes,
186    },
187}
188
189/// Write a blob from a byte stream
190#[derive(Serialize, Deserialize, Debug)]
191pub struct AddStreamRequest {
192    /// Tag to tag the data with.
193    pub tag: SetTagOption,
194}
195
196/// Write a blob from a byte stream
197#[derive(Serialize, Deserialize, Debug)]
198pub enum AddStreamUpdate {
199    /// A chunk of stream data
200    Chunk(Bytes),
201    /// Abort the request due to an error on the client side
202    Abort,
203}
204
205/// Wrapper around [`AddProgress`].
206#[derive(Debug, Serialize, Deserialize, derive_more::Into)]
207pub struct AddStreamResponse(pub AddProgress);
208
209/// Delete a blob
210#[derive(Debug, Serialize, Deserialize)]
211pub struct DeleteRequest {
212    /// Name of the tag
213    pub hash: Hash,
214}
215
216/// Create a collection.
217#[derive(Debug, Serialize, Deserialize)]
218pub struct CreateCollectionRequest {
219    /// The collection
220    pub collection: Collection,
221    /// Tag option.
222    pub tag: SetTagOption,
223    /// Tags that should be deleted after creation.
224    pub tags_to_delete: Vec<Tag>,
225}
226
227/// A response to a create collection request
228#[derive(Debug, Serialize, Deserialize)]
229pub struct CreateCollectionResponse {
230    /// The resulting hash.
231    pub hash: Hash,
232    /// The resulting tag.
233    pub tag: Tag,
234}
235
236/// Request to get the status of a blob
237#[derive(Debug, Serialize, Deserialize)]
238pub struct BlobStatusRequest {
239    /// The hash of the blob
240    pub hash: Hash,
241}
242
243/// The response to a status request
244#[derive(Debug, Serialize, Deserialize, derive_more::From, derive_more::Into)]
245pub struct BlobStatusResponse(pub BlobStatus);
246
247/// Request to create a new scope for temp tags
248#[derive(Debug, Serialize, Deserialize)]
249pub struct BatchCreateRequest;
250
251/// Update to a temp tag scope
252#[derive(Debug, Serialize, Deserialize)]
253pub enum BatchUpdate {
254    /// Drop of a remote temp tag
255    Drop(HashAndFormat),
256    /// Message to check that the connection is still alive
257    Ping,
258}
259
260/// Response to a temp tag scope request
261#[derive(Debug, Serialize, Deserialize)]
262pub enum BatchCreateResponse {
263    /// We got the id of the scope
264    Id(BatchId),
265}
266
267/// Create a temp tag with a given hash and format
268#[derive(Debug, Serialize, Deserialize)]
269pub struct BatchCreateTempTagRequest {
270    /// Content to protect
271    pub content: HashAndFormat,
272    /// Batch to create the temp tag in
273    pub batch: BatchId,
274}
275
276/// Write a blob from a byte stream
277#[derive(Serialize, Deserialize, Debug)]
278pub struct BatchAddStreamRequest {
279    /// What format to use for the blob
280    pub format: BlobFormat,
281    /// Batch to create the temp tag in
282    pub batch: BatchId,
283}
284
285/// Write a blob from a byte stream
286#[derive(Serialize, Deserialize, Debug)]
287pub enum BatchAddStreamUpdate {
288    /// A chunk of stream data
289    Chunk(Bytes),
290    /// Abort the request due to an error on the client side
291    Abort,
292}
293
294/// Wrapper around [`AddProgress`].
295#[allow(missing_docs)]
296#[derive(Debug, Serialize, Deserialize)]
297pub enum BatchAddStreamResponse {
298    Abort(RpcError),
299    OutboardProgress { offset: u64 },
300    Result { hash: Hash },
301}
302
303/// Write a blob from a byte stream
304#[derive(Serialize, Deserialize, Debug)]
305pub struct BatchAddPathRequest {
306    /// The path to the data to provide.
307    pub path: PathBuf,
308    /// Add the data in place
309    pub import_mode: ImportMode,
310    /// What format to use for the blob
311    pub format: BlobFormat,
312    /// Batch to create the temp tag in
313    pub batch: BatchId,
314}
315
316/// Response to a batch add path request
317#[derive(Serialize, Deserialize, Debug)]
318pub struct BatchAddPathResponse(pub BatchAddPathProgress);
iroh_blobs/rpc/proto/blobs.rs

iroh_blobs/rpc/proto/
blobs.rs
