workspace

package
v0.0.0-...-1a28f28 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package workspace provides Docker-specific workspace isolation.

Package workspace provides file masking for sandbox isolation.

Package workspace provides post-execution review workflows for sandbox isolation.

Package workspace provides workspace isolation modes for sandbox execution.

Workspace isolation controls how the sandbox interacts with the host filesystem, providing defense-in-depth for supply chain security. Available modes:

  • Direct: Simple bind mount (default, backward compatible)
  • Overlay: Copy-on-write using overlayfs
  • Snapshot: Full copy to temporary directory
  • GitWorktree: Git worktree for repository isolation
  • Tmpfs: In-memory overlay for ephemeral operations

Each mode offers different tradeoffs between performance, isolation, and the ability to review/rollback changes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAgentMask 

func DefaultAgentMask() *sandboxv1.FileMaskConfig

DefaultAgentMask returns the default file mask for AI agent execution.

func DefaultSupplyChainMask 

func DefaultSupplyChainMask() *sandboxv1.FileMaskConfig

DefaultSupplyChainMask returns the default file mask for supply chain security.

Types

type ChangeSummary 

type ChangeSummary struct {
	Added    int
	Modified int
	Deleted  int
	Total    int
	Selected int
}

ChangeSummary provides a summary of changes.

type Config 

type Config struct {
	// Mode determines the isolation strategy.
	Mode sandboxv1.WorkspaceIsolationMode

	// OriginalPath is the original workspace directory.
	OriginalPath string

	// OverlaySizeLimit for overlay modes (e.g., "1g").
	OverlaySizeLimit string

	// SnapshotDir for snapshot mode.
	SnapshotDir string

	// WorktreeBranch for git worktree mode.
	WorktreeBranch string

	// PreserveAfterExecution keeps the isolated workspace for review.
	PreserveAfterExecution bool

	// SetupTimeout limits time spent setting up isolation.
	SetupTimeout time.Duration

	// SyncPatterns are glob patterns for files to sync back.
	SyncPatterns []string

	// ExcludeSyncPatterns are glob patterns for files to never sync.
	ExcludeSyncPatterns []string
}

Config configures workspace isolation behavior.

type DiffGenerator 

type DiffGenerator interface {
	// GenerateDiff creates a unified diff between original and modified files.
	GenerateDiff(originalPath, modifiedPath string) (string, error)
}

DiffGenerator generates diff output for file changes.

type DockerIsolationOptions 

type DockerIsolationOptions struct {
	// Mode is the workspace isolation mode.
	Mode sandboxv1.WorkspaceIsolationMode

	// FileMask configuration for hiding sensitive files.
	FileMask *sandboxv1.FileMaskConfig

	// OriginalPath is the host workspace path.
	OriginalPath string

	// ContainerPath is where the workspace is mounted in the container.
	ContainerPath string

	// SizeLimit for overlay/tmpfs upper layer.
	SizeLimit string

	// SyncPatterns for selective file sync after execution.
	SyncPatterns []string

	// ExcludeSyncPatterns for files to never sync.
	ExcludeSyncPatterns []string

	// PreserveAfterExecution keeps workspace for review.
	PreserveAfterExecution bool
}

DockerIsolationOptions holds options for Docker-specific workspace isolation.

func AgentDockerIsolation 

func AgentDockerIsolation(workspacePath string) DockerIsolationOptions

AgentDockerIsolation returns isolation settings optimized for AI agents.

func DefaultDockerIsolation 

func DefaultDockerIsolation(workspacePath string) DockerIsolationOptions

DefaultDockerIsolation returns recommended defaults for Docker isolation.

type DockerIsolator 

type DockerIsolator struct {
	// contains filtered or unexported fields
}

DockerIsolator provides workspace isolation using Docker-native mechanisms. Unlike the host-based isolators, this works without root privileges and leverages Docker's overlay storage driver.

func NewDockerIsolationFromOptions 

func NewDockerIsolationFromOptions(opts DockerIsolationOptions) (*DockerIsolator, error)

NewDockerIsolationFromOptions creates a DockerIsolator from options.

func NewDockerIsolator 

func NewDockerIsolator(cfg Config, masker *FileMasker) (*DockerIsolator, error)

NewDockerIsolator creates a Docker-aware workspace isolator.

func (*DockerIsolator) ApplyToHostConfig 

func (d *DockerIsolator) ApplyToHostConfig(hostConfig *container.HostConfig, containerWorkspace string, mode sandboxv1.Mode)

ApplyToHostConfig applies isolation settings to Docker HostConfig. This sets up tmpfs, mounts, and other container configuration.

func (*DockerIsolator) BuildHiddenPathMounts 

func (d *DockerIsolator) BuildHiddenPathMounts(containerWorkspace string) []mount.Mount

