planner

package
v0.8.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetServiceNames 

func GetServiceNames(services []ServiceInfo) []string

GetServiceNames extracts service names from a list of ServiceInfo.

func NeedsApply 

func NeedsApply(services []ServiceInfo) bool

NeedsApply determines if any services in the list require application/reconciliation.

func RenderResourcePlan added in v0.1.1 

func RenderResourcePlan(rp *ResourcePlan) string

RenderResourcePlan renders a ResourcePlan with consistent formatting

Types

type Action added in v0.1.1 

type Action string

Action represents a standardized action that can be taken on a resource 

const (
	ActionCreate    Action = "create"
	ActionUpdate    Action = "update"
	ActionDelete    Action = "delete"
	ActionReconcile Action = "reconcile"
	ActionNoop      Action = "no-op"
)

type CleanupOptions 

type CleanupOptions struct {
	// Strict makes cleanup errors fail the command.
	Strict bool
	// VerboseErrors logs full aggregated cleanup errors when Strict is false.
	VerboseErrors bool
}

CleanupOptions controls behavior for cleanup operations (prune/destroy).

type ContextExecutionContext 

type ContextExecutionContext struct {
	ContextName string
	Identifier  string

	// Per-stack execution data (keys are stack names without daemon prefix)
	Stacks map[string]*StackExecutionData
	// Per-fileset execution data (indexes and diffs computed during plan)
	Filesets map[string]*FilesetExecutionData
	// Snapshot of existing volumes (used for fileset sync validation and progress estimation)
	ExistingVolumes map[string]struct{}
	// Snapshot of existing networks (used for progress estimation)
	ExistingNetworks map[string]struct{}
}

ContextExecutionContext contains pre-computed data needed to execute the plan for a single context. This allows Apply to reuse state detection results from BuildPlan, avoiding duplicate Docker API calls, SOPS decryption, and compose config parsing.

func NewContextExecutionContext 

func NewContextExecutionContext(contextName, identifier string) *ContextExecutionContext

NewContextExecutionContext creates a new empty context execution context.

type ContextPlan 

type ContextPlan struct {
	ContextName string
	Identifier  string
	Resources   *ResourcePlan
}

ContextPlan represents the plan for a single context.

type ContextResult 

type ContextResult struct {
	ContextName string
	Err         error
}

ContextResult holds the outcome of executing an operation on one context.

type DockerClient 

type DockerClient interface {
	// Volume operations
	ListVolumes(ctx context.Context) ([]string, error)
	CreateVolume(ctx context.Context, name string, labels map[string]string) error
	RemoveVolume(ctx context.Context, name string) error

	// Volume file operations
	ReadFileFromVolume(ctx context.Context, volumeName, targetPath, relFile string) (string, error)
	WriteFileToVolume(ctx context.Context, volumeName, targetPath, relFile, content string) error
	ExtractTarToVolume(ctx context.Context, volumeName, targetPath string, tarReader io.Reader) error
	RemovePathsFromVolume(ctx context.Context, volumeName, targetPath string, relPaths []string) error
	RunVolumeScript(ctx context.Context, volumeName, targetPath, script string, env []string) (dockercli.VolumeScriptResult, error)

	// Network operations
	ListNetworks(ctx context.Context) ([]string, error)
	CreateNetwork(ctx context.Context, name string, labels map[string]string, opts ...dockercli.NetworkCreateOpts) error
	RemoveNetwork(ctx context.Context, name string) error
	InspectNetwork(ctx context.Context, name string) (dockercli.NetworkInspect, error)

	// Container operations
	ListComposeContainersAll(ctx context.Context) ([]dockercli.PsBrief, error)
	ListContainersUsingVolume(ctx context.Context, volumeName string) ([]string, error)
	ListRunningContainersUsingVolume(ctx context.Context, volumeName string) ([]string, error)
	RestartContainer(ctx context.Context, name string) error
	StopContainers(ctx context.Context, names []string) error
	StartContainers(ctx context.Context, names []string) error
	RemoveContainer(ctx context.Context, name string, force bool) error
	UpdateContainerLabels(ctx context.Context, containerName string, labels map[string]string) error
	InspectContainerLabels(ctx context.Context, containerName string, keys []string) (map[string]string, error)
	InspectMultipleContainerLabels(ctx context.Context, containerNames []string, keys []string) (map[string]map[string]string, error)

	// Compose operations
	ComposeConfigFull(ctx context.Context, root string, files []string, profiles []string, envFiles []string, inline []string) (dockercli.ComposeConfigDoc, error)
	ComposeConfigServices(ctx context.Context, root string, files []string, profiles []string, envFiles []string, inline []string) ([]string, error)
	ComposeConfigHash(ctx context.Context, root string, files []string, profiles []string, envFiles []string, project, serviceName, identifier string, inline []string) (string, error)
	ComposeConfigHashes(ctx context.Context, root string, files []string, profiles []string, envFiles []string, project string, services []string, identifier string, inline []string) (map[string]string, error)
	ComposePs(ctx context.Context, root string, files []string, profiles []string, envFiles []string, project string, inline []string) ([]dockercli.ComposePsItem, error)
	ComposeUp(ctx context.Context, root string, files []string, profiles []string, envFiles []string, project string, inline []string) (string, error)
}

