volume

package
v2.8.1 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: BSD-3-Clause Imports: 57 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

This section is empty.

Variables

This section is empty.

Functions

func RegisterVolumes

func RegisterVolumes(api huma.API, dockerService *docker.DockerClientService, volumeService *VolumeService, activityService *activity.ActivityService, uploadService *upload.UploadService, appCtx handlerutil.ActivityAppContext)

RegisterVolumes registers volume management routes using Huma.

Types

type BackupHasPathInput

type BackupHasPathInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
	Path          string `query:"path" doc:"Path to check"`
}

type BackupHasPathOutput

type BackupHasPathOutput struct {
	Body base.ApiResponse[BackupHasPathResponse]
}

type BackupHasPathResponse

type BackupHasPathResponse struct {
	Exists bool `json:"exists"`
}

type CreateBackupInput

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

type CreateBackupOutput

type CreateBackupOutput struct {
	Body base.ApiResponse[*VolumeBackup]
}

type CreateVolumeInput

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

type CreateVolumeOutput

type CreateVolumeOutput struct {
	Body base.ApiResponse[*volumetypes.Volume]
}

type DeleteBackupInput

type DeleteBackupInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
}

type DeleteBackupOutput

type DeleteBackupOutput struct {
	Body base.ApiResponse[base.MessageResponse]
}

type Dependencies

type Dependencies struct {
	DB       *database.DB
	Docker   *docker.DockerClientService
	Event    *event.EventService
	Settings *settings.SettingsService
	Image    *image.ImageService
	Activity *activity.ActivityService
	Config   *config.Config
	Upload   *upload.UploadService
}

Dependencies are the collaborators the volume domain needs.

type DownloadBackupInput

type DownloadBackupInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
}

type GetVolumeInput

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

type GetVolumeOutput

type GetVolumeOutput struct {
	Body base.ApiResponse[*volumetypes.Volume]
}

type GetVolumeSizesInput

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

type GetVolumeSizesOutput

type GetVolumeSizesOutput struct {
	Body base.ApiResponse[[]VolumeSizeInfo]
}

type GetVolumeUsageCountsInput

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

type GetVolumeUsageCountsOutput

type GetVolumeUsageCountsOutput struct {
	Body base.ApiResponse[VolumeUsageCountsData]
}

type GetVolumeUsageInput

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

type GetVolumeUsageOutput

type GetVolumeUsageOutput struct {
	Body base.ApiResponse[VolumeUsageResponse]
}

type GetVolumeWorkspaceFileInput

type GetVolumeWorkspaceFileInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	RelativePath  string `query:"relativePath" doc:"Path relative to the volume workspace root"`
}

type GetVolumeWorkspaceFileOutput

type GetVolumeWorkspaceFileOutput struct {
	Body base.ApiResponse[workspacetypes.FileContent]
}

type GetVolumeWorkspaceInput

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

type GetVolumeWorkspaceOutput

type GetVolumeWorkspaceOutput struct {
	Body base.ApiResponse[workspacetypes.Workspace]
}

type ListBackupFilesInput

type ListBackupFilesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
}

type ListBackupFilesOutput

type ListBackupFilesOutput struct {
	Body base.ApiResponse[[]string]
}

type ListBackupsInput

type ListBackupsInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	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"`
	Start         int    `query:"start" default:"0" doc:"Start index"`
	Limit         int    `query:"limit" default:"20" doc:"Limit"`
}

type ListBackupsOutput

type ListBackupsOutput struct {
	Body VolumeBackupPaginatedResponse
}

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[volumetypes.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(deps Dependencies) *Module

New builds the volume domain from its dependencies.

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 PruneVolumesOutput

type PruneVolumesOutput struct {
	Body base.ApiResponse[VolumePruneReportData]
}

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 RemoveVolumeOutput

type RemoveVolumeOutput struct {
	Body base.ApiResponse[base.MessageResponse]
}

type RestoreBackupFilesInput

type RestoreBackupFilesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
	Body          struct {
		Paths []string `json:"paths" doc:"Paths to restore from backup"`
	}
}

type RestoreBackupFilesOutput

type RestoreBackupFilesOutput struct {
	Body base.ApiResponse[base.MessageResponse]
}

type RestoreBackupInput

type RestoreBackupInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	BackupID      string `path:"backupId" doc:"Backup ID"`
}

