volume

package
v2.17.3 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: BSD-3-Clause Imports: 63 Imported by: 0

Documentation

Overview

Package volume owns Docker volumes: CRUD and pruning, the helper-container file browser, backup and restore, and the HTTP surface for all of it.

Index

Constants

Variables

View Source
var ErrVolumeBackupAlreadyRunning = errors.New("a backup is already running for this volume")

Functions

func RegisterVolumes

func RegisterVolumes(
	api huma.API,
	dockerService *docker.DockerClientService,
	volumeService *VolumeService,
	activityService *activity.ActivityService,
	environmentService *environment.EnvironmentService,
	appCtx handlerutil.ActivityAppContext,
)

RegisterVolumes registers volume management routes using Huma.

Types

type CreateVolumeInput

type CreateVolumeInput struct {
	EnvironmentID string        `path:"id" doc:"Environment ID"`
	Body          volume.Create `doc:"Volume creation data"`
}

type GetVolumeInput

type GetVolumeInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
}

type GetVolumeSizesInput

type GetVolumeSizesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type GetVolumeUsageCountsInput

type GetVolumeUsageCountsInput struct {
	EnvironmentID   string `path:"id" doc:"Environment ID"`
	IncludeInternal bool   `query:"includeInternal" default:"false" doc:"Include internal volumes"`
}

type GetVolumeUsageInput

type GetVolumeUsageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
}

type ListVolumesInput

type ListVolumesInput struct {
	EnvironmentID   string `path:"id" doc:"Environment ID"`
	Search          string `query:"search" doc:"Search query"`
	Sort            string `query:"sort" doc:"Column to sort by"`
	Order           string `query:"order" default:"asc" doc:"Sort direction (asc or desc)"`
	Start           int    `query:"start" default:"0" doc:"Start index for pagination"`
	Limit           int    `query:"limit" default:"20" doc:"Number of items per page"`
	InUse           string `query:"inUse" doc:"Filter by in-use status (true/false)"`
	IncludeInternal bool   `query:"includeInternal" default:"false" doc:"Include internal volumes"`
}

type ListVolumesOutput

type ListVolumesOutput struct {
	Body base.PaginatedWithCounts[volume.Volume, VolumeUsageCountsData]
}

type Module

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

Module wires the volume domain and mounts its routes.

func New

func New(
	service *VolumeService,
	dockerService *docker.DockerClientService,
	activityService *activity.ActivityService,
	environmentService *environment.EnvironmentService,
	uploadService *upload.UploadService,
) *Module

New wires volume routes around an existing service.

func (*Module) RegisterRoutes

func (m *Module) RegisterRoutes(api huma.API, appCtx handlerutil.ActivityAppContext)

RegisterRoutes mounts the volume endpoints. A nil module still registers, so OpenAPI spec generation can discover the routes without a service graph.

func (*Module) Service

func (m *Module) Service() *VolumeService

Service exposes the volume service to collaborators that use it directly, such as the helper-container reaper job.

type PruneVolumesInput

type PruneVolumesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type RemoveVolumeInput

type RemoveVolumeInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	Force         bool   `query:"force" doc:"Force removal"`
}

type RenameVolumeInput added in v2.9.0

type RenameVolumeInput struct {
	EnvironmentID string        `path:"id" doc:"Environment ID"`
	VolumeName    string        `path:"volumeName" doc:"Current volume name"`
	Body          volume.Rename `doc:"Volume rename data"`
}

type VolumeBackup added in v2.8.1

