Help us shape the future of Go! Take the 2026 Go Developer Survey

rootfs

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2026 License: BSD-3-Clause Imports: 14 Imported by: 0

Documentation

Overview

Package rootfs is a container's root filesystem: an in-memory tree that image layers are applied to, frozen as a read-only lower, and cloned per container into a copy-on-write upper.

It is deliberately free of any WebAssembly runtime type, so the native executor (wazero) and the browser executor can both adapt the same tree.

The tree lives entirely in memory and every path is resolved inside it: absolute symlink targets are relative to the tree's root and ".." stops at the root, so nothing a container or a layer does can reach the host.

Index

Constants

View Source 
const (
	Modified = 0 // C
	Added    = 1 // A
	Deleted  = 2 // D
)

Change kinds, as the Docker Engine API numbers them.

Variables

View Source 
var (
	ErrNotDir      = errors.New("not a directory")
	ErrIsDir       = errors.New("is a directory")
	ErrNotEmpty    = errors.New("directory not empty")
	ErrLoop        = errors.New("too many levels of symbolic links")
	ErrNoSpace     = errors.New("no space left on device")
	ErrReadOnly    = errors.New("read-only file system")
	ErrNameTooLong = errors.New("file name too long")
	ErrBadFile     = errors.New("bad file descriptor")
	ErrCrossLink   = errors.New("invalid cross-device link")
)

Errors beyond those io/fs defines.

View Source 
var DefaultLimits = Limits{
	MaxBytes:   1 << 30,
	MaxFiles:   1 << 17,
	MaxRatio:   200,
	MaxPathLen: 4096,
	MaxDepth:   128,
}

DefaultLimits fit wasm images with a wide margin.

View Source 
var ErrLayer = errors.New("unsafe or invalid layer")

ErrLayer is wrapped by every refusal of layer content.

Functions

func ModulePath 

func ModulePath(title string) string

ModulePath is where a bare wasm module layer is placed: "/" plus its title when that is a plain, safe file name, otherwise "/module.wasm".

Types

type Budget 

type Budget struct {
	Limits
	Bytes int64
	Files int
}

Budget tracks what has been spent of a Limits.

func NewBudget 

func NewBudget(lim Limits) *Budget

NewBudget starts spending lim.

type Change added in v0.4.0 

type Change struct {
	Path string
	Kind int
}

Change is one path a clone changed relative to its base.

type DirEntry 

type DirEntry struct {
	// contains filtered or unexported fields
}

DirEntry is one directory entry. It implements fs.DirEntry.

func (DirEntry) Info 

func (d DirEntry) Info() (fs.FileInfo, error)

func (DirEntry) Ino 

func (d DirEntry) Ino() uint64

Ino returns the entry's inode number.

func (DirEntry) IsDir 

func (d DirEntry) IsDir() bool

func (DirEntry) Name 

func (d DirEntry) Name() string

func (DirEntry) Type 

func (d DirEntry) Type() fs.FileMode

type FS 

type FS struct {
	// contains filtered or unexported fields
}

FS is an in-memory filesystem tree. It is safe for concurrent use.

func Build 

func Build(layers []LayerReader, lim Limits) (*FS, error)

Build applies layers in order to a new tree and freezes it.

func New 

func New() *FS

New returns an empty tree with a 0755 root directory.

func (*FS) ApplyDiff added in v0.4.0 

func (f *FS) ApplyDiff(r io.Reader, u Usage, lim Limits) error

ApplyDiff applies WriteDiff's output to f, a fresh clone of the same base, and restores the usage it recorded (bounded by f's quota). The changeset is untrusted (it comes back from storage): it is checked as an image layer is, under lim.

func (*FS) ApplyLayer 

func (f *FS) ApplyLayer(r io.Reader, mediaType, title string, b *Budget) error

ApplyLayer applies one layer blob of the given media type to f. title is the layer's org.opencontainers.image.title annotation, used to name a bare wasm module.

func (*FS) ApplyTar 

func (f *FS) ApplyTar(r io.Reader, b *Budget) error

ApplyTar applies an uncompressed tar changeset to f, per the OCI layer specification: opaque whiteouts first, then explicit whiteouts, both against what lower layers left; then additions in archive order, so a whiteout never hides an entry of its own layer.

Refused outright: absolute names, "..", names under a non-directory (which is how a symlink planted by one entry redirects the next), symlink targets that climb above the root, hard links to anything but an existing regular file, and anything over the budget.

