rust_unixfs/dir/
builder.rs

1use core::fmt;
2use ipld_core::cid::Cid;
3
4mod dir_builder;
5use dir_builder::DirBuilder;
6
7mod iter;
8pub use iter::{OwnedTreeNode, PostOrderIterator, TreeNode};
9
10mod buffered;
11pub use buffered::BufferingTreeBuilder;
12
13mod custom_pb;
14use custom_pb::CustomFlatUnixFs;
15
16enum Entry {
17    Leaf(Leaf),
18    Directory(DirBuilder),
19}
20
21impl fmt::Debug for Entry {
22    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
23        use Entry::*;
24
25        match self {
26            Leaf(leaf) => write!(fmt, "Leaf {{ {leaf:?} }}"),
27            Directory(_) => write!(fmt, "DirBuilder {{ .. }}"),
28        }
29    }
30}
31
32impl Entry {
33    fn as_dir_builder(&mut self) -> Result<&mut DirBuilder, ()> {
34        use Entry::*;
35        match self {
36            Directory(ref mut d) => Ok(d),
37            _ => Err(()),
38        }
39    }
40}
41
42struct Leaf {
43    link: Cid,
44    total_size: u64,
45}
46
47impl fmt::Debug for Leaf {
48    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
49        write!(fmt, "{}, {}", self.link, self.total_size)
50    }
51}
52
53/// Configuration for customizing how the tree is built.
54#[derive(Debug, Clone)]
55pub struct TreeOptions {
56    block_size_limit: Option<u64>,
57    wrap_with_directory: bool,
58}
59
60impl Default for TreeOptions {
61    fn default() -> Self {
62        TreeOptions {
63            block_size_limit: Some(512 * 1024),
64            wrap_with_directory: false,
65        }
66    }
67}
68
69impl TreeOptions {
70    /// Overrides the default directory block size limit. If the size limit is set to `None`, no
71    /// directory will be too large.
72    pub fn block_size_limit(&mut self, limit: Option<u64>) {
73        self.block_size_limit = limit;
74    }
75
76    /// When true, allow multiple top level entries, otherwise error on the second entry.
77    /// Defaults to false.
78    pub fn wrap_with_directory(&mut self) {
79        self.wrap_with_directory = true;
80    }
81}
82
83/// Tree building failure cases.
84#[derive(Debug)]
85pub enum TreeBuildingFailed {
86    /// The given full path started with a slash; paths in the `/add` convention are not rooted.
87    RootedPath(String),
88    /// The given full path contained an empty segment.
89    RepeatSlashesInPath(String),
90    /// The given full path ends in slash.
91    PathEndsInSlash(String),
92    /// If the `BufferingTreeBuilder` was created without `TreeOptions` with the option
93    /// `wrap_with_directory` enabled, then there can be only a single element at the root.
94    TooManyRootLevelEntries,
95    /// The given full path had already been added.
96    DuplicatePath(String),
97    /// The given full path had already been added as a link to an opaque entry.
98    LeafAsDirectory(String),
99}
100
101impl fmt::Display for TreeBuildingFailed {
102    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
103        use TreeBuildingFailed::*;
104
105        match self {
106            RootedPath(s) => write!(fmt, "path is rooted: {s:?}"),
107            RepeatSlashesInPath(s) => write!(fmt, "path contains repeat slashes: {s:?}"),
108            PathEndsInSlash(s) => write!(fmt, "path ends in a slash: {s:?}"),
109            TooManyRootLevelEntries => write!(
110                fmt,
111                "multiple root level entries while configured wrap_with_directory = false"
112            ),
113            // TODO: perhaps we should allow adding two leafs with the same Cid?
114            DuplicatePath(s) => write!(fmt, "path exists already: {s:?}"),
115            LeafAsDirectory(s) => write!(
116                fmt,
117                "attempted to use already added leaf as a subdirectory: {s:?}"
118            ),
119        }
120    }
121}
122
123impl std::error::Error for TreeBuildingFailed {}
124
125/// Failure cases for `PostOrderIterator` creating the tree dag-pb nodes.
126#[derive(Debug)]
127pub enum TreeConstructionFailed {
128    /// Failed to serialize the protobuf node for the directory
129    Protobuf(quick_protobuf::Error),
130    /// The resulting directory would be too large and HAMT sharding is yet to be implemented or
131    /// denied.
132    TooLargeBlock(u64),
133}
134
135impl fmt::Display for TreeConstructionFailed {
136    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
137        use TreeConstructionFailed::*;
138
139        match self {
140            Protobuf(e) => write!(fmt, "serialization failed: {e}"),
141            TooLargeBlock(size) => write!(fmt, "attempted to create block of {size} bytes"),
142        }
143    }
144}
145
146impl std::error::Error for TreeConstructionFailed {}
147
148#[derive(Debug)]
149struct NamedLeaf(String, Cid, u64);
rust_unixfs/dir/builder.rs

rust_unixfs/dir/
builder.rs