type VolumeBackup struct {
	database.BaseModel

	VolumeName        string                   `json:"volumeName" gorm:"column:volume_name;index"`
	Size              int64                    `json:"size" gorm:"column:size"`
	CreatedAt         time.Time                `json:"createdAt" gorm:"column:created_at"`
	Status            VolumeBackupStatus       `json:"status" gorm:"column:status;type:text;not null;default:succeeded"`
	Trigger           VolumeBackupTrigger      `json:"trigger" gorm:"column:trigger;type:text;not null;default:manual"`
	Destination       volume.BackupDestination `json:"destination" gorm:"column:destination;type:text;not null;default:local"`
	Format            VolumeBackupFormat       `json:"format" gorm:"column:format;type:text;not null;default:archive"`
	LocalSnapshotID   string                   `json:"localSnapshotId,omitempty" gorm:"column:local_snapshot_id;type:text"`
	RemoteSnapshotID  string                   `json:"remoteSnapshotId,omitempty" gorm:"column:remote_snapshot_id;type:text"`
	S3DestinationID   string                   `json:"s3DestinationId,omitempty" gorm:"column:s3_destination_id;type:text;index"`
	RemoteInstanceID  string                   `json:"remoteInstanceId,omitempty" gorm:"column:remote_instance_id;type:text"`
	S3DestinationName string                   `json:"s3DestinationName,omitempty" gorm:"-"`
	PolicyID          string                   `json:"policyId,omitempty" gorm:"column:policy_id;type:text;index"`
	Error             string                   `json:"error,omitempty" gorm:"column:error;type:text"`
	ActivityID        *string                  `json:"activityId,omitempty" gorm:"-"`
	Type              backup.ManagementType    `json:"type" gorm:"-"`
	RemoteAvailable   *bool                    `json:"remoteAvailable,omitempty" gorm:"-"`
}

func (*VolumeBackup) TableName added in v2.8.1

func (*VolumeBackup) TableName() string

type VolumeBackupFormat added in v2.9.0

type VolumeBackupFormat string

type VolumeBackupStatus added in v2.9.0

type VolumeBackupStatus string

type VolumeBackupTrigger added in v2.9.0

type VolumeBackupTrigger string

type VolumeHandler

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

VolumeHandler provides Huma-based volume management endpoints.

func (*VolumeHandler) CreateVolume

func (h *VolumeHandler) CreateVolume(ctx context.Context, input *CreateVolumeInput) (*handlerutil.Out[*volume.Volume], error)

CreateVolume creates a new Docker volume.

func (*VolumeHandler) GetVolume

func (h *VolumeHandler) GetVolume(ctx context.Context, input *GetVolumeInput) (*handlerutil.Out[*volume.Volume], error)

GetVolume returns a volume by name.

func (*VolumeHandler) GetVolumeSizes

func (h *VolumeHandler) GetVolumeSizes(ctx context.Context, input *GetVolumeSizesInput) (*handlerutil.Out[[]VolumeSizeInfo], error)

GetVolumeSizes returns disk usage sizes for all volumes. This is a slow operation as it requires calculating disk usage.

func (*VolumeHandler) GetVolumeUsage

GetVolumeUsage returns containers using a specific volume.

func (*VolumeHandler) GetVolumeUsageCounts

GetVolumeUsageCounts returns counts of volumes by usage status.

func (*VolumeHandler) ListVolumes

func (h *VolumeHandler) ListVolumes(ctx context.Context, input *ListVolumesInput) (*ListVolumesOutput, error)

ListVolumes returns a paginated list of volumes.

func (*VolumeHandler) PruneVolumes

PruneVolumes removes all unused Docker volumes.

func (*VolumeHandler) RemoveVolume

RemoveVolume removes a Docker volume.

func (*VolumeHandler) RenameVolume added in v2.9.0

func (h *VolumeHandler) RenameVolume(ctx context.Context, input *RenameVolumeInput) (*handlerutil.Out[*volume.Volume], error)

RenameVolume renames an unused Docker volume.

type VolumePruneReportData

type VolumePruneReportData struct {
	VolumesDeleted []string `json:"volumesDeleted,omitempty"`
	SpaceReclaimed uint64   `json:"spaceReclaimed"`
	ActivityID     *string  `json:"activityId,omitempty"`
}

