Documentation
¶
Overview ¶
Package volume provides the HTTP transport layer and business logic for block storage volume lifecycle management.
@title Block Storage API @version 1.0.0 @description Pluggable block storage API — Ceph, Lustre backends with FSM volume lifecycle. @contact.name Ciré LY @contact.url https://github.com/cire-ly/block-storage-api @contact.email cire.ly@nexonode.tech @license.name MIT @license.url https://opensource.org/licenses/MIT @host 163.172.144.70:8080 @BasePath / @tag.name volumes @tag.description Block storage volume lifecycle operations @tag.name system @tag.description Health and observability endpoints
Index ¶
- Constants
- Variables
- func CanTransition(currentState, event string) bool
- func NewVolumeFSM(initialState string) *fsm.FSM
- func Transition(ctx context.Context, currentState, event string) (string, error)
- type ApplicationContract
- type DatabaseDependency
- type FeatureContract
- type LoggerDependency
- type NewVolumeFeatureParams
- type RetryPolicy
- type StorageBackendDependency
- type VolumeEvent
- type VolumeFeature
- type VolumeStateEvent
Constants ¶
const ( StatePending = storage.StatePending StateCreating = storage.StateCreating StateCreatingFailed = storage.StateCreatingFailed StateAvailable = storage.StateAvailable StateAttaching = storage.StateAttaching StateAttachingFailed = storage.StateAttachingFailed StateAttached = storage.StateAttached StateDetaching = storage.StateDetaching StateDetachingFailed = storage.StateDetachingFailed StateDeleting = storage.StateDeleting StateDeletingFailed = storage.StateDeletingFailed StateDeleted = storage.StateDeleted StateError = storage.StateError )
Volume states — aliases to storage constants for use within this package.
const ( EventCreate = "create" EventReady = "ready" EventAttach = "attach" EventAttached = "attached" EventDetach = "detach" EventDetached = "detached" EventDelete = "delete" EventDeleted = "deleted" EventError = "error" EventRetry = "retry" EventFail = "fail" )
Volume events.
Variables ¶
var ( ErrVolumeNotFound = errors.New("volume not found") ErrVolumeExists = errors.New("volume already exists") ErrInvalidTransition = errors.New("invalid state transition") ErrInvalidSize = errors.New("size must be > 0 MB") )
Sentinel errors used for HTTP status mapping.
Functions ¶
func CanTransition ¶
CanTransition reports whether event is valid from currentState.
func NewVolumeFSM ¶
NewVolumeFSM builds a new FSM seeded at initialState.
Transitions:
pending → [create] → creating → [ready] → available
available → [attach] → attaching → [attached] → attached
attached → [detach] → detaching → [detached] → available
available → [delete] → deleting → [deleted] → deleted
creating|attaching|detaching|deleting → [error] → *_failed
*_failed → [retry] → original in-progress state
*_failed → [fail] → error (after MaxAttempts)
error → reconcile via POST /api/v1/volumes/{name}/reconcile
Types ¶
type ApplicationContract ¶
type ApplicationContract interface {
CreateVolume(ctx context.Context, name string, sizeMB int) (*storage.Volume, error)
DeleteVolume(ctx context.Context, name string) error
ListVolumes(ctx context.Context) ([]*storage.Volume, error)
GetVolume(ctx context.Context, name string) (*storage.Volume, error)
AttachVolume(ctx context.Context, name string, nodeID string) error
DetachVolume(ctx context.Context, name string) error
ReconcileVolume(ctx context.Context, name string) (*storage.Volume, error)
HealthCheck(ctx context.Context) error
// Subscribe returns a buffered channel that receives every FSM state transition
// for the named volume. The channel is closed when the volume reaches a terminal
// state or when Unsubscribe is called.
Subscribe(ctx context.Context, name string) (<-chan VolumeStateEvent, error)
Unsubscribe(name string, ch <-chan VolumeStateEvent)
}
ApplicationContract defines all volume business operations. Implemented by application, consumed by controller_http.
type DatabaseDependency ¶
type DatabaseDependency interface {
SaveVolume(ctx context.Context, v *storage.Volume) error
UpdateVolume(ctx context.Context, v *storage.Volume) error
// LoadVolume returns nil, nil when the volume does not exist.
LoadVolume(ctx context.Context, name string) (*storage.Volume, error)
ListVolumes(ctx context.Context) ([]*storage.Volume, error)
ListVolumesByState(ctx context.Context, states ...string) ([]*storage.Volume, error)
DeleteVolume(ctx context.Context, name string) error
SaveEvent(ctx context.Context, e VolumeEvent) error
}
DatabaseDependency is the persistence layer required by the volume feature. Defined on the consumer side — the concrete implementation lives in internal/db.
type FeatureContract ¶
type FeatureContract interface {
Application() ApplicationContract
Close(context.Context) error
}
FeatureContract is the external face of the volume feature, consumed by setup.go.
type LoggerDependency ¶
type LoggerDependency interface {
Debug(string, ...any)
Info(string, ...any)
Warn(string, ...any)
Error(string, ...any)
}
LoggerDependency is the structured logger required by the volume feature.
type NewVolumeFeatureParams ¶
type NewVolumeFeatureParams struct {
Logger LoggerDependency // required
Backend StorageBackendDependency // required
DB DatabaseDependency // required
Tracer trace.Tracer // required
Meter metric.Meter // optional
Router chi.Router // required
RetryPolicy RetryPolicy // optional — DefaultRetryPolicy applied when zero
ReconcilePolicy config.ReconcilePolicy // optional — defaults: DBOnly=error, CephOnly=ignore
}
NewVolumeFeatureParams holds all required dependencies for the volume feature. Every field is required unless noted.
type RetryPolicy ¶
type RetryPolicy struct {
MaxAttempts int
InitialWait time.Duration
Multiplier float64
MaxWait time.Duration
}
RetryPolicy controls exponential back-off for failed FSM transitions.
func DefaultRetryPolicy ¶
func DefaultRetryPolicy() RetryPolicy
DefaultRetryPolicy returns the recommended retry configuration.
type StorageBackendDependency ¶
type StorageBackendDependency interface {
storage.VolumeBackend
}
StorageBackendDependency is the storage backend required by the volume feature. Defined on the consumer side (volume package) — implementations live in storage/.
type VolumeEvent ¶
VolumeEvent records a single FSM state transition for the audit trail.
type VolumeFeature ¶
type VolumeFeature struct {
// contains filtered or unexported fields
}
VolumeFeature is the wired volume feature, implementing FeatureContract.
func NewVolumeFeature ¶
func NewVolumeFeature(params NewVolumeFeatureParams) (*VolumeFeature, error)
NewVolumeFeature validates all params, wires the application and HTTP controller, registers routes, and schedules startup reconciliation.
func (*VolumeFeature) Application ¶
func (f *VolumeFeature) Application() ApplicationContract
Application returns the ApplicationContract for this feature.
func (*VolumeFeature) Close ¶
func (f *VolumeFeature) Close(ctx context.Context) error
Close shuts down the feature in three steps:
- Cancel the internal lifecycle context — signals all goroutines to stop.
- Wait for all goroutines to finish, bounded by the caller's deadline.
- Close remaining resources in LIFO order.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package repository provides PostgreSQL and in-memory implementations of volume.DatabaseDependency.
|
Package repository provides PostgreSQL and in-memory implementations of volume.DatabaseDependency. |