file

package
v0.1.0-dev.20260303180853 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 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 string
}

Provider provides file system actions.

Compensable forward methods return (string, map[string]any, error): the resource path, the compensation receipt, and an error. The map is opaque to the executor, meaningful only to the corresponding "Compensate*" backward method.

+devlore:access=both +devlore:bind Root=WorkDir

func (*Provider) Backup 

func (p *Provider) Backup(path, backupSuffix string) (result string, undo map[string]any, 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:

  • The backup path and compensation state.

func (*Provider) CompensateBackup 

func (p *Provider) CompensateBackup(undo map[string]any) error

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

If a written_checksum is present, the backup file is verified before restoring; a mismatch indicates external modification and the compensation is skipped.

func (*Provider) CompensateCopy 

func (p *Provider) CompensateCopy(undo map[string]any) error

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

Parameters:

  • undo: The state map returned by Copy

Returns:

  • err: any error that occurred during the compensation
func (p *Provider) CompensateLink(undo map[string]any) error

CompensateLink undoes a Link action using the captured state.

If the symlink existed before, it is removed. Otherwise, it is recreated.

Parameters:

  • state: The state map returned by Link

Returns:

  • err: any error that occurred during the compensation

func (*Provider) CompensateMove 

func (p *Provider) CompensateMove(undo map[string]any) error

CompensateMove undoes a Move by moving the file back from path to source.

If a written_checksum is present, the destination file is verified before restoring; a mismatch indicates external modification and the compensation is skipped.

Parameters:

  • undo: The state map returned by Move

Returns:

  • err: any error that occurred during the compensation

func (*Provider) CompensateRemove 

func (p *Provider) CompensateRemove(undo map[string]any) error

CompensateRemove undoes a Remove by re-creating the file with saved content and mode.

If content is not available, the file is recreated with default permissions.

Parameters:

  • undo: The state map returned by Remove

Returns:

  • err: any error that occurred during the compensation

func (*Provider) CompensateRemoveAll 

func (p *Provider) CompensateRemoveAll(undo map[string]any) error

CompensateRemoveAll is the compensating action for RemoveAll.

It moves the files from the recovery site back to the original location.

Parameters:

  • undo: The state map returned by RemoveAll

Returns:

  • err: any error that occurred during the compensation
func (p *Provider) CompensateUnlink(undo map[string]any) error

CompensateUnlink undoes an Unlink by re-creating the symlink.

Parameters:

  • state: The state map returned by Unlink

Returns:

  • err: any error that occurred during the compensation

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 map[string]any) error

CompensateWriteBytes restores the previous state of written bytes using the provided undo map data.

It delegates to the internal [compensateWrite] method to perform the actual compensation operation.

Parameters:

  • undo: The state map returned by [WriteBytes]

Returns:

  • err: any error that occurred during the compensation

func (*Provider) CompensateWriteText 

func (p *Provider) CompensateWriteText(undo map[string]any) error

CompensateWriteText undoes a WriteText action using the captured state.

It delegates to the internal [compensateWrite] method to perform the actual compensation operation.

Parameters:

  • undo: The state map returned by [WriteText]

Returns:

  • err: any error that occurred during the compensation

func (*Provider) Copy 

func (p *Provider) Copy(sourceFile Resource, destinationFilename string, destinationFileMode os.FileMode) (result Resource, undo map[string]any, err error)

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

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

Parameters:

  • destination: Absolute path to the file to write
  • source: The content to copy (a Resource wrapping a file path)
  • mode: The file mode to use (default: 0644)

Returns:

  • result: the path to the written file
  • undo: a state map containing the tombstone for recovery
  • err: any error that occurred during the copy

func (*Provider) Exists 

func (p *Provider) Exists(fileResource Resource) bool

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

Parameters:

  • path: Absolute path to check

Returns:

  • bool: true if the file at "path" exists, false otherwise

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(path string) bool

IsDir returns true if the file at "path" exists and is a directory.

Parameters:

  • path: Absolute path to check

Returns:

  • bool: true if the file at "path "is a directory, false otherwise

func (*Provider) IsFile 

func (p *Provider) IsFile(path string) bool

IsFile returns true if the file at "path" exists and is a regular file.