BuildHiddenPathMounts returns tmpfs mounts for hiding files inside the container. This is used when file masking is done at container runtime rather than by copying.

func (*DockerIsolator) BuildMounts 

func (d *DockerIsolator) BuildMounts(containerWorkspace string, readOnly bool) []mount.Mount

BuildMounts returns Docker mount configurations for the isolated workspace. This configures how the workspace should be mounted into the container.

func (*DockerIsolator) Changes 

func (d *DockerIsolator) Changes(ctx context.Context) ([]FileChange, error)

Changes returns files modified in the isolated workspace.

func (*DockerIsolator) IsolatedPath 

func (d *DockerIsolator) IsolatedPath() string

IsolatedPath returns the path to the isolated workspace.

func (*DockerIsolator) OriginalPath 

func (d *DockerIsolator) OriginalPath() string

OriginalPath returns the original workspace path.

func (*DockerIsolator) Setup 

func (d *DockerIsolator) Setup(ctx context.Context) (string, error)

Setup prepares the isolated workspace for Docker. For Docker, we create a local copy with masking applied, then mount it.

func (*DockerIsolator) Sync 

func (d *DockerIsolator) Sync(ctx context.Context, patterns, excludePatterns []string) error

Sync copies changes from isolated workspace back to original.

func (*DockerIsolator) Teardown 

func (d *DockerIsolator) Teardown(ctx context.Context, preserveChanges bool) error

Teardown cleans up the isolated workspace.

type FileChange 

type FileChange struct {
	// Path relative to workspace root.
	Path string

	// Type of change: "added", "modified", "deleted", "renamed".
	Type string

	// OldPath for renamed files.
	OldPath string

	// Size in bytes (0 for deleted files).
	Size int64

	// ModTime of the file.
	ModTime time.Time
}

FileChange represents a file that was modified in the isolated workspace.

type FileMasker 

type FileMasker struct {
	// contains filtered or unexported fields
}

FileMasker handles file masking for sandboxed execution. It creates a view of the workspace where sensitive files are hidden, emptied, or replaced with placeholders.

func NewFileMasker 

func NewFileMasker(config *sandboxv1.FileMaskConfig) *FileMasker

NewFileMasker creates a new file masker from configuration.

func (*FileMasker) CreateMaskedWorkspace 

func (fm *FileMasker) CreateMaskedWorkspace(srcDir, dstDir string) error

CreateMaskedWorkspace creates a copy of the workspace with masked files. SECURITY: Uses os.Root (Go 1.24+) for traversal-resistant file operations. Returns the path to the masked workspace.

func (*FileMasker) GenerateDockerIgnore 

func (fm *FileMasker) GenerateDockerIgnore() []string

GenerateDockerIgnore generates a .dockerignore-style list of patterns to exclude. Useful for Docker's --ignore option or building exclusion lists.

func (*FileMasker) GenerateHiddenPaths 

func (fm *FileMasker) GenerateHiddenPaths(workspaceDir string) []string

GenerateHiddenPaths returns paths that should be hidden via tmpfs mounts. SECURITY: Uses os.Root (Go 1.24+) for traversal-resistant file operations. Useful for Docker's --tmpfs option for hiding paths.

func (*FileMasker) ShouldMask 

func (fm *FileMasker) ShouldMask(path string) (sandboxv1.FileMaskMode, string)

ShouldMask determines if a file should be masked and how. Returns the mask mode and reason.

type Isolator 

type Isolator interface {
	// Setup prepares the isolated workspace and returns the path to use.
	// The returned path should be mounted into the sandbox.
	Setup(ctx context.Context) (isolatedPath string, err error)

	// Teardown cleans up the isolated workspace.
	// If preserveChanges is true, modified files are kept for review.
	Teardown(ctx context.Context, preserveChanges bool) error

	// Changes returns the list of files modified during execution.
	// Only available after sandbox execution completes.
	Changes(ctx context.Context) ([]FileChange, error)

	// Sync copies changes from isolated workspace back to original.
	// Respects sync_patterns and exclude_sync_patterns from config.
	Sync(ctx context.Context, patterns, excludePatterns []string) error

	// IsolatedPath returns the path to the isolated workspace.
	IsolatedPath() string

	// OriginalPath returns the original workspace path.
	OriginalPath() string
}

Isolator manages workspace isolation for sandbox execution. It handles setup, teardown, and change synchronization.

func New 

func New(cfg Config) (Isolator, error)

New creates a new workspace isolator based on the configuration.

type ReviewOptions 

