Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish Crates, Npm Package and Usage Docs #21

Merged
merged 8 commits into from
May 24, 2022
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

121 changes: 112 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,103 @@

##

This project will implement a pure rust crate for creating and manipulating IPLD graphs that encode WNFS.
Its goal is to be as dependency-less as possible in order to be easily compiled to WebAssembly to be used in the browsers or other environments.
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](#usage)
- [Building the Project](#building-the-project)
- [Testing the Project](#testing-the-project)

## Usage

Creating a new public directory.

```rust
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](https://github.com/WebNativeFileSystem/rs-wnfs/blob/8bb0fbb457051295f1ed4a4707dc230c04612658/crates/fs/common/blockstore.rs#L42-L62) can be used.

```rust
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.

```rust
// ...
#[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

Expand All @@ -44,7 +139,7 @@ Its goal is to be as dependency-less as possible in order to be easily compiled

- **The WebAssembly Toolchain**

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

<details>
<summary>Read more</summary>
Expand Down Expand Up @@ -85,9 +180,9 @@ Its goal is to be as dependency-less as possible in order to be easily compiled

</details>

- **The _wnfs_ Helper Script**
- **The _wnfs_ Command**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should rename the script in order to avoid confusion with a potential wnfs CLI that actually reads and writes WNFS similar to what the ipfs CLI is doing today.

Or we could go for a Justfile which is similar to a makefile, but simpler. We're using it in a lot of other places at fission.

And lastly we could go for a nix version, but that's way more involved to set up compared to a justfile.

Copy link
Member Author

@appcypher appcypher May 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was considering make but had issues with it in the past. Just looks like an improved make. I'm going to switch to it later.
I agree with renaming it. Maybe rs-wnfs because it is specific to the repo?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about build-wnfs.sh? Or maybe make-wnfs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rs-wnfs fine too probably.


If you are on a Unix platform, you can optionally install the `wnfs` script.
You can optionally set up the `wnfs` script.

<details>
<summary>Read more</summary>
Expand All @@ -98,7 +193,7 @@ Its goal is to be as dependency-less as possible in order to be easily compiled
sh script/wnfs.sh setup
```

- This lets you run the `wnfs.sh` script with just the `wnfs` command.
- This lets you run the `wnfs.sh` script as a command.

```bash
wnfs help
Expand All @@ -122,20 +217,28 @@ Its goal is to be as dependency-less as possible in order to be easily compiled

- Build the project

Check [REQUIREMENTS](#requirements) on how to set up the `wnfs` command.

```bash
wnfs build --all
```

- You can also build for specific crates

```bash
sh scripts/wnfs.sh build
wnfs build --wasm
```

## Testing the Project

- Run all tests

```bash
sh scripts/wnfs.sh test
wnfs test --all
```

- Show code coverage

```bash
sh scripts/wnfs.sh coverage
wnfs coverage
```
8 changes: 4 additions & 4 deletions crates/fs/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "wnfs"
version = "0.1.1"
version = "0.1.6"
description = "WebNative filesystem core implementation"
keywords = ["wnfs", "webnative", "ipfs", "decentralisation"]
categories = [
Expand All @@ -9,10 +9,10 @@ categories = [
"web-programming",
"wasm",
]
license-file = "../../LICENSE"
license = "Apache-2.0"
readme = "README.md"
edition = "2021"
repository = "https://github.com/fission-suite/rs-wnfs"
repository = "https://github.com/WebNativeFileSystem/rs-wnfs/tree/main/crates/fs"
homepage = "https://fission.codes"
authors = ["The Fission Authors"]

Expand All @@ -29,7 +29,7 @@ async-recursion = "1.0.0"
field_names = "0.2.0"
futures = "0.3.21"
async-stream = "0.3.3"

futures-util = "0.3.21"

[lib]
path = "lib.rs"
Expand Down
Loading