update examples for v0.12.0

Author: ramfox

api-code-examples/README.md

@@ -0,0 +1,43 @@
+# iroh API code examples
+
+This directory includes all the code examples that show how to achieve `iroh` cli commands programmatically using rust, golang, and python.
+
+## running the examples
+
+There is a `run_files.sh` bash script that will run all of the python and golang examples. The following sections will describe how to set up the golang and python environments to run the script correctly.
+
+You can also run the individual examples without using the `run_files.sh` script.
+
+### running python
+
+Download python3 and download some way to manage virtual environments. pip will likely come with python, but if not, download pip3 as well.
+
+Navigate into the `python` directory.
+
+Create and activate a virtual environment for this project.
+
+Install iroh:
+`python3 -m pip install iroh`
+
+To run an example, eg for file `author-list.py`:
+`python3 run author-list.py`
+
+### running golang
+
+Download & set up go.
+
+Navigate to the go directory.
+
+Run the following commands:
+```
+$ go get github.com/n0-computer/iroh-ffi/iroh-go/iroh
+$ git submodule add https://github.com/n0-computer/iroh-ffi.git extern/iroh-ffi
+$ make -f extern/iroh-ffi/InstallGo
+$ go mod edit -replace=github.com/n0-computer/iroh-ffi/iroh-go=./extern/iroh-ffi/iroh-go
+```
+
+To run an example, eg for the file `author-list.py`:
+`go run author-list.py`
+
+### running the script
+Once the above are set up, run the `run_files.sh` script to iterate through each go and python file to ensure that the examples work!

api-code-examples/api.mjs