func (*FS) ApplyWasm 

func (f *FS) ApplyWasm(r io.Reader, title string, b *Budget) (string, error)

ApplyWasm writes a single wasm module (a CNCF wasm artifact layer) into the tree and returns its path.

func (*FS) Changes added in v0.4.0 

func (f *FS) Changes() uint64

Changes counts this tree's mutations: equal counts, equal trees.

func (*FS) Chmod 

func (f *FS) Chmod(p string, mode fs.FileMode) error

Chmod changes permission bits.

func (*FS) Chtimes 

func (f *FS) Chtimes(p string, mtime time.Time, follow bool) error

Chtimes sets the modification time (access time is not kept).

func (*FS) Clone 

func (f *FS) Clone(q Quota) *FS

Clone returns a writable copy-on-write view of f: f's nodes are shared until the clone writes to them, at which point the clone copies them up. Writing to f afterwards (if it is not frozen) copies up as well, so neither ever sees the other's changes.

func (*FS) Diff added in v0.4.0 

func (f *FS) Diff() []Change

Diff lists what this tree changed relative to its base, sorted by path, as `docker diff` does: a changed directory is Modified and its changed entries follow; everything under a new directory is Added.

func (*FS) Freeze 

func (f *FS) Freeze()

Freeze makes the tree read-only: every later mutation fails with ErrReadOnly. Clones of a frozen tree are writable.

func (*FS) IOFS 

func (f *FS) IOFS() fs.FS

IOFS returns a read-only io/fs view of the tree, with fs.FS's strict path rules (unrooted, slash-separated, no "." or ".." elements), so the tree can be handed to anything that reads an fs.FS, fstest included. 

func (f *FS) Link(oldPath, newPath string) error

Link creates newPath as a hard link to the non-directory oldPath.

func (*FS) Lstat 

func (f *FS) Lstat(p string) (*Info, error)

Lstat describes the file at p without following a final symlink.

func (*FS) Mkdir 

func (f *FS) Mkdir(p string, perm fs.FileMode) error

Mkdir creates a directory.

func (*FS) MkdirAll 

func (f *FS) MkdirAll(p string, perm fs.FileMode) error

MkdirAll creates p and any missing parents.

func (*FS) OpenFile 

func (f *FS) OpenFile(p string, flag Flag, perm fs.FileMode) (*File, error)

OpenFile opens p with the given flags; perm is used when creating.

func (*FS) ReadDir 

func (f *FS) ReadDir(p string) ([]DirEntry, error)

ReadDir lists the directory at p, sorted by name.

func (*FS) ReadFile 

func (f *FS) ReadFile(p string) ([]byte, error)

ReadFile returns a copy of the content of the file at p. 

func (f *FS) Readlink(p string) (string, error)

Readlink returns a symlink's target.

func (*FS) Remove 

func (f *FS) Remove(p string) error

Remove unlinks a non-directory entry (a symlink itself, not its target).

func (*FS) Rename 

func (f *FS) Rename(from, to string) error

Rename moves from to to, replacing to as POSIX rename does.

func (*FS) Rmdir 

func (f *FS) Rmdir(p string) error

Rmdir removes an empty directory.

func (*FS) Stat 

func (f *FS) Stat(p string) (*Info, error)

Stat describes the file at p, following symlinks. 

func (f *FS) Symlink(target, linkPath string) error

Symlink creates linkPath pointing at target.

func (*FS) Usage 

func (f *FS) Usage() (bytes int64, files int)

Usage returns the bytes and entries this tree has added.

func (*FS) WriteDiff added in v0.4.0 

func (f *FS) WriteDiff(w io.Writer) (Usage, error)

WriteDiff writes what this tree changed relative to the tree it was cloned from as a tar changeset that ApplyDiff, on a fresh clone of the same base, turns back into an equal tree: added and changed entries in full, removed ones as whiteouts, a directory removed and made again as opaque. A tree that is not a clone is written whole. Hard links among the written entries are kept; a link to an entry left unchanged in the base is written as a copy.

func (*FS) WriteFile 

func (f *FS) WriteFile(p string, data []byte, perm fs.FileMode) error

WriteFile creates or truncates the file at p and writes data to it.

type File 

type File struct {
	// contains filtered or unexported fields
}

File is an open file or directory.

