filesystem

package
v0.50.0 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package filesystem owns root-confined production filesystem access.

Index

Constants

This section is empty.

Variables

View Source 
var ErrDirectoryNotEmpty = errors.New("filesystem: directory not empty")

ErrDirectoryNotEmpty reports that expected removal safely preserved a directory containing another entry.

View Source 
var ErrIdentityChanged = errors.New("filesystem: observed identity changed")

ErrIdentityChanged reports that a path no longer names the entry observed by the caller. It is stable under wrapping.

Functions

func CanonicalRoot added in v0.41.0 

func CanonicalRoot(root string) (string, error)

CanonicalRoot returns the symlink-resolved absolute identity used to serialize one existing physical root.

func NormalizePlatformPath added in v0.45.0 

func NormalizePlatformPath(value string) string

NormalizePlatformPath returns the stable spelling for trusted operating-system path aliases without resolving caller-controlled symbolic links.

func SupportedTreeEntry added in v0.41.0 

func SupportedTreeEntry(entry fs.DirEntry) (bool, error)

SupportedTreeEntry reports whether entry is a directory or regular file. A zero type is ambiguous, so it resolves the complete mode before admitting the entry to a readable project-tree inventory.

Types

type ExpectedIdentity added in v0.41.0 

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

ExpectedIdentity is an opaque, releasable identity capability for one observed directory entry. It is acquired only for an expected mutation. On platforms that need it to resist inode reuse it retains a native handle.

func (*ExpectedIdentity) IsDir added in v0.41.0 

func (e *ExpectedIdentity) IsDir() bool

func (*ExpectedIdentity) ModTime added in v0.41.0 

func (e *ExpectedIdentity) ModTime() time.Time

func (*ExpectedIdentity) Mode added in v0.41.0 

func (e *ExpectedIdentity) Mode() fs.FileMode

func (*ExpectedIdentity) Name added in v0.41.0 

func (e *ExpectedIdentity) Name() string

func (*ExpectedIdentity) Release added in v0.41.0 

func (e *ExpectedIdentity) Release() error

Release releases resources retained by this identity. It is idempotent.

func (*ExpectedIdentity) SameFile added in v0.41.0 

func (e *ExpectedIdentity) SameFile(info fs.FileInfo) bool

SameFile reports whether info names the entry retained by this identity.

func (*ExpectedIdentity) Size added in v0.41.0 

func (e *ExpectedIdentity) Size() int64

func (*ExpectedIdentity) Sys added in v0.41.0 

func (e *ExpectedIdentity) Sys() any

type Handle 

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

Handle provides root-confined filesystem operations.

func Open 

func Open(root string) (*Handle, error)

Open opens root as a root-confined filesystem handle.

func (*Handle) Chmod added in v0.35.1 

func (h *Handle) Chmod(path string, mode fs.FileMode) error

Chmod changes path's permission mode beneath the selected root.

func (*Handle) Close 

func (h *Handle) Close() error

Close closes the root-confined filesystem handle.

func (*Handle) CreateDirectory added in v0.41.0 

func (h *Handle) CreateDirectory(destination string, mode fs.FileMode) (created *ExpectedIdentity, returnErr error)

CreateDirectory atomically publishes one new directory and returns the identity of the directory it created. It refuses an existing destination.

func (*Handle) ExpectedIdentity added in v0.41.0 

func (h *Handle) ExpectedIdentity(name string) (*ExpectedIdentity, error)

ExpectedIdentity pins one leaf for an expected mutation. The caller must Release an identity it abandons; expected-mutation methods consume it.

func (*Handle) Info 

func (h *Handle) Info(path string) (fs.FileInfo, error)

Info returns metadata for path, following a final symbolic link.

func (*Handle) LinkInfo 

func (h *Handle) LinkInfo(path string) (fs.FileInfo, error)

LinkInfo returns metadata for path without following a final symbolic link.

func (*Handle) MkdirAll added in v0.34.0 

func (h *Handle) MkdirAll(path string, mode fs.FileMode) error

MkdirAll creates path and missing parents beneath the selected root.

func (*Handle) Publish added in v0.34.0 

func (h *Handle) Publish(path string, contents []byte, mode fs.FileMode) error

Publish atomically publishes one complete file without replacement beneath the selected root.

func (*Handle) Read 

func (h *Handle) Read(path string) ([]byte, error)

Read reads path beneath the selected root.

func (*Handle) ReadDir added in v0.41.0 

func (h *Handle) ReadDir(path string) ([]fs.DirEntry, error)

ReadDir lists direct children beneath the selected root without following a replacement final entry.

func (*Handle) ReadDirExpected added in v0.49.0 

func (h *Handle) ReadDirExpected(path string, expected *ExpectedIdentity) ([]fs.DirEntry, error)

ReadDirExpected lists children only while path retains expected's directory identity. A nonblocking no-follow open prevents a replacement special file from hanging recovery before identity validation.

func (*Handle) ReadExpected added in v0.44.0 

func (h *Handle) ReadExpected(path string, expected *ExpectedIdentity) ([]byte, fs.FileMode, error)

