feat: Non MFS Files API tutorial (#303)

* feat: first draft of first lesson

* feat: draft of the second lesson done. also bumped ipfs version

* feat: first draft of the 3rd lesson

* chore: first draft of the 4th lesson

* chore: first draft of the 5th lesson

* feat: first draft of 6th and last lesson

* chore: revisit lesson 2: change information on add method argument

* Er suggestions nonmfs (#304)

* Title renaming for parallelism

* Copy suggestions - lesson 1

* Lesson 1 edits

* Lesson 2 edits

* Lesson 3 edits

* Lessons 4-6 edits

* chore: update to review

* chore: restore section on file upload in lesson 2

* chore: worked on last comment left

* chore: made several revisions from feedback. missing discussion on directories and simplifying lesson 7

* copy edits to lesson 1

* copy edits to lesson 2

* copy edits to lesson 3

* fix typos

* remove old comments from Vue files

* add MFS tutorial to resources page

* update featured courses

* fix typo

* copy edits to lesson 4

* chore: update approach to lesson 5

* chore: update lesson 6 to match lesson 5

* chore: added content to lesson 5

* copy edits to Lesson 5k

* fix tutorial path

* add IPFS Camp course to resources

* fix: fixed bug causing race conditions on fast executing user code

* copy edits to lesson 6

* add resulting code block sample to L6

* chore: added lesson on cat file inside directory

* copy edits to lesson 7

* feat: improved lessons 7 and 8

Note: success.txt is now inside a subdirectory

* feat: made some improvements to lesson 5

* lesson 7 copy edits

* copy edit to lesson 5 success msg

* lesson 8 copy edits, adding ls comparison

* fix merge issue

* update references to Regular Files API

* update tutorial description

* fix: lesson 1: add format for mfs files API method calls

* fix copy paste errors

* mention IPLD when describing DAG API

* change tutorial url

* chore: minor changes

* chore: update with most of the changes suggested by Alan

* Use ipfs in path in src/tutorials/0005/07.md

Co-Authored-By: Marcin Rataj <[email protected]>

* Apply suggestions from code review

Co-Authored-By: Marcin Rataj <[email protected]>

* add /ipfs/ to paths

* incorporate feedback from Alan & Marcin

* chore: change main solution in lesson 05

* chore: updated file structure and contents

* chore: update src/tutorials/0005/07-exercise.md

Co-Authored-By: Marcin Rataj <[email protected]>

* chore: updated validation for lessons 3, 4, and 5. Fixed a bug in validation of lesson 10 in the MFS tutorial

* chore: update to lesson 6 validation

* chore: update feedback on lesson 7

* chore: update lesson 8 validation

* remove all references to 'root' directory

* imrpove catch-all error msg

* tweaks to error messages

* move javascript hints from solution to hints in exercise

* chore: update validation for lessons 5 and 7 according to comments

* validation tweaks + new override

* rename variable

* minor copy edit

Author: dominguesgm

package-lock.json

@@ -15,12 +15,13 @@
   },
   "dependencies": {
     "async": "^2.6.1",
-    "cids": "^0.5.6",
+    "cids": "^0.7.1",
     "highlight.js": "^9.12.0",
-    "ipfs": "^0.36.4",
+    "ipfs": "^0.39.0",
     "ipfs-css": "^0.6.0",
     "marked": "^0.4.0",
     "monaco-editor": "^0.6.1",
+    "p-timeout": "^3.2.0",
     "raw-loader": "^0.5.1",
     "shallow-equal": "^1.0.0",
     "tachyons": "^4.11.1",

package.json

@@ -132,8 +132,6 @@ marked.setOptions({
 })
 
 const _eval = async (text, ipfs, modules = {}, args = []) => {
-  await new Promise(resolve => ipfs.on('ready', resolve))
-
   let fn
   let result
   try {
@@ -212,6 +210,7 @@ export default {
       lessonKey: 'passed' + self.$route.path,
       lessonPassed: !!localStorage['passed' + self.$route.path],
       createTestFile: self.$attrs.createTestFile,
+      createTestTree: self.$attrs.createTestTree,
       output: self.output,
       showUploadInfo: false,
       expandExercise: false,
@@ -279,9 +278,15 @@ export default {
       }
       let output = this.output
       let ipfs = await this.createIPFS()
+
+      await ipfs.ready
       if (this.createTestFile) {
         await this.createFile(ipfs)
       }
+      if (this.createTestTree) {
+        await this.createTree(ipfs)
+      }
+
       let code = this.editor.getValue()
       let modules = {}
 
@@ -347,12 +352,24 @@ export default {
     },
     createFile: function (ipfs) {
       /* eslint-disable no-new */
-      new Promise((resolve, reject) => {
-        ipfs.on('ready', async () => {
-          await ipfs.add(this.ipfsConstructor.Buffer.from('You did it!'))
-          resolve()
-        })
-      })
+      return ipfs.add(this.ipfsConstructor.Buffer.from('You did it!'))
+    },
+    createTree: function (ipfs) {
+      /* eslint-disable no-new */
+      return ipfs.add([
+        {
+          content: this.ipfsConstructor.Buffer.from('¯\\_(ツ)_/¯'),
+          path: 'shrug.txt'
+        },
+        {
+          content: this.ipfsConstructor.Buffer.from(':)'),
+          path: 'smile.txt'
+        },
+        {
+          content: this.ipfsConstructor.Buffer.from('You did it!'),
+          path: 'fun/success.txt'
+        }
+      ], { wrapWithDirectory: true })
     },
     resetCode: function () {
       // TRACK? User chose to reset code

src/components/Lesson.vue

@@ -46,6 +46,14 @@ import T0004L08 from './tutorials/0004/08.vue'
 import T0004L09 from './tutorials/0004/09.vue'
 import T0004L10 from './tutorials/0004/10.vue'
 import T0004L11 from './tutorials/0004/11.vue'
+import T0005L01 from './tutorials/0005/01.vue'
+import T0005L02 from './tutorials/0005/02.vue'
+import T0005L03 from './tutorials/0005/03.vue'
+import T0005L04 from './tutorials/0005/04.vue'
+import T0005L05 from './tutorials/0005/05.vue'
+import T0005L06 from './tutorials/0005/06.vue'
+import T0005L07 from './tutorials/0005/07.vue'
+import T0005L08 from './tutorials/0005/08.vue'
 
 Vue
   .use(VueRouter)
@@ -96,7 +104,18 @@ const routes = [
   { path: '/mutable-file-system/08', component: T0004L08 },
   { path: '/mutable-file-system/09', component: T0004L09 },
   { path: '/mutable-file-system/10', component: T0004L10 },
-  { path: '/mutable-file-system/11', component: T0004L11 },
+  { path: '/mutable-file-system/01', component: T0004L11 },
+  // Tutorial 0005
+  { path: '/regular-files-api', component: Landing, props: { tutorialId: '0005' } },
+  { path: '/regular-files-api/resources', component: ResourcesLesson, props: { tutorialId: '0005' } },
+  { path: '/regular-files-api/01', component: T0005L01 },
+  { path: '/regular-files-api/02', component: T0005L02 },
+  { path: '/regular-files-api/03', component: T0005L03 },
+  { path: '/regular-files-api/04', component: T0005L04 },
+  { path: '/regular-files-api/05', component: T0005L05 },
+  { path: '/regular-files-api/06', component: T0005L06 },
+  { path: '/regular-files-api/07', component: T0005L07 },
+  { path: '/regular-files-api/08', component: T0005L08 },
   // 404
   { path: '*', name: '404', component: NotFound, props: { notFound: true } }
 ]

src/main.js

@@ -55,7 +55,8 @@ export default {
 
 <style scoped>
 .tutorial-tile {
-  max-width: 49%
+  max-width: 49%;
+  min-height: 167px;
 }
 .tutorial-tile a  {
   text-decoration: none;

src/pages/Home.vue

@@ -1,4 +1,4 @@
 {
-  "all": ["0004", "0001", "0002", "0003"],
-  "featured": ["0004", "0001", "0002", "0003"]
+  "all": ["0004", "0005", "0001", "0002", "0003"],
+  "featured": ["0001", "0004", "0005", "0002"]
 }

src/static/courses.json

@@ -59,7 +59,7 @@
     "url": "basics",
 		"project": "IPFS",
 		"title": "P2P data links with content addressing",
-		"description": "Store, fetch, and create verifiable links between peer-hosted datasets with IPFS and CIDs. It’s graphs with friends!",
+		"description": "Store, fetch, and create verifiable links between peer-hosted datasets using the IPFS DAG API and CIDs. It’s graphs with friends!",
 		"lessons": [
 			"Create a node and return a Content Identifier (CID)",
 			"Create a new node that's linked to an old one",
@@ -143,5 +143,47 @@
 				"description": "You've seen the IPFS Files API. Now explore the IPFS DAG API, where you'll use CIDs to create verifiable links between datasets."
 			}
 		]
+	},
+	"0005": {
+		"url": "regular-files-api",
+		"project": "IPFS",
+		"title": "IPFS: Regular Files API",
+		"description": "The IPFS Regular Files API provides a way to store and share files in a peer-to-peer storage system.",
+		"lessons": [
+			"Introducing the Files API",
+			"Working with files in ProtoSchool",
+			"Add a file",
+			"Read the contents of a file",
+			"Add files in a directory",
+			"List the files in a directory",
+			"Read a file in a directory",
+			"Get all of the files in a directory"
+		],
+		"resources": [
+			{
+				 "title": "Understanding How IPFS Deals with Files",
+				 "link": "https://youtu.be/Z5zNPwMDYGg",
+				 "type": "video",
+				 "description": "This course from IPFS Camp 2019 offers a deep exploration of how IPFS deals with files, including key concepts like immutability, content addressing, hashing, the anatomy of CIDs, what the heck a Merkle DAG is, and how chunk size affects file imports. It also introduces some the joys and pitfalls of the Mutable File System (MFS)."
+			 },
+		   {
+					"title": "JS-IPFS Files API",
+					"link": "https://github.com/ipfs/interface-js-ipfs-core/blob/master/SPEC/FILES.md",
+					"type": "docs",
+					"description": "Notice that these docs contain two sections, one for top-level methods relevant to files, which we learned about in this tutorial, and one for the Mutable File System (MFS)."
+				},
+				{
+					"title": "IPFS: Mutable File System (MFS)",
+					"link": "https://proto.school/#/mutable-file-system",
+					"type": "tutorial",
+					"description": "Wish adding files to IPFS felt more like using a traditional name-based file system? Explore the Mutable File System (MFS)."
+				},
+				{
+					"title": "P2P Data Links with Content Addressing",
+					"link": "https://proto.school/#/basics/",
+					"type": "tutorial",
+					"description": "You've seen the IPFS Files API. Now explore the IPFS DAG API, where you'll use CIDs to create verifiable links between datasets."
+				}
+			]
 	}
 }

src/static/tutorials.json

@@ -20,6 +20,8 @@ const validate = async (result, ipfs) => {
 
   if (!result) {
     return { fail: 'You forgot to return a result. Did you accidentally edit the return statement?' }
+  } else if (result.error) {
+    return { error: result.error }
   } else if (result && typeof result !== 'string') {
     return { fail: 'Oops. `secretMessage` should be a string. Did you forget to convert the buffer to a string?' }
   } else if (result !== correctMessage) {
@@ -34,8 +36,6 @@ const validate = async (result, ipfs) => {
       logDesc: "Here's the secret message you discovered in the file:",
       log: result
     }
-  } else if (result.error) {
-    return { error: result.error }
   }
 }
 

src/tutorials/0004/10.vue

@@ -0,0 +1,28 @@
+
+## IPFS: The InterPlanetary File System
+
+[IPFS](https://ipfs.io/) is a peer-to-peer (P2P) networking protocol used to share data on the distributed web. You can think of it as a file system with some unique characteristics that make it ideal for safe, decentralized sharing.
+
+If you haven't yet done so, we encourage you to check out our [Decentralized Data Structures](https://proto.school/#/data-structures/) tutorial to learn all about the decentralized web and how it compares to the web you're accustomed to. There you'll learn all about content addressing, cryptographic hashing, Content Identifiers (CIDs), and sharing with peers, all of which you'll need to understand to make the most of this tutorial.
+
+## The Files API vs the DAG API
+
+You can store multiple types of data with IPFS. If you've explored our [P2P Data Links with Content Addressing](https://proto.school/#/basics) or [Blogging on the Decentralized Web](https://proto.school/#/blog) tutorial, you've already seen how you can store primitives, objects and arrays on the network using the DAG API.
+
+The DAG API allows you to use the unique and versatile primitive data structures offered by [IPLD](https://github.com/ipld/ipld) (InterPlanetary Linked Data) within IPFS. You can recognize its methods in js-ipfs (the JavaScript implementation of IPFS) because they take the following format: `ipfs.dag.someMethod()`
+
+The DAG API is the most generic and flexible approach to adding data to the IPFS node, but it's not the most efficient when it comes to the very common use case of sharing files. What if you wanted to share a picture of a kitten, or a larger file like a funny video of your favorite celebrity dog? How would you add these files to the network and provide a way for your friends to see them? How should each file be placed in the Directed Acyclic Graph (DAG), in a single block or split into chunks? These are optimization details that fall beyond the scope of the DAG API. Though it would be possible to use the DAG API to add files to an IPFS node, it would be a labor-intensive task.
+
+The Files API, on the other hand, is custom-built for a more specific use case. The Files API prepares files to be placed in the network and ensures that IPFS knows how to access them and handle them efficiently. The Files API is made of two parts: the Regular Files API, which we'll cover in this tutorial, and the Mutable File System (MFS).
+
+## The Regular Files API vs the MFS Files API
+
+If you've read our [Mutable File System tutorial](https://proto.school/#/mutable-file-system), you may be thinking, "I've already learned how to work with files on IPFS. How will this be any different?"
+
+The Mutable File System (MFS) provides an API designed to replicate familiar file system operations such as `mkdir`, `ls`, `cp`, and others, mimicking the way you organize files and directories on a computer. However, the way that content is addressed in IPFS makes it an immutable file system. The address to a file or directory depends on its contents, so any change to a file or directory will result in an entirely new address. The MFS Files API works on a familiar-looking file system with regular paths — like `/some/stuff` — in the local IPFS node, which hides the complexity of immutable content addressing.
+
+Although MFS is very useful, the abstraction it provides hides some of the inner workings of IPFS. The Regular Files API we will discuss here is instead a bare bones approach to managing files in IPFS. It trades the powerful abstractions of MFS for a scheme which helps you understand what is actually happening in the file system. In the Regular Files API you'll find methods like `add`, `cat`, `get` and `ls`.
+
+Unlike the MFS API, which can be recognized in js-ipfs by the format `ipfs.files.someMethod()`, the Regular Files API uses top-level methods that take the format `ipfs.someMethod()`.
+
+The distinction between these two versions of the Files APIs is a bit confusing the moment, but the IPFS team is currently working on revamping them to make the whole Files API more user-friendly. We'll be sure to update our tutorials when things change!

src/tutorials/0005/01.md

@@ -0,0 +1,17 @@
+<template>
+    <Lesson :text="text" />
+</template>
+
+<script>
+import Lesson from '../../components/Lesson'
+import text from './01.md'
+
+export default {
+  components: {
+    Lesson
+  },
+  data: () => {
+    return { text }
+  }
+}
+</script>

src/tutorials/0005/01.vue

@@ -0,0 +1 @@
+First, upload one or more files by dragging and dropping below or clicking to make a selection from your file explorer.  Next, in the code editor, remove the comment markers (`//`) that precede `return files` within the `run` function.

src/tutorials/0005/02-exercise.md

@@ -0,0 +1,12 @@
+As a matter of security, web browsers don't let us directly change files that live in your computer's file system. Therefore, you'll need to upload one or more files to the browser that you can use throughout this tutorial.
+
+Within each exercise, you'll see that you can upload files from your computer either by dragging and dropping or selecting them from your file explorer. If you look closely at the `run` function in the code editor, you'll notice that it now takes an argument `files`. When you upload files from your computer, we'll make sure they're passed into the function as the `files` array. As long as you don't refresh your browser, these files will remain accessible for the next lesson in the tutorial, but you'll also have the option to upload different files to work with for each lesson.
+
+Each element in this `files` array will be a `File` object, as defined by the browser's [File API](https://developer.mozilla.org/en-US/docs/Web/API/File) (not to be confused with the IPFS Files API). Aside from the contents of the uploaded file, a `File` object also contains the following attributes:
+
+* **name** (name of the uploaded file)
+* **lastModified** (date the uploaded file was last modified)
+* **size** (size of the uploaded file)
+* **type** (type of the uploaded file)
+
+To practice, let's upload one or more files from your computer and take a look at what's been received by the browser as the `files` array.

src/tutorials/0005/02.md

@@ -0,0 +1,56 @@
+<template>
+  <FileLesson
+    :text="text"
+    :code="code"
+    :validate="validate"
+    :modules="modules"
+    :exercise="exercise"
+    :solution="solution"/>
+</template>
+
+<script>
+import FileLesson from '../../components/FileLesson.vue'
+import text from './02.md'
+import exercise from './02-exercise.md'
+import { logFiles } from '../../utils/files'
+
+const validate = async (result, ipfs) => {
+  if (!result) {
+    return { fail: 'Looks like you forgot to return a result. Did you forget to remove the `//` before `return files`?' }
+  } else if (typeof result.length === 'number') {
+    const fileCount = result.length > 1 ? `${result.length} files` : '1 file'
+    return {
+      success: `You successfully uploaded ${fileCount}!`,
+      logDesc: "Check out the data below to see the data now accessible in the `files` array. Note that these files are only in the browser right now. In the next lesson we'll see how to add them to IPFS.",
+      log: logFiles(result)
+    }
+  } else {
+    return { fail: `Something seems to be wrong. Please click "Reset Code" and try again, taking another look at the instructions and editing only the portion of code indicated. Feeling really stuck? You can click "View Solution" to see our suggested code.` }
+  }
+}
+
+const code = `const run = async (files) => {
+  /* remove the '//' on the line below to complete this challenge */
+  // return files
+}
+return run
+`
+
+const solution = `const run = async (files) => {
+  return files
+}
+
+return run
+`
+
+const modules = { cids: require('cids') }
+
+export default {
+  components: {
+    FileLesson
+  },
+  data: () => {
+    return { text, validate, code, modules, exercise, solution }
+  }
+}
+</script>

src/tutorials/0005/02.vue

@@ -0,0 +1,3 @@
+Add the files in your browser (available in the `files` array below) to your IPFS node using the `add` method.
+
+**Hint:** You can pass either a single `File` object or an array of `File` objects to the `add` method.