DockerClient defines the interface for Docker operations needed by the planner. This allows for easy mocking in tests and potential future support for other container runtimes.

type ExecutionContext added in v0.7.0 

type ExecutionContext = ContextExecutionContext

Legacy support: ExecutionContext for single-context backward compatibility This is used during the transition period and maps to the first context's execution context.

type FilesetExecutionData added in v0.7.0 

type FilesetExecutionData struct {
	// Local filesystem index (files + SHA256 hashes)
	LocalIndex filesets.Index
	// Remote volume index (if volume exists)
	RemoteIndex filesets.Index
	// Diff between local and remote
	Diff filesets.Diff
}

FilesetExecutionData contains pre-computed fileset indexes and diffs to avoid redundant filesystem walks, volume reads, and SHA256 computations during apply phase.

type FilesetManager 

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

FilesetManager handles synchronization of filesets into Docker volumes.

func NewFilesetManager 

func NewFilesetManager(docker DockerClient, progress ProgressReporter) *FilesetManager

NewFilesetManager creates a new fileset manager.

func NewFilesetManagerWithClient 

func NewFilesetManagerWithClient(client DockerClient, progress ProgressReporter) *FilesetManager

NewFilesetManagerWithClient creates a new fileset manager with a specific client.

func (*FilesetManager) SyncFilesetsForContext 

func (fm *FilesetManager) SyncFilesetsForContext(ctx context.Context, cfg manifest.Config, contextName string, existingVolumes map[string]struct{}, execCtx *ContextExecutionContext) (map[string]struct{}, error)

SyncFilesetsForContext synchronizes filesets for a specific context into their target volumes. Returns services that need restart.

type MultiContextExecutionContext 

type MultiContextExecutionContext struct {
	// Per-context execution contexts
	ByContext map[string]*ContextExecutionContext
}

MultiContextExecutionContext contains pre-computed data for all contexts.

func NewMultiContextExecutionContext 

func NewMultiContextExecutionContext() *MultiContextExecutionContext

NewMultiContextExecutionContext creates a new empty multi-context execution context.

type Plan 

type Plan struct {
	// Resources organized by context
	ByContext map[string]*ContextPlan

	// Aggregated resource plan (for display - combines all contexts)
	Resources *ResourcePlan

	// Multi-context execution context
	ExecutionContext *MultiContextExecutionContext
}

Plan represents a structured plan with resources organized by context and type.

func (*Plan) CountChanges 

func (pln *Plan) CountChanges() (add, update, remove int)

CountChanges returns the total number of changes across all contexts.

func (*Plan) GetContextExecutionContext 

func (pln *Plan) GetContextExecutionContext(contextName string) *ContextExecutionContext

GetContextExecutionContext returns the execution context for a specific context.

func (*Plan) GetContextNames 

func (pln *Plan) GetContextNames() []string

GetContextNames returns sorted list of context names in the plan.

func (*Plan) IsEmpty 

func (pln *Plan) IsEmpty() bool

IsEmpty returns true if there are no changes in the plan.

func (*Plan) String 

func (pln *Plan) String() string

type Planner 

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

