file

package
v0.1.0-dev.20260307215707 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package file provides filesystem actions for the operation graph.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// SkipDir indicates that the current directory should be skipped.
	SkipDir = fs.SkipDir

	// SkipAll signals the walker to terminate immediately (success).
	SkipAll = fs.SkipAll
)

Functions

This section is empty.

Types

type Provider 

type Provider struct {
	op.ProviderBase
	Root Resource
}

Provider provides file system actions.

Compensable forward methods return (T, Tombstone, error): the result, the compensation tombstone, and an error. The tombstone is opaque to the executor, meaningful only to the corresponding "Compensate*" backward method.

+devlore:access=both

func (*Provider) Backup 

func (p *Provider) Backup(path Resource, backupSuffix string) (result Resource, undo Tombstone, err error)

Backup moves the file at "path" to a timestamped backup location.

Parameters:

  • path: Absolute path to the file to back up
  • backupSuffix: Suffix appended before the timestamp (default: .devlore-backup)

Returns:

  • result: Resource at the backup location
  • undo: Tombstone for restoring the original
  • err: any error

func (*Provider) CompensateBackup 

func (p *Provider) CompensateBackup(undo Tombstone) error

CompensateBackup undoes a Backup by moving the backup back to the original path.

The resource's checksum is verified before restoring; a mismatch indicates external modification.

func (*Provider) CompensateCopy 

func (p *Provider) CompensateCopy(undo Tombstone) error

CompensateCopy undoes a Copy by restoring the original file from recovery. 

func (p *Provider) CompensateLink(undo Tombstone) error

CompensateLink undoes a Link by removing the symlink and restoring whatever was there before.

func (*Provider) CompensateMove 

func (p *Provider) CompensateMove(undo Tombstone) error

CompensateMove undoes a Move by moving the file back to its original location.

The resource's checksum is verified before restoring; a mismatch indicates external modification.

func (*Provider) CompensateRemove 

func (p *Provider) CompensateRemove(undo Tombstone) error

CompensateRemove undoes a Remove by restoring the file from recovery.

func (*Provider) CompensateRemoveAll 

func (p *Provider) CompensateRemoveAll(undo Tombstone) error

CompensateRemoveAll undoes a RemoveAll by restoring from recovery. 

func (p *Provider) CompensateUnlink(undo Tombstone) error

CompensateUnlink undoes an Unlink by restoring the symlink from recovery.

func (*Provider) CompensateWalkTree 

func (p *Provider) CompensateWalkTree(stack *op.RecoveryStack) error

CompensateWalkTree unwinds the RecoveryStack returned by WalkTree in LIFO order.

Best-effort: all entries are attempted, errors are joined.

Parameters:

  • stack: The stack returned by WalkTree

Returns:

  • err: The first error encountered during compensation, if any

func (*Provider) CompensateWriteBytes 

func (p *Provider) CompensateWriteBytes(undo Tombstone) error

CompensateWriteBytes undoes a WriteBytes by restoring the original file.

func (*Provider) CompensateWriteText 

func (p *Provider) CompensateWriteText(undo Tombstone) error

CompensateWriteText undoes a WriteText by restoring the original file.

func (*Provider) Copy 

func (p *Provider) Copy(sourceFile Resource, destinationFilename Resource, destinationFileMode os.FileMode) (result Resource, undo Tombstone, err error)

Copy copies a blob to the file at "destination" with the given mode.

If the destination already exists, it is moved to a recovery site before writing.

Parameters:

  • sourceFile: Resource wrapping the source file path
  • destinationFilename: Resource for the destination path
  • destinationFileMode: The file mode to use (default: 0644)

Returns:

  • result: Resource for the written file
  • undo: Tombstone for restoring the original state
  • err: any error that occurred during the copy

func (*Provider) Exists 

func (p *Provider) Exists(resource Resource) (bool, error)

Exists returns true if the file at "path" exists.

Parameters:

  • resource: Resource to check

Returns:

  • bool: true if the resource exists, false otherwise
  • error: permission or other I/O errors (not-exist is not an error)

func (*Provider) Glob 

func (p *Provider) Glob(pattern string, honorGitignore bool) ([]string, error)

Glob returns file paths matching a pattern relative to Root.

Parameters:

  • pattern: Glob pattern (e.g., "*.go", "**/*.yaml")
  • honorGitignore: If true, filter results using gitignore rules

Returns:

  • []string: List of matching file paths

func (*Provider) IsDir 

func (p *Provider) IsDir(resource Resource) (bool, error)

IsDir returns true if the resource exists and is a directory.

Parameters:

  • resource: Resource to check