func (*File) Chtimes 

func (h *File) Chtimes(mtime time.Time) error

Chtimes sets the open file's modification time.

func (*File) Close 

func (h *File) Close() error

Close implements io.Closer.

func (*File) Entries 

func (h *File) Entries(n int) ([]DirEntry, error)

Entries is ReadDir with the concrete type and no io.EOF.

func (*File) Info 

func (h *File) Info() (*Info, error)

Info is Stat with the concrete type.

func (*File) IsAppend 

func (h *File) IsAppend() bool

IsAppend reports whether writes go to the end.

func (*File) IsDir 

func (h *File) IsDir() bool

IsDir reports whether the file is a directory.

func (*File) Name 

func (h *File) Name() string

Name returns the base name the file was opened by.

func (*File) Read 

func (h *File) Read(p []byte) (int, error)

Read implements io.Reader.

func (*File) ReadAt 

func (h *File) ReadAt(p []byte, off int64) (int, error)

ReadAt implements io.ReaderAt.

func (*File) ReadDir 

func (h *File) ReadDir(n int) ([]fs.DirEntry, error)

ReadDir implements fs.ReadDirFile: with n > 0 it returns at most n entries and io.EOF at the end; with n <= 0 all remaining entries.

func (*File) Seek 

func (h *File) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker. On a directory only (0, SeekStart) is accepted, which rewinds ReadDir.

func (*File) SetAppend 

func (h *File) SetAppend(on bool)

SetAppend toggles append mode.

func (*File) Stat 

func (h *File) Stat() (fs.FileInfo, error)

Stat implements fs.File.

func (*File) Truncate 

func (h *File) Truncate(size int64) error

Truncate changes the file's size.

func (*File) Write 

func (h *File) Write(p []byte) (int, error)

Write implements io.Writer.

func (*File) WriteAt 

func (h *File) WriteAt(p []byte, off int64) (int, error)

WriteAt implements io.WriterAt. It ignores O_APPEND, as pwrite does on most systems wasm guests expect.

type Flag 

type Flag int

Flag is an open flag. The access modes are exclusive; the rest combine. 

const (
	O_RDONLY Flag = 0
	O_WRONLY Flag = 1
	O_RDWR   Flag = 2
	// O_ACCMODE masks the access mode.
	O_ACCMODE Flag = 3

	O_CREATE    Flag = 1 << 3
	O_EXCL      Flag = 1 << 4
	O_TRUNC     Flag = 1 << 5
	O_APPEND    Flag = 1 << 6
	O_DIRECTORY Flag = 1 << 7
	O_NOFOLLOW  Flag = 1 << 8
)

type Info 

type Info struct {
	Ino   uint64
	Nlink uint64
	// contains filtered or unexported fields
}

Info describes a file. It implements fs.FileInfo.

func (*Info) IsDir 

func (i *Info) IsDir() bool

func (*Info) ModTime 

func (i *Info) ModTime() time.Time

func (*Info) Mode 

func (i *Info) Mode() fs.FileMode

func (*Info) Name 

func (i *Info) Name() string

func (*Info) Size 

func (i *Info) Size() int64

func (*Info) Sys 

func (i *Info) Sys() any

type LayerReader 

type LayerReader struct {
	MediaType string
	Title     string
	Open      func() (io.ReadCloser, error)
}

LayerReader is one layer to build from.

type Limits 

type Limits struct {
	// MaxBytes bounds the total uncompressed bytes of file content.
	MaxBytes int64
	// MaxFiles bounds the total number of entries.
	MaxFiles int
	// MaxRatio bounds decompressed/compressed bytes of a compressed layer.
	MaxRatio int64
	// MaxPathLen bounds an entry name or link target.
	MaxPathLen int
	// MaxDepth bounds the number of components of an entry name.
	MaxDepth int
}

Limits bounds what unpacking an image's layers may produce. A Budget spends one Limits across all the layers of an image.

type Quota 

type Quota struct {
	// MaxBytes bounds the bytes this tree adds (0 = unlimited).
	MaxBytes int64
	// MaxFiles bounds the entries this tree adds (0 = unlimited).
	MaxFiles int
}

Quota bounds what may be written into a tree.

type Usage added in v0.4.0 

type Usage struct {
	Bytes int64 `json:"bytes"`
	Files int   `json:"files"`
}

Usage is what a tree has added, as Quota counts it.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.