type RestoreBackupOutput

type RestoreBackupOutput struct {
	Body base.ApiResponse[base.MessageResponse]
}

type UpdateVolumeWorkspaceInput

type UpdateVolumeWorkspaceInput struct {
	EnvironmentID string         `path:"id" doc:"Environment ID"`
	VolumeName    string         `path:"volumeName" doc:"Volume name"`
	RawBody       multipart.Form `contentType:"multipart/form-data"`
}

type UpdateVolumeWorkspaceOutput

type UpdateVolumeWorkspaceOutput struct {
	Body base.ApiResponse[workspacetypes.Workspace]
}

type UploadAndRestoreInput

type UploadAndRestoreInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	VolumeName    string `path:"volumeName" doc:"Volume name"`
	Body          uploadtypes.ConsumeRequest
}

type UploadAndRestoreOutput

type UploadAndRestoreOutput struct {
	Body base.ApiResponse[base.MessageResponse]
}

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"`
	ActivityID *string   `json:"activityId,omitempty" gorm:"-"`
}

func (*VolumeBackup) TableName added in v2.8.1

func (*VolumeBackup) TableName() string

func (*VolumeBackup) ToDTO added in v2.8.1

func (b *VolumeBackup) ToDTO() volume.BackupEntry

type VolumeBackupPaginatedResponse

type VolumeBackupPaginatedResponse struct {
	Success    bool                    `json:"success"`
	Data       []VolumeBackup          `json:"data"`
	Pagination base.PaginationResponse `json:"pagination"`
	Warnings   []string                `json:"warnings,omitempty"`
}

type VolumeHandler

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

VolumeHandler provides Huma-based volume management endpoints.

func (*VolumeHandler) BackupHasPath

func (h *VolumeHandler) BackupHasPath(ctx context.Context, input *BackupHasPathInput) (*BackupHasPathOutput, error)

func (*VolumeHandler) CreateBackup

func (h *VolumeHandler) CreateBackup(ctx context.Context, input *CreateBackupInput) (*CreateBackupOutput, error)

func (*VolumeHandler) CreateVolume

func (h *VolumeHandler) CreateVolume(ctx context.Context, input *CreateVolumeInput) (*CreateVolumeOutput, error)

CreateVolume creates a new Docker volume.

func (*VolumeHandler) DeleteBackup

func (h *VolumeHandler) DeleteBackup(ctx context.Context, input *DeleteBackupInput) (*DeleteBackupOutput, error)

func (*VolumeHandler) DownloadBackup

func (h *VolumeHandler) DownloadBackup(ctx context.Context, input *DownloadBackupInput) (*huma.StreamResponse, error)

func (*VolumeHandler) DownloadVolumeWorkspaceFile

func (h *VolumeHandler) DownloadVolumeWorkspaceFile(ctx context.Context, input *GetVolumeWorkspaceFileInput) (*huma.StreamResponse, error)

func (*VolumeHandler) GetVolume

func (h *VolumeHandler) GetVolume(ctx context.Context, input *GetVolumeInput) (*GetVolumeOutput, error)

GetVolume returns a volume by name.

func (*VolumeHandler) GetVolumeSizes

func (h *VolumeHandler) GetVolumeSizes(ctx context.Context, input *GetVolumeSizesInput) (*GetVolumeSizesOutput, 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) (*GetVolumeUsageOutput, error)

GetVolumeUsage returns containers using a specific volume.

func (*VolumeHandler) GetVolumeUsageCounts

GetVolumeUsageCounts returns counts of volumes by usage status.

func (*VolumeHandler) GetVolumeWorkspace

func (h *VolumeHandler) GetVolumeWorkspace(ctx context.Context, input *GetVolumeWorkspaceInput) (*GetVolumeWorkspaceOutput, error)

func (*VolumeHandler) GetVolumeWorkspaceFile

func (*VolumeHandler) ListBackupFiles

func (h *VolumeHandler) ListBackupFiles(ctx context.Context, input *ListBackupFilesInput) (*ListBackupFilesOutput, error)

func (*VolumeHandler) ListBackups

func (h *VolumeHandler) ListBackups(ctx context.Context, input *ListBackupsInput) (*ListBackupsOutput, error)

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) (*PruneVolumesOutput, error)

