driver

type Capabilities struct {
	// AccessModes is the set of access modes the driver can satisfy.
	AccessModes []types.AccessMode

	// Snapshots indicates Snapshot/RestoreFromSnapshot are implemented.
	Snapshots bool

	// Expand indicates Expand is implemented (some drivers only support
	// offline expand — see Driver.Expand docs).
	Expand bool

	// OnlineExpand is true if Expand may be called while the volume is
	// Bound (without first detaching).
	OnlineExpand bool

	// BlockDevice is true if the driver exposes a raw block device the
	// runner is expected to format/mount itself. Directory-style drivers
	// (local, local-host, NFS) set this to false.
	BlockDevice bool

	// TopologyKeys are the well-known label keys this driver consumes from
	// StorageClass.AllowedTopologies. Used by the API-server linter to
	// reject unknown keys early.
	TopologyKeys []string
}

type DevicePath string

type Driver interface {
	// Name returns the registered driver name (e.g. "local", "do-volume").
	// Must match the registry key.
	Name() string

	// Capabilities describes what this driver supports. Returned values are
	// expected to be stable for the lifetime of the process.
	Capabilities() Capabilities

	// Provision creates a new backing store for the volume and returns an
	// opaque handle that subsequent calls (Attach, Snapshot, ...) re-parse.
	// MUST be idempotent on Volume.ID — the controller retries on failure.
	Provision(ctx context.Context, opctx OpContext, req ProvisionRequest) (VolumeHandle, error)

	// Delete destroys the backing store identified by handle. Implementations
	// MUST tolerate missing/already-deleted handles (return nil).
	Delete(ctx context.Context, opctx OpContext, handle VolumeHandle) error

	// Attach makes the volume available to the named node (e.g. attaches a
	// cloud block device, opens an iSCSI session, no-ops for local
	// directories). Returns the device path the node should Mount.
	// For drivers that don't have a separate attach step, return an empty
	// DevicePath and a nil error.
	Attach(ctx context.Context, opctx OpContext, handle VolumeHandle, node NodeID) (DevicePath, error)

	// Detach is the inverse of Attach. Idempotent.
	Detach(ctx context.Context, opctx OpContext, handle VolumeHandle, node NodeID) error

	// Mount makes the volume usable at MountTarget. For block-device drivers
	// this typically formats (if needed) and mounts; for directory-style
	// drivers it bind-mounts or returns the source path the runner should
	// bind-mount itself. The returned MountTarget is what the runner uses —
	// drivers may rewrite it (e.g. local-host returns the host path
	// directly rather than the proposed Target).
	Mount(ctx context.Context, opctx OpContext, opts MountOpts) (MountTarget, error)

	// Unmount is the inverse of Mount. Idempotent.
	Unmount(ctx context.Context, opctx OpContext, target MountTarget) error

	// Snapshot creates a point-in-time snapshot of the volume. Drivers
	// without snapshot support (Capabilities.Snapshots == false) MUST return
	// ErrUnsupported.
	Snapshot(ctx context.Context, opctx OpContext, req SnapshotRequest) (SnapshotHandle, error)

	// RestoreFromSnapshot provisions a NEW volume from a snapshot. The
	// returned handle replaces the volume's existing handle. OpContext
	// here describes the TARGET volume + its class — the source snapshot
	// is carried on RestoreRequest.
	// Drivers without snapshot support MUST return ErrUnsupported.
	RestoreFromSnapshot(ctx context.Context, opctx OpContext, req RestoreRequest) (VolumeHandle, error)

	// DeleteSnapshot destroys the snapshot identified by handle. MUST be
	// idempotent — implementations should swallow ErrNotFound and return
	// nil so the controller can re-drive a Deleting snapshot safely.
	// Drivers without snapshot support MUST return ErrUnsupported.
	DeleteSnapshot(ctx context.Context, opctx OpContext, handle SnapshotHandle) error

	// Expand grows the volume to NewSize. Online expansion vs offline is
	// driver-dependent; drivers that only support offline expand (e.g.
	// do-volume) MUST refuse if the volume is currently Bound and return
	// ErrOnlineExpandUnsupported.
	// Drivers without expand support (Capabilities.Expand == false) MUST
	// return ErrUnsupported.
	Expand(ctx context.Context, opctx OpContext, handle VolumeHandle, newSize string) error
}

type Factory func(config map[string]any) (Driver, error)

type MountOpts struct {
	Handle   VolumeHandle
	Node     NodeID
	Device   DevicePath  // device returned by Attach (empty for directory drivers)
	Target   MountTarget // proposed mount target (may be rewritten by driver)
	ReadOnly bool
	// FsType is the filesystem to format with on first mount of a block
	// device. Ignored by directory drivers. Sourced from StorageClass /
	// Volume parameters.
	FsType string
}

type MountTarget string

type NodeID string

type OpContext struct {
	// StorageClass that this operation is acting on. May be nil for
	// orphan deletes (class removed before its volumes). Live operations
	// always carry the resolved class.
	StorageClass *types.StorageClass

	// Volume is the row this operation pertains to. Always non-nil for
	// volume-scoped operations (every method on the interface).
	Volume *types.Volume

	// Parameters is StorageClass.Parameters with Volume.Parameters
	// overlaid on top, pre-merged by the caller. Drivers consult this
	// map for per-class configuration (region, fsType, auth refs, etc.)
	// rather than re-merging themselves.
	Parameters map[string]string

	// NodeHostname is the OS hostname (os.Hostname()) of the agent
	// running this call, populated by the controller / agent at
	// build time. Cloud-backed drivers use it to map Rune's node
	// identity onto the cloud provider's instance identity — DO
	// droplets, for example, are addressable by their hostname-derived
	// name via /v2/droplets?name=... Empty when the caller has no
	// hostname to report (controller-only operations like Provision /
	// Delete that don't run on a specific node, or tests).
	NodeHostname string
}

type ProvisionRequest struct {
	// SizeBytes is Volume.Size already parsed into bytes by the controller.
	// Drivers that need the original string can read OpContext.Volume.Size.
	SizeBytes int64

	// Topology is the topology constraint the controller selected for this
	// provision (the chosen TopologySelector after intersecting
	// StorageClass.AllowedTopologies with node availability). Empty means
	// no constraint.
	Topology *types.TopologySelector

	// Deadline is a soft deadline for the operation. Drivers should respect
	// ctx.Done() but may use this for finer-grained internal timeouts.
	Deadline time.Time
}

type RestoreRequest struct {
	// Source is the snapshot being restored.
	Source       *types.Snapshot
	SourceHandle SnapshotHandle

	// SizeBytes is the target Volume.Size already parsed into bytes.
	SizeBytes int64
}

type SnapshotHandle string

type SnapshotRequest struct {
	Handle   VolumeHandle
	Snapshot *types.Snapshot
}

type UsageReporter interface {
	Usage(ctx context.Context, opctx OpContext, handle VolumeHandle) (usedBytes, capacityBytes uint64, err error)
}

type VolumeHandle string