storage

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package storage manages persistent (Docker) volumes owned by workspaces.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrDriverOptKey is returned for a driver option outside type/o/device. The local driver takes
	// only those three; anything else is either ignored or a way to reach a mount feature Miabi has
	// not reviewed.
	ErrDriverOptKey = errors.New("shared volumes accept only the 'device' and 'o' driver options")
	// ErrDriverMountFlag is returned when the `o` list carries a mount FLAG rather than a data
	// option. This is the one that matters: the kernel ignores the filesystem type when MS_BIND is
	// set, so `o=bind` with `device=/` bind-mounts the host's root filesystem into the volume
	// whatever `type` says. Verified against a live daemon, 2026-09-18.
	ErrDriverMountFlag = errors.New("shared volumes may not set mount flags such as bind, remount or a propagation mode")
	// ErrDriverOptValue is returned for an unknown or malformed entry in the `o` list.
	ErrDriverOptValue = errors.New("unsupported mount option for this share type")
	// ErrDriverDeviceForm is returned when `device` is not a remote export or share.
	ErrDriverDeviceForm = errors.New("device must be an NFS export (host:/export) or a CIFS share (//host/share), never a local path")
)

Errors a rejected shared-storage option set returns.

View Source
var (
	ErrVolumeShrink     = errors.New("a volume's capacity can only be expanded")
	ErrVolumeBelowUsage = errors.New("declared size is below the volume's measured usage")
)

ErrVolumeShrink refuses lowering a volume's declared capacity; ErrVolumeBelowUsage refuses a capacity smaller than what the volume already holds on disk.

View Source
var ErrDriverDeviceRequired = errors.New("shared volume requires a 'device' driver option (the NFS export or CIFS share)")

ErrDriverDeviceRequired is returned when a shared-storage volume (nfs/cifs) is created without a backing device (the export/share path).

View Source
var ErrFileNotFound = errors.New("file not found in volume")

ErrFileNotFound is returned when a requested path is absent from the volume.

View Source
var ErrHostMountNotPrivileged = errors.New("host-path volumes require a privileged workspace")

ErrHostMountNotPrivileged is returned when a non-privileged workspace tries to create a host-path volume.

View Source
var ErrHostPathRequired = errors.New("host-path volume requires a 'path' driver option (an absolute path under " + hostmount.CustomHostRoot + "/)")

ErrHostPathRequired is returned when a "host" driver volume is created without a host path.

View Source
var ErrHostVolumeImmovable = errors.New("a host-path volume cannot be moved: its data is an operator-managed directory on the node")

ErrHostVolumeImmovable refuses to move a host-path volume: its data is a directory on the node that Miabi does not own.

View Source
var ErrInvalidDriver = errors.New("invalid volume driver")

ErrInvalidDriver is returned for an unknown volume driver.

View Source
var ErrVolumeInUse = errors.New("volume is in use by one or more applications; detach it first")

ErrVolumeInUse is returned when deleting a volume still mounted by an app.

View Source
var ErrVolumeOwned = errors.New("volume is owned by another resource")

ErrVolumeOwned is returned when deleting a volume whose owning resource (the app/database/stack it backs) still exists. Wrapped with a message naming the owner so callers can guide the user to delete it there instead.

Functions

func SharedDriverOptsValid added in v1.10.2

func SharedDriverOptsValid(opts map[string]string) error

SharedDriverOptsValid re-checks a stored option set, for the deploy path and the boot audit. A volume created before the allow-list existed must not be able to mount just because its row survived.

Types

type CreateInput added in v1.10.2

type CreateInput struct {
	Name      string
	SizeBytes int64 // declared capacity (0 = unspecified/unlimited)
	// Driver is "" or "local" for a node-local volume (rwo), "nfs"/"cifs" for shared storage (rwx)
	// a replicated service can mount across nodes, or "host" for a bind to an operator path.
	Driver string
	// DriverOpts are the backend mount options, encrypted at rest since they may carry a CIFS
	// password.
	DriverOpts map[string]string
	// StorageClass names the admin-registered directory the volume is created under. Empty resolves
	// through the workspace's plan and then the node's default class.
	StorageClass string
	Meta         models.Metadata
	Annotations  models.Metadata
}

