rust_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)]
40#[non_exhaustive]
41pub struct InvalidCidInLink {
42    /// The index of this link, from zero
43    pub nth: usize,
44    /// Hash which could not be turned into a `Cid`
45    pub hash: Cow<'static, [u8]>,
46    /// Name of the link, most likely empty when this originates from a file, most likely non-empty
47    /// for other kinds.
48    pub name: Cow<'static, str>,
49    /// Error from the attempted conversion
50    pub source: ipld_core::cid::Error,
51}
52
53impl<'a> From<(usize, pb::PBLink<'a>, ipld_core::cid::Error)> for InvalidCidInLink {
54    fn from((nth, link, source): (usize, pb::PBLink<'a>, ipld_core::cid::Error)) -> Self {
55        let hash = match link.Hash {
56            Some(Cow::Borrowed(x)) if !x.is_empty() => Cow::Owned(x.to_vec()),
57            Some(Cow::Borrowed(_)) | None => Cow::Borrowed(&[][..]),
58            Some(Cow::Owned(x)) => Cow::Owned(x),
59        };
60
61        let name = match link.Name {
62            Some(Cow::Borrowed(x)) if !x.is_empty() => Cow::Owned(x.to_string()),
63            Some(Cow::Borrowed(_)) | None => Cow::Borrowed(""),
64            Some(Cow::Owned(x)) => Cow::Owned(x),
65        };
66
67        InvalidCidInLink {
68            nth,
69            hash,
70            name,
71            source,
72        }
73    }
74}
75
76impl fmt::Display for InvalidCidInLink {
77    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
78        write!(
79            fmt,
80            "failed to convert link #{} ({:?}) to Cid: {}",
81            self.nth, self.name, self.source
82        )
83    }
84}
85
86impl std::error::Error for InvalidCidInLink {
87    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
88        Some(&self.source)
89    }
90}
91
92/// Wrapper around the unexpected UnixFs node type, allowing access to querying what is known about
93/// the type.
94pub struct UnexpectedNodeType(i32);
95
96impl fmt::Debug for UnexpectedNodeType {
97    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
98        let converted = UnixFsType::from(self.0);
99        // the conversion defaults to Raw
100        if converted == UnixFsType::Raw && self.0 != 0 {
101            write!(fmt, "{} or <unknown>", self.0)
102        } else {
103            write!(fmt, "{} or {:?}", self.0, converted)
104        }
105    }
106}
107
108impl From<UnixFsType> for UnexpectedNodeType {
109    fn from(t: UnixFsType) -> UnexpectedNodeType {
110        UnexpectedNodeType(t.into())
111    }
112}
113
114impl UnexpectedNodeType {
115    /// Returns `true` if the type represents some directory
116    pub fn is_directory(&self) -> bool {
117        matches!(
118            UnixFsType::from(self.0),
119            UnixFsType::Directory | UnixFsType::HAMTShard
120        )
121    }
122
123    /// Returns `true` if the type represents a `File`
124    pub fn is_file(&self) -> bool {
125        matches!(UnixFsType::from(self.0), UnixFsType::File)
126    }
127}
128
129/// A container for the UnixFs metadata, which can be present at the root of the file, directory, or symlink trees.
130#[derive(Debug, Default, PartialEq, Eq, Clone)]
131pub struct Metadata {
132    mode: Option<u32>,
133    mtime: Option<(i64, u32)>,
134}
135
136impl Metadata {
137    /// Returns the full file mode, if one has been specified.
138    ///
139    /// The full file mode is originally read through `st_mode` field of `stat` struct defined in
140    /// `sys/stat.h` and its defining OpenGroup standard. The lowest 3 bytes correspond to read,
141    /// write, and execute rights per user, group, and other, while the 4th byte determines sticky bits,
142    /// set user id or set group id. The following two bytes correspond to the different file types, as
143    /// defined by the same OpenGroup standard:
144    /// https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html
145    pub fn mode(&self) -> Option<u32> {
146        self.mode
147    }
148
149    /// Returns the raw timestamp of last modification time, if specified.
150    ///
151    /// The timestamp is `(seconds, nanos)` - similar to `core::time::Duration`, with the exception of
152    /// allowing seconds to be negative. The seconds are calculated from `1970-01-01 00:00:00` or
153    /// the common "unix epoch".
154    pub fn mtime(&self) -> Option<(i64, u32)> {
155        self.mtime
156    }
157
158    /// Returns the mtime metadata as a `FileTime`. Enabled only in the `filetime` feature.
159    #[cfg(feature = "filetime")]
160    pub fn mtime_as_filetime(&self) -> Option<filetime::FileTime> {
161        self.mtime()
162            .map(|(seconds, nanos)| filetime::FileTime::from_unix_time(seconds, nanos))
163    }
164}
165
166impl<'a> From<&'a UnixFs<'_>> for Metadata {
167    fn from(data: &'a UnixFs<'_>) -> Self {
168        let mode = data.mode;
169        let mtime = data
170            .mtime
171            .clone()
172            .map(|ut| (ut.Seconds, ut.FractionalNanoseconds.unwrap_or(0)));
173
174        Metadata { mode, mtime }
175    }
176}
rust_unixfs/lib.rs

rust_unixfs/
lib.rs
