Merge branch 'develop' and bump to v0.1.3

Author: burmecia

Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "zbox"
-version = "0.1.2"
+version = "0.1.3"
 authors = ["Bo Lu"]
-description = "Zbox is a zero-knowledge, privacy-focused embeddable file system."
+description = "Zbox is a zero-details, privacy-focused embeddable file system."
 documentation = "https://docs.rs/zbox"
 homepage = "https://github.com/zboxfs/zbox"
 repository = "https://github.com/zboxfs/zbox"
@@ -13,7 +13,7 @@ license = "Apache-2.0"
 build = "build.rs"
 
 [badges]
-circle-ci = { repository = "zboxfs/zbox" }
+travis-ci = { repository = "zboxfs/zbox" }
 
 [lib]
 name = "zbox"

README.md

@@ -7,18 +7,18 @@
 [![license](https://img.shields.io/github/license/zboxfs/zbox.svg?style=flat-square)](https://github.com/zboxfs/zbox)
 [![GitHub stars](https://img.shields.io/github/stars/zboxfs/zbox.svg?style=social&label=Stars)](https://github.com/zboxfs/zbox)
 
-Zbox is a zero-knowledge, privacy-focused embeddable file system. Its goal is
+Zbox is a zero-details, privacy-focused embeddable file system. Its goal is
 to help application store files securely, privately and reliably. By
 encapsulating files and directories into an encrypted repository, it provides
 a virtual file system and exclusive access to authorised application.
 
 Unlike other system-level file systems, such as [ext4], [XFS] and [Btrfs], which
 provide shared access to multiple processes, Zbox is a file system that runs
-in the same memory space as the application. It only provide access to one
+in the same memory space as the application. It only provides access to one
 process at a time.
 
 By abstracting IO access, Zbox supports a variety of underlying storage layers.
-Memory and OS file system are supported, RDBMS and key-value object store
+Memory and OS file system are supported now, RDBMS and key-value object store
 supports are coming soon.
 
 ## Disclaimer
@@ -50,7 +50,7 @@ Many OS-level file systems support encryption, such as [EncFS], [APFS] and
 [ZFS]. Some disk encryption tools also provide virtual file system, such as
 [TrueCrypt] and [VeraCrypt].
 
-This diagram shows the differece between Zbox and them.
+This diagram shows the difference between Zbox and them.
 
 ![Comparison](https://www.zbox.io/svg/zbox-compare.svg)
 
@@ -106,11 +106,11 @@ zbox = "~0.1"
 extern crate zbox;
 
 use std::io::{Read, Write};
-use zbox::{zbox_init, RepoOpener, OpenOptions};
+use zbox::{init_env, RepoOpener, OpenOptions};
 
 fn main() {
     // initialise zbox environment, called first
-    zbox_init();
+    init_env();
 
     // create and open a repository in current OS directory
     let mut repo = RepoOpener::new()
@@ -139,7 +139,7 @@ fn main() {
 
 ## Build with Docker
 
-Zbox comes with Docker support, it is based on rust:latest and [libsodium] is
+Zbox comes with Docker support, it is based on [rust:latest] and [libsodium] is
 included. Check the [Dockerfile](Dockerfile) for the details.
 
 First, we build the Docker image which can be used to compile Zbox, run below
@@ -189,4 +189,4 @@ file for details.
 [ZFS]: https://en.wikipedia.org/wiki/ZFS
 [TrueCrypt]: http://truecrypt.sourceforge.net
 [VeraCrypt]: https://veracrypt.codeplex.com
-
+[rust:latest]: https://hub.docker.com/_/rust/

src/lib.rs

@@ -1,4 +1,4 @@
-//! Zbox is a zero-knowledge, privacy-focused embeddable file system.
+//! Zbox is a zero-details, privacy-focused embeddable file system.
 //!
 //! It keeps files securely, privately and reliably on underlying storages.
 //! By encapsulating files and directories into an encrypted repository, it
@@ -8,8 +8,8 @@
 //! The most core part of this module is [`Repo`] and [`File`], which provides
 //! most file system operations and file I/O.
 //!
-//! - [`Repo`] provides similar file system manipulation methods as [`std::fs`]
-//! - [`File`] provides similar file I/O methods as [`std::fs::File`]
+//! - [`Repo`] provides similar file system manipulation methods to [`std::fs`]
+//! - [`File`] provides similar file I/O methods to [`std::fs::File`]
 //!
 //! [`init_env`] initialises the environment and should be called before
 //! any other methods provied by Zbox.

src/repo.rs

@@ -63,6 +63,7 @@ pub struct RepoOpener {
     cost: Cost,
     cipher: Cipher,
     create: bool,
+    create_new: bool,
     read_only: bool,
 }
 
@@ -109,7 +110,21 @@ impl RepoOpener {
         self
     }
 
+    /// Sets the option to always create a new repository.
+    ///
+    /// This option indicates whether a new repository will be created. No
+    /// repository is allowed to exist at the target location.
+    pub fn create_new(&mut self, create_new: bool) -> &mut Self {
+        self.create_new = create_new;
+        if create_new {
+            self.create = true;
+        }
+        self
+    }
+
     /// Sets the option for read-only mode.
+    ///
+    /// This option cannot be true with either `create` or `create_new` is true.
     pub fn read_only(&mut self, read_only: bool) -> &mut Self {
         self.read_only = read_only;
         self
@@ -134,6 +149,9 @@ impl RepoOpener {
     /// After a repository is opened, all of the other functions provided by
     /// Zbox will be thread-safe.
     ///
+    /// The application should destroy the password as soon as possible after
+    /// calling this function.
+    ///
     /// # Errors
     ///
     /// Open a memory based repository without enable `create` option will
@@ -144,6 +162,9 @@ impl RepoOpener {
                 return Err(Error::InvalidArgument);
             }
             if Repo::exists(uri)? {
+                if self.create_new {
+                    return Err(Error::AlreadyExists);
+                }
                 Repo::open(uri, pwd, self.read_only)
             } else {
                 Repo::create(uri, pwd, self.cost, self.cipher)
@@ -166,6 +187,7 @@ impl Default for RepoOpener {
             cost: Cost::default(),
             cipher: default_cipher,
             create: false,
+            create_new: false,
             read_only: false,
         }
     }

tests/repo.rs

@@ -39,11 +39,13 @@ fn repo_oper() {
     // case #3: open repo in read-only mode
     let path = base.clone() + "/repo3";
     {
-        RepoOpener::new()
-            .create(true)
-            .read_only(true)
-            .open(&path, &pwd)
-            .is_err();
+        assert!(
+            RepoOpener::new()
+                .create(true)
+                .read_only(true)
+                .open(&path, &pwd)
+                .is_err()
+        );
         RepoOpener::new().create(true).open(&path, &pwd).unwrap();
     }
     let mut repo = RepoOpener::new().read_only(true).open(&path, &pwd).unwrap();
@@ -79,4 +81,21 @@ fn repo_oper() {
     {
         assert!(RepoOpener::new().open("mem://foo", &pwd).is_err());
     }
+
+    // case #6: test create_new option
+    {
+        let path = base.clone() + "/repo6";
+        RepoOpener::new()
+            .create_new(true)
+            .open(&path, &pwd)
+            .unwrap();
+        assert_eq!(
+            RepoOpener::new()
+                .create_new(true)
+                .open(&path, &pwd)
+                .unwrap_err(),
+            Error::AlreadyExists
+        );
+        RepoOpener::new().create(true).open(&path, &pwd).unwrap();
+    }
 }