Merge pull request #71 from uqbar-dao/bp/drives

vfs drives clarification

src/apis/vfs.md

@@ -5,20 +5,65 @@ Useful helper functions can be found in the [kinode_process_lib](https://github.
 The VFS API tries to map over the [std::fs](https://doc.rust-lang.org/std/fs/index.html) calls as directly as possible.
 
 Every request takes a path and a corresponding action.
-The paths look like normal relative paths within the folder `your_node_home/vfs`, but they include 2 parts at the start, a `package_id` and a `drive`.
 
-Example path: `/your_package:publisher.os/pkg/`. This folder is usually filled with files put into the /pkg folder when installing with app_store.
+## Drives
 
-Capabilities are checked on the package_id/drive part of the path, when calling CreateDrive you'll be given "Read" and "Write" caps that you can share with other processes.
+VFS paths are normal relative paths within the directory `/your_node_home/vfs/`, but to be valid they need to be within a drive.
+A drive is just a directory within your vfs, consisting of 2 parts: `/package_id/drive_name/`.
+
+For example: `/your_package:publisher.os/pkg/`.
+This directory is usually filled with files put into the `/pkg` directory when installing with app_store.
+[Capabilities](../process-capabilities.md) are checked on the drive part of the path.
+When calling `create_drive()` you'll be given "read" and "write" caps that you can share with other processes.
 
 Other processes within your package will have access by default.
 They can open and modify files and directories within their own package_id.
 
-### Opening/Creating a drive
+### Imports
+
+```rust
+use kinode_process_lib::vfs::{
+  create_drive, open_file, open_dir, create_file, metadata, File, Directory,
+};
+```
+
+### Opening/Creating a Drive
 
 ```rust
 let drive_path: String = create_drive(our.package_id(), "drive_name")?;
 // you can now prepend this path to any files/directories you're interacting with
+let file = open_file(&format!("{}/hello.txt", &drive_path), true);
+```
+
+### Sharing a Drive Capability
+
+```rust
+let vfs_read_cap = serde_json::json!({
+    "kind": "read",
+    "drive": drive_path,
+}).to_string();
+
+let vfs_address = Address {
+    node: our.node.clone(),
+    process: ProcessId::from_str("vfs:distro:sys").unwrap(),
+};
+
+// get this capability from our store
+let cap = get_capability(&vfs_address, &vfs_read_cap);
+
+// now if we have that Capability, we can attach it to a subsequent message.
+if let Some(cap) = cap {
+    Request::new()
+        .capabilities(vec![cap])
+        .body(b"hello".to_vec())
+        .send()?;
+}
+```
+
+```rust
+// the receiving process can then save the capability to it's store, and open the drive.
+save_capabilities(incoming_request.capabilities);
+let dir = open_dir(&drive_path, false)?;
 ```
 
 ### Files
@@ -36,7 +81,7 @@ let file = open_file(&file_path, true);
 ```rust
 /// Creates a file at path, if file found at path, truncates it to 0.
 let file_path = format!("{}/hello.txt", &drive_path);
-let file = create(&file_path);
+let file = create_file(&file_path);
 ```
 
 #### Read a File
@@ -111,7 +156,7 @@ let metadata = file.metadata()?;
 /// Opens or creates a directory at path.
 /// If trying to create an existing file, will just give you the path.
 let dir_path = format!("{}/my_pics", &drive_path);
-let dir = open_dir(&file_path, true);
+let dir = open_dir(&dir_path, true);
 ```
 
 #### Read a Directory
@@ -134,8 +179,8 @@ let metadata = metadata(&some_path)?;
 
 ```rust
 pub struct VfsRequest {
-    /// path is always prepended by package_id, the capabilities of the topmost folder are checked
-    /// "/your_package:publisher.os/drive_folder/another_folder_or_file"
+    /// path is always prepended by package_id, the capabilities of the topmost directory are checked
+    /// "/your_package:publisher.os/drive_dir/another_dir_or_file"
     pub path: String,
     pub action: VfsAction,
 }

src/cookbook/file_transfer.md

@@ -88,7 +88,7 @@ Before delving into the code, you can handle the capabilities you need to reques
 ]
 ```
 
-Now, start by creating a drive (folder) in your vfs and opening it, where files will be downloaded by other nodes.
+Now, start by creating a [drive](../apis/vfs.md#drives) in your vfs and opening it, where files will be downloaded by other nodes.
 You can add a whitelist a bit later!
 
 Also, import some vfs functions from the `process_lib`.

src/files.md

@@ -33,15 +33,15 @@ For example, part of the VFS might look like:
 
 ## Usage
 
-To access files in the vfs, you need to create or open a drive, this can be done with the function `create_drive` from the [standard library](./process_stdlib/overview.md):
+To access files in the vfs, you need to create or open a [drive](./apis/vfs.md#drives), this can be done with the function `create_drive` from the [standard library](./process_stdlib/overview.md):
 
 ```rust
 let drive_path: String = create_drive(our.package_id(), "drive_name")?;
 
 let test_file = create_file(&format("{}/test.txt", &drive_path))?;
 
 let text = b"hello world!"
-file.write(&text);
+file.write(&text)?;
 ```
 
 ## References