Documentation
¶
Index ¶
- Variables
- type Provider
- func (p *Provider) Backup(path Resource, backupSuffix string) (result Resource, undo Tombstone, err error)
- func (p *Provider) CompensateBackup(undo Tombstone) error
- func (p *Provider) CompensateCopy(undo Tombstone) error
- func (p *Provider) CompensateLink(undo Tombstone) error
- func (p *Provider) CompensateMove(undo Tombstone) error
- func (p *Provider) CompensateRemove(undo Tombstone) error
- func (p *Provider) CompensateRemoveAll(undo Tombstone) error
- func (p *Provider) CompensateUnlink(undo Tombstone) error
- func (p *Provider) CompensateWalkTree(stack *op.RecoveryStack) error
- func (p *Provider) CompensateWriteBytes(undo Tombstone) error
- func (p *Provider) CompensateWriteText(undo Tombstone) error
- func (p *Provider) Copy(sourceFile Resource, destinationFilename Resource, ...) (result Resource, undo Tombstone, err error)
- func (p *Provider) Exists(resource Resource) (bool, error)
- func (p *Provider) Glob(pattern string, honorGitignore bool) ([]string, error)
- func (p *Provider) IsDir(resource Resource) (bool, error)
- func (p *Provider) IsFile(resource Resource) (bool, error)
- func (p *Provider) Join(parts ...string) string
- func (p *Provider) Link(source, path Resource) (result Resource, undo Tombstone, err error)
- func (p *Provider) Mkdir(resource Resource, mode os.FileMode) (Resource, error)
- func (p *Provider) Move(source, destination Resource) (result Resource, undo Tombstone, err error)
- func (p *Provider) Name(path string) string
- func (p *Provider) Parent(path string) string
- func (p *Provider) Read(path Resource) (result Resource, err error)
- func (p *Provider) Remove(path Resource, prune bool, boundary Resource) (result Tombstone, undo Tombstone, err error)
- func (p *Provider) RemoveAll(path Resource, prune bool, boundary Resource) (result Tombstone, undo Tombstone, err error)
- func (p *Provider) Root() string
- func (p *Provider) Unlink(path Resource, prune bool, boundary Resource) (result Tombstone, undo Tombstone, err error)
- func (p *Provider) WalkTree(root Resource, fn Reducer, honorGitignore bool) (result any, stack *op.RecoveryStack, err error)
- func (p *Provider) WriteBytes(destination Resource, content string, mode os.FileMode) (result Resource, undo Tombstone, err error)
- func (p *Provider) WriteText(destination Resource, content string, mode os.FileMode) (result Resource, undo Tombstone, err error)
- type Reducer
- type Resource
- func (r *Resource) Exists() bool
- func (r *Resource) Refresh(root op.Root) error
- func (r *Resource) RefreshWith(root op.Root, checksum string, size int64) error
- func (r *Resource) Resolve(root op.Root) error
- func (r *Resource) String() string
- func (r *Resource) WriteTo(root op.Root, writer io.Writer) (int64, error)
- type Tombstone
Constants ¶
This section is empty.
Variables ¶
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
}
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=planned
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 ¶
CompensateBackup undoes a Backup by moving the backup back to the original path.
Backup uses a plain rename (not RecoverySite), so compensation renames back directly. The resource's checksum is verified before restoring; a mismatch indicates external modification.
func (*Provider) CompensateCopy ¶
CompensateCopy undoes a Copy by restoring the original file from recovery.
func (*Provider) CompensateLink ¶
CompensateLink undoes a Link by removing the symlink and restoring whatever was there before.
func (*Provider) CompensateMove ¶
CompensateMove undoes a Move by moving the file back to its original location.
Move uses a plain rename (not RecoverySite), so compensation renames back directly. The resource's checksum is verified before restoring; a mismatch indicates external modification.
func (*Provider) CompensateRemove ¶
CompensateRemove undoes a Remove by restoring the file from recovery.
func (*Provider) CompensateRemoveAll ¶
CompensateRemoveAll undoes a RemoveAll by restoring from recovery.
func (*Provider) CompensateUnlink ¶
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 ¶
CompensateWriteBytes undoes a WriteBytes by restoring the original file.
func (*Provider) CompensateWriteText ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 (*Provider) Link ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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, boundary Resource) (result Tombstone, undo Tombstone, err error)
Remove deletes the file at "path".
If prune is true and boundary 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
- boundary: 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, boundary 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
- boundary: Stop pruning at this directory (prevents removing too much)
Returns:
- result: Tombstone for restoring the deleted tree
- err: any error
func (*Provider) Unlink ¶
func (p *Provider) Unlink(path Resource, prune bool, boundary Resource) (result Tombstone, undo Tombstone, err error)
Unlink removes the symlink at "path".
If prune is true and boundary 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
- boundary: 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 [#Provider.WalkTree] operation.
type Resource ¶
type Resource struct {
op.ResourceBase
SourcePath op.Path
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 ¶
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 ResourceFromValue ¶
ResourceFromValue constructs a file.Resource from a string path.
Parameters:
- v: expected to be a string file path
Returns:
- Resource: initialized with the given path
- error: if v is not a string
func (*Resource) Exists ¶
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) Refresh ¶
Refresh re-populates the resource's metadata by performing a fresh stat and re-calculating the checksum. Call after any successful physical mutation. I/O is scoped through op.Root.
Parameters:
- root: op.Root for scoped I/O
Returns:
- error: any stat or read error
func (*Resource) RefreshWith ¶
RefreshWith updates metadata after a write operation using a known checksum and size. A stat is still performed to capture kernel-assigned identity (Inode, Device). I/O is scoped through op.Root.
Parameters:
- root: op.Root for scoped I/O
- checksum: Pre-computed checksum string
- size: Known file size in bytes
Returns:
- error: any stat error
func (*Resource) Resolve ¶
Resolve populates the resource's metadata by canonicalizing the path and performing a stat. If the file does not exist, Resolve returns nil and metadata remains empty (Resource.Exists returns false). Other stat errors are returned. I/O is scoped through op.Root and SourcePath.Rel is populated.
Parameters:
- root: op.Root for scoped I/O
Returns:
- error: any stat error (not-exist is not an error)
func (*Resource) WriteTo ¶
WriteTo allows the Resource to be streamed directly to any io.Writer. I/O is scoped through op.Root.
For efficiency, it uses io.Copy which automatically attempts a zero-copy syscall before falling back to a 32KB buffer.
Parameters:
- root: op.Root for scoped I/O
- 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
// RecoveryID records where the data was temporarily moved during the operation (backup, recovery site, or move
// destination). An empty RecoveryID means no prior data existed to recover.
RecoveryID string
}
Tombstone holds file-specific compensation state.
The embedded op.TombstoneBase carries the affected Resource whose identity is preserved — SourcePath always reflects the file's true home.
Source Files
Directories