volume

type ID struct {
	Namespace v1.NamespaceName
	Function  v1.ObjectName
	Name      v1.ObjectName
	Worker    string // "" for a local volume
}

type Info struct {
	ID        ID
	Owner     v1.UID // "" ⇒ retained: no Function holds it
	SizeBytes int64
	Deletion  v1.DeletionPolicy
}

type Limiter interface {
	// Limit sets dir's project id and a hard limit of sizeBytes.
	Limit(dir string, project uint32, sizeBytes int64) error
	// Enforced reports whether Limit is a kernel limit.
	Enforced() bool
}

type Manager interface {
	// Book records sizeBytes for id under the allocator's lock, with no leaf; VolumeCapacity or VolumeBudget
	// (fault.Conflict) when it does not fit, Invalid when id is booked or stored with another size. Idempotent for
	// the same id and size.
	Book(ctx context.Context, id ID, sizeBytes int64) error
	// Reserve creates or checks id's leaf and sets its quota against its booking (booking it first when it has
	// none); StoreNotOwned when the meta names another UID. deletion is recorded for the delete path.
	Reserve(ctx context.Context, id ID, owner v1.UID, sizeBytes int64, deletion v1.DeletionPolicy) (hostPath string, err error)
	// Adopt stamps owner on a retained local volume; "" retains it; Conflict while another live Function holds it.
	Adopt(ctx context.Context, id ID, owner v1.UID) error
	Release(ctx context.Context, id ID) error              // removes the leaf and frees its booking
	Retained(ctx context.Context) ([]ID, error)            // local volumes with no owner
	List(ctx context.Context) ([]Info, error)              // every volume with a leaf, local and emptyDir
	Tar(ctx context.Context, id ID) (io.ReadCloser, error) // the backup member stream
	Untar(ctx context.Context, id ID, r io.Reader) error   // Conflict when the leaf is not empty
	Empty(ctx context.Context, id ID) (bool, error)        // the leaf holds no entry; NotFound with no leaf
	Clear(ctx context.Context, id ID) error                // removes the leaf's entries, after a failed load
}

type Options struct {
	Root          string // where the leaves and metas live; created 0700
	Limiter       Limiter
	CapacityBytes int64 // 0 ⇒ no capacity check (funcdctl dev)
	// Budget returns a namespace's volume budget in bytes, 0 for none.
	Budget func(ctx context.Context, ns v1.NamespaceName) (int64, error)
	// Holder returns the UID of the stored Function a volume's path names, or false when none is stored.
	Holder func(ctx context.Context, ns v1.NamespaceName, fn v1.ObjectName) (v1.UID, bool, error)
	// UID and GID own each leaf (the runtime images run as root, the zero value).
	UID, GID int
	// BookingTTL drops a booking no Reserve backed (an apply refused after its admission); default 1 minute.
	BookingTTL time.Duration
	// MeasureInterval paces the measurement of an unenforced Limiter; default 30 s.
	MeasureInterval time.Duration
	Logger          *slog.Logger
	Clock           func() time.Time
}