Skip to main content

WorkspaceBackend

maw::backend

Trait WorkspaceBackend 

Source 
pub trait WorkspaceBackend {
    type Error: Error + Send + Sync + 'static;

    // Required methods
    fn create(
        &self,
        name: &WorkspaceId,
        epoch: &EpochId,
    ) -> Result<WorkspaceInfo, Self::Error>;
    fn destroy(&self, name: &WorkspaceId) -> Result<(), Self::Error>;
    fn list(&self) -> Result<Vec<WorkspaceInfo>, Self::Error>;
    fn status(&self, name: &WorkspaceId) -> Result<WorkspaceStatus, Self::Error>;
    fn snapshot(
        &self,
        name: &WorkspaceId,
    ) -> Result<SnapshotResult, Self::Error>;
    fn workspace_path(&self, name: &WorkspaceId) -> PathBuf;
    fn exists(&self, name: &WorkspaceId) -> bool;
}
Expand description

A workspace backend implementation.

The WorkspaceBackend trait defines the interface for creating, managing, and querying workspaces. Implementations of this trait are responsible for the actual isolation mechanism (e.g., git worktrees, reflinks, overlays).

§Key Invariants

  • Workspace isolation: Each workspace’s working copy is independent. Changes in one workspace don’t affect others until explicitly merged.
  • Workspace uniqueness: No two active workspaces can have the same name within a given repository.
  • Epoch tracking: Each workspace is anchored to an epoch (a specific repository state). Workspaces can become stale if the repository advances.

Required Associated Types§

Source

type Error: Error + Send + Sync + 'static

The error type returned by backend operations.

Required Methods§

Source

fn create( &self, name: &WorkspaceId, epoch: &EpochId, ) -> Result<WorkspaceInfo, Self::Error>

Create a new workspace.

Creates a new workspace with the given name, anchored to the provided epoch. The workspace is initialized with a clean working copy at that epoch.

§Arguments
  • name - Unique workspace identifier (must be a valid WorkspaceId)
  • epoch - The repository state this workspace is based on
§Returns

Complete information about the newly created workspace, including its path and initial state.

§Invariants
  • The returned WorkspaceInfo has state [WorkspaceState::Active]
  • The workspace directory exists and is ready for use
  • No workspace with the same name exists before the call
  • The workspace is isolated from all other workspaces
Source

fn destroy(&self, name: &WorkspaceId) -> Result<(), Self::Error>

Destroy a workspace.

Removes the workspace from the system. The workspace directory and all its contents are deleted. The workspace becomes unavailable for future operations.

§Arguments
  • name - Identifier of the workspace to destroy
§Invariants
  • The workspace directory is fully removed
  • The workspace can no longer be accessed via any backend method
  • Destroying a non-existent workspace is a no-op (idempotent)
Source

fn list(&self) -> Result<Vec<WorkspaceInfo>, Self::Error>

List all workspaces.

Returns information about all active workspaces in the repository. Does not include destroyed workspaces.

§Returns

A vector of WorkspaceInfo for all active workspaces, or empty vector if no workspaces exist.

§Invariants
  • Only active workspaces are included
  • Order is consistent but unspecified
Source

fn status(&self, name: &WorkspaceId) -> Result<WorkspaceStatus, Self::Error>

Get the current status of a workspace.

Returns detailed information about the workspace’s current state, including its epoch, dirty files, and staleness.

§Arguments
  • name - Identifier of the workspace to query
§Invariants
  • The returned status reflects the workspace’s current state
  • For a stale workspace, is_stale is true and behind_epochs indicates how many epochs the workspace is behind
  • For a destroyed workspace, returns an error (not a status)
Source

fn snapshot(&self, name: &WorkspaceId) -> Result<SnapshotResult, Self::Error>

Capture all changes in the workspace.

Scans the workspace for all modified, added, and deleted files. Returns a snapshot of changes that can be committed or discarded.

§Arguments
  • name - Identifier of the workspace to snapshot
§Returns

A SnapshotResult containing the list of changed paths and their change kinds (add, modify, delete).

§Invariants
  • Only working copy changes are included; committed changes are not
  • All reported paths are relative to the workspace root
  • The snapshot is point-in-time; changes made after the snapshot are not included
Source

fn workspace_path(&self, name: &WorkspaceId) -> PathBuf

Get the absolute path to a workspace.

Returns the absolute filesystem path where the workspace’s files are stored. Does not verify that the workspace exists.

§Arguments
  • name - Identifier of the workspace
§Returns

An absolute PathBuf to the workspace root directory.

§Invariants
  • The path is absolute (not relative)
  • The path is consistent: repeated calls return equal paths
  • The path may not exist if the workspace has been destroyed
Source

fn exists(&self, name: &WorkspaceId) -> bool

Check if a workspace exists.

Returns true if a workspace with the given name exists and is active, false otherwise.

§Arguments
  • name - Identifier of the workspace
§Invariants
  • Returns true only if the workspace is active and accessible
  • Destroyed or non-existent workspaces return false
  • This is a lightweight check; no I/O is guaranteed

Implementors§