Documentation
¶
Overview ¶
Package storage manages persistent (Docker) volumes owned by workspaces.
Index ¶
- Variables
- func SharedDriverOptsValid(opts map[string]string) error
- type CreateInput
- type ImageResolver
- type MoveTarget
- type NodeDocker
- type NodeGuard
- type OwnerExister
- type ServerInfo
- type Service
- func (s *Service) AuditSharedVolumes()
- func (s *Service) ClassAvailable(serverID uint, name string) bool
- func (s *Service) Create(ctx context.Context, workspaceID, serverID uint, name string, sizeBytes int64, ...) (*models.Volume, error)
- func (s *Service) CreateOn(ctx context.Context, workspaceID, serverID uint, in CreateInput) (*models.Volume, error)
- func (s *Service) CreateWith(ctx context.Context, workspaceID, serverID uint, name string, sizeBytes int64, ...) (*models.Volume, error)
- func (s *Service) Delete(ctx context.Context, v *models.Volume) error
- func (s *Service) DeleteFile(ctx context.Context, v *models.Volume, rel string) error
- func (s *Service) Detail(ctx context.Context, workspaceID, id uint) (*VolumeDetail, error)
- func (s *Service) DownloadFile(ctx context.Context, v *models.Volume, rel string) (io.ReadCloser, int64, error)
- func (s *Service) DropCopy(ctx context.Context, serverID uint, dockerName, className string) error
- func (s *Service) Get(workspaceID, id uint) (*models.Volume, error)
- func (s *Service) IDByUID(uid string) (uint, error)
- func (s *Service) List(workspaceID uint) ([]models.Volume, error)
- func (s *Service) ListFiles(ctx context.Context, v *models.Volume) ([]VolumeFile, error)
- func (s *Service) MeasureUsage(ctx context.Context) error
- func (s *Service) PlaceVolume(ctx context.Context, workspaceID, serverID uint, requested, dockerName string) (className, devicePath string, err error)
- func (s *Service) PrepareMove(ctx context.Context, v *models.Volume, serverID uint) (MoveTarget, error)
- func (s *Service) ReclaimVolumeDir(ctx context.Context, serverID uint, className, dockerName string)
- func (s *Service) Reencrypt(ctx context.Context, workspaceID uint) (int, error)
- func (s *Service) Resize(workspaceID, id uint, sizeBytes int64) error
- func (s *Service) SetImageResolver(r ImageResolver)
- func (s *Service) SetNodeGuard(g NodeGuard)
- func (s *Service) SetOwner(workspaceID, id uint, kind string, ownerID uint, name string) error
- func (s *Service) SetOwnerExister(fn OwnerExister)
- func (s *Service) SetQuota(q *quota.Service)
- func (s *Service) SetServerInfo(si ServerInfo)
- func (s *Service) SetStorageClasses(c StorageClasses)
- func (s *Service) SetWorkspacePrivilege(w WorkspacePrivilege)
- func (s *Service) UploadFile(ctx context.Context, v *models.Volume, subdir, filename string, ...) (string, error)
- func (s *Service) VolumeConsumers(workspaceID, volumeID uint) ([]VolumeUsage, error)
- func (s *Service) WorkspaceStorage(workspaceID uint) (*WorkspaceStorage, error)
- type StorageClasses
- type VolumeDetail
- type VolumeFile
- type VolumeUsage
- type WorkspacePrivilege
- type WorkspaceStorage
Constants ¶
This section is empty.
Variables ¶
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.
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.
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).
var ErrFileNotFound = errors.New("file not found in volume")
ErrFileNotFound is returned when a requested path is absent from the volume.
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.
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.
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.
var ErrInvalidDriver = errors.New("invalid volume driver")
ErrInvalidDriver is returned for an unknown volume driver.
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.
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
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 ¶
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 ¶
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 ¶
NodeGuard validates that a node can accept a new placement (exists, not cordoned). Implemented by the node service; injected after construction.
type OwnerExister ¶
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 ¶
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 NewService ¶
func NewService(repo *repositories.VolumeRepository, apps *repositories.ApplicationRepository, clients NodeDocker) *Service
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
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 ¶
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 ¶
DeleteFile removes a file or directory (recursively) from a volume.
func (*Service) Detail ¶
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
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) ListFiles ¶
ListFiles returns the files and directories stored in a volume by inspecting it with a short-lived helper container.
func (*Service) MeasureUsage ¶
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 (*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 ¶
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
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 ¶
SetNodeGuard wires the placement guard consulted when creating a volume on a node.
func (*Service) SetOwner ¶
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) 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 ¶
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.