VolumePruneReportData represents the result of a volume prune operation. This is a local type to avoid schema naming conflicts with image.PruneReport.

type VolumeService

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

func NewVolumeService

func NewVolumeService(
	db *database.DB,
	dockerService *dockerInternal.DockerClientService,
	eventService *event.EventService,
	settingsService *settings.SettingsService,
	containerService *containerdomain.ContainerService,
	imageService *image.ImageService,
	engine *backup.Engine,
	s3Destinations *s3.S3DestinationService,
	cfg *config.Config,
	recoveryKeys *backup.RecoveryKeyStore,
) *VolumeService

func (*VolumeService) AggregateVolumeSizes added in v2.16.1

func (s *VolumeService) AggregateVolumeSizes(ctx context.Context) (base.ApiResponse[[]VolumeSizeInfo], error)

func (*VolumeService) AggregateVolumes added in v2.16.1

func (*VolumeService) BackupStorageMount added in v2.9.0

func (s *VolumeService) BackupStorageMount(ctx context.Context, dockerClient *client.Client, target string, readOnly bool) (mount.Mount, error)

BackupStorageMount resolves the repository mount shared with system-backup operations.

func (*VolumeService) CleanupHelperContainers

func (s *VolumeService) CleanupHelperContainers(ctx context.Context)

func (*VolumeService) CleanupOrphanedVolumeHelpers

func (s *VolumeService) CleanupOrphanedVolumeHelpers(ctx context.Context) (int, error)

func (*VolumeService) CountUsageFromSnapshot

func (s *VolumeService) CountUsageFromSnapshot(dockerVolumes []volume.Volume, containers []container.Summary) volumetypes.UsageCounts

CountUsageFromSnapshot derives usage counts from fetched volumes and containers with ListVolumesPaginated's semantics (internal volumes excluded, mounted means in use) so dashboard tiles match the volumes page.

func (*VolumeService) CreateSystemManagedBackup added in v2.10.0

func (s *VolumeService) CreateSystemManagedBackup(
	ctx context.Context,
	volumeName string,
	user usertypes.Actor,
	trigger VolumeBackupTrigger,
	policyID string,
	policy backuptypes.UpdateBackupPolicy,
) (*VolumeBackup, error)

CreateSystemManagedBackup runs the existing volume backup workflow with a transient centralized policy.

func (*VolumeService) CreateVolume

func (*VolumeService) DeleteVolume

func (s *VolumeService) DeleteVolume(ctx context.Context, name string, force bool, user usertypes.Actor) error

func (*VolumeService) GetVolumeByName

func (s *VolumeService) GetVolumeByName(ctx context.Context, name string) (*volumetypes.Volume, error)

func (*VolumeService) GetVolumeSizes

func (s *VolumeService) GetVolumeSizes(ctx context.Context) (map[string]VolumeSizeData, error)

GetVolumeSizes returns disk usage data for all volumes. This is a slow operation as it calls Docker's DiskUsage API.

func (*VolumeService) GetVolumeUsage

func (s *VolumeService) GetVolumeUsage(ctx context.Context, name string) (bool, []string, error)

func (*VolumeService) HasEnabledBackupPolicy added in v2.10.0

func (s *VolumeService) HasEnabledBackupPolicy(ctx context.Context, volumeName string) (bool, error)

HasEnabledBackupPolicy reports whether a volume-level schedule takes precedence over centralized backups.

func (*VolumeService) IsBackupVolume added in v2.16.0

func (s *VolumeService) IsBackupVolume(name string) bool

IsBackupVolume reports whether name is the volume that stores this environment's backups.

func (*VolumeService) ListBackupVolumeOptions added in v2.10.0

func (s *VolumeService) ListBackupVolumeOptions(ctx context.Context) ([]backuptypes.SystemVolumeBackupOption, error)

ListBackupVolumeOptions returns the current non-internal volumes used by centralized backup selection.

func (*VolumeService) ListVolumesPaginated