PruneVolumes removes all unused Docker volumes.

func (*VolumeHandler) RemoveVolume

func (h *VolumeHandler) RemoveVolume(ctx context.Context, input *RemoveVolumeInput) (*RemoveVolumeOutput, error)

RemoveVolume removes a Docker volume.

func (*VolumeHandler) RestoreBackup

func (h *VolumeHandler) RestoreBackup(ctx context.Context, input *RestoreBackupInput) (*RestoreBackupOutput, error)

func (*VolumeHandler) RestoreBackupFiles

func (h *VolumeHandler) RestoreBackupFiles(ctx context.Context, input *RestoreBackupFilesInput) (*RestoreBackupFilesOutput, error)

func (*VolumeHandler) UpdateVolumeWorkspace

func (*VolumeHandler) UploadAndRestore

func (h *VolumeHandler) UploadAndRestore(ctx context.Context, input *UploadAndRestoreInput) (*UploadAndRestoreOutput, error)

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 *docker.DockerClientService, eventService *event.EventService, settingsService *settings.SettingsService, imageService *image.ImageService, cfg *config.Config) *VolumeService

func (*VolumeService) BackupHasPath

func (s *VolumeService) BackupHasPath(ctx context.Context, backupID string, filePath string) (bool, error)

func (*VolumeService) BackupMountWarning

func (s *VolumeService) BackupMountWarning(ctx context.Context) string

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(volumes []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) CreateBackup

func (s *VolumeService) CreateBackup(ctx context.Context, volumeName string, user common.User) (*VolumeBackup, error)

func (*VolumeService) CreateVolume

func (s *VolumeService) CreateVolume(ctx context.Context, options client.VolumeCreateOptions, user common.User) (*volumetypes.Volume, error)

func (*VolumeService) DeleteBackup

func (s *VolumeService) DeleteBackup(ctx context.Context, backupID string, user *common.User) error

func (*VolumeService) DeleteVolume

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

func (*VolumeService) DownloadBackup

func (s *VolumeService) DownloadBackup(ctx context.Context, backupID string, user *common.User) (io.ReadCloser, int64, error)

func (*VolumeService) DownloadVolumeWorkspaceFile

func (s *VolumeService) DownloadVolumeWorkspaceFile(ctx context.Context, volumeName, relativePath string) (io.ReadCloser, int64, 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) GetVolumeWorkspace

func (s *VolumeService) GetVolumeWorkspace(ctx context.Context, volumeName string) (*workspacetypes.Workspace, error)

func (*VolumeService) GetVolumeWorkspaceFile

func (s *VolumeService) GetVolumeWorkspaceFile(ctx context.Context, volumeName, relativePath string) (*workspacetypes.FileContent, error)

func (*VolumeService) ListBackupFiles

func (s *VolumeService) ListBackupFiles(ctx context.Context, backupID string) ([]string, error)

func (*VolumeService) ListBackups

func (s *VolumeService) ListBackups(ctx context.Context, volumeName string) ([]VolumeBackup, error)

func (*VolumeService) ListBackupsPaginated

func (s *VolumeService) ListBackupsPaginated(ctx context.Context, volumeName string, params pagination.QueryParams) ([]VolumeBackup, pagination.Response, error)

func (*VolumeService) ListVolumesPaginated

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

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

func (s *VolumeService) RestoreBackup(ctx context.Context, volumeName, backupID string, user common.User) error

func (*VolumeService) RestoreBackupFiles

func (s *VolumeService) RestoreBackupFiles(ctx context.Context, volumeName, backupID string, paths []string, user common.User) error

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.

func (*VolumeService) UpdateVolumeWorkspace

func (s *VolumeService) UpdateVolumeWorkspace(ctx context.Context, volumeName string, manifest volumetypes.WorkspaceUpdateManifest, uploads map[int][]byte, user common.User) (*workspacetypes.Workspace, error)

func (*VolumeService) UploadAndRestore

func (s *VolumeService) UploadAndRestore(ctx context.Context, volumeName string, archive io.ReadSeeker, filename string, user common.User) error

type VolumeSizeData

type VolumeSizeData struct {
	Size     int64
	RefCount int64
}

VolumeSizeData holds size information for a volume.

type VolumeSizeInfo

type VolumeSizeInfo struct {
	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.

Jump to

Keyboard shortcuts

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