tree

package
v0.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package tree provides immutable, confined in-memory filesystems and private construction overlays. It depends only on the standard library.

Index

Constants

This section is empty.

Variables

View Source
var ErrConflict = errors.New("file/directory conflict")

ErrConflict identifies incompatible node kinds at a construction path.

View Source
var ErrEscape = errors.New("path escapes tree")

ErrEscape identifies a path or link target outside the tree. All absolute link targets are escapes, including host paths that point inside an input root; input loaders must translate those targets before construction if permitted.

View Source
var ErrLoop = errors.New("too many symlinks")

ErrLoop identifies resolution exceeding eight symlink traversals.

View Source
var ErrSealed = errors.New("builder is sealed")

ErrSealed identifies an operation on a builder whose ownership was transferred.

Functions

This section is empty.

Types

type Builder

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

Builder owns mutable construction state and must not be copied or shared between renders or source producers. Reads can memoize lower metadata.

func NewBuilder

func NewBuilder(lower fs.FS) *Builder

NewBuilder creates a private overlay over lower, or an empty source builder when lower is nil. Only upper directory indexes and inserted bytes are copied.

func (*Builder) AddFile

func (b *Builder) AddFile(name string, data []byte, mode fs.FileMode) error

AddFile copies data once. Duplicate files are last-wins; directories and symlinks are conflicts until removed explicitly.

func (b *Builder) AddSymlink(name, target string) error

AddSymlink stores a lexical target, including dangling, absolute and escaping targets. Follow operations enforce confinement; raw scans do not follow links.

func (*Builder) Build

func (b *Builder) Build() (*Tree, error)

Build transfers ownership to an immutable Tree and seals the builder.

func (*Builder) Lstat

func (t *Builder) Lstat(name string) (fs.FileInfo, error)

Lstat follows intermediate links but leaves the final link visible.

func (*Builder) Mount

func (b *Builder) Mount(name string, input fs.FS) error

Mount replaces a directory's indexed subtree with immutable content without copying bytes. Mounted inputs MUST remain read-only for the resulting tree lifetime.

func (*Builder) Open

func (t *Builder) Open(name string) (fs.File, error)

Open returns a read-only handle with an independent cursor.

func (*Builder) ReadDir

func (t *Builder) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir returns caller-owned entries sorted by name, following a link root.

func (*Builder) ReadFile

func (t *Builder) ReadFile(name string) ([]byte, error)

ReadFile follows links and returns caller-owned bytes.

func (t *Builder) ReadLink(name string) (string, error)

ReadLink returns the final link's target without resolving it.

func (*Builder) RemoveAll

func (b *Builder) RemoveAll(name string) error

RemoveAll masks a subtree without mutating the lower tree. Recreated nodes never expose lower descendants of that subtree.

func (*Builder) Resolve

func (t *Builder) Resolve(name string) (string, error)

Resolve follows links before subsequent parent components and returns a canonical slash path. Unlike the io/fs methods, it accepts unclean relative paths. Links stay confined to the tree.

func (*Builder) Stat

func (t *Builder) Stat(name string) (fs.FileInfo, error)

Stat follows the final link.

func (*Builder) WalkRaw

func (t *Builder) WalkRaw(name string, fn fs.WalkDirFunc) error

WalkRaw walks lexical nodes in order without following a link root or link entries. SkipDir prunes the single merged directory index.

type Tree

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

Tree is a sealed filesystem. An immutable lower permits concurrent readers without synchronization. Lower filesystems MUST remain read-only for the tree lifetime. Public slices are copies.

func (*Tree) Lstat

func (t *Tree) Lstat(name string) (fs.FileInfo, error)

Lstat follows intermediate links but leaves the final link visible.

func (*Tree) Open

func (t *Tree) Open(name string) (fs.File, error)

Open returns a read-only handle with an independent cursor.

func (*Tree) ReadDir

func (t *Tree) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir returns caller-owned entries sorted by name, following a link root.

func (*Tree) ReadFile

func (t *Tree) ReadFile(name string) ([]byte, error)

ReadFile follows links and returns caller-owned bytes.

func (t *Tree) ReadLink(name string) (string, error)

ReadLink returns the final link's target without resolving it.

func (*Tree) Resolve

func (t *Tree) Resolve(name string) (string, error)

Resolve follows links before subsequent parent components and returns a canonical slash path. Unlike the io/fs methods, it accepts unclean relative paths. Links stay confined to the tree.

func (*Tree) Stat

func (t *Tree) Stat(name string) (fs.FileInfo, error)

Stat follows the final link.

func (*Tree) WalkRaw

func (t *Tree) WalkRaw(name string, fn fs.WalkDirFunc) error

WalkRaw walks lexical nodes in order without following a link root or link entries. SkipDir prunes the single merged directory index.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL