Skip to content

Latest commit

 

History

History
158 lines (116 loc) · 3.18 KB

backend.md

File metadata and controls

158 lines (116 loc) · 3.18 KB

backend

Package backend provides a means of allowing backend file systems to self-register on load via an init() call to backend.Register("some scheme", vfs.FileSystem)

In this way, a caller of vfs backends can simply load the backend file system (and ONLY those needed) and begin using it:

package main

// import backend and each backend you intend to use
import (
	"github.com/c2fo/vfs/v7"
	"github.com/c2fo/vfs/v7/backend"
	"github.com/c2fo/vfs/v7/backend/os"
	"github.com/c2fo/vfs/v7/backend/s3"
)

func main() {
    var err error
    var osfile, s3file vfs.File

    // THEN begin using the file systems
    osfile, err = backend.Backend(os.Scheme).NewFile("", "/path/to/file.txt")
    if err != nil {
        panic(err)
    }

    s3file, err = backend.Backend(s3.Scheme).NewFile("mybucket", "/some/file.txt")
    if err != nil {
        panic(err)
    }

    err = osfile.CopyTo(s3file)
    if err != nil {
        panic(err)
    }
}

Development

To create your own backend, you must create a package that implements the interfaces: vfs.FileSystem, vfs.Location, and vfs.File. Then ensure it registers itself on load:

package myexoticfilesystem

    import(
        ...
        "github.com/c2fo/vfs/v7"
        "github.com/c2fo/vfs/v7/backend"
    )

    // IMPLEMENT vfs interfaces
    ...

    // register backend
    func init() {
        backend.Register("exfs", &MyExoticFileSystem{})
    }

Then do use it in some other package do

    package MyExoticFileSystem

    import(
        "github.com/c2fo/vfs/v7/backend"
        "github.com/acme/myexoticfilesystem"
    )

    ...

    func useNewBackend() error {
        myExoticFs, err = backend.Backend(myexoticfilesystem.Scheme)
        ...
    }

That's it. Simple.

Testing Your Backend

To verify your backend implementation is correct, use the conformance test suite provided by backend/testsuite. See Conformance Tests for detailed instructions.

Quick example:

//go:build vfsintegration

package myexoticfilesystem

import (
    "os"
    "testing"
    "github.com/c2fo/vfs/v7/backend/testsuite"
)

func TestConformance(t *testing.T) {
    fs := NewFileSystem(/* options */)
    location, _ := fs.NewLocation("", "/test-path/")
    testsuite.RunConformanceTests(t, location)
}

func TestIOConformance(t *testing.T) {
    fs := NewFileSystem(/* options */)
    location, _ := fs.NewLocation("", "/test-path/")
    testsuite.RunIOTests(t, location)
}

Run with: go test -v -tags=vfsintegration ./...

Usage

func Backend

func Backend(name string) vfs.FileSystem

Backend returns the backend file system by name

func Register

func Register(name string, v vfs.FileSystem)

Register a new file system in backend map

func RegisteredBackends

func RegisteredBackends() []string

RegisteredBackends returns an array of backend names

func Unregister

func Unregister(name string)

Unregister unregisters a file system from backend map

func UnregisterAll

func UnregisterAll()

UnregisterAll unregisters all file systems from backend map