6.6 KiB
Afero
A FileSystem Abstraction System for Go
Overview
Package Afero provides types and methods for interacting with the filesystem, as an abstraction layer.
It provides a few implementations that are largely interoperable. One that uses the operating system filesystem, one that uses memory to store files (cross platform) and an interface that should be implemented if you want to provide your own filesystem.
It is suitable for use in a any situation where you would consider using the OS package as it provides an additional abstraction that makes it easy to use a memory backed file system during testing. It also adds support for the http filesystem for full interoperability.
Afero has an exceptionally clean interface and simple design without needless constructors or initialization methods.
The name
Initially this project was called fs. Unfortunately as I used it, the name proved confusing, there were too many fs’. In looking for alternatives I looked up the word 'abstract' in a variety of different languages. Afero is the Greek word for abstract and it seemed to be a fitting name for the project. It also means ‘to do’ or ‘thing’ in Esperanto which is also fitting.
Interface
Afero simply takes the interfaces already defined throughout the standard library and unifies them into a pair of interfaces that satisfy all known uses. One interface for a file and one for a filesystem.
Filesystems
Afero additionally comes with a few filesystems and file implementations ready to use.
OsFs
The first is simply a wrapper around the native OS calls. This makes it very easy to use as all of the calls are the same as the existing OS calls. It also makes it trivial to have your code use the OS during operation and a mock filesystem during testing or as needed.
MemMapFs
Afero also provides a fully atomic memory backed filesystem perfect for use in mocking and to speed up unnecessary disk io when persistence isn’t necessary. It is fully concurrent and will work within go routines safely.
InMemoryFile
As part of MemMapFs, Afero also provides an atomic, fully concurrent memory backed file implementation. This can be used in other memory backed file systems with ease. Plans are to add a radix tree memory stored file system using InMemoryFile.
Usage
Installing
Using Afero is easy. First use go get to install the latest version of the library.
$ go get github.com/spf13/afero
Next include Afero in your application.
import "github.com/spf13/afero"
Using Afero
There are a few different ways to use Afero. You could use the interfaces alone to define you own file system. You could use it as a wrapper for the OS packages. You could use it to define different filesystems for different parts of your application. Here we will demonstrate a basic usage.
First define a package variable and set it to a pointer to a filesystem.
var AppFs afero.Fs = &afero.MemMapFs{}
or
var AppFs afero.Fs = &afero.OsFs{}
It is important to note that if you repeat the composite literal you will be using a completely new and isolated filesystem. In the case of OsFs it will still use the same underlying filesystem but will reduce the ability to drop in other filesystems as desired.
Then throughout your functions and methods use the methods familiar already from the OS package.
File System Methods Available:
Chmod(name string, mode os.FileMode) : error
Chtimes(name string, atime time.Time, mtime time.Time) : error
Create(name string) : File, error
Mkdir(name string, perm os.FileMode) : error
MkdirAll(path string, perm os.FileMode) : error
Name() : string
Open(name string) : File, error
OpenFile(name string, flag int, perm os.FileMode) : File, error
Remove(name string) : error
RemoveAll(path string) : error
Rename(oldname, newname string) : error
Stat(name string) : os.FileInfo, error
File Interfaces and Methods Available:
io.Closer
io.Reader
io.ReaderAt
io.Seeker
io.Writer
io.WriterAt
Stat() : os.FileInfo, error
Readdir(count int) : []os.FileInfo, error
Readdirnames(n int) : []string, error
WriteString(s string) : ret int, err error
Truncate(size int64) : error
Name() : string
In our case we would call AppFs.Open() as an example because that is how we’ve defined to
access our filesystem.
In some applications it may make sense to define a new package that simply exports the file system variable for easy access from anywhere.
Using a Mock Filesystem for Testing
There is a large benefit to using a mock filesystem for testing. It has a completely blank state every time it is initialized and can be easily reproducible regardless of OS. It is also faster than disk which makes the tests run faster. Lastly it doesn’t require any clean up after tests are run.
One way to accomplish this is to define a variable as mentioned above. In your application this will be set to &afero.OsFs{} during testing you can set it to &afero.MemMapFs{}.
Using with Http
The Http package requires a slightly specific version of Open which returns an http.File type.
Afero provides an httpFs file system which satisfies this requirement. Any Afero FileSystem can be used as an httpFs.
httpFs := &afero.HttpFs{SourceFs: <ExistingFS>}
fileserver := http.FileServer(httpFs.Dir(<PATH>)))
http.Handle("/", fileserver)
Release Notes
- 0.9.0 2015.11.05
- New Walk function similar to filepath.Walk
- MemMapFs.OpenFile handles O_TRUNC, O_APPEND, O_TRUNC
- MemMapFs.Remove now really deletes the file
- InMemoryFile.Readdir and Readdirnames work correctly
- InMemoryFile functions lock it for concurrent access
- Test suite improvements
- 0.8.0 2014.10.28
- First public version
- Interfaces feel ready for people to build using
- Interfaces satisfy all known uses
- MemMapFs passes the majority of the OS test suite
- OsFs passes the majority of the OS test suite
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Contributors
Names in no particular order:
License
Afero is released under the Apache 2.0 license. See LICENSE.txt