filesystem

filesystem (interface)

Shared, minimal filesystem interfaces used by the concrete filesystem implementations in this repository.

Module

github.com/go-filesystems/interface

Purpose

This package defines a small, stable contract that filesystem drivers implement so higher-level tools can operate on different filesystem images without depending on concrete types. The interface intentionally focuses on common file and directory operations needed by tooling and tests.

API (summary)

• Filesystem — minimal filesystem API implemented by concrete packages:

type Filesystem interface {
	Close() error
	ReadFile(path string) ([]byte, error)
	ListDir(path string) ([]DirEntry, error)
	Stat(path string) (Stat, error)
	WriteFile(path string, data []byte, perm os.FileMode) error
	ReadLink(path string) (string, error)
	MkDir(path string, perm os.FileMode) error
	DeleteFile(path string) error
	DeleteDir(path string) error
	Rename(oldPath, newPath string) error
}

• Labeller — optional interface for filesystems that expose a volume label. Implementations cap the label at their own length limit (ext2/3/4: 16 bytes; FAT: 11 bytes). Probe via type assertion; not part of Filesystem because some filesystems genuinely have no label concept or where label mutation is non-trivial.

type Labeller interface {
    Label() string
    SetLabel(label string) error
}

if l, ok := fs.(filesystem.Labeller); ok {
    l.SetLabel("rootfs")
}

• LabelReader — optional read-only counterpart to Labeller, for drivers that can decode a volume label but can't yet rewrite it through their regular commit machinery. Every Labeller embeds this, so type-assert LabelReader when only reading is needed:

type LabelReader interface {
    Label() string
}

• Symlinker — optional interface for creating symbolic links (ReadLink is already part of Filesystem; this gates the write side):

type Symlinker interface {
    Symlink(target, linkPath string) error
}

• HardLinker — optional interface for POSIX hardlinks (directories cannot be hardlinked; implementations must reject that case):

type HardLinker interface {
    Link(oldPath, newPath string) error
}

• MetadataSetter — optional interface bundling the POSIX metadata mutators (chmod / chown / utimes):

type MetadataSetter interface {
    Chmod(path string, perm os.FileMode) error
    Chown(path string, uid, gid uint32) error
    Chtimes(path string, atime, mtime time.Time) error
}

• Truncater — optional interface for resizing a regular file in place (grow zero-fills, shrink drops trailing data):

type Truncater interface {
    Truncate(path string, newSize int64) error
}

• Grower / Resizer — optional interfaces for changing a filesystem's on-disk size. Grower.GrowTo is grow-only; Resizer.Resize is the newer, uniform entry point that also handles shrink where the format allows it, returning the sentinel ErrShrinkUnsupported when it doesn't:

type Grower interface {
    GrowTo(newSizeBytes int64) error
}

type Resizer interface {
    Resize(newSize int64) error
}

var ErrShrinkUnsupported = errors.New("filesystem: shrink not supported")

if r, ok := fs.(filesystem.Resizer); ok {
    if err := r.Resize(newSize); errors.Is(err, filesystem.ErrShrinkUnsupported) {
        // driver only grows — caller decides how to handle
    }
}

• Opener / File — optional interface for reading part of a file without materialising the whole thing. Filesystem.ReadFile is per-path and returns the entire file, which no mount or network export can build on: serving a 4 KiB request out of a 4 GiB file would allocate 4 GiB. Opener is the capability that makes those callers possible, and it is optional and non-breaking — probe for it, fall back to ReadFile when a driver lacks it:

type Opener interface {
    OpenFile(path string) (File, error)
}

type File interface {
    io.ReaderAt
    io.Closer
    Size() int64
}

if o, ok := fs.(filesystem.Opener); ok {
    f, err := o.OpenFile("/big.img")
    if err != nil {
        return err
    }
    defer f.Close()
    n, err := f.ReadAt(buf, off) // only the bytes asked for
    _, _ = n, err
} else {
    data, err := fs.ReadFile("/big.img") // fallback: the whole file
    _, _ = data, err
}

ReadAt follows io.ReaderAt to the letter: n < len(p) only ever comes back with a non-nil error, end of file reports io.EOF, and an offset at or past Size() returns 0, io.EOF. Anything looser breaks io.SectionReader and every consumer built on it, silently. Reads are safe to issue concurrently on one File, as io.ReaderAt requires. Size() comes from metadata already read at open time, so a caller can answer a stat without touching the data.

A driver whose format genuinely cannot answer a byte range without decoding everything before it should simply not implement Opener, rather than emulate it with a hidden full read — the probe exists so the caller learns the truth.

• DirEntry — accessor interface for directory entries:

type DirEntry interface {
	Inode() uint64
	Name() string
	FileType() uint8
}

• Stat — file metadata accessor:

type Stat interface {
	Mode() uint16
	Size() uint64
	Inode() uint64
}

Constructors NewDirEntry(inode, name, fileType) and NewStat(mode,size,inode) are provided for convenience.

Implementations

Known implementations, across the go-filesystems org:

• github.com/go-filesystems/apfs
• github.com/go-filesystems/btrfs
• github.com/go-filesystems/exfat
• github.com/go-filesystems/ext4
• github.com/go-filesystems/fat32
• github.com/go-filesystems/ffs (re-export of ufs)
• github.com/go-filesystems/hfsplus
• github.com/go-filesystems/iso9660
• github.com/go-filesystems/ntfs
• github.com/go-filesystems/oci
• github.com/go-filesystems/squashfs
• github.com/go-filesystems/uefi
• github.com/go-filesystems/ufs
• github.com/go-filesystems/xfs
• github.com/go-filesystems/zfs

See each implementor's README for format-specific details, examples, and which optional interfaces above it satisfies; or see go-filesystems.github.io/docs/drivers for a capability matrix. github.com/go-filesystems/detect composes over this interface too, as a type-probing dispatch registry rather than a driver.

Usage example

The interface can be used as a programming abstraction so callers accept a filesystem.Filesystem regardless of the concrete implementation:

import (
	filesystem "github.com/go-filesystems/interface"
	fsx "github.com/go-filesystems/xfs"
)

func example() error {
	f, err := fsx.Open("image.img", -1)
	if err != nil {
		return err
	}
	defer f.Close()

	// Use as the generic interface
	var fs filesystem.Filesystem = f
	data, err := fs.ReadFile("/hello.txt")
	if err != nil {
		return err
	}
	_ = data
	return nil
}

Notes

Keep the interface minimal; add helpers in implementor packages when format-specific functionality is required.