Documentation
¶
Overview ¶
Package jvs provides a high-level Go facade for JVS file-system version control.
It wraps internal packages into a clean, stable public API for applications that need to save, inspect, restore, and clean up versioned folder state.
Concurrency Safety ¶
JVS operations are filesystem-based and follow these concurrency rules:
Save() is safe when no concurrent writes to the workspace folder. Quiesce writers before saving a folder state.
Restore() is safe when no concurrent reads from the workspace folder. Quiesce readers and writers before restoring a folder state.
Multiple Client instances for DIFFERENT repositories are fully independent and safe to use concurrently.
Multiple Client instances for the SAME repository must NOT call mutating operations (Save, Restore, PreviewCleanup, RunCleanup) concurrently.
Recommended Usage Pattern ¶
// Open or initialize a managed folder.
client, err := jvs.OpenOrInit(repoPath, jvs.InitOptions{Name: "workspace"})
workspacePath := client.WorkspacePath("main")
// Restore a chosen save point before using the folder.
if latest, _ := client.LatestSavePoint(ctx, "main"); latest != nil {
client.Restore(ctx, jvs.RestoreOptions{Target: latest.SavePointID.String()})
}
// Use workspacePath as the application content folder, then save completed work.
client.Save(ctx, jvs.SaveOptions{
Message: "completed workspace update",
})
Index ¶
- func DetectEngine(path string) model.EngineType
- func ValidateEngine(path string, engineType model.EngineType) error
- type CleanupOptions
- type CleanupPlan
- type CleanupProtectionGroup
- type CleanupProtectionReason
- type Client
- func (c *Client) EngineType() model.EngineType
- func (c *Client) HasSavePoints(ctx context.Context, workspaceName string) (bool, error)
- func (c *Client) History(ctx context.Context, workspaceName string, limit int) ([]*SavePoint, error)
- func (c *Client) LatestSavePoint(ctx context.Context, workspaceName string) (*SavePoint, error)
- func (c *Client) PreviewCleanup(ctx context.Context, _ CleanupOptions) (*CleanupPlan, error)
- func (c *Client) RepoID() string
- func (c *Client) RepoRoot() string
- func (c *Client) Restore(ctx context.Context, opts RestoreOptions) error
- func (c *Client) RestoreLatest(ctx context.Context, workspaceName string) error
- func (c *Client) RunCleanup(ctx context.Context, planID string) error
- func (c *Client) Save(ctx context.Context, opts SaveOptions) (*SavePoint, error)
- func (c *Client) Verify(ctx context.Context, savePointID SavePointID) error
- func (c *Client) WorkspacePath(workspaceName string) string
- type InitOptions
- type RestoreOptions
- type SaveOptions
- type SavePoint
- type SavePointID
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetectEngine ¶
func DetectEngine(path string) model.EngineType
DetectEngine returns the best available save point materialization engine for the given path. Detection priority: juicefs-clone > reflink-copy > copy. The path should be the repository root or intended repository location.
func ValidateEngine ¶
func ValidateEngine(path string, engineType model.EngineType) error
ValidateEngine checks whether the given engine type is usable at the given path. Returns nil if the engine can operate correctly, or an error describing why not.
Types ¶
type CleanupPlan ¶
type CleanupPlan struct {
PlanID string `json:"plan_id"`
CreatedAt time.Time `json:"created_at"`
ProtectedSavePoints []SavePointID `json:"protected_save_points"`
ProtectionGroups []CleanupProtectionGroup `json:"protection_groups"`
ProtectedByHistory int `json:"protected_by_history"`
CandidateCount int `json:"candidate_count"`
ReclaimableSavePoints []SavePointID `json:"reclaimable_save_points"`
ReclaimableBytesEstimate int64 `json:"reclaimable_bytes_estimate"`
}
CleanupPlan is the public library view of a cleanup plan.
type CleanupProtectionGroup ¶ added in v0.4.7
type CleanupProtectionGroup struct {
Reason CleanupProtectionReason `json:"reason"`
Count int `json:"count"`
SavePoints []SavePointID `json:"save_points"`
}
CleanupProtectionGroup explains why save points are protected from cleanup.
type CleanupProtectionReason ¶ added in v0.4.7
type CleanupProtectionReason = string
CleanupProtectionReason is a stable public reason token explaining why save points are protected from cleanup. It aliases string so cleanup plans remain natural to use with ordinary Go string APIs.
const ( CleanupProtectionReasonHistory CleanupProtectionReason = "history" CleanupProtectionReasonOpenView CleanupProtectionReason = "open_view" CleanupProtectionReasonActiveRecovery CleanupProtectionReason = "active_recovery" CleanupProtectionReasonActiveOperation CleanupProtectionReason = "active_operation" CleanupProtectionReasonImportedCloneHistory CleanupProtectionReason = "imported_clone_history" )
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides high-level JVS operations on a repository.
func Init ¶
func Init(path string, opts InitOptions) (*Client, error)
Init initializes a new JVS repository at the given path.
func OpenOrInit ¶
func OpenOrInit(path string, opts InitOptions) (*Client, error)
OpenOrInit opens an existing JVS repository, or initializes a new one if none exists. It is the usual entry point for applications embedding the file-system version control facade.
func (*Client) EngineType ¶
func (c *Client) EngineType() model.EngineType
EngineType returns the save point materialization engine in use.
func (*Client) HasSavePoints ¶
HasSavePoints returns true if the workspace has at least one save point.
func (*Client) History ¶
func (c *Client) History(ctx context.Context, workspaceName string, limit int) ([]*SavePoint, error)
History returns save points for a workspace, sorted newest first. Pass limit <= 0 for all save points.
func (*Client) LatestSavePoint ¶
LatestSavePoint returns the most recent save point for a workspace. Returns nil, nil if no save points exist.
func (*Client) PreviewCleanup ¶
func (c *Client) PreviewCleanup(ctx context.Context, _ CleanupOptions) (*CleanupPlan, error)
PreviewCleanup creates a cleanup plan without deleting anything.
func (*Client) Restore ¶
func (c *Client) Restore(ctx context.Context, opts RestoreOptions) error
Restore restores a workspace to a specific save point identified by opts.Target. Target must be a save point ID or ID prefix.
func (*Client) RestoreLatest ¶
RestoreLatest restores a workspace to its most recent save point. Returns nil if the workspace has no save points.
func (*Client) RunCleanup ¶
RunCleanup executes a previously created cleanup plan by ID.
func (*Client) Save ¶
Save creates a new save point for the workspace. The workspace must not be in detached state.
func (*Client) Verify ¶
func (c *Client) Verify(ctx context.Context, savePointID SavePointID) error
Verify checks a save point's integrity.
func (*Client) WorkspacePath ¶
WorkspacePath returns the filesystem path to a workspace folder. This is the folder path to open directly or mount into another environment.
type InitOptions ¶
type InitOptions struct {
Name string // Repository name (validated: alphanumeric, hyphens, underscores)
EngineType model.EngineType // Save point materialization engine; empty string triggers auto-detection
}
InitOptions configures repository initialization.
type RestoreOptions ¶
type RestoreOptions struct {
WorkspaceName string // Target workspace; defaults to "main"
Target string // Save point ID or ID prefix
}
RestoreOptions configures workspace restore.
type SaveOptions ¶
type SaveOptions struct {
WorkspaceName string // Target workspace; defaults to "main"
Message string // Human-readable description
Tags []string // Organization tags
}
SaveOptions configures save point creation.
type SavePoint ¶
type SavePoint struct {
SavePointID SavePointID `json:"save_point_id"`
WorkspaceName string `json:"workspace_name"`
CreatedAt time.Time `json:"created_at"`
Message string `json:"message,omitempty"`
Tags []string `json:"tags,omitempty"`
Engine model.EngineType `json:"engine"`
ContentRootHash model.HashValue `json:"content_root_hash"`
DescriptorChecksum model.HashValue `json:"descriptor_checksum"`
IntegrityState model.IntegrityState `json:"integrity_state"`
}
SavePoint is the public library view of a saved workspace state.
type SavePointID ¶
type SavePointID string
SavePointID identifies a save point in the public library facade.
func (SavePointID) String ¶
func (id SavePointID) String() string
String returns the save point ID as a string.
Source Files