Parameters:

  • path: Absolute path to check

Returns:

  • bool: true if the file at "path" is a regular file, false otherwise

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 string) (result string, undo map[string]any, 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.

Parameters:

  • source: Absolute path to the symlink target
  • path: Absolute path where the symlink will be created

Returns:

  • result: the path to the symlink
  • undo: a state map with the following keys: > path: the path to the symlink > existed_before: true if the symlink already existed before > previous_target: the target of the symlink before it was created if it existed

func (*Provider) Mkdir 

func (p *Provider) Mkdir(path string, mode os.FileMode) (string, 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 string) (result string, undo map[string]any, err error)

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

Parameters:

  • source: Absolute path to the source file
  • destination: Absolute path to the destination file

Returns:

  • result: the path to the moved file
  • undo: a state map with the following keys: > source: the source path of the move > path: the destination path of the move > written_checksum: the checksum of the moved file (if available)

func (*Provider) Name 

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

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 string) (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 string, prune bool, pruneBoundary string) (result Tombstone, undo map[string]any, 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: Absolute path to 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: the path to the deleted file
  • compState: a state map with the following keys: > path: the path to the deleted file > content: the content of the deleted file (if available) > mode: the file mode of the deleted file (if available)

func (*Provider) RemoveAll 

func (p *Provider) RemoveAll(path string, prune bool, pruneBoundary string) (result Tombstone, undo map[string]any, err error)

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

Parameters:

  • path: Absolute path to 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: the path to the deleted file or directory
  • undo: a state map with the following keys: > path: the path to the deleted file or directory > files_moved: the number of files moved to the recovery directory > recovery_dir: the path to the recovery directory
  • err: any error that occurred during the removal
func (p *Provider) Unlink(path string, prune bool, pruneBoundary string) (result Tombstone, undo map[string]any, 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: Absolute path to 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: the path to the deleted symlink
  • compState: a state map with the following keys: > path: the path to the deleted symlink > target: the target of the deleted symlink

func (*Provider) WalkTree 

func (p *Provider) WalkTree(root string, 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, content string, mode os.FileMode) (result Resource, undo map[string]any, err error)

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

Parameters:

  • content: String content to write to the file
  • path: Absolute path where the file will be written
  • mode: File permission bits (e.g., 0o644)

Returns:

  • result: the path to the written file
  • undo: a state map with the following keys: > tombstone: a Tombstone
  • err: any error that occurred while writing

func (*Provider) WriteText 

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

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

Parameters:

  • content: String content to write to the file
  • path: Absolute path where the file will be written
  • mode: File permission bits (e.g., 0o644)

Returns:

  • result: the path to the written file
  • undo: a state map with the following keys: > tombstone: a Tombstone
  • err: any error that occurred while writing

type Reducer 

type Reducer func(initial any, path string, dirEntry os.DirEntry, 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(path string, dirEntry os.DirEntry) 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.Resource
	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, error)

NewResource initializes a new Resource by checking the existence and size of the file at the provided sourcePath.

Parameters:

  • sourcePath: path to the file to read

Returns: an error if the path does not exist or is a directory

func (*Resource) Exists 

func (r *Resource) Exists() bool

Exists returns true if the Resource references a file that existed when the Resource was created.

This method checks if the ModTime is non-zero, indicating that the file existed at the time of Resource creation.

Parameters:

  • none

Returns:

  • bool: true if the file exists, false otherwise

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) RefreshMetadata 

func (r *Resource) RefreshMetadata() error

RefreshMetadata updates the Resource's metadata by performing a fresh os.Stat and re-calculating the checksum.

This should be called after any successful physical mutation.

Parameters:

  • none

Returns:

  • error: any error that occurred during refreshing

func (*Resource) RefreshMetadataWith 

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

RefreshMetadataWith updates the resource metadata after a write operation.

It takes the known size and checksum to avoid redundant I/O but performs an os.Stat to capture Kernel-assigned identity (Device and Inode)

Parameters:

  • checksum: the checksum of the blob after the write operation
  • size: the size of the blob after the write operation

Returns:

  • error: any error that occurred during finalization

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 {
	RecoveryPath string // Where it is now
	OriginalPath string // Where it used to be
}

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.