engine

package
v0.4.10 Latest Latest
Warning

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

 Go to latest Published: May 18, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package engine provides snapshot engines for copying worktree data. Engines support different cloning strategies: juicefs-clone, reflink-copy, and copy.

Index

Constants

View Source 
const (
	CapabilityConfirmed = "confirmed"
	CapabilityUnknown   = "unknown"
	EngineAuto          = model.EngineType("auto")
)

Variables

This section is empty.

Functions

func MetadataPreservationForEngine 

func MetadataPreservationForEngine(engineType model.EngineType) model.MetadataPreservation

MetadataPreservationForEngine returns the documented preservation contract for materializing payloads with engineType.

func PerformanceClassForEngine 

func PerformanceClassForEngine(engineType model.EngineType) string

PerformanceClassForEngine returns the public performance class for an engine without promising benchmark-specific throughput.

func PrepareCloneToNewDestination 

func PrepareCloneToNewDestination(dst string) error

PrepareCloneToNewDestination creates the destination parent if necessary and verifies that the destination leaf is absent.

Types

type Capability 

type Capability struct {
	Available  bool     `json:"available"`
	Supported  bool     `json:"supported"`
	Confidence string   `json:"confidence"`
	Warnings   []string `json:"warnings"`
}

Capability describes whether one transfer mechanism can be used at a target.

type CapabilityProber 

type CapabilityProber interface {
	ProbeCapabilities(targetPath string, writeProbe bool) (*CapabilityReport, error)
	ProbeTransferPair(sourcePath, destinationPath string) (*TransferPairReport, error)
}

CapabilityProber is the filesystem probing surface used by capability reporting and transfer planning. Tests can replace it without touching the actual filesystem.

type CapabilityReport 

type CapabilityReport struct {
	TargetPath           string                     `json:"target_path"`
	ProbePath            string                     `json:"probe_path"`
	WriteProbe           bool                       `json:"write_probe"`
	Write                Capability                 `json:"write"`
	JuiceFS              Capability                 `json:"juicefs"`
	Reflink              Capability                 `json:"reflink"`
	Copy                 Capability                 `json:"copy"`
	RecommendedEngine    model.EngineType           `json:"recommended_engine"`
	MetadataPreservation model.MetadataPreservation `json:"metadata_preservation"`
	PerformanceClass     string                     `json:"performance_class"`
	Warnings             []string                   `json:"warnings"`
}

CapabilityReport is a non-mutating report by default. Reflink support is only confirmed when writeProbe is true.

func ProbeCapabilities 

func ProbeCapabilities(targetPath string, writeProbe bool) (*CapabilityReport, error)

ProbeCapabilities reports JuiceFS, reflink, and copy support for targetPath. With writeProbe=false it does not create test files.

type CloneResult 

type CloneResult struct {
	ActualEngine         model.EngineType           // engine that actually wrote data
	EffectiveEngine      model.EngineType           // public effective transfer/materialization engine
	MetadataPreservation model.MetadataPreservation // metadata preservation contract
	PerformanceClass     string                     // performance class for the effective engine
	Degraded             bool                       // true if any degradation occurred
	Degradations         []string                   // list of degradation types
}

CloneResult contains the result of a clone operation, including any degradation information if the clone could not use the optimal method.

func CloneToNew 

func CloneToNew(eng Engine, src, dst string) (*CloneResult, error)

CloneToNew clones src into an owned destination path whose leaf must not already exist. This is the mode required by engines such as `juicefs clone`.

func NewCloneResult 

func NewCloneResult(engineType model.EngineType) *CloneResult

NewCloneResult initializes result metadata for engineType.

func (*CloneResult) AddDegradation 

func (r *CloneResult) AddDegradation(reason string, effectiveEngine model.EngineType)

AddDegradation records a degradation and updates the effective engine when the operation fell back to a different public class.

type CopyEngine 

type CopyEngine struct{}

CopyEngine performs a full recursive copy of directories. This is the fallback engine that works on any filesystem but does not preserve hardlinks (they become separate copies).

func NewCopyEngine 

func NewCopyEngine() *CopyEngine

NewCopyEngine creates a new CopyEngine.

func (*CopyEngine) Clone 

func (e *CopyEngine) Clone(src, dst string) (*CloneResult, error)

Clone recursively copies src to dst. Returns a degraded result if hardlinks were detected (they become separate copies).

func (*CopyEngine) CloneToNew added in v0.4.7 

func (e *CopyEngine) CloneToNew(src, dst string) (*CloneResult, error)

CloneToNew clones src into an owned destination path whose leaf does not already exist. File and symlink roots are materialized as leaf paths, so the durable parent is the destination parent rather than the leaf itself.

func (*CopyEngine) Name 

func (e *CopyEngine) Name() model.EngineType

Name returns the engine type.

type DefaultTransferSelector 

type DefaultTransferSelector struct{}

DefaultTransferSelector is the production selector.

func (DefaultTransferSelector) SelectTransfer 

func (DefaultTransferSelector) SelectTransfer(req TransferSelectionRequest) TransferSelection

SelectTransfer chooses an engine using destination capabilities.

type Engine 

type Engine interface {
	// Name returns the engine type identifier.
	Name() model.EngineType

	// Clone performs a copy of src to dst.
	// Returns CloneResult with degradation info if applicable.
	Clone(src, dst string) (*CloneResult, error)
}