Planner creates a plan comparing desired and current docker state. For multi-context support, it uses a ClientFactory to get clients per context.

func New 

func New() *Planner

func NewWithDocker 

func NewWithDocker(client DockerClient) *Planner

func NewWithFactory 

func NewWithFactory(factory *dockercli.DefaultClientFactory) *Planner

NewWithFactory creates a planner using a client factory for multi-context support.

func (*Planner) Apply 

func (p *Planner) Apply(ctx context.Context, cfg manifest.Config) error

Apply creates missing top-level resources with labels and performs compose up, labeling containers with identifier. This method detects the current state fresh, which may duplicate work if a plan was already built. Consider using ApplyWithPlan if you have a pre-built plan to avoid redundant state detection.

func (*Planner) ApplyWithPlan added in v0.7.0 

func (p *Planner) ApplyWithPlan(ctx context.Context, cfg manifest.Config, plan *Plan) error

ApplyWithPlan applies the desired state for all contexts, optionally reusing execution context from a pre-built plan. If plan is non-nil and contains ExecutionContext, this avoids redundant Docker API calls, SOPS decryption, and compose config parsing by reusing the state detection results from BuildPlan.

func (*Planner) BuildDestroyPlan added in v0.2.0 

func (p *Planner) BuildDestroyPlan(ctx context.Context, cfg manifest.Config) (*Plan, error)

BuildDestroyPlan creates a plan to destroy all managed resources. Unlike BuildPlan, this discovers all labeled resources regardless of configuration.

func (*Planner) BuildPlan 

func (p *Planner) BuildPlan(ctx context.Context, cfg manifest.Config) (*Plan, error)

BuildPlan produces a structured plan with resources organized by context and type. For multi-context configs, it builds per-context plans and aggregates them.

func (*Planner) Destroy added in v0.2.0 

func (p *Planner) Destroy(ctx context.Context, cfg manifest.Config) error

Destroy executes the destruction of all managed resources.

func (*Planner) DestroyWithOptions 

func (p *Planner) DestroyWithOptions(ctx context.Context, cfg manifest.Config, opts CleanupOptions) error

DestroyWithOptions executes the destruction of all managed resources with explicit cleanup options.

func (*Planner) ExecuteAcrossContexts 

func (p *Planner) ExecuteAcrossContexts(ctx context.Context, cfg *manifest.Config, fn func(ctx context.Context, contextName string) error) error

ExecuteAcrossContexts runs fn for each context, either in parallel or sequentially based on the planner's parallel flag.

func (*Planner) Prune 

func (p *Planner) Prune(ctx context.Context, cfg manifest.Config) error

Prune removes unmanaged resources labeled with the identifier. It deletes volumes, networks, and containers that are labeled but not present in cfg.

func (*Planner) PruneWithPlan added in v0.7.0 

func (p *Planner) PruneWithPlan(ctx context.Context, cfg manifest.Config, plan *Plan) error

PruneWithPlan removes unmanaged resources, optionally reusing execution context from a pre-built plan.

func (*Planner) PruneWithPlanOptions 

func (p *Planner) PruneWithPlanOptions(ctx context.Context, cfg manifest.Config, plan *Plan, opts CleanupOptions) error

PruneWithPlanOptions removes unmanaged resources using explicit cleanup behavior options.

func (*Planner) WithParallel 

func (p *Planner) WithParallel(enabled bool) *Planner

WithParallel enables or disables parallel processing for plan building.

func (*Planner) WithPrinter 

func (p *Planner) WithPrinter(pr ui.Printer) *Planner

WithPrinter sets the output printer for user-facing messages during apply/prune.

func (*Planner) WithSpinner added in v0.7.0 

func (p *Planner) WithSpinner(s *ui.Spinner, prefix string) *Planner

WithSpinner sets a spinner to show current task during apply, with a prefix for dynamic labels.

type ProgressEstimator 

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

ProgressEstimator handles progress tracking for apply operations. It used to estimate total work items for progress bars, but now serves as a simple container for the progress reporter (spinner).

func NewProgressEstimator 

func NewProgressEstimator(docker DockerClient, progress ProgressReporter) *ProgressEstimator

NewProgressEstimator creates a new progress estimator.

