Documentation
¶
Overview ¶
Package fs provides the filesystem contracts and virtual filesystem backends used by gbash, including the default mutable in-memory backend and the experimental read-mostly trie-backed backend.
This is a supported public extension package for callers that need to supply custom filesystem implementations or factories. Most embedders should still prefer the root `github.com/ewhauser/gbash` package and its higher-level filesystem helpers.
Index ¶
- Constants
- func Clean(name string) string
- func Resolve(dir, name string) string
- type FIFOFileSystem
- type Factory
- func Host(opts HostOptions) Factory
- func Memory() Factory
- func Mountable(opts MountableOptions) Factory
- func Overlay(lower Factory) Factory
- func ReadWrite(opts ReadWriteOptions) Factory
- func Reusable(source Factory) Factory
- func SeededMemory(files InitialFiles) Factory
- func SeededTrie(files InitialFiles) Factory
- func Snapshot(source FileSystem) Factory
- func Trie() Factory
- type FactoryFunc
- type File
- type FileOwnership
- type FileSystem
- type HostFS
- func (h *HostFS) Chdir(name string) error
- func (h *HostFS) Chmod(_ context.Context, name string, _ stdfs.FileMode) error
- func (h *HostFS) Chown(_ context.Context, name string, _, _ uint32, _ bool) error
- func (h *HostFS) Chtimes(_ context.Context, name string, _, _ time.Time) error
- func (h *HostFS) Getwd() string
- func (h *HostFS) Link(_ context.Context, _, newName string) error
- func (h *HostFS) Lstat(_ context.Context, name string) (stdfs.FileInfo, error)
- func (h *HostFS) MkdirAll(_ context.Context, name string, _ stdfs.FileMode) error
- func (h *HostFS) Mkfifo(_ context.Context, name string, _ stdfs.FileMode) error
- func (h *HostFS) Open(ctx context.Context, name string) (File, error)
- func (h *HostFS) OpenFile(_ context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (h *HostFS) ReadDir(_ context.Context, name string) ([]stdfs.DirEntry, error)
- func (h *HostFS) Readlink(_ context.Context, name string) (string, error)
- func (h *HostFS) Realpath(_ context.Context, name string) (string, error)
- func (h *HostFS) Remove(_ context.Context, name string, _ bool) error
- func (h *HostFS) Rename(_ context.Context, oldName, _ string) error
- func (h *HostFS) Stat(_ context.Context, name string) (stdfs.FileInfo, error)
- func (h *HostFS) Symlink(_ context.Context, _, linkName string) error
- type HostOptions
- type InitialFile
- type InitialFiles
- type LazyFileProvider
- type MemoryFS
- func (m *MemoryFS) Chdir(name string) error
- func (m *MemoryFS) Chmod(_ context.Context, name string, mode stdfs.FileMode) error
- func (m *MemoryFS) Chown(_ context.Context, name string, uid, gid uint32, follow bool) error
- func (m *MemoryFS) Chtimes(_ context.Context, name string, atime, mtime time.Time) error
- func (m *MemoryFS) Clone() *MemoryFS
- func (m *MemoryFS) Getwd() string
- func (m *MemoryFS) Link(_ context.Context, oldName, newName string) error
- func (m *MemoryFS) Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (m *MemoryFS) MkdirAll(_ context.Context, name string, perm stdfs.FileMode) error
- func (m *MemoryFS) Mkfifo(_ context.Context, name string, perm stdfs.FileMode) error
- func (m *MemoryFS) Open(ctx context.Context, name string) (File, error)
- func (m *MemoryFS) OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (m *MemoryFS) ReadDir(_ context.Context, name string) ([]stdfs.DirEntry, error)
- func (m *MemoryFS) Readlink(_ context.Context, name string) (string, error)
- func (m *MemoryFS) Realpath(_ context.Context, name string) (string, error)
- func (m *MemoryFS) Remove(_ context.Context, name string, recursive bool) error
- func (m *MemoryFS) Rename(_ context.Context, oldName, newName string) error
- func (m *MemoryFS) Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (m *MemoryFS) Symlink(_ context.Context, target, linkName string) error
- type MountConfig
- type MountableFS
- func (m *MountableFS) Chdir(name string) error
- func (m *MountableFS) Chmod(ctx context.Context, name string, mode stdfs.FileMode) error
- func (m *MountableFS) Chown(ctx context.Context, name string, uid, gid uint32, follow bool) error
- func (m *MountableFS) Chtimes(ctx context.Context, name string, atime, mtime time.Time) error
- func (m *MountableFS) Getwd() string
- func (m *MountableFS) IsMountPoint(pathValue string) bool
- func (m *MountableFS) Link(ctx context.Context, oldName, newName string) error
- func (m *MountableFS) Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (m *MountableFS) MkdirAll(ctx context.Context, name string, perm stdfs.FileMode) error
- func (m *MountableFS) Mkfifo(ctx context.Context, name string, perm stdfs.FileMode) error
- func (m *MountableFS) Mount(mountPoint string, fsys FileSystem) error
- func (m *MountableFS) Mounts() []MountedFS
- func (m *MountableFS) Open(ctx context.Context, name string) (File, error)
- func (m *MountableFS) OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (m *MountableFS) ReadDir(ctx context.Context, name string) ([]stdfs.DirEntry, error)
- func (m *MountableFS) Readlink(ctx context.Context, name string) (string, error)
- func (m *MountableFS) Realpath(ctx context.Context, name string) (string, error)
- func (m *MountableFS) Remove(ctx context.Context, name string, recursive bool) error
- func (m *MountableFS) Rename(ctx context.Context, oldName, newName string) error
- func (m *MountableFS) Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (m *MountableFS) Symlink(ctx context.Context, target, linkName string) error
- func (m *MountableFS) Unmount(mountPoint string) error
- type MountableOptions
- type MountedFS
- type OverlayFS
- func (o *OverlayFS) Chdir(name string) error
- func (o *OverlayFS) Chmod(ctx context.Context, name string, mode stdfs.FileMode) error
- func (o *OverlayFS) Chown(ctx context.Context, name string, uid, gid uint32, follow bool) error
- func (o *OverlayFS) Chtimes(ctx context.Context, name string, atime, mtime time.Time) error
- func (o *OverlayFS) Getwd() string
- func (o *OverlayFS) Link(ctx context.Context, oldName, newName string) error
- func (o *OverlayFS) Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (o *OverlayFS) MkdirAll(ctx context.Context, name string, perm stdfs.FileMode) error
- func (o *OverlayFS) Mkfifo(ctx context.Context, name string, perm stdfs.FileMode) error
- func (o *OverlayFS) Open(ctx context.Context, name string) (File, error)
- func (o *OverlayFS) OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (o *OverlayFS) ReadDir(ctx context.Context, name string) ([]stdfs.DirEntry, error)
- func (o *OverlayFS) Readlink(ctx context.Context, name string) (string, error)
- func (o *OverlayFS) Realpath(ctx context.Context, name string) (string, error)
- func (o *OverlayFS) Remove(ctx context.Context, name string, recursive bool) error
- func (o *OverlayFS) Rename(ctx context.Context, oldName, newName string) error
- func (o *OverlayFS) Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (o *OverlayFS) Symlink(ctx context.Context, target, linkName string) error
- type ReadWriteFS
- func (h *ReadWriteFS) Chdir(name string) error
- func (h *ReadWriteFS) Chmod(_ context.Context, name string, mode stdfs.FileMode) error
- func (h *ReadWriteFS) Chown(_ context.Context, name string, uid, gid uint32, follow bool) error
- func (h *ReadWriteFS) Chtimes(_ context.Context, name string, atime, mtime time.Time) error
- func (h *ReadWriteFS) Getwd() string
- func (h *ReadWriteFS) Link(_ context.Context, oldName, newName string) error
- func (h *ReadWriteFS) Lstat(_ context.Context, name string) (stdfs.FileInfo, error)
- func (h *ReadWriteFS) MkdirAll(_ context.Context, name string, perm stdfs.FileMode) error
- func (h *ReadWriteFS) Mkfifo(_ context.Context, name string, perm stdfs.FileMode) error
- func (h *ReadWriteFS) Open(ctx context.Context, name string) (File, error)
- func (h *ReadWriteFS) OpenFile(_ context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (h *ReadWriteFS) ReadDir(_ context.Context, name string) ([]stdfs.DirEntry, error)
- func (h *ReadWriteFS) Readlink(_ context.Context, name string) (string, error)
- func (h *ReadWriteFS) Realpath(_ context.Context, name string) (string, error)
- func (h *ReadWriteFS) Remove(_ context.Context, name string, recursive bool) error
- func (h *ReadWriteFS) Rename(_ context.Context, oldName, newName string) error
- func (h *ReadWriteFS) Stat(_ context.Context, name string) (stdfs.FileInfo, error)
- func (h *ReadWriteFS) Symlink(_ context.Context, target, linkName string) error
- type ReadWriteOptions
- type SnapshotFS
- func (s *SnapshotFS) Chdir(name string) error
- func (s *SnapshotFS) Chmod(_ context.Context, name string, _ stdfs.FileMode) error
- func (s *SnapshotFS) Chown(_ context.Context, name string, _, _ uint32, _ bool) error
- func (s *SnapshotFS) Chtimes(_ context.Context, name string, _, _ time.Time) error
- func (s *SnapshotFS) Getwd() string
- func (s *SnapshotFS) Link(_ context.Context, oldName, _ string) error
- func (s *SnapshotFS) Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (s *SnapshotFS) MkdirAll(_ context.Context, name string, _ stdfs.FileMode) error
- func (s *SnapshotFS) Open(ctx context.Context, name string) (File, error)
- func (s *SnapshotFS) OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (s *SnapshotFS) ReadDir(ctx context.Context, name string) ([]stdfs.DirEntry, error)
- func (s *SnapshotFS) Readlink(ctx context.Context, name string) (string, error)
- func (s *SnapshotFS) Realpath(ctx context.Context, name string) (string, error)
- func (s *SnapshotFS) Remove(_ context.Context, name string, _ bool) error
- func (s *SnapshotFS) Rename(_ context.Context, oldName, _ string) error
- func (s *SnapshotFS) Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (s *SnapshotFS) Symlink(_ context.Context, _, linkName string) error
- type TrieFS
- func (f *TrieFS) Chdir(name string) error
- func (f *TrieFS) Chmod(_ context.Context, name string, mode stdfs.FileMode) error
- func (f *TrieFS) Chown(_ context.Context, name string, uid, gid uint32, follow bool) error
- func (f *TrieFS) Chtimes(_ context.Context, name string, atime, mtime time.Time) error
- func (f *TrieFS) Clone() *TrieFS
- func (f *TrieFS) Getwd() string
- func (f *TrieFS) Link(_ context.Context, oldName, newName string) error
- func (f *TrieFS) Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (f *TrieFS) MkdirAll(_ context.Context, name string, perm stdfs.FileMode) error
- func (f *TrieFS) Open(ctx context.Context, name string) (File, error)
- func (f *TrieFS) OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
- func (f *TrieFS) ReadDir(_ context.Context, name string) ([]stdfs.DirEntry, error)
- func (f *TrieFS) Readlink(_ context.Context, name string) (string, error)
- func (f *TrieFS) Realpath(_ context.Context, name string) (string, error)
- func (f *TrieFS) Remove(_ context.Context, name string, recursive bool) error
- func (f *TrieFS) Rename(_ context.Context, oldName, newName string) error
- func (f *TrieFS) Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
- func (f *TrieFS) Symlink(_ context.Context, target, linkName string) error
Constants ¶
const ( // DefaultHostVirtualRoot is the default virtual mount point for host-backed project trees. DefaultHostVirtualRoot = defaultHostVirtualRoot // DefaultHostMaxFileReadBytes is the default regular-file read cap for HostFS. DefaultHostMaxFileReadBytes = defaultHostMaxFileReadBytes )
const ( DefaultOwnerUID uint32 = 1000 DefaultOwnerGID uint32 = 1000 )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type FIFOFileSystem ¶ added in v0.0.23
type FIFOFileSystem interface {
Mkfifo(ctx context.Context, name string, perm stdfs.FileMode) error
}
FIFOFileSystem is an optional filesystem capability for creating named pipes.
type Factory ¶
type Factory interface {
New(ctx context.Context) (FileSystem, error)
}
Factory creates a fresh filesystem instance for a runtime session.
func Host ¶
func Host(opts HostOptions) Factory
Host returns a factory that mounts a read-only host directory into the sandbox.
func Memory ¶
func Memory() Factory
Memory returns a factory that creates a fresh in-memory filesystem per session.
func Mountable ¶
func Mountable(opts MountableOptions) Factory
Mountable returns a factory that provisions a multi-mount filesystem.
func ReadWrite ¶
func ReadWrite(opts ReadWriteOptions) Factory
ReadWrite returns a factory that mounts a real host directory as a mutable sandbox root.
func Reusable ¶
Reusable returns a factory that materializes source once and gives each caller a fresh writable overlay above that shared base.
func SeededMemory ¶
func SeededMemory(files InitialFiles) Factory
SeededMemory returns a factory that creates a fresh in-memory filesystem preloaded with the provided initial files.
func SeededTrie ¶ added in v0.0.17
func SeededTrie(files InitialFiles) Factory
SeededTrie returns a trie-backed filesystem factory preloaded with the provided files.
This is the usual entry point for read-mostly trie data. The recommended composition is `Reusable(SeededTrie(...))`, which shares one trie-backed lower tree and gives each caller a fresh writable overlay. That factory can then be passed through `gbash.CustomFileSystem(...)`, mounted with `gbash.MountableFileSystem(...)`.
Example single-root usage:
gb, err := gbash.New(
gbash.WithFileSystem(gbash.CustomFileSystem(
gbfs.Reusable(gbfs.SeededTrie(gbfs.InitialFiles{
"/data/catalog/manifest.txt": {Content: []byte("dataset\n")},
"/data/catalog/index.txt": {
Lazy: func(ctx context.Context) ([]byte, error) {
return fetchLargeFixture(ctx)
},
},
})),
"/data",
)),
)
Example mountable dataset plus scratch storage:
gb, err := gbash.New(
gbash.WithFileSystem(gbash.MountableFileSystem(gbash.MountableFileSystemOptions{
Base: gbfs.Memory(),
Mounts: []gbfs.MountConfig{
{
MountPoint: "/dataset",
Factory: gbfs.Reusable(gbfs.SeededTrie(gbfs.InitialFiles{
"/docs/guide.txt": {Content: []byte("guide\n")},
})),
},
{MountPoint: "/scratch", Factory: gbfs.Memory()},
},
WorkingDir: "/scratch",
})),
)
Experimental: This backend is intended for explicit opt-in use in read-mostly compositions.
func Snapshot ¶
func Snapshot(source FileSystem) Factory
Snapshot returns a factory that clones source into a read-only snapshot per session.
type FactoryFunc ¶
type FactoryFunc func(ctx context.Context) (FileSystem, error)
FactoryFunc adapts a function into a Factory.
func (FactoryFunc) New ¶
func (f FactoryFunc) New(ctx context.Context) (FileSystem, error)
type FileOwnership ¶
func DefaultOwnership ¶
func DefaultOwnership() FileOwnership
func OwnershipFromFileInfo ¶
func OwnershipFromFileInfo(info stdfs.FileInfo) (FileOwnership, bool)
func OwnershipFromSys ¶
func OwnershipFromSys(sys any) (FileOwnership, bool)
type FileSystem ¶
type FileSystem interface {
Open(ctx context.Context, name string) (File, error)
OpenFile(ctx context.Context, name string, flag int, perm stdfs.FileMode) (File, error)
Stat(ctx context.Context, name string) (stdfs.FileInfo, error)
Lstat(ctx context.Context, name string) (stdfs.FileInfo, error)
ReadDir(ctx context.Context, name string) ([]stdfs.DirEntry, error)
Readlink(ctx context.Context, name string) (string, error)
Realpath(ctx context.Context, name string) (string, error)
Symlink(ctx context.Context, target, linkName string) error
Link(ctx context.Context, oldName, newName string) error
Chown(ctx context.Context, name string, uid, gid uint32, follow bool) error
Chmod(ctx context.Context, name string, mode stdfs.FileMode) error
Chtimes(ctx context.Context, name string, atime, mtime time.Time) error
MkdirAll(ctx context.Context, name string, perm stdfs.FileMode) error
Remove(ctx context.Context, name string, recursive bool) error
Rename(ctx context.Context, oldName, newName string) error
Getwd() string
Chdir(name string) error
}
FileSystem is the project-owned filesystem contract used by the runtime.
type HostFS ¶
type HostFS struct {
// contains filtered or unexported fields
}
HostFS exposes a read-only host directory at a virtual sandbox path.
func NewHost ¶
func NewHost(opts HostOptions) (*HostFS, error)
NewHost creates a concrete host-backed filesystem instance.
type HostOptions ¶
HostOptions configures a read-only host directory mounted into the sandbox.
type InitialFile ¶
type InitialFile struct {
Content []byte
Lazy LazyFileProvider
Mode stdfs.FileMode
ModTime time.Time
}
InitialFile describes an eagerly or lazily seeded in-memory file.
When Lazy is nil, Content is used as the initial file contents. A nil Content value in that case represents an empty file.
type InitialFiles ¶
type InitialFiles map[string]InitialFile
InitialFiles maps sandbox paths to seeded file contents.
type LazyFileProvider ¶
LazyFileProvider returns file contents on first materialization.
type MemoryFS ¶
type MemoryFS struct {
// contains filtered or unexported fields
}
MemoryFS is the default mutable in-memory sandbox filesystem.
func NewMemory ¶
func NewMemory() *MemoryFS
NewMemory creates a fresh in-memory filesystem rooted at "/".
type MountConfig ¶
MountConfig describes a filesystem mounted at a sandbox path.
type MountableFS ¶
type MountableFS struct {
// contains filtered or unexported fields
}
MountableFS routes sandbox paths across a base filesystem and mounted child filesystems.
func NewMountable ¶
func NewMountable(base FileSystem) *MountableFS
NewMountable creates a mountable filesystem over base.
func (*MountableFS) Chdir ¶
func (m *MountableFS) Chdir(name string) error
func (*MountableFS) Getwd ¶
func (m *MountableFS) Getwd() string
func (*MountableFS) IsMountPoint ¶
func (m *MountableFS) IsMountPoint(pathValue string) bool
IsMountPoint reports whether path is an exact mount point.
func (*MountableFS) Link ¶
func (m *MountableFS) Link(ctx context.Context, oldName, newName string) error
func (*MountableFS) Mount ¶
func (m *MountableFS) Mount(mountPoint string, fsys FileSystem) error
Mount mounts fs at mountPoint.
func (*MountableFS) Mounts ¶
func (m *MountableFS) Mounts() []MountedFS
Mounts returns a stable snapshot of the current mount table.
func (*MountableFS) Rename ¶
func (m *MountableFS) Rename(ctx context.Context, oldName, newName string) error
func (*MountableFS) Symlink ¶
func (m *MountableFS) Symlink(ctx context.Context, target, linkName string) error
func (*MountableFS) Unmount ¶
func (m *MountableFS) Unmount(mountPoint string) error
Unmount removes the filesystem mounted at mountPoint.
type MountableOptions ¶
type MountableOptions struct {
Base Factory
Mounts []MountConfig
}
MountableOptions configures a multi-mount filesystem factory.
type MountedFS ¶
type MountedFS struct {
MountPoint string
FileSystem FileSystem
}
MountedFS is a snapshot of a live mount table entry.
type OverlayFS ¶
type OverlayFS struct {
// contains filtered or unexported fields
}
OverlayFS is a copy-on-write filesystem with a writable in-memory upper layer and a read-only lower layer.
func NewOverlay ¶
func NewOverlay(lower FileSystem) *OverlayFS
NewOverlay creates a concrete overlay filesystem over lower.
type ReadWriteFS ¶
type ReadWriteFS struct {
// contains filtered or unexported fields
}
ReadWriteFS exposes a mutable host directory as the sandbox root.
All sandbox paths are rooted at "/", but they map onto the configured host directory. Path resolution follows host symlinks only when the resolved path remains within the configured root.
func NewReadWrite ¶
func NewReadWrite(opts ReadWriteOptions) (*ReadWriteFS, error)
NewReadWrite creates a concrete read-write host-backed filesystem instance.
func (*ReadWriteFS) Chdir ¶
func (h *ReadWriteFS) Chdir(name string) error
func (*ReadWriteFS) Getwd ¶
func (h *ReadWriteFS) Getwd() string
func (*ReadWriteFS) Link ¶
func (h *ReadWriteFS) Link(_ context.Context, oldName, newName string) error
func (*ReadWriteFS) Rename ¶
func (h *ReadWriteFS) Rename(_ context.Context, oldName, newName string) error
type ReadWriteOptions ¶
ReadWriteOptions configures a read-write host directory mounted as the sandbox root.
type SnapshotFS ¶
type SnapshotFS struct {
// contains filtered or unexported fields
}
SnapshotFS is a read-only clone of another filesystem.
func NewSnapshot ¶
func NewSnapshot(ctx context.Context, source FileSystem) (*SnapshotFS, error)
NewSnapshot clones source into a read-only snapshot filesystem.
func (*SnapshotFS) Chdir ¶
func (s *SnapshotFS) Chdir(name string) error
func (*SnapshotFS) Getwd ¶
func (s *SnapshotFS) Getwd() string
type TrieFS ¶ added in v0.0.17
type TrieFS struct {
// contains filtered or unexported fields
}
TrieFS is an experimental in-memory filesystem optimized for read-heavy directory traversals and lookups.
This backend is intended for explicit opt-in use in static or read-mostly compositions. It is not the default runtime backend, and it is not the recommended path for live host-backed workspace helpers.
func NewTrie ¶ added in v0.0.17
func NewTrie() *TrieFS
NewTrie creates a fresh trie-backed filesystem rooted at "/".
Experimental: This backend is intended for explicit opt-in use in read-mostly compositions.
func (*TrieFS) Clone ¶ added in v0.0.17
Clone returns an isolated copy of the trie-backed filesystem while preserving hard-link sharing across cloned dentries.