ReadExpected reads the exact regular-file entry retained by expected. It refuses if the selected path changed between identity observation and open.

func (*Handle) ReadWithMode added in v0.35.1 

func (h *Handle) ReadWithMode(path string) ([]byte, fs.FileMode, error)

ReadWithMode reads path and returns its permission mode from one confined open.

func (*Handle) Remove added in v0.34.0 

func (h *Handle) Remove(path string) error

Remove removes path beneath the selected root.

func (*Handle) RemoveAll added in v0.40.0 

func (h *Handle) RemoveAll(path string) error

RemoveAll removes path and its descendants beneath the selected root.

func (*Handle) RemoveExpected added in v0.41.0 

func (h *Handle) RemoveExpected(destination string, expected *ExpectedIdentity) error

RemoveExpected removes path only while it still has expected's identity.

func (*Handle) RemoveExpectedRegularFile added in v0.49.0 

func (h *Handle) RemoveExpectedRegularFile(destination string, expected *ExpectedIdentity, expectedContents []byte, expectedMode fs.FileMode) error

RemoveExpectedRegularFile removes path only if the displaced entry retains both expected's identity and the exact regular-file bytes and permission mode.

func (*Handle) Rename added in v0.40.0 

func (h *Handle) Rename(oldPath, newPath string) error

Rename moves oldPath to newPath beneath the selected root.

func (*Handle) Replace added in v0.34.0 

func (h *Handle) Replace(destination string, contents []byte, mode fs.FileMode) error

Replace atomically replaces path with one complete file beneath the selected root, preserving the requested final mode. Callers that previously observed the destination should use ReplaceExpected.

func (*Handle) ReplaceExpected added in v0.41.0 

func (h *Handle) ReplaceExpected(destination string, expected *ExpectedIdentity, contents []byte, mode fs.FileMode) error

ReplaceExpected publishes only while destination still has expected's entry identity. A nil expected identity creates exclusively rather than clobbering.

func (*Handle) ReplaceExpectedRegularFile added in v0.49.0 

func (h *Handle) ReplaceExpectedRegularFile(destination string, expected *ExpectedIdentity, expectedContents []byte, expectedMode fs.FileMode, contents []byte, mode fs.FileMode) error

ReplaceExpectedRegularFile publishes only if the displaced entry retains both expected's identity and the exact regular-file bytes and permission mode.

func (*Handle) RootMatches added in v0.41.0 

func (h *Handle) RootMatches(root string) (bool, error)

RootMatches reports whether this handle remains anchored at root's current directory identity. It lets operation owners reject a handle supplied for a different selected checkout before it can observe or publish anything.

func (*Handle) Walk 

func (h *Handle) Walk(subtree string, visit func(path string, info fs.FileInfo) (bool, error)) error

Walk visits subtree entries with metadata describing each entry itself.

type Lease added in v0.41.0 

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

Lease is an acquired, ordered set of advisory identities. Keeping this value explicit lets an operation prove that authority loading and publication share the same writer exclusion without making the mechanism own operation policy.

func AcquireProjectLease added in v0.41.0 

func AcquireProjectLease(ctx context.Context, tracked, resident string) (*Lease, error)

AcquireProjectLease returns the writer identity for an operation that changes both checkout-local and primary-resident state. acquire canonicalizes and orders both identities before taking either lock.

func AcquireTrackedLease added in v0.41.0 

func AcquireTrackedLease(ctx context.Context, root string) (*Lease, error)

AcquireTrackedLease obtains the checkout-local mutation lease. Operations that do not reach primary-resident state must use this instead of a combined project lease so independent linked worktrees can proceed concurrently.

func (*Lease) CoversProject added in v0.41.0 

func (l *Lease) CoversProject(tracked, resident string) bool

CoversProject reports whether this live lease contains the complete tracked and resident identity set for roots.

func (*Lease) CoversTracked added in v0.41.0 

func (l *Lease) CoversTracked(root string) bool

CoversTracked reports whether this live lease contains the selected checkout's tracked-tree identity.

func (*Lease) Release added in v0.41.0 

func (l *Lease) Release() error

Release relinquishes every identity in reverse acquisition order.

type LeaseError added in v0.41.0 

type LeaseError struct {
	Kind  LeaseErrorKind
	Cause error
}

LeaseError preserves the failed lease stage and underlying error identity.

func (*LeaseError) Error added in v0.41.0 

func (e *LeaseError) Error() string

func (*LeaseError) Unwrap added in v0.41.0 

func (e *LeaseError) Unwrap() error

type LeaseErrorKind added in v0.41.0 

type LeaseErrorKind string

LeaseErrorKind identifies the lease stage that failed so focused callers can preserve their own diagnostics without branching on filesystem error text. 

const (
	LeaseCanonicalRoot LeaseErrorKind = "canonical-root"
	LeaseCacheLocation LeaseErrorKind = "cache-location"
	LeaseCacheCreation LeaseErrorKind = "cache-creation"
	LeaseCacheMode     LeaseErrorKind = "cache-mode"
	LeaseAcquisition   LeaseErrorKind = "acquisition"
	LeaseFileMode      LeaseErrorKind = "file-mode"
)

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.