func NewProgressEstimatorWithClient 

func NewProgressEstimatorWithClient(client DockerClient, progress ProgressReporter) *ProgressEstimator

NewProgressEstimatorWithClient creates a new progress estimator with a specific client.

func (*ProgressEstimator) EstimateAndStartProgress 

func (pe *ProgressEstimator) EstimateAndStartProgress(ctx context.Context, cfg manifest.Config, identifier string) error

EstimateAndStartProgress is a no-op for spinner-based progress tracking. Spinners don't need total work item counts, unlike progress bars. This function is kept for API compatibility but does nothing.

func (*ProgressEstimator) EstimateAndStartProgressForContext 

func (pe *ProgressEstimator) EstimateAndStartProgressForContext(ctx context.Context, cfg manifest.Config, contextName string, identifier string) error

EstimateAndStartProgressForContext is a no-op for spinner-based progress tracking. This is the context-specific version for multi-context apply.

func (*ProgressEstimator) WithExecutionContext added in v0.7.0 

func (pe *ProgressEstimator) WithExecutionContext(execCtx *ContextExecutionContext) *ProgressEstimator

WithExecutionContext sets the execution context for reusing pre-computed data.

type ProgressReporter added in v0.5.0 

type ProgressReporter interface {
	SetAction(action string)
}

ProgressReporter exposes the subset of spinner behavior needed by planner helpers. It updates the spinner label to show the current task.

type Resource added in v0.1.1 

type Resource struct {
	Type       ResourceType
	Name       string        // e.g., "traefik_config" for volumes, "linkwarden/postgres" for services
	Action     Action        // The action to be taken
	Details    string        // Optional details about the action
	Parent     string        // For nested resources (e.g., fileset name for files)
	ChangeType ui.ChangeType // Maps to UI change type for rendering
}

Resource represents a single infrastructure resource with its planned action

func NewNestedResource added in v0.1.1 

func NewNestedResource(resType ResourceType, name string, parent string, action Action, details string) Resource

NewNestedResource creates a resource that belongs to a parent (e.g., service in app, file in fileset)

func NewResource added in v0.1.1 

func NewResource(resType ResourceType, name string, action Action, details string) Resource

NewResource creates a new resource with the appropriate change type

func (Resource) FormatAction added in v0.1.1 

func (r Resource) FormatAction() string

FormatAction returns a human-readable action string

type ResourceManager 

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

ResourceManager handles creation of top-level resources like volumes and networks.

func NewResourceManager 

func NewResourceManager(docker DockerClient, progress ProgressReporter) *ResourceManager

NewResourceManager creates a new resource manager.

func NewResourceManagerWithClient 

func NewResourceManagerWithClient(client DockerClient, progress ProgressReporter) *ResourceManager

NewResourceManagerWithClient creates a new resource manager with a specific client.

func (*ResourceManager) EnsureNetworksExistForContext 

func (rm *ResourceManager) EnsureNetworksExistForContext(ctx context.Context, cfg manifest.Config, contextName string, labels map[string]string, existingNetworks map[string]struct{}) error

EnsureNetworksExistForContext creates any missing networks declared in the context config.

func (*ResourceManager) EnsureVolumesExistForContext 

func (rm *ResourceManager) EnsureVolumesExistForContext(ctx context.Context, cfg manifest.Config, contextName string, labels map[string]string) (map[string]struct{}, error)

EnsureVolumesExistForContext creates any missing volumes for a specific context. Volumes are derived from filesets targeting this context.

type ResourcePlan added in v0.1.1 

type ResourcePlan struct {
	Volumes    []Resource
	Networks   []Resource
	Stacks     map[string][]Resource // Stack name -> services
	Filesets   map[string][]Resource // Fileset name -> file changes
	Containers []Resource            // Orphaned containers to remove
}

ResourcePlan represents a structured plan with resources organized by type

func (*ResourcePlan) AllResources added in v0.1.1 

func (rp *ResourcePlan) AllResources() []Resource

AllResources returns all resources from the plan as a flat list (for testing)

func (*ResourcePlan) CountActions added in v0.1.1 

func (rp *ResourcePlan) CountActions() (create, update, delete int)

CountActions counts the number of each action type in the plan

