planner

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2025 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 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 struct {
	// Per-stack execution data
	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{}
}

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

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 (*FilesetManager) SyncFilesets 

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

SyncFilesets synchronizes all filesets into their target volumes and returns services that need restart. If execCtx is provided with cached fileset data, it reuses the pre-computed indexes and diffs to avoid redundant filesystem walks, volume reads, and SHA256 computations.

type Plan 

type Plan struct {
	Resources        *ResourcePlan
	ExecutionContext *ExecutionContext
}

Plan represents a structured plan with resources organized by type

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.

func New 

func New() *Planner

func NewWithDocker 

func NewWithDocker(client DockerClient) *Planner

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, 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 type.

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) 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) 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 (*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) WithExecutionContext added in v0.7.0 

func (pe *ProgressEstimator) WithExecutionContext(execCtx *ExecutionContext) *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 (*ResourceManager) EnsureNetworksExist 

func (rm *ResourceManager) EnsureNetworksExist(ctx context.Context, cfg manifest.Config, labels map[string]string, execCtx *ExecutionContext) error

EnsureNetworksExist creates any missing networks defined in the manifest. If execCtx is provided with cached network list, it reuses it to avoid redundant ListNetworks call.

func (*ResourceManager) EnsureVolumesExist 

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

EnsureVolumesExist creates any missing volumes derived from filesets and explicit volume definitions.

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 (*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

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.