type ReviewOptions struct {
	// AutoApply automatically applies changes without prompting.
	AutoApply bool

	// AutoDiscard automatically discards changes without prompting.
	AutoDiscard bool

	// PreserveOnError keeps the workspace if an error occurs.
	PreserveOnError bool

	// ShowDiffs shows diffs for each changed file.
	ShowDiffs bool

	// MaxDiffLines limits the number of diff lines shown per file.
	MaxDiffLines int

	// FilterPatterns only shows changes matching these patterns.
	FilterPatterns []string
}

ReviewOptions configures the review workflow.

func AgentReviewOptions 

func AgentReviewOptions() ReviewOptions

AgentReviewOptions returns options suitable for AI agent workflows. These preserve the workspace by default for human review.

func DefaultReviewOptions 

func DefaultReviewOptions() ReviewOptions

DefaultReviewOptions returns sensible defaults for review.

type ReviewResult 

type ReviewResult int

ReviewResult represents the outcome of a user's review decision. 

const (
	// ReviewResultPending means no decision has been made yet.
	ReviewResultPending ReviewResult = iota
	// ReviewResultApplyAll applies all changes to the original workspace.
	ReviewResultApplyAll
	// ReviewResultApplySelected applies only selected changes.
	ReviewResultApplySelected
	// ReviewResultDiscard discards all changes.
	ReviewResultDiscard
	// ReviewResultPreserve keeps the isolated workspace for manual review.
	ReviewResultPreserve
)

type ReviewSession 

type ReviewSession struct {
	// contains filtered or unexported fields
}

ReviewSession manages the post-execution review workflow. It allows users to inspect changes, selectively apply them, or discard everything.

func NewReviewSession 

func NewReviewSession(isolator Isolator) *ReviewSession

NewReviewSession creates a new review session for an isolator.

func (*ReviewSession) ApplyAll 

func (r *ReviewSession) ApplyAll(ctx context.Context) error

ApplyAll applies all changes to the original workspace.

func (*ReviewSession) ApplySelected 

func (r *ReviewSession) ApplySelected(ctx context.Context) error

ApplySelected applies only selected changes to the original workspace.

func (*ReviewSession) Changes 

func (r *ReviewSession) Changes() []FileChange

Changes returns the detected file changes.

func (*ReviewSession) DeselectAll 

func (r *ReviewSession) DeselectAll()

DeselectAll deselects all changes.

func (*ReviewSession) DeselectPath 

func (r *ReviewSession) DeselectPath(path string)

DeselectPath marks a path as not selected.

func (*ReviewSession) Discard 

func (r *ReviewSession) Discard(ctx context.Context) error

Discard discards all changes and cleans up.

func (*ReviewSession) GetDiff 

func (r *ReviewSession) GetDiff(change FileChange) (string, error)

GetDiff returns the diff for a specific file change. SECURITY: Uses os.Root (Go 1.24+) for traversal-resistant file operations.

func (*ReviewSession) HasChanges 

func (r *ReviewSession) HasChanges() bool

HasChanges returns true if there are any changes to review.

func (*ReviewSession) IsSelected 

func (r *ReviewSession) IsSelected(path string) bool

IsSelected returns true if a path is selected.

func (*ReviewSession) LoadChanges 

func (r *ReviewSession) LoadChanges(ctx context.Context) error

LoadChanges detects all changes in the isolated workspace.

func (*ReviewSession) Preserve 

func (r *ReviewSession) Preserve() string

Preserve keeps the isolated workspace for manual review.

func (*ReviewSession) PreservedPath 

func (r *ReviewSession) PreservedPath() string

PreservedPath returns the path to the preserved workspace (if preserved).

func (*ReviewSession) PrintChanges 

func (r *ReviewSession) PrintChanges(w io.Writer)

PrintChanges prints the list of changes to a writer.

func (*ReviewSession) Result 

func (r *ReviewSession) Result() ReviewResult

Result returns the review result.

func (*ReviewSession) SelectAll 

func (r *ReviewSession) SelectAll()

SelectAll selects all changes.

func (*ReviewSession) SelectPath 

func (r *ReviewSession) SelectPath(path string)

SelectPath marks a path as selected for application.

func (*ReviewSession) SelectedChanges 

func (r *ReviewSession) SelectedChanges() []FileChange

SelectedChanges returns only the selected changes.

func (*ReviewSession) SelectedCount 

func (r *ReviewSession) SelectedCount() int

SelectedCount returns the number of selected changes.

func (*ReviewSession) Summary 

func (r *ReviewSession) Summary() ChangeSummary

Summary returns a summary of changes by type.

func (*ReviewSession) TogglePath 

func (r *ReviewSession) TogglePath(path string)

TogglePath toggles the selection state of a path.

func (*ReviewSession) WithDiffGenerator 

func (r *ReviewSession) WithDiffGenerator(gen DiffGenerator) *ReviewSession

WithDiffGenerator sets a custom diff generator.

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.