README
¶
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)
Documentation
¶
Index ¶
- type Dir
- type FS
- type File
- func (f *File) Cid() cid.Cid
- func (f *File) Close() error
- func (f *File) Info() (fs.FileInfo, error)
- func (f *File) IsDir() bool
- func (f *File) Name() string
- func (f *File) Read(buf []byte) (int, error)
- func (f *File) Seek(offset int64, whence int) (int64, error)
- func (f *File) Stat() (fs.FileInfo, error)
- func (f *File) Type() fs.FileMode
- func (f *File) WriteTo(w io.Writer) (int64, error)
- type FileInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dir ¶
type Dir struct {
// contains filtered or unexported fields
}
func (*Dir) ReadDir ¶
ReadDir reads the contents of the directory and returns a slice of up to n DirEntry values in directory order. Subsequent calls on the same file will yield further DirEntry values. If n > 0, ReadDir returns at most n DirEntry structures. In this case, if ReadDir returns an empty slice, it will return a non-nil error explaining why. At the end of a directory, the error is io.EOF.
If n <= 0, ReadDir returns all the DirEntry values from the directory in a single slice. In this case, if ReadDir succeeds (reads all the way to the end of the directory), it returns the slice and a nil error. If it encounters an error before the end of the directory, ReadDir returns the DirEntry list read until that point and a non-nil error.
type FS ¶
type FS struct {
// contains filtered or unexported fields
}
func ReadFS ¶
ReadFS returns a read-only filesystem. It expects the supplied node to be the root of a UnixFS merkledag.
func (*FS) ReadDir ¶
ReadDir reads the named directory and returns a list of directory entries sorted by filename.
type File ¶
type File struct {
// contains filtered or unexported fields
}
type FileInfo ¶
type FileInfo struct {
// contains filtered or unexported fields
}
func (*FileInfo) Cid ¶
func (f *FileInfo) Cid() cid.Cid
Cid returns the CID of the file or directory's root node.
func (*FileInfo) ModTime ¶
Mode returns the modification time of the file if known or the zero time otherwise.
Source Files