@@ -3,7 +3,7 @@ const doc = [
   {
     name: 'doc delete',
     description: 'Delete all document entries below a key prefix.',
-    slug: 'doc-del',
+    slug: 'doc-delete',
     arguments: [
       { name: "prefix", necessity: 'required', description: "Prefix to delete. All entries whose key starts with or is equal to the prefix will be deleted" }
     ],
@@ -373,17 +373,6 @@ Collection: bafkr4ie3xsx3vdsbflainnk6p4xs4h2hq3hdmuasuoflkgybvnsbljb3ke`,
       console: `> `,
     }
   },
-  { 
-    name: 'blob validate',
-    description: 'Validate hashes on the running node.',
-    slug: 'blob-validate',
-    arguments: [
-      { name: 'repair', necessity: '', description: 'Repair the store by removing invalid data.' }
-    ],
-    examples: {
-      console: `> `,
-    }
-  }
 ]
 
 const api = {

api-code-examples/go/author-list.go

@@ -12,16 +12,19 @@ func main() {
 		panic(err)
 	}
 
-	if _, err := node.AuthorCreate(); err != nil {
+	author, err := node.AuthorCreate()
+	if err != nil {
 		panic(err)
 	}
+	fmt.Println("Created author:", author.ToString())
 
 	authors, err := node.AuthorList()
 	if err != nil {
 		panic(err)
 	}
 
+	fmt.Println("Authors:")
 	for _, author := range authors {
-		fmt.Println(author.ToString())
+		fmt.Println("\t", author.ToString())
 	}
 }

api-code-examples/go/blob-add.go

@@ -0,0 +1,129 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/n0-computer/iroh-ffi/iroh-go/iroh"
+)
+
+type addCallback struct {
+}
+
+func (a addCallback) Progress(event *iroh.AddProgress) *iroh.IrohError {
+	switch t := event.Type(); t {
+	case iroh.AddProgressTypeFound:
+		fmt.Println("AddProgress - Found:")
+		found := event.AsFound()
+		fmt.Printf("\tid: %d, name: %s, size: %d\n", found.Id, found.Name, found.Size)
+	case iroh.AddProgressTypeProgress:
+		fmt.Println("AddProgress - Progress:")
+		progress := event.AsProgress()
+		fmt.Printf("\tid: %d, offset: %d\n", progress.Id, progress.Offset)
+	case iroh.AddProgressTypeDone:
+		fmt.Println("AddProgress - Done:")
+		done := event.AsDone()
+		fmt.Printf("\tid: %d, hash: %s\n", done.Id, done.Hash.ToString())
+	case iroh.AddProgressTypeAllDone:
+		fmt.Println("AddProgress - AllDone:")
+		allDone := event.AsAllDone()
+		fmt.Printf("\thash: %s, format: %v, tag: %s\n", allDone.Hash.ToString(), allDone.Format, allDone.Tag.ToString())
+	case iroh.AddProgressTypeAbort:
+		fmt.Println("AddProgress - Abort:")
+		abort := event.AsAbort()
+		fmt.Printf("\terror: %s", abort.Error)
+	default:
+		fmt.Println("Unknown AddProgress event: %v", event)
+		return &iroh.IrohError{}
+	}
+	return nil
+}
+
+func main() {
+	// create folder
+	if err := os.Mkdir("tmp", os.ModePerm); err != nil {
+		panic(err)
+	}
+	defer func() {
+		os.RemoveAll("tmp")
+		fmt.Println("Removed dir 'tmp'")
+	}()
+
+	path, err := filepath.Abs(filepath.Join("tmp"))
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("Created dir \"tmp\"")
+
+	fileNames := []string{"foo", "bar", "bat"}
+	// create three files in the folder
+	for _, fileName := range fileNames {
+		path := filepath.Join("tmp", fileName)
+		f, err := os.Create(path)
+		if err != nil {
+			panic(err)
+		}
+		_, err = f.WriteString(fmt.Sprintf("%s", fileName))
+		if err != nil {
+			panic(err)
+		}
+		fmt.Printf("Created file %q\n", path)
+	}
+
+	node, err := iroh.NewIrohNode("iroh_data_dir")
+	if err != nil {
+		panic(err)
+	}
+
+	// when `inPlace` is true, iroh will NOT copy over the files into its
+	// internal database. Only use this option when you know the file will never
+	// move or change
+	inPlace := false
+	// iroh blobs can be "tagged" with human readable names, this creates a tag
+	// automatically
+	tag := iroh.SetTagOptionAuto()
+	// when adding a single file, if you use `iroh.WrapOptionWrap`, you will turn
+	// the single file into a collection with one entry
+	wrap := iroh.WrapOptionNoWrap()
+	// you can use this callback to react to progress updates
+	callback := addCallback{}
+
+	// import the directory, creating one blob for each file, and one metadata
+	// blob that stores the file names for each blob
+	// also creates a 'collection' from the directory, grouping together the
+	// blobs
+
+	err = node.BlobsAddFromPath(path, inPlace, tag, wrap, callback)
+	if err != nil {
+		panic(err)
+	}
+
+	// Output:
+	// Created dir "tmp"
+	// Created file "tmp/foo"
+	// Created file "tmp/bar"
+	// Created file "tmp/bat"
+	// AddProgress - Found:
+	//    id: 2, name: $HOME/tmp/bar, size: 3
+	// AddProgress - Found:
+	//		id: 0, name: $HOME/tmp/foo, size: 3
+	// AddProgress - Found:
+	//		id: 1, name: $HOME/tmp/bat, size: 3
+	// AddProgress - Progress:
+	//		id: 1, offset: 3
+	// AddProgress - Done:
+	//		id: 1, hash: bafkr4iabccdb2eyeu764xoewbcqv62sjaggxibtmxx5tnmwer3wp3rquq4
+	// AddProgress - Progress:
+	//		id: 2, offset: 3
+	// AddProgress - Progress:
+	//		id: 0, offset: 3
+	// AddProgress - Done:
+	//		id: 2, hash: bafkr4ihs5cl65v6sa3gykxkecwmpuuq2xr22vfuvh2l4amgjmewdbqjjhu
+	// AddProgress - Done:
+	//		id: 0, hash: bafkr4iae4c5tt4yldi76xcpvg3etxykqkvec352im5fqbutolj2xo5yc5e
+	// AddProgress - AllDone:
+	//		hash: bafkr4iaotzhxuiak7eusnngngnwsqdu4crf4lmdxzkbhuebunevecjzkim, format: 2, tag: "auto-2023-12-09T17:37:42.432Z"
+	// Removed dir 'tmp'
+}

api-code-examples/go/blob-list-blobs.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/n0-computer/iroh-ffi/iroh-go/iroh"
+)
+
+func main() {
+	node, err := iroh.NewIrohNode("iroh_data_dir")
+	if err != nil {
+		panic(err)
+	}
+
+	b := []byte("hello world!")
+	tag := iroh.SetTagOptionAuto()
+
+	// add blob
+	outcome, err := node.BlobsAddBytes(b, tag)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("Added blob %s (%d bytes)\n", outcome.Hash.ToString(), outcome.Size)
+
+	fmt.Println("blobs list:")
+
+	blobs, err := node.BlobsList()
+	if err != nil {
+		panic(err)
+	}
+
+	for _, hash := range blobs {
+		fmt.Println("\t", hash.ToString())
+	}
+
+	// Output:
+	// Added blob bafkr4ib2uyoebh6xof6j3hddsibk6l5oi4ga55tjxz52fsxkk544wu2otu (12 bytes)
+	// blobs list:
+	//  bafkr4ib2uyoebh6xof6j3hddsibk6l5oi4ga55tjxz52fsxkk544wu2otu
+	//
+	//  (may contain additional hashes if you have previously added content to your node)
+}

api-code-examples/go/blob-list-collections.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/n0-computer/iroh-ffi/iroh-go/iroh"
+)
+
+type addCallback struct {
+	hashCh chan iroh.Hash
+}
+
+func (a addCallback) Progress(event *iroh.AddProgress) *iroh.IrohError {
+	if event.Type() == iroh.AddProgressTypeAllDone {
+		allDone := event.AsAllDone()
+		a.hashCh <- *allDone.Hash
+	}
+	return nil
+}
+
+func main() {
+	// create folder
+	if err := os.Mkdir("tmp", os.ModePerm); err != nil {
+		panic(err)
+	}
+	defer func() {
+		os.RemoveAll("tmp")
+		fmt.Println("Removed dir 'tmp'")
+	}()
+
+	path, err := filepath.Abs(filepath.Join("tmp"))
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("Created dir \"tmp\"")
+
+	fileNames := []string{"foo", "bar", "bat"}
+	// create three files in the folder
+	for _, fileName := range fileNames {
+		path := filepath.Join("tmp", fileName)
+		f, err := os.Create(path)
+		if err != nil {
+			panic(err)
+		}
+		_, err = f.WriteString(fmt.Sprintf("%s", fileName))
+		if err != nil {
+			panic(err)
+		}
+		fmt.Printf("Created file %q\n", path)
+	}
+
+	node, err := iroh.NewIrohNode("iroh_data_dir")
+	if err != nil {
+		panic(err)
+	}
+
+	// when `inPlace` is true, iroh will NOT copy over the files into its
+	// internal database. Only use this option when you know the file will never
+	// move or change
+	inPlace := false
+	// iroh blobs can be "tagged" with human readable names, this creates a tag
+	// automatically
+	tag := iroh.SetTagOptionNamed(iroh.TagFromString("my_collection"))
+	// when adding a single file, if you use `iroh.WrapOptionWrap`, you will turn
+	// the single file into a collection with one entry
+	wrap := iroh.WrapOptionNoWrap()
+	// you can use this callback to react to progress updates
+	hashCh := make(chan iroh.Hash, 1)
+	callback := addCallback{hashCh}
+
+	// import the directory, creating one blob for each file, and one metadata
+	// blob that stores the file names for each blob
+	// also creates a 'collection' from the directory, grouping together the
+	// blobs
+
+	err = node.BlobsAddFromPath(path, inPlace, tag, wrap, callback)
+	if err != nil {
+		panic(err)
+	}
+
+	hash := <-hashCh
+
+	fmt.Println("Added collection", hash.ToString())
+
+	fmt.Println("collections list:")
+
+	collRes, err := node.BlobsListCollections()
+	if err != nil {
+		panic(err)
+	}
+
+	for _, res := range collRes {
+		fmt.Printf("\thash: %s tag: %s\n", res.Hash.ToString(), res.Tag.ToString())
+	}
+
+	// Output:
+	// Created dir "tmp"
+	// Created file "tmp/foo"
+	// Created file "tmp/bar"
+	// Created file "tmp/bat"
+	// AllDone
+	// Added collection bafkr4iaotzhxuiak7eusnngngnwsqdu4crf4lmdxzkbhuebunevecjzkim
+	// collections list:
+	// 	hash:bafkr4iaotzhxuiak7eusnngngnwsqdu4crf4lmdxzkbhuebunevecjzkim tag:"my_collection"
+	// Removed dir 'tmp'
+	//
+	// (may contain additional collections if you have previously added content to your node)
+}