ipfs_unixfs/
lib.rs

1#![warn(rust_2018_idioms, missing_docs)]
2//! ipfs-unixfs: UnixFs tree support in Rust.
3//!
4//! The crate aims to provide a blockstore implementation independent of the UnixFs implementation by
5//! working on slices and not doing any IO operations.
6//!
7//! The main entry point for extracting information and/or data out of UnixFs trees is
8//! `ipfs_unixfs::walk::Walker`. To resolve `IpfsPath` segments over dag-pb nodes,
9//! `ipfs_unixfs::resolve` should be used.
10
11extern crate alloc;
12
13use alloc::borrow::Cow;
14use core::fmt;
15
16/// File support.
17pub mod file;
18
19/// Symlink creation support
20pub mod symlink;
21
22/// Directory and directory tree support
23pub mod dir;
24pub use dir::{resolve, LookupError, MaybeResolved, ResolveError};
25
26mod pb;
27use pb::{UnixFs, UnixFsType};
28
29/// Support operations for the dag-pb, the outer shell of UnixFS
30pub mod dagpb;
31
32/// Support for walking over all UnixFs trees
33pub mod walk;
34
35#[cfg(test)]
36pub(crate) mod test_support;
37
38/// A link could not be transformed into a Cid.
39#[derive(Debug)]
40pub struct InvalidCidInLink {
41    /// The index of this link, from zero
42    pub nth: usize,
43    /// Hash which could not be turned into a `Cid`
44    pub hash: Cow<'static, [u8]>,
45    /// Name of the link, most likely empty when this originates from a file, most likely non-empty
46    /// for other kinds.
47    pub name: Cow<'static, str>,
48    /// Error from the attempted conversion
49    pub source: cid::Error,
50    /// This is to deny creating these outside of the crate
51    hidden: (),
52}
53
54impl<'a> From<(usize, pb::PBLink<'a>, cid::Error)> for InvalidCidInLink {
55    fn from((nth, link, source): (usize, pb::PBLink<'a>, cid::Error)) -> Self {
56        let hash = match link.Hash {
57            Some(Cow::Borrowed(x)) if !x.is_empty() => Cow::Owned(x.to_vec()),
58            Some(Cow::Borrowed(_)) | None => Cow::Borrowed(&[][..]),
59            Some(Cow::Owned(x)) => Cow::Owned(x),
60        };
61
62        let name = match link.Name {
63            Some(Cow::Borrowed(x)) if !x.is_empty() => Cow::Owned(x.to_string()),
64            Some(Cow::Borrowed(_)) | None => Cow::Borrowed(""),
65            Some(Cow::Owned(x)) => Cow::Owned(x),
66        };
67
68        InvalidCidInLink {
69            nth,
70            hash,
71            name,
72            source,
73            hidden: (),
74        }
75    }
76}
77
78impl fmt::Display for InvalidCidInLink {
79    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
80        write!(
81            fmt,
82            "failed to convert link #{} ({:?}) to Cid: {}",
83            self.nth, self.name, self.source
84        )
85    }
86}
87
88impl std::error::Error for InvalidCidInLink {
89    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
90        Some(&self.source)
91    }
92}
93
94/// Wrapper around the unexpected UnixFs node type, allowing access to querying what is known about
95/// the type.
96pub struct UnexpectedNodeType(i32);
97
98impl fmt::Debug for UnexpectedNodeType {
99    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
100        let converted = UnixFsType::from(self.0);
101        // the conversion defaults to Raw
102        if converted == UnixFsType::Raw && self.0 != 0 {
103            write!(fmt, "{} or <unknown>", self.0)
104        } else {
105            write!(fmt, "{} or {:?}", self.0, converted)
106        }
107    }
108}
109
110impl From<UnixFsType> for UnexpectedNodeType {
111    fn from(t: UnixFsType) -> UnexpectedNodeType {
112        UnexpectedNodeType(t.into())
113    }
114}
115
116impl UnexpectedNodeType {
117    /// Returns `true` if the type represents some directory
118    pub fn is_directory(&self) -> bool {
119        matches!(
120            UnixFsType::from(self.0),
121            UnixFsType::Directory | UnixFsType::HAMTShard
122        )
123    }
124
125    /// Returns `true` if the type represents a `File`
126    pub fn is_file(&self) -> bool {
127        matches!(UnixFsType::from(self.0), UnixFsType::File)
128    }
129}
130
131/// A container for the UnixFs metadata, which can be present at the root of the file, directory, or symlink trees.
132#[derive(Debug, Default, PartialEq, Eq, Clone)]
133pub struct Metadata {
134    mode: Option<u32>,
135    mtime: Option<(i64, u32)>,
136}
137
138impl Metadata {
139    /// Returns the full file mode, if one has been specified.
140    ///
141    /// The full file mode is originally read through `st_mode` field of `stat` struct defined in
142    /// `sys/stat.h` and its defining OpenGroup standard. The lowest 3 bytes correspond to read,
143    /// write, and execute rights per user, group, and other, while the 4th byte determines sticky bits,
144    /// set user id or set group id. The following two bytes correspond to the different file types, as
145    /// defined by the same OpenGroup standard:
146    /// https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html
147    pub fn mode(&self) -> Option<u32> {
148        self.mode
149    }
150
151    /// Returns the raw timestamp of last modification time, if specified.
152    ///
153    /// The timestamp is `(seconds, nanos)` - similar to `core::time::Duration`, with the exception of
154    /// allowing seconds to be negative. The seconds are calculated from `1970-01-01 00:00:00` or
155    /// the common "unix epoch".
156    pub fn mtime(&self) -> Option<(i64, u32)> {
157        self.mtime
158    }
159
160    /// Returns the mtime metadata as a `FileTime`. Enabled only in the `filetime` feature.
161    #[cfg(feature = "filetime")]
162    pub fn mtime_as_filetime(&self) -> Option<filetime::FileTime> {
163        self.mtime()
164            .map(|(seconds, nanos)| filetime::FileTime::from_unix_time(seconds, nanos))
165    }
166}
167
168impl<'a> From<&'a UnixFs<'_>> for Metadata {
169    fn from(data: &'a UnixFs<'_>) -> Self {
170        let mode = data.mode;
171        let mtime = data
172            .mtime
173            .clone()
174            .map(|ut| (ut.Seconds, ut.FractionalNanoseconds.unwrap_or(0)));
175
176        Metadata { mode, mtime }
177    }
178}
ipfs_unixfs/lib.rs

ipfs_unixfs/
lib.rs
