mfsng

An implementation of Go's filesystem interface for the IPFS UnixFS format.

Overview

mfsng is an implementation of fs.FS over a UnixFS merkledag.

Example Usage

In this example printFile prints the file folder/hello.txt held in the UnixFS represented by the supplied ipld.Node. getter is something that implements ipld.NodeGetter, such as a DagService

func printFile(node ipld.Node, getter ipld.NodeGetter) {
	fsys, err := mfsng.ReadFS(node, getter)
	if err != nil {
		log.Fatalf("failed to create fs: %v", err)
	}

	f, err := fsys.Open("folder/hello.txt")
	if err != nil {
		log.Fatalf("failed to open file: %v", err)
	}
	defer f.Close()

	data, err := io.ReadAll(f)
	if err != nil {
		log.Fatalf("failed to read file: %v", err)
	}

	fmt.Println(string(data))
}

This example demonstrates how the FS can be used with Go's standard walk function and shows how the underlying CID can be obtained for a file.

func walkFiles(node ipld.Node, getter ipld.NodeGetter) {
	fsys, err := mfsng.ReadFS(node, getter)
	if err != nil {
		log.Fatalf("failed to create fs: %v", err)
	}
	if err := fs.WalkDir(fsys, ".", func(path string, de fs.DirEntry, rerr error) error {
		if de.IsDir() {
			fmt.Printf("D %s\n", path)
		} else {
			f := de.(*mfsng.File)
			fmt.Printf("F %s (cid=%s)\n", path, f.Cid())
		}
		return nil
	}); err != nil {
		return log.Fatalf("failed walk: %v", err)
	}
}

An example of using the FS with Go's Glob functionality:

func matchFiles(node ipld.Node, getter ipld.NodeGetter) {
	fsys, err := mfsng.ReadFS(node, getter)
	if err != nil {
		log.Fatalf("failed to create fs: %v", err)
	}
	matches, err := fs.Glob(fsys, "some/*/folder/*.txt")
	if err != nil {
		log.Fatalf("failed to glob: %v", err)
	}

	for _, match := range matches {
		fmt.Println(match)
	}
}

Status

This package is experimental. It has a number of limitations:

• Read only
• No support for symlinks.
• No support for modtimes since they are not exposed by go-unixfs (but see go-unixfs#117)

Adding write capabilities is planned but some thought is needed around the API since there is no official one (although see go#issue-45757 for some discussion). Write capabilities are under development in the writefs branch.

Contributing

Welcoming new issues and pull requests.

License

This software is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)