Returns:

  • bool: true if the resource is a directory, false otherwise
  • error: permission or other I/O errors (not-exist is not an error)

func (*Provider) IsFile 

func (p *Provider) IsFile(resource Resource) (bool, error)

IsFile returns true if the resource exists and is a regular file.

Parameters:

  • resource: Resource to check

Returns:

  • bool: true if the resource is a regular file, false otherwise
  • error: permission or other I/O errors (not-exist is not an error)

func (*Provider) Join 

func (p *Provider) Join(parts ...string) string

Join joins path components using the OS path separator.

Parameters:

  • parts: Path components to join

Returns:

  • string: The joined path or an empty string, if no parts are provided or all parts are empty
func (p *Provider) Link(source, path Resource) (result Resource, undo Tombstone, err error)

Link creates a symlink at a path pointing to a source file.

Idempotent: if the symlink already points correctly, it's a no-op.

If something exists at the path, it is moved to recovery before creating the symlink.

Parameters:

  • source: Resource for the symlink target
  • path: Resource for the symlink location

Returns:

  • result: Resource for the created symlink
  • undo: Tombstone for restoring the previous state
  • err: any error

func (*Provider) Mkdir 

func (p *Provider) Mkdir(resource Resource, mode os.FileMode) (Resource, error)

Mkdir creates a directory (and parents) with the given mode.

Parameters:

  • path: Absolute path of the directory to create
  • mode: Directory permission bits (e.g., 0o755)

Returns:

  • string: The absolute path of the created directory

func (*Provider) Move 

func (p *Provider) Move(source, destination Resource) (result Resource, undo Tombstone, err error)

Move moves a file from source to destination using "os.Rename".

Parameters:

  • source: Resource at the source location
  • destination: Resource for the destination location

Returns:

  • result: Resource at the destination
  • undo: Tombstone for moving the file back
  • err: any error

func (*Provider) Name 

func (p *Provider) Name(path string) string

Name returns the last element of "path" (a file or directory name).

Parameters:

  • path: Path to extract the name from

Returns:

  • string: The name of the file or directory

func (*Provider) Parent 

func (p *Provider) Parent(path string) string

Parent returns the directory containing the file at "path".

Parameters:

  • path: Path to a file

Returns:

  • string: The parent directory of the file

func (*Provider) Read 

func (p *Provider) Read(path Resource) (result Resource, err error)

Read creates a Resource from the file at "path" for reading the contents of the file at "path".

Parameters:

  • path: Absolute path to the file to read

Returns:

  • result: the contents of the file

func (*Provider) Remove 

func (p *Provider) Remove(path Resource, prune bool, pruneBoundary Resource) (result Tombstone, undo Tombstone, err error)

Remove deletes the file at "path".

If prune is true and pruneBoundary is set, empty parent directories are removed up to the boundary.

Parameters:

  • path: Resource for the file to delete
  • prune: If true, remove empty parent directories after deletion
  • pruneBoundary: Stop pruning at this directory (prevents removing too much)

Returns:

  • result: Tombstone for restoring the deleted file
  • err: any error

func (*Provider) RemoveAll 

func (p *Provider) RemoveAll(path Resource, prune bool, pruneBoundary Resource) (result Tombstone, undo Tombstone, err error)

RemoveAll removes the file at "path" and any children it contains.

Parameters:

  • path: Resource for the file or directory to remove
  • prune: If true, remove empty parent directories after deletion
  • pruneBoundary: Stop pruning at this directory (prevents removing too much)

Returns:

  • result: Tombstone for restoring the deleted tree
  • err: any error
func (p *Provider) Unlink(path Resource, prune bool, pruneBoundary Resource) (result Tombstone, undo Tombstone, err error)

Unlink removes the symlink at "path".

If prune is true and pruneBoundary is set, empty parent directories are removed up to the boundary.

Parameters:

  • path: Resource for the symlink to remove
  • prune: If true, remove empty parent directories after unlinking
  • pruneBoundary: Stop pruning at this directory (prevents removing too much)

Returns:

  • result: Tombstone for restoring the deleted symlink
  • err: any error

func (*Provider) WalkTree 

func (p *Provider) WalkTree(root Resource, fn Reducer, honorGitignore bool) (result any, stack *op.RecoveryStack, err error)

WalkTree performs a depth-first traversal with an accumulator and a RecoveryStack for compensable operations.

The visitor can push compensable operations onto the stack during traversal. On error mid-walk, the stack is unwound automatically and errors are joined. On success, the accumulated result and the stack are returned--the stack serves as the undo receipt.