type ResourceType added in v0.1.1 

type ResourceType string

ResourceType represents the type of infrastructure resource 

const (
	ResourceVolume    ResourceType = "volume"
	ResourceNetwork   ResourceType = "network"
	ResourceService   ResourceType = "service"
	ResourceContainer ResourceType = "container"
	ResourceFileset   ResourceType = "fileset"
	ResourceFile      ResourceType = "file" // Individual file in a fileset
)

type RestartManager 

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

RestartManager handles restarting services after fileset updates.

func NewRestartManager 

func NewRestartManager(docker DockerClient, printer ui.Printer, progress ProgressReporter) *RestartManager

NewRestartManager creates a new restart manager.

func NewRestartManagerWithClient 

func NewRestartManagerWithClient(client DockerClient, printer ui.Printer, progress ProgressReporter) *RestartManager

NewRestartManagerWithClient creates a new restart manager with a specific client.

func (*RestartManager) RestartPendingServices 

func (rm *RestartManager) RestartPendingServices(ctx context.Context, restartPending map[string]struct{}) error

RestartPendingServices restarts all services queued for restart after fileset updates.

type ServiceInfo 

type ServiceInfo struct {
	Name        string
	AppName     string
	State       ServiceState
	DesiredHash string
	RunningHash string
	Container   *dockercli.ComposePsItem // nil if not running
}

ServiceInfo contains information about a service's desired and actual state.

type ServiceState 

type ServiceState int

ServiceState represents the current state of a service relative to its desired configuration. 

const (
	// ServiceMissing indicates the service is not running
	ServiceMissing ServiceState = iota
	// ServiceRunning indicates the service is running and up-to-date
	ServiceRunning
	// ServiceDrifted indicates the service is running but configuration has drifted
	ServiceDrifted
	// ServiceIdentifierMismatch indicates the service is running but has wrong identifier label
	ServiceIdentifierMismatch
)

type ServiceStateDetector 

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

ServiceStateDetector handles detection of service state changes.

func NewServiceStateDetector 

func NewServiceStateDetector(docker DockerClient) *ServiceStateDetector

NewServiceStateDetector creates a new service state detector.

func (*ServiceStateDetector) BuildInlineEnv 

func (d *ServiceStateDetector) BuildInlineEnv(ctx context.Context, stack manifest.Stack, sopsConfig *manifest.SopsConfig) ([]string, error)

BuildInlineEnv constructs the inline environment variables for a stack, including SOPS secrets.

func (*ServiceStateDetector) DetectAllServicesState 

func (d *ServiceStateDetector) DetectAllServicesState(ctx context.Context, stackName string, stack manifest.Stack, identifier string, sopsConfig *manifest.SopsConfig) ([]ServiceInfo, error)

DetectAllServicesState analyzes the state of all services in a stack.

func (*ServiceStateDetector) DetectServiceState 

func (d *ServiceStateDetector) DetectServiceState(ctx context.Context, serviceName, stackName string, stack manifest.Stack, identifier string, inline []string, running map[string]dockercli.ComposePsItem) (ServiceInfo, error)

DetectServiceState determines the state of a single service.

func (*ServiceStateDetector) GetPlannedServices 

func (d *ServiceStateDetector) GetPlannedServices(ctx context.Context, stack manifest.Stack, inline []string) ([]string, error)

GetPlannedServices returns the list of services defined in the stack's compose files.

func (*ServiceStateDetector) GetRunningServices 

func (d *ServiceStateDetector) GetRunningServices(ctx context.Context, stack manifest.Stack, inline []string) (map[string]dockercli.ComposePsItem, error)

GetRunningServices returns a map of currently running services for the stack.

func (*ServiceStateDetector) WithParallel 

func (d *ServiceStateDetector) WithParallel(enabled bool) *ServiceStateDetector

WithParallel enables or disables parallel processing for service state detection.

type StackExecutionData added in v0.7.0 

type StackExecutionData struct {
	// Full service state detection results
	Services []ServiceInfo
	// Pre-built inline environment (with decrypted secrets)
	InlineEnv []string
	// Whether this stack needs compose up
	NeedsApply bool
}

StackExecutionData contains pre-computed data for applying a stack

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.