Engine defines the snapshot engine interface for copying worktree data.

func DetectEngine 

func DetectEngine(repoRoot string) (Engine, error)

DetectEngine auto-detects the best available engine for the given repository. Detection order: juicefs-clone (if on JuiceFS), reflink-copy (if supported), copy.

func DetectEngineAuto 

func DetectEngineAuto(repoRoot string) (Engine, error)

DetectEngineAuto auto-detects the best available engine without considering environment overrides.

func NewEngine 

func NewEngine(engineType model.EngineType) Engine

NewEngine creates an engine based on the specified type. Falls back to CopyEngine if the requested engine is not available.

type JuiceFSEngine 

type JuiceFSEngine struct {
	CopyEngine *CopyEngine // Fallback
	// contains filtered or unexported fields
}

JuiceFSEngine performs clone using `juicefs clone` command. When juicefs is unavailable or the source is not on JuiceFS, it falls back to the copy engine.

func NewJuiceFSEngine 

func NewJuiceFSEngine() *JuiceFSEngine

NewJuiceFSEngine creates a new JuiceFSEngine.

func (*JuiceFSEngine) Clone 

func (e *JuiceFSEngine) Clone(src, dst string) (*CloneResult, error)

Clone performs a juicefs clone if available, falls back to copy otherwise. Returns a degraded result if juicefs is not available or not on JuiceFS.

func (*JuiceFSEngine) CloneToNew 

func (e *JuiceFSEngine) CloneToNew(src, dst string) (*CloneResult, error)

CloneToNew performs a juicefs clone into an owned destination path whose leaf must not already exist. If juicefs leaves a partial leaf before failing, it is removed before fallback copy.

func (*JuiceFSEngine) Name 

func (e *JuiceFSEngine) Name() model.EngineType

Name returns the engine type.

type ReflinkEngine 

type ReflinkEngine struct {
	CopyEngine *CopyEngine
}

ReflinkEngine performs reflink-based copy (O(1) CoW) on supported filesystems. Falls back to regular copy for files that cannot be reflinked.

func NewReflinkEngine 

func NewReflinkEngine() *ReflinkEngine

NewReflinkEngine creates a new ReflinkEngine.

func (*ReflinkEngine) Clone 

func (e *ReflinkEngine) Clone(src, dst string) (*CloneResult, error)

Clone performs a reflink copy if supported, falls back to regular copy otherwise.

func (*ReflinkEngine) CloneToNew 

func (e *ReflinkEngine) CloneToNew(src, dst string) (*CloneResult, error)

CloneToNew clones src into an owned destination path whose leaf must not already exist. Unlike legacy Clone, it leaves the destination leaf for the source root itself so file and symlink roots materialize as leaves.

func (*ReflinkEngine) Name 

func (e *ReflinkEngine) Name() model.EngineType

Name returns the engine type.

type TransferPairReport 

type TransferPairReport struct {
	SourcePath      string     `json:"source_path"`
	DestinationPath string     `json:"destination_path"`
	Reflink         Capability `json:"reflink"`
	Warnings        []string   `json:"warnings,omitempty"`
}

TransferPairReport describes capabilities that depend on both source and destination paths.

type TransferPlan 

type TransferPlan struct {
	RequestedEngine   model.EngineType  `json:"requested_engine"`
	TransferEngine    model.EngineType  `json:"transfer_engine"`
	EffectiveEngine   model.EngineType  `json:"effective_engine"`
	OptimizedTransfer bool              `json:"optimized_transfer"`
	Capabilities      *CapabilityReport `json:"capabilities,omitempty"`
	DegradedReasons   []string          `json:"degraded_reasons"`
	Warnings          []string          `json:"warnings,omitempty"`
}

TransferPlan is the contract surfaced by CLI lifecycle operations.

func PlanTransfer 

func PlanTransfer(req TransferPlanRequest) (*TransferPlan, error)

PlanTransfer uses destination capabilities plus pair probes to select an engine for source+destination transfer operations. Preview-only requests are read-only and therefore do not perform write probes.

type TransferPlanRequest 

type TransferPlanRequest struct {
	SourcePath      string
	DestinationPath string
	CapabilityPath  string
	RequestedEngine model.EngineType
	PreviewOnly     bool
}

TransferPlanRequest contains the inputs needed to choose a transfer engine.

type TransferPlanner 

type TransferPlanner struct {
	Prober   CapabilityProber
	Selector TransferSelector
}

TransferPlanner plans source+destination transfers from shared capabilities.

func (TransferPlanner) PlanTransfer 

func (p TransferPlanner) PlanTransfer(req TransferPlanRequest) (*TransferPlan, error)

PlanTransfer uses destination capabilities plus pair probes to select an engine for source+destination transfer operations. Preview-only requests are read-only and therefore do not perform write probes.

type TransferSelection 

type TransferSelection struct {
	TransferEngine  model.EngineType
	DegradedReasons []string
	Warnings        []string
}

TransferSelection is a destination-level engine choice before pair probes.

type TransferSelectionRequest 

type TransferSelectionRequest struct {
	RequestedEngine model.EngineType
	Capabilities    *CapabilityReport
}

TransferSelectionRequest is passed to a selector after destination capabilities are known.

type TransferSelector 

type TransferSelector interface {
	SelectTransfer(TransferSelectionRequest) TransferSelection
}

TransferSelector chooses the destination-level engine from a capability report and a requested engine.

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.