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

rootfs

package
v0.34.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: BSD-3-Clause Imports: 15 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.

View Source 
const MaxZstdWindow = 64 << 20

MaxZstdWindow bounds a zstd layer's window, which is what the decoder allocates: zstd's levels 1-19 use at most 8 MiB, --long up to 128 MiB.

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 ErrArchive = errors.New("rootfs: archive")

ErrArchive is wrapped by every refusal of an archive (PUT/GET /containers/{id}/archive).

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

ErrLayer is wrapped by every refusal of layer content.

View Source 
var ErrWhiteoutName = errors.New("rootfs: a file name beginning with .wh. cannot be written to an image layer")

ErrWhiteoutName is returned by WriteLayer for a changed path whose name begins with ".wh.": an OCI layer would read it as a whiteout.

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) AddExternal added in v0.33.0 

func (f *FS) AddExternal(p string, r io.ReaderAt, size int64) error

AddExternal adds a read-only regular file at p (parents are created) whose content is read from r on demand: nothing is copied into memory and nothing is charged to the quota. Every write, truncation or open for writing of it fails with ErrReadOnly, in this tree and in its clones.

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) Extract added in v0.12.0 

func (f *FS) Extract(dst string, r io.Reader, lim Limits, noOverwriteDirNonDir bool) error

Extract writes a tar into the directory dst of the tree, as `docker cp` into a container does. The tar is untrusted: names must be relative and clean (no "..", no absolute path), hard links must name an entry inside dst, devices and FIFOs are refused, and the entries, each file and the total are bounded by lim. Every write goes through the tree's own operations, so paths resolve inside the root (a symlink cannot lead out) and the tree's quota applies. With noOverwriteDirNonDir, an entry that would replace a directory with a non-directory, or the reverse, is refused.

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.

func (*FS) WriteLayer added in v0.12.0 

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

WriteLayer writes what this tree changed relative to its base as an OCI image layer (an uncompressed tar changeset): added and changed entries in full, removed ones as ".wh.<name>" entries, a directory removed and made again followed by ".wh..wh..opq". It is what `commit` stores. A tree that is not a clone is written whole.

func (*FS) WriteTar added in v0.12.0 

func (f *FS) WriteTar(src string, w io.Writer) error

WriteTar writes the file or directory at src as a tar rooted at its base name, as `docker cp` out of a container does: directories recursively, symlinks as links (not followed), each regular file with its content.

func (*FS) Written added in v0.7.0 

func (f *FS) Written() int64

Written is how many bytes have been written to this tree's files, over its life (not what it holds: see Usage).

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.