CreateInput is the full create surface for a managed volume.

type ImageResolver

type ImageResolver interface {
	Ref(key string) string
}

ImageResolver resolves a deployment-config catalog key to an image ref.

type MoveTarget added in v1.10.9

type MoveTarget struct {
	StorageClass string `json:"storage_class"`
	Mountpoint   string `json:"mountpoint"`
	CreatedAt    string `json:"created_at"`
}

MoveTarget is the copy of a volume prepared on another node.

type NodeDocker

type NodeDocker interface {
	For(serverID uint) (docker.Client, error)
	LocalID() uint
}

NodeDocker resolves the Docker client for a node id (0 = local). Implemented by nodes.Clients; an interface here keeps services decoupled from the agent machinery.

type NodeGuard

type NodeGuard interface {
	Placeable(serverID uint) error
}

NodeGuard validates that a node can accept a new placement (exists, not cordoned). Implemented by the node service; injected after construction.

type OwnerExister

type OwnerExister func(kind string, id, workspaceID uint) bool

OwnerExister reports whether an owning resource of the given kind and id still exists in the workspace. Wired by the composition root so the service can refuse to orphan a resource whose owner is still around, without depending on the app, database or stack repositories directly.

type ServerInfo

type ServerInfo interface {
	Get(id uint) (*models.Server, error)
}

ServerInfo resolves a node's display metadata by id (implemented by the node service; optional).

type Service

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

func (*Service) AuditSharedVolumes added in v1.10.2

func (s *Service) AuditSharedVolumes()

AuditSharedVolumes re-checks every stored shared volume against the allow-list and reports the ones that would be refused. Volumes created before the allow-list existed keep their options encrypted on the row; the deploy path already refuses to mount them, but an operator should learn which ones need recreating from a log line at boot, not from a deploy that quietly lost its data.

func (*Service) ClassAvailable added in v1.10.9

func (s *Service) ClassAvailable(serverID uint, name string) bool

ClassAvailable reports whether a node registers a storage class, so a plan can say where a volume lands.

func (*Service) Create

func (s *Service) Create(ctx context.Context, workspaceID, serverID uint, name string, sizeBytes int64, meta, annotations models.Metadata) (*models.Volume, error)

Create provisions a managed Docker volume on the given node (serverID 0 = local). sizeBytes is the declared capacity (0 = unspecified/unlimited).

func (*Service) CreateOn added in v1.10.2

func (s *Service) CreateOn(ctx context.Context, workspaceID, serverID uint, in CreateInput) (*models.Volume, error)

CreateOn creates a managed volume on a node, under the storage class the workspace resolves to.

func (*Service) CreateWith

func (s *Service) CreateWith(ctx context.Context, workspaceID, serverID uint, name string, sizeBytes int64, driver string, driverOpts map[string]string, meta, annotations models.Metadata) (*models.Volume, error)

CreateWith creates a managed volume with an explicit driver and driver options.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, v *models.Volume) error

Delete removes the volume record and the underlying Docker volume. Refuses when any application still mounts it (guards against deleting live data) or when it still backs an owning app/database/stack.

func (*Service) DeleteFile

func (s *Service) DeleteFile(ctx context.Context, v *models.Volume, rel string) error

DeleteFile removes a file or directory (recursively) from a volume.

func (*Service) Detail

func (s *Service) Detail(ctx context.Context, workspaceID, id uint) (*VolumeDetail, error)

Detail returns a volume with its live Docker driver/mountpoint and the list of applications that currently mount it.

func (*Service) DownloadFile

func (s *Service) DownloadFile(ctx context.Context, v *models.Volume, rel string) (io.ReadCloser, int64, error)

DownloadFile streams a single file out of a volume.

func (*Service) DropCopy added in v1.10.9

func (s *Service) DropCopy(ctx context.Context, serverID uint, dockerName, className string) error

