Merge #313

313: Prepare unixfs release v0.1.0 r=koivunej a=koivunej Per semver the next must be a minor bump at least. While I don't have a concrete path forward to 1.0 in mind for this crate I am sure we'll be doing smaller bits and bobs soon as we approach a rust-ipfs release as well. Co-authored-by: Joonas Koivunen <[email protected]> Co-authored-by: Joonas Koivunen <[email protected]>
rs-ipfs · Aug 14, 2020 · c41b564 · c41b564
2 parents d977e98 + ff8824c
commit c41b564
Show file tree

Hide file tree

Showing 8 changed files with 36 additions and 30 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/unixfs/CHANGELOG.md b/unixfs/CHANGELOG.md
@@ -1,10 +1,22 @@
-# Next
+# 0.1.0
+
+Minor version bump due to many new features and broken API.
 
 * Initial facilities for building File trees [#220]
 * Hide `ipfs_unixfs::file::reader` to hide non-exported type on pub fn [#203]
+* More ergonomic `ipfs_unixfs::walk::Walker` [#269], [#272], [#294]
+* Update `filetime` dependency [#278]
+* Directory tree building [#284]
+* Symlink block serialization [#302]
 
 [#203]: https://github.com/rs-ipfs/rust-ipfs/pull/203
 [#220]: https://github.com/rs-ipfs/rust-ipfs/pull/220
+[#269]: https://github.com/rs-ipfs/rust-ipfs/pull/269
+[#272]: https://github.com/rs-ipfs/rust-ipfs/pull/272
+[#278]: https://github.com/rs-ipfs/rust-ipfs/pull/278
+[#284]: https://github.com/rs-ipfs/rust-ipfs/pull/284
+[#294]: https://github.com/rs-ipfs/rust-ipfs/pull/294
+[#302]: https://github.com/rs-ipfs/rust-ipfs/pull/302
 
 # 0.0.1
 

diff --git a/unixfs/Cargo.toml b/unixfs/Cargo.toml
@@ -6,7 +6,7 @@ license = "MIT OR Apache-2.0"
 name = "ipfs-unixfs"
 readme = "README.md"
 repository = "https://github.com/rs-ipfs/rust-ipfs"
-version = "0.0.1"
+version = "0.1.0"
 
 [features]
 default = ["filetime"]

diff --git a/unixfs/README.md b/unixfs/README.md
@@ -8,21 +8,11 @@
 
 ## Status
 
-* first iteration of file reader has been implemented
-* first iteration of resolving IpfsPath segments through directories has been
- implemented
- * as the HAMTShard structure is not fully understood, all buckets are
- searched, however the API is expected to remain the same even if more
- efficient lookup is implemented
-* first iteration of `/get`-like tree walking implemented
-* creation and alteration of dags has not been implemented
+* unfiltered walking of known unixfs trees
+* creation of balanced file trees
+* creation of non HAMT-sharded directory trees
 
-## Usage
-
-* The main entry point to walking anything unixfs should be `ipfs_unixfs::walk::Walker`
-* The main entry point to resolving links under dag-pb or unixfs should be `ipfs_unixfs::resolve`
-* There is a `ipfs_unixfs::file::visit::FileVisit` utility but it should be
- considered superceded by `ipfs_unixfs::walk::Walker`
+See the docs at https://docs.rs/ipfs-unixfs.
 
 ## License
 

diff --git a/unixfs/src/file.rs b/unixfs/src/file.rs
@@ -1,7 +1,7 @@
 ///! UnixFS file support.
 ///!
-///! Most usable for walking UnixFS file trees provided by the `visit::IdleFileVisit` and
-///! `visit::FileVisit` types.
+///! The module provides low-level File tree visitor support and file importing support. Note: The
+///! [`ipfs_unixfs::walk::Walker`] should typically be used for accessing file content.
 use crate::pb::ParsingFailed;
 use crate::{InvalidCidInLink, Metadata, UnexpectedNodeType};
 use std::borrow::Cow;
@@ -10,10 +10,10 @@ use std::fmt;
 /// Low level UnixFS file descriptor reader support.
 mod reader;
 
-/// Higher level API for visiting the file tree.
+/// Mid level API for visiting the file tree.
 pub mod visit;
 
-/// Initial version of file adder capable of constructing UnixFs v1 trees
+/// File adder capable of constructing UnixFs v1 trees
 pub mod adder;
 
 /// Describes the errors which can happen during a visit or lower level block-by-block walking of

diff --git a/unixfs/src/file/adder.rs b/unixfs/src/file/adder.rs
@@ -7,7 +7,7 @@ use std::fmt;
 
 use sha2::{Digest, Sha256};
 
-/// File tree builder. Implements `Default` which tracks the recent defaults.
+/// File tree builder. Implements [`std::default::Default`] which tracks the recent defaults.
 ///
 /// Custom file tree builder can be created with [`FileAdder::builder()`] and configuring the
 /// chunker and collector.
@@ -21,7 +21,10 @@ pub struct FileAdder {
  collector: Collector,
  block_buffer: Vec<u8>,
  // all unflushed links as a flat vec; this is compacted as we grow and need to create a link
- // block for the last N blocks, as decided by the collector
+ // block for the last N blocks, as decided by the collector.
+ // FIXME: this is a cause of likely "accidentially quadratic" behaviour visible when adding a
+ // large file and using a minimal chunk size. Could be that this must be moved to Collector to
+ // help collector (or layout) to decide how this should be persisted.
  unflushed_links: Vec<Link>,
 }
 
@@ -106,7 +109,7 @@ impl fmt::Debug for Link {
  }
 }
 
-/// Convinience type to facilitate configuring FileAdders
+/// Convinience type to facilitate configuring [`FileAdder`]s.
 #[derive(Default)]
 pub struct FileAdderBuilder {
  chunker: Chunker,

diff --git a/unixfs/src/lib.rs b/unixfs/src/lib.rs
@@ -11,23 +11,23 @@
 use std::borrow::Cow;
 use std::fmt;
 
-/// UnixFS file support.
+/// File support.
 pub mod file;
 
-/// UnixFS symlink creation support
+/// Symlink creation support
 pub mod symlink;
 
-/// UnixFS directory support, currently only the resolving re-exported at root level.
+/// Directory and directory tree support
 pub mod dir;
 pub use dir::{resolve, LookupError, MaybeResolved, ResolveError};
 
 mod pb;
 use pb::{UnixFs, UnixFsType};
 
-/// Support operations for the dag-pb, the outer shell of UnixFS.
+/// Support operations for the dag-pb, the outer shell of UnixFS
 pub mod dagpb;
 
-/// Support for walking over all UnixFs trees.
+/// Support for walking over all UnixFs trees
 pub mod walk;
 
 #[cfg(test)]

diff --git a/unixfs/src/symlink.rs b/unixfs/src/symlink.rs
@@ -8,7 +8,8 @@ use quick_protobuf::{MessageWrite, Writer};
 use std::borrow::Cow;
 
 /// Appends a dag-pb block for for a symlink to the given target_path. It is expected that the
-/// target_path is valid relative unix path but targets validity cannot really be judged.
+/// `target_path` is valid relative unix path relative to the place in which this is used but
+/// targets validity cannot really be judged.
 pub fn serialize_symlink_block(target_path: &str, block_buffer: &mut Vec<u8>) {
  // should this fail or not? protobuf encoding cannot fail here, however we might create a too
  // large block but what's the limit?