+devlore:defaults root="",honorGitignore=true

Parameters:

  • root: Root directory to start traversal from
  • fn: Reducer function to call for each file or directory
  • gitignore: If true, filter results using gitignore rules

Returns:

  • result: The accumulated result from the visitor function
  • stack: The compensable operations stack
  • err: The first error encountered during traversal, if any

func (*Provider) WriteBytes 

func (p *Provider) WriteBytes(destination Resource, content string, mode os.FileMode) (result Resource, undo Tombstone, err error)

WriteBytes writes inline content to the file at "path" with the given mode.

Parameters:

  • destination: Resource for the file to write
  • content: String content to write to the file
  • mode: File permission bits (e.g., 0o644)

Returns:

  • result: Resource for the written file
  • undo: Tombstone for restoring the previous state
  • err: any error that occurred while writing

func (*Provider) WriteText 

func (p *Provider) WriteText(destination Resource, content string, mode os.FileMode) (result Resource, undo Tombstone, err error)

WriteText writes inline content to the file at "path" with the given mode.

Parameters:

  • destination: Resource for the file to write
  • content: String content to write to the file
  • mode: File permission bits (e.g., 0o644)

Returns:

  • result: Resource for the written file
  • undo: Tombstone for restoring the previous state
  • err: any error that occurred while writing

type Reducer 

type Reducer func(initial any, resource Resource, relativePath string, stack *op.RecoveryStack) (result any, err error)

Reducer is a function called for each file or directory in a WalkTree operation. +devlore:callable swallow=stack

func Actor 

func Actor(fn func(resource Resource, relativePath string) error) Reducer

Actor returns a Reducer that calls the given function for each file or directory in a WalkTree operation.

This is a convenience function for creating Reducers from simple functions that don't accumulate results or need to access the recovery stack.

type Resource 

type Resource struct {
	op.ResourceBase
	SourcePath string
	Inode      uint64
	Device     uint64
	Size       int64
	Mode       os.FileMode
	ModTime    time.Time
	Checksum   string
}

Resource represents a handle to data that can be streamed.

func NewResource 

func NewResource(path string) Resource

NewResource creates a Resource with the given source path. The constructor is pure computation — no I/O, no error. Metadata (size, mode, checksum) is populated later by Resource.Resolve.

func (*Resource) Exists 

func (r *Resource) Exists() bool

Exists returns true if the resource has been resolved and the file existed at resolve time. An unresolved resource always reports Exists() == false.

func (*Resource) Reader 

func (r *Resource) Reader() (io.ReadCloser, error)

Reader returns an io.ReadCloser for reading the file resource's data from its source path.

The caller is responsible for closing the returned reader.

Parameters:

  • none

Returns:

  • io.ReadCloser: an io.ReadCloser for reading the file resource's data
  • error: any error that occurred during opening

func (*Resource) Refresh 

func (r *Resource) Refresh() error

Refresh re-populates the resource's metadata by performing a fresh os.Stat and re-calculating the checksum. Call after any successful physical mutation.

func (*Resource) RefreshWith 

func (r *Resource) RefreshWith(checksum string, size int64) error

RefreshWith updates metadata after a write operation using a known checksum and size. An os.Stat is still performed to capture kernel-assigned identity (Inode, Device).

func (*Resource) Resolve 

func (r *Resource) Resolve() error

Resolve populates the resource's metadata by canonicalizing the path and performing an os.Stat. If the file does not exist, Resolve returns nil and metadata remains empty (Resource.Exists returns false). Other stat errors are returned.

func (Resource) String 

func (r Resource) String() string

String returns a compact JSON representation of the resource.

func (*Resource) WriteTo 

func (r *Resource) WriteTo(writer io.Writer) (int64, error)

WriteTo allows the Resource to be streamed directly to any io.Writer.

For efficiency, it uses io.Copy which automatically attempts a zero-copy syscall before falling back to a 32KB buffer.

Parameters:

  • writer: io.Writer to write to

Returns:

  • int64: number of bytes written
  • error: any error that occurred during writing

type Tombstone 

type Tombstone struct {
	op.TombstoneBase
	OriginalPath string
}

Tombstone holds file-specific compensation state.

The embedded op.TombstoneBase carries the affected Resource whose SourcePath reflects where the data physically IS after the operation (e.g., the recovery path after moveToRecovery). OriginalPath records where the data WAS before the operation — the restoration target.

Source Files

View all Source files

Directories

Path Synopsis
Package gitignore provides gitignore-aware file filtering using go-git's gitignore package.
 Package gitignore provides gitignore-aware file filtering using go-git's gitignore package.

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.