DropCopy removes a volume's copy from a node that no longer holds it: the source after a move is finalized, or the target after one is rolled back. Best-effort on the class directory, like Delete.

func (*Service) Get

func (s *Service) Get(workspaceID, id uint) (*models.Volume, error)

func (*Service) IDByUID

func (s *Service) IDByUID(uid string) (uint, error)

IDByUID resolves a volume's portable uid to its numeric id.

func (*Service) List

func (s *Service) List(workspaceID uint) ([]models.Volume, error)

func (*Service) ListFiles

func (s *Service) ListFiles(ctx context.Context, v *models.Volume) ([]VolumeFile, error)

ListFiles returns the files and directories stored in a volume by inspecting it with a short-lived helper container.

func (*Service) MeasureUsage

func (s *Service) MeasureUsage(ctx context.Context) error

MeasureUsage is the storage sweep: one `docker system df` per node (never per read), joined back to Volume rows by Docker name. Best-effort — an unreachable node keeps its prior measurement and the sweep always returns nil for cron.

func (*Service) PlaceVolume added in v1.10.4

func (s *Service) PlaceVolume(ctx context.Context, workspaceID, serverID uint, requested, dockerName string) (className, devicePath string, err error)

PlaceVolume resolves which operator-registered disk a volume should land on and prepares its directory there, returning the class name to record and the host path to bind. It is how a resource that manages its own Docker volume — a database's data volume — gets the same placement a workspace volume gets, including the plan's storage-class binding.

An empty device path means the default class: Docker's own data root, nothing to prepare.

func (*Service) PrepareMove added in v1.10.9

func (s *Service) PrepareMove(ctx context.Context, v *models.Volume, serverID uint) (MoveTarget, error)

func (*Service) ReclaimVolumeDir added in v1.10.4

func (s *Service) ReclaimVolumeDir(ctx context.Context, serverID uint, className, dockerName string)

ReclaimVolumeDir removes a class-backed directory for a volume this service does not own the row for. Best-effort, like the volume reclaim it mirrors: a leftover directory is a reclaimable orphan, while a failed delete would leave a resource that cannot be removed.

func (*Service) Reencrypt

func (s *Service) Reencrypt(ctx context.Context, workspaceID uint) (int, error)

Reencrypt re-encrypts this owner's workspace secrets under the workspace's active DEK (key rotation). Idempotent; returns the number rewritten.

func (*Service) Resize added in v1.10.2

func (s *Service) Resize(workspaceID, id uint, sizeBytes int64) error

Resize changes a volume's DECLARED capacity. That number drives quota accounting and the UI, not the filesystem: hard enforcement depends on the node's storage backend, so nothing on disk moves and the engine's create-time size label keeps its original value. Capacity only grows: a smaller number, or one below what the volume already holds, is refused.

func (*Service) SetImageResolver

func (s *Service) SetImageResolver(r ImageResolver)

SetImageResolver wires the deployment-config resolver for the volume helper image.

func (*Service) SetNodeGuard

func (s *Service) SetNodeGuard(g NodeGuard)

SetNodeGuard wires the placement guard consulted when creating a volume on a node.

func (*Service) SetOwner

func (s *Service) SetOwner(workspaceID, id uint, kind string, ownerID uint, name string) error

SetOwner records the owning resource (app, database, stack or user) on an existing volume's metadata. Used to back-link template volumes to the app or stack they back once those have been created. Built-in keys are authoritative, so this overrides any prior owner.

func (*Service) SetOwnerExister

func (s *Service) SetOwnerExister(fn OwnerExister)

SetOwnerExister wires the owner-existence check used by Delete to guard a volume that still backs an app/database/stack (nil-safe; nil skips the guard).

func (*Service) SetQuota

func (s *Service) SetQuota(q *quota.Service)

SetQuota wires the plan/quota enforcer (nil-safe; nil skips checks).

func (*Service) SetServerInfo

func (s *Service) SetServerInfo(si ServerInfo)

SetServerInfo wires the resolver used to annotate volumes with their node's name.

