filesystem

Documentation

Overview

Package filesystem binds the family's interfaces.Vfs seam to the real operating-system filesystem.

The interfaces sibling owns the seam and ships an in-memory implementation for tests, and no library in the family ships a host one — so the harness does, for the same reason it ships the terminal binding: a fixture materialized only into memory is a fixture a compiled artifact cannot read, which would make the compiled-artifact driver useless.

It is the only place in this module that touches os and path/filepath.

Index

• Constants
• type Vfs
  • func NewVfs() Vfs
  • func (Vfs) CreateDirectory(_ context.Context, path string, options interfaces.DirectoryOptions) error
  • func (Vfs) Delete(_ context.Context, path string, options interfaces.DirectoryOptions) error
  • func (Vfs) Exists(_ context.Context, path string) (bool, error)
  • func (Vfs) List(_ context.Context, path string, options interfaces.ListOptions) ([]interfaces.VfsEntry, error)
  • func (Vfs) ReadBytes(_ context.Context, path string) ([]byte, error)
  • func (v Vfs) ReadText(ctx context.Context, path string) (string, error)
  • func (Vfs) WriteBytes(_ context.Context, path string, content []byte, ...) error
  • func (v Vfs) WriteText(ctx context.Context, path string, content string, ...) error

Examples

• NewVfs
• Vfs.Exists
• Vfs.List

Constants

const (
	// FilePermissions is the mode a written fixture file carries.
	FilePermissions fs.FileMode = 0o600
	// DirectoryPermissions is the mode a created fixture directory carries.
	DirectoryPermissions fs.FileMode = 0o700
)

Permissions the harness creates fixture files and directories with.

A fixture holds injected credentials, so it is owner-only. Nothing in a SIT run needs another account to read the environment a test was handed.

Types

type Vfs

type Vfs struct{}

Vfs is the process-backed filesystem seam and satisfies interfaces.Vfs.

It is a value type with no mutable state, so one instance is safe to share across a whole suite.

func NewVfs

func NewVfs() Vfs

NewVfs returns the process-backed filesystem seam.

Example

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/AtomiCloud/diene.go-e2e/adapters/filesystem"
	"github.com/AtomiCloud/diene.go-interfaces/lib/interfaces"
)

func main() {
	vfs := filesystem.NewVfs()
	root, err := os.MkdirTemp("", "diene-e2e-example-")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(root) }()

	target := filepath.Join(root, "config", "base.yaml")
	if writeErr := vfs.WriteText(context.Background(), target, "app: billing\n", interfaces.WriteOptions{CreateParents: true}); writeErr != nil {
		panic(writeErr)
	}
	present, err := vfs.Exists(context.Background(), target)
	if err != nil {
		panic(err)
	}
	content, err := vfs.ReadText(context.Background(), target)
	if err != nil {
		panic(err)
	}
	fmt.Print(present, " ", content)
}

Output:
true app: billing

func (Vfs) CreateDirectory

func (Vfs) CreateDirectory(_ context.Context, path string, options interfaces.DirectoryOptions) error

CreateDirectory creates path, and its parents when options asks for it.

func (Vfs) Delete

func (Vfs) Delete(_ context.Context, path string, options interfaces.DirectoryOptions) error

Delete removes path, and its contents when options asks for it.

func (Vfs) Exists

func (Vfs) Exists(_ context.Context, path string) (bool, error)

Exists reports whether path is present.

An absent path is NOT an error: "does the artifact exist" is a question, and answering it with a failure would force every caller to unwrap os errors.

Example

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/AtomiCloud/diene.go-e2e/adapters/filesystem"
)

func main() {
	vfs := filesystem.NewVfs()
	// An absent path is an answer, not a failure.
	present, err := vfs.Exists(context.Background(), filepath.Join(os.TempDir(), "diene-e2e-absent"))
	fmt.Println(present, err)
}

Output:
false <nil>

func (Vfs) List

func (Vfs) List(_ context.Context, path string, options interfaces.ListOptions) ([]interfaces.VfsEntry, error)

List returns the entries under path, recursively when options asks for it.

Both modes are one walk. A shallow listing simply refuses to descend, which keeps a single error path for an entry that cannot be read — two implementations would eventually disagree about what a listing failure is.

Entries come back in a stable order so a failing SIT report can be diffed against a passing one.

Example

package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"

	"github.com/AtomiCloud/diene.go-e2e/adapters/filesystem"
	"github.com/AtomiCloud/diene.go-interfaces/lib/interfaces"
)

func main() {
	vfs := filesystem.NewVfs()
	root, err := os.MkdirTemp("", "diene-e2e-example-")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(root) }()

	for _, name := range []string{"garden.yaml", "base.yaml"} {
		if writeErr := vfs.WriteText(context.Background(), filepath.Join(root, name), "{}\n", interfaces.WriteOptions{}); writeErr != nil {
			panic(writeErr)
		}
	}
	entries, err := vfs.List(context.Background(), root, interfaces.ListOptions{})
	if err != nil {
		panic(err)
	}
	for _, entry := range entries {
		fmt.Println(filepath.Base(entry.Path), entry.Type)
	}
}

Output:
base.yaml file
garden.yaml file

func (Vfs) ReadBytes

func (Vfs) ReadBytes(_ context.Context, path string) ([]byte, error)

ReadBytes reads the whole file at path.

func (Vfs) ReadText

func (v Vfs) ReadText(ctx context.Context, path string) (string, error)

ReadText reads the whole file at path as text.

func (Vfs) WriteBytes

func (Vfs) WriteBytes(_ context.Context, path string, content []byte, options interfaces.WriteOptions) error

WriteBytes writes content to path, creating parent directories when options asks for it.

func (Vfs) WriteText

func (v Vfs) WriteText(ctx context.Context, path string, content string, options interfaces.WriteOptions) error

WriteText writes content to path as text, creating parent directories when options asks for it.