func (s *VolumeService) ListVolumesPaginated(ctx context.Context, params pagination.QueryParams, includeInternal bool) ([]volumetypes.Volume, pagination.Response, volumetypes.UsageCounts, error)

func (*VolumeService) MigrateRepositoryPasswords added in v2.12.0

func (s *VolumeService) MigrateRepositoryPasswords(ctx context.Context, previousKey, newKey string) error

MigrateRepositoryPasswords re-keys this instance's own volume backup repositories to the recovery key; other instances re-key their own roots.

func (*VolumeService) PruneLocalBackupRepository added in v2.16.0

func (s *VolumeService) PruneLocalBackupRepository(ctx context.Context) error

PruneLocalBackupRepository frees the space of deleted local volume backups.

func (*VolumeService) PruneVolumes

func (s *VolumeService) PruneVolumes(ctx context.Context) (*volumetypes.PruneReport, error)

func (*VolumeService) ReapIdleHelpers

func (s *VolumeService) ReapIdleHelpers(ctx context.Context, idleTimeout time.Duration) (int, error)

ReapIdleHelpers removes tracked helpers idle for idleTimeout; untracked orphans are left to the startup sweep.

func (*VolumeService) ReconcileBackup added in v2.15.0

func (s *VolumeService) ReconcileBackup(ctx context.Context, previous scheduler.Run, volumeName string) (scheduler.Outcome, error)

func (*VolumeService) ReconcileInterruptedBackups added in v2.10.2

func (s *VolumeService) ReconcileInterruptedBackups(ctx context.Context, protectedIDs ...string) error

ReconcileInterruptedBackups fails backups left running by the previous process and watches the manual backups that saved workflows resume.

func (*VolumeService) RegisterBackupJobsOnStartup added in v2.9.0

func (s *VolumeService) RegisterBackupJobsOnStartup(ctx context.Context)

func (*VolumeService) RegisterWorkflows added in v2.16.0

func (s *VolumeService) RegisterWorkflows(engine *flow.Engine) error

ReconcileInterruptedBackups runs before this process can accept backup work. RegisterWorkflows defines the backup workflows while the host is still unstarted.

func (*VolumeService) RenameVolume added in v2.9.0

func (s *VolumeService) RenameVolume(ctx context.Context, oldName, newName string, user usertypes.Actor) (*volumetypes.Volume, error)

RenameVolume copies an unused volume to a new name and removes the source.

func (*VolumeService) SetScheduler added in v2.9.0

func (s *VolumeService) SetScheduler(ctx context.Context, dynamicScheduler scheduler.DynamicScheduler, admissionGate *runs.Admission) error

SetScheduler injects the dynamic scheduler and admission gate for per-policy backup jobs. Agent mode passes them too: agents run their own volume backups.

func (*VolumeService) StopHelper

func (s *VolumeService) StopHelper(ctx context.Context, volumeName string) error

StopHelper removes the reused helper for a single volume; it is a no-op when none exists.

type VolumeSizeData

type VolumeSizeData struct {
	Size     int64
	RefCount int64
}

VolumeSizeData holds size information for a volume.

type VolumeSizeInfo

type VolumeSizeInfo struct {
	base.EnvironmentTag

	Name     string `json:"name"`
	Size     int64  `json:"size"`
	RefCount int64  `json:"refCount"`
}

VolumeSizeInfo represents size information for a single volume.

type VolumeUsageCountsData

type VolumeUsageCountsData struct {
	Inuse  int `json:"inuse"`
	Unused int `json:"unused"`
	Total  int `json:"total"`
}

VolumeUsageCountsData represents the counts of volumes by usage status. This is a local type to avoid schema naming conflicts with image.UsageCounts.

type VolumeUsageResponse

type VolumeUsageResponse struct {
	InUse      bool     `json:"inUse"`
	Containers []string `json:"containers"`
}

VolumeUsageResponse represents volume usage information.

Directories

Path Synopsis
children

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL