WebNative FileSystem (WNFS)

_{⚠️ Work in progress ⚠️}

This crate is a Rust implementation of the primitives for creating and manipulating IPLD graphs that encode WNFS.

A goal of the project is to be easily compiled to WebAssembly to be used in the browsers or other environments.

Outline

• Usage
• Building the Project
• Testing the Project

Usage

Creating a new public directory.

use wnfs::{PublicDirectory, Id};

use async_std::main;
use chrono::Utc;

#[async_std::main]
async fn main() {
  let dir = PublicDirectory::new(Utc::now());
  println!("id = {}", dir.get_id());
}

The in-memory files and directories you create with wnfs will need to be sealed and stored somewhere. For that, a type that implements the BlockStore trait like this one can be used.

use wnfs::{MemoryBlockStore, PublicDirectory, OpResult, ipld::Cid};

use async_std::main;
use chrono::Utc;

use std::rc::Rc;
// ...

The WNFS API is immutable, therefore, we need to keep track of the updated root directory after every change.

Each fs operation returns a possibly updated root directory that subsequent changes can be applied on.

// ...
#[async_std::main]
async fn main() {
    let time = Utc::now();
    let dir = Rc::new(PublicDirectory::new(time));
    let store = MemoryBlockStore::default();

    // Create a /pictures/cats directory.
    let OpResult { root_dir, .. } = dir
        .mkdir(&["pictures".into(), "cats".into()], time, &store)
        .await
        .unwrap();

    // Get a sample CIDv1.
    let cid = Cid::default();

    // Add a file to /pictures/cats.
    let OpResult { root_dir, .. } = root_dir
        .write(
            &["pictures".into(), "cats".into(), "tabby.png".into()],
            cid,
            time,
            &store,
        )
        .await
        .unwrap();

    // Create and add a file to /pictures/dogs directory.
    let OpResult { root_dir, .. } = root_dir
        .write(
            &["pictures".into(), "dogs".into(), "billie.jpeg".into()],
            cid,
            time,
            &store,
        )
        .await
        .unwrap();

    // Delete /pictures/cats directory.
    let OpResult { root_dir, .. } = root_dir
        .rm(&["pictures".into(), "cats".into()], &store)
        .await
        .unwrap();

    // List all files in /pictures directory.
    let OpResult { result, .. } = root_dir
        .ls(&["pictures".into()], &store)
        .await
        .unwrap();

    println!("Files in /pictures: {:#?}", result);
}

Building the Project

REQUIREMENTS

• The Rust Toolchain

  Follow the instructions here to install the official Rust toolchain.

• The WebAssembly Toolchain

  If you are interested in compiling the project for WebAssembly, you can follow the instructions below.

  Read more

  • Install wasm32-unknown-unknown target

    rustup target add wasm32-unknown-unknown

  • rust-analyzer is the go-to IDE tool for Rust and if you have it set up, you may want to set the rust-analyzer.cargo.target setting to wasm32-unknown-unknown

  • Install wasm-pack

    cargo install wasm-pack

  • Install playwrigth binaries

    npx playwright install

  On ARM-based (M1 family) macOS, you might need to explicitly install the following:

  • Install wasm-bindgen

    cargo install -f wasm-bindgen-cli

  • Install wasm-opt

    brew install binaryen

  On Arch Linux based distributions, you might need to explicitly install the following:

  • Install wasm-opt

    sudo pacman -S binaryen

• The rs-wnfs Command

  You can optionally set up the rs-wnfs script.

  Read more

  • Install it using the following command:

    sh scripts/rs-wnfs.sh setup

  • This lets you run the rs-wnfs.sh script as a command.

    rs-wnfs help

STEPS

• Clone the repository.

  git clone https://github.com/WebNativeFileSystem/rs-wnfs.git

• Change directory

  cd rs-wnfs

• Build the project

  Check REQUIREMENTS on how to set up the rs-wnfs command.

  rs-wnfs build --all

• You can also build for specific crates

  rs-wnfs build --wasm

Testing the Project

• Run all tests

  rs-wnfs test --all

• Show code coverage

  rs-wnfs coverage