func (*Service) SetStorageClasses added in v1.10.2

func (s *Service) SetStorageClasses(c StorageClasses)

SetStorageClasses wires the storage-class resolver (nil-safe; nil keeps every volume on the engine's own data root).

func (*Service) SetWorkspacePrivilege

func (s *Service) SetWorkspacePrivilege(w WorkspacePrivilege)

SetWorkspacePrivilege wires the privileged-workspace check gating host-path volume creation (nil-safe; nil refuses host-path volumes).

func (*Service) UploadFile

func (s *Service) UploadFile(ctx context.Context, v *models.Volume, subdir, filename string, content io.Reader, size int64) (string, error)

UploadFile streams an uploaded file into a volume at the given (optional) sub-directory, creating intermediate directories as needed.

func (*Service) VolumeConsumers added in v1.10.9

func (s *Service) VolumeConsumers(workspaceID, volumeID uint) ([]VolumeUsage, error)

VolumeConsumers lists the applications that mount a volume.

func (*Service) WorkspaceStorage

func (s *Service) WorkspaceStorage(workspaceID uint) (*WorkspaceStorage, error)

WorkspaceStorage sums the workspace's volumes from cached columns (no live disk walk). Computed in Go, not SUM/MIN SQL, to behave the same on sqlite.

type StorageClasses added in v1.10.2

type StorageClasses interface {
	Resolve(serverID uint, name string) (*models.StorageClass, error)
	EnsureDir(ctx context.Context, c *models.StorageClass, dockerName string) error
	RemoveDir(ctx context.Context, c *models.StorageClass, dockerName string) error
	DiskUsageAll(ctx context.Context, c *models.StorageClass) (map[string]int64, error)
	ListManaged() ([]models.StorageClass, error)
}

StorageClasses resolves the admin-registered directory a volume is created under and owns the node-side filesystem actions that go with it. Implemented by storageclass.Service; nil leaves every volume on the built-in class, i.e. exactly the pre-storage-class behaviour.

type VolumeDetail

type VolumeDetail struct {
	models.Volume
	Driver string        `json:"driver,omitempty"`
	Exists bool          `json:"exists"` // whether the underlying Docker volume is present
	InUse  bool          `json:"in_use"`
	UsedBy []VolumeUsage `json:"used_by"`
}

VolumeDetail enriches a stored volume with live Docker info and the apps that mount it.

type VolumeFile

type VolumeFile struct {
	Path    string `json:"path"`     // path relative to the volume root, e.g. "config/app.yaml"
	Size    int64  `json:"size"`     // bytes (0 for directories)
	ModTime int64  `json:"mod_time"` // unix seconds
	IsDir   bool   `json:"is_dir"`
}

VolumeFile is one entry in a volume's filesystem listing.

type VolumeUsage

type VolumeUsage struct {
	AppID          uint   `json:"app_id"`
	AppName        string `json:"app_name"`         // unique slug handle
	AppDisplayName string `json:"app_display_name"` // free-text label
	Path           string `json:"path"`
}

VolumeUsage is an application that mounts a volume, with its mount path.

type WorkspacePrivilege

type WorkspacePrivilege interface {
	FindByID(id uint) (*models.Workspace, error)
}

WorkspacePrivilege reports whether a workspace holds the platform-admin-granted privileged flag, required (with the plan capability) to create host-path volumes. Implemented by the workspace repository; injected after construction.

type WorkspaceStorage

type WorkspaceStorage struct {
	DeclaredBytes int64      `json:"declared_bytes"` // SUM(SizeBytes) — asked for
	UsedBytes     int64      `json:"used_bytes"`     // SUM(UsedBytes) — measured on disk
	LimitMB       int        `json:"limit_mb"`       // effective plan MaxStorageMB (-1 = unlimited)
	MeasuredAt    *time.Time `json:"measured_at,omitempty"`
	VolumeCount   int64      `json:"volume_count"`
}

WorkspaceStorage is a workspace's declared-vs-measured storage summary.

Jump to

Keyboard shortcuts

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