Documentation
¶
Overview ¶
Package jvs provides a high-level library API for JVS (Juicy Versioned Workspaces).
This package is the primary integration point for external consumers such as sandbox-manager. It wraps internal packages into a clean, stable public API.
Concurrency Safety ¶
JVS operations are filesystem-based and follow these concurrency rules:
Save() is safe when no concurrent writes to the payload directory. Always save AFTER the agent pod has been deleted (process stopped).
Restore() is safe when no concurrent reads from the payload directory. Always restore BEFORE the agent pod is created.
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 (sandbox-manager) ¶
// Pod startup: restore workspace before creating pod
client, err := jvs.OpenOrInit(repoPath, jvs.InitOptions{Name: "agent-ws"})
payloadPath := client.WorkspacePath("main")
if latest, _ := client.LatestSavePoint(ctx, "main"); latest != nil {
client.Restore(ctx, jvs.RestoreOptions{Target: latest.SavePointID.String()})
}
// Mount payloadPath as /workspace in pod via JuiceFS subPath
// Pod shutdown: save after pod is deleted
client.Save(ctx, jvs.SaveOptions{
Message: "auto: pod shutdown",
Tags: []string{"auto", "shutdown"},
})
Index ¶
- func DetectEngine(path string) model.EngineType
- func ValidateEngine(path string, engineType model.EngineType) error
- type CleanupOptions
- type CleanupPlan
- 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"`
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 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 repository, or initializes a new one if none exists. This is the recommended entry point for sandbox-manager integration.
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 payload directory. This is the path that should be mounted into agent pods as /workspace.
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"`
PayloadRootHash model.HashValue `json:"payload_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