filesystem

package
v0.41.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: AGPL-3.0 Imports: 18 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 Backup added in v0.36.0 

func Backup(source string, readWithMode func(string) ([]byte, fs.FileMode, error), publish func(string, []byte, fs.FileMode) error) (string, error)

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 CommittedPublication added in v0.41.0 

func CommittedPublication(err error) (destination, residue string, committed bool)

CommittedPublication reports the confined destination and cleanup residue carried by a committed exclusive-publication error.

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) Backup added in v0.36.0 

func (h *Handle) Backup(source string) (string, error)

Backup reads source once, preserving its permission mode, then exclusively publishes a complete sibling backup at source.awf-bak or its first available numbered suffix. The supplied confined callbacks keep source access and publication policy with the caller while this package owns the shared naming and collision protocol. Backup copies a source beneath this handle to its first free sibling backup.

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.

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) (returnErr error)

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

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) (returnErr error)

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

func (*Handle) RetireExpected added in v0.41.0 

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

RetireExpected atomically detaches the expected directory before deleting its contents. A same-name successor installed after the exchange is never traversed or removed.

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 transaction 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 transaction identity for an operation that changes both checkout-local and primary-resident state. acquire canonicalizes and orders both identities before taking either lock.

func AcquireResidentLease added in v0.41.0 

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

AcquireResidentLease obtains the primary-resident transaction capability. Resident-only operations use it so independent selected checkouts contend on their shared lifecycle state without unnecessarily serializing tracked work.

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.