Help us shape the future of Go! Take the 2026 Go Developer Survey

volume

package
v2.16.1 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2026 License: BSD-3-Clause Imports: 62 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

View Source 
const (
	VolumeBackupStatusRunning   VolumeBackupStatus = backup.VolumeBackupStatusRunning
	VolumeBackupStatusSucceeded VolumeBackupStatus = backup.VolumeBackupStatusSucceeded
	VolumeBackupStatusFailed    VolumeBackupStatus = backup.VolumeBackupStatusFailed

	VolumeBackupTriggerManual    VolumeBackupTrigger = backup.VolumeBackupTriggerManual
	VolumeBackupTriggerScheduled VolumeBackupTrigger = backup.VolumeBackupTriggerScheduled
	VolumeBackupTriggerSafety    VolumeBackupTrigger = backup.VolumeBackupTriggerSafety

	VolumeBackupFormatArchive VolumeBackupFormat = VolumeBackupFormat(volume.BackupFormatArchive)
	VolumeBackupFormatRustic  VolumeBackupFormat = VolumeBackupFormat(volume.BackupFormatRustic)
)

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 

func (h *VolumeHandler) GetVolumeUsage(ctx context.Context, input *GetVolumeUsageInput) (*handlerutil.Out[VolumeUsageResponse], error)

GetVolumeUsage returns containers using a specific volume.

func (*VolumeHandler) GetVolumeUsageCounts 

func (h *VolumeHandler) GetVolumeUsageCounts(ctx context.Context, input *GetVolumeUsageCountsInput) (*handlerutil.Out[VolumeUsageCountsData], error)

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 

func (h *VolumeHandler) PruneVolumes(ctx context.Context, input *PruneVolumesInput) (*handlerutil.Out[VolumePruneReportData], error)

PruneVolumes removes all unused Docker volumes.

func (*VolumeHandler) RemoveVolume 

func (h *VolumeHandler) RemoveVolume(ctx context.Context, input *RemoveVolumeInput) (*handlerutil.Out[base.MessageResponse], error)

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 (s *VolumeService) AggregateVolumes(ctx context.Context, params pagination.QueryParams) (base.PaginatedWithCounts[volumetypes.Volume, VolumeUsageCountsData], error)

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 volume usage counts from an already-fetched volume and container listing. It mirrors the semantics of ListVolumesPaginated — internal volumes are excluded and a volume counts as in use when any container mounts it — so dashboard tile numbers agree with 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 (s *VolumeService) CreateVolume(ctx context.Context, options client.VolumeCreateOptions, user usertypes.Actor) (*volumetypes.Volume, error)

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) 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) PruneVolumesWithOptions 

func (s *VolumeService) PruneVolumesWithOptions(ctx context.Context, all bool) (*volumetypes.PruneReport, error)

func (*VolumeService) ReapIdleHelpers 

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

ReapIdleHelpers removes reused helper containers that have not serviced a request within idleTimeout. It is map-driven (orphaned helpers not tracked in helperByVolume are left to the startup orphan sweep). Entries are removed from the map before the container is removed, so a concurrent request simply gets a cache miss and re-creates a fresh helper.

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, if one exists. It is idempotent: stopping a volume with no active helper returns nil.

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.

Source Files

View all Source files

Directories

Path Synopsis
children
backup
backup/children/browser
backup/children/policies
backup/children/restore
workspace

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.