storage

type Bucket interface {
	io.Closer
	Operation

	// ID returns the Bucket ID.
	ID() string
	// Weight returns the Bucket weight, range 0-1000.
	Weight() int
	// Allow returns the allow percent of the Bucket, range 0-100.
	Allow() int
	// UseAllow returns whether to use the allow percent.
	UseAllow() bool
	// Objects returns whether to all cached objects len.
	Objects() uint64
	// HasBad returns whether the Bucket is in bad state.
	HasBad() bool
	// Type returns the Bucket type, empty memory native
	Type() string
	// StoreType returns the Bucket store-type, cold hot fastmemory
	StoreType() string
	// Path returns the Bucket path.
	Path() string
}

type CacheStatus int

type File interface {
	io.Closer
	io.Reader
	io.ReaderAt
	// Unlike the specification for io.Writer.Write(), the vfs.File.Write()
	// method *is* allowed to modify the slice passed in, whether temporarily
	// or permanently. Callers of Write() need to take this into account.
	io.Writer
	// WriteAt() is only supported for files that were opened with FS.OpenReadWrite.
	io.WriterAt

	// Preallocate optionally preallocates storage for `length` at `offset`
	// within the file. Implementations may choose to do nothing.
	Stat() (os.FileInfo, error)
	Sync() error

	// Fd returns the raw file descriptor when a File is backed by an *os.File.
	// It can be used for specific functionality like Prefetch.
	// Returns InvalidFd if not supported.
	Fd() uintptr

	Name() string
}

type IndexDB interface {
	io.Closer

	// Get retrieves metadata for the given key from the IndexDB
	// Returns the metadata object if found, or error if not found or on failure
	Get(ctx context.Context, key []byte) (*object.Metadata, error)

	// Set stores or updates metadata for the given key in the IndexDB
	// Returns error if the operation fails
	Set(ctx context.Context, key []byte, val *object.Metadata) error

	// Exist checks if metadata exists for the given key
	// Returns true if the key exists, false otherwise
	Exist(ctx context.Context, key []byte) bool

	// Delete removes metadata for the given key from the IndexDB
	// Returns error if the operation fails
	Delete(ctx context.Context, key []byte) error

	// Iterate walks through all metadata entries with the given prefix
	// Calls the provided function f for each entry found
	// Returns error if the iteration fails
	Iterate(ctx context.Context, prefix []byte, f IterateFunc) error

	// Expired iterates through expired metadata entries
	// Calls the provided function f for each expired entry
	// Returns error if the iteration fails
	Expired(ctx context.Context, f IterateFunc) error

	// GC performs garbage collection on the IndexDB
	// Returns error if the operation fails
	GC(ctx context.Context) error
}

type IndexDBFactory func(path string, option Option) (IndexDB, error)

type IterateFunc func(key []byte, val *object.Metadata) bool

type Mark uint64

type Operation interface {
	// Lookup retrieves the metadata for the specified object ID.
	Lookup(ctx context.Context, id *object.ID) (*object.Metadata, error)
	// Store store the metadata for the specified object ID.
	Store(ctx context.Context, meta *object.Metadata) error
	// Exist checks if the object exists.
	Exist(ctx context.Context, id []byte) bool
	// Remove soft-removes the object.
	Remove(ctx context.Context, id *object.ID) error
	// Discard hard-removes the object.
	Discard(ctx context.Context, id *object.ID) error
	// DiscardWithHash hard-removes the hash of the object.
	DiscardWithHash(ctx context.Context, hash object.IDHash) error
	// DiscardWithMessage hard-removes the object with a message.
	DiscardWithMessage(ctx context.Context, id *object.ID, msg string) error
	// DiscardWithMetadata hard-removes the object with a metadata.
	DiscardWithMetadata(ctx context.Context, meta *object.Metadata) error
	// Iterate iterates the objects.
	Iterate(ctx context.Context, fn func(*object.Metadata) error) error
	// Expired if the object is expired callback.
	Expired(ctx context.Context, id *object.ID, md *object.Metadata) bool
	// WriteChunkFile open chunk file and returns io.WriteCloser
	WriteChunkFile(ctx context.Context, id *object.ID, index uint32) (io.WriteCloser, string, error)
	// ReadChunkFile open chunk file and returns io.ReadCloser
	ReadChunkFile(ctx context.Context, id *object.ID, index uint32) (File, string, error)
}

type Option interface {
	// DBType returns the type of the IndexDB
	DBType() string
	// DBPath returns the path to the IndexDB file
	DBPath() string
	// Codec returns the codec for encoding and decoding metadata
	Codec() encoding.Codec
	// Unmarshal decodes the given data into the provided interface
	Unmarshal(v interface{}) error
}

type PurgeControl struct {
	Hard        bool `json:"hard"`         // 是否硬删除, default: false 与 MarkExpired 冲突
	Dir         bool `json:"dir"`          // 是否清理目录, default: false
	MarkExpired bool `json:"mark_expired"` // 是否标记为过期, default: false 与 Hard 冲突
}

type ResourceLocker interface {
	// Key returns the lock key.
	Key() string
	// Lock acquires the lock.
	Lock()
	// Unlock releases the lock.
	Unlock()
	// RLock acquires a read lock.
	RLock()
	// RUnlock releases a read lock.
	RUnlock()
}

type Selector interface {
	// Select selects the Bucket by the object ID.
	Select(ctx context.Context, id *object.ID) Bucket
	// Rebuild rebuilds the Bucket hashring.
	// do not call this method frequently.
	Rebuild(ctx context.Context, buckets []Bucket) error
}

type SharedKV interface {
	io.Closer

	// Get returns the value for the given key.
	Get(ctx context.Context, key []byte) ([]byte, error)
	// Set sets the value for the given key.
	Set(ctx context.Context, key []byte, val []byte) error
	// Incr increments the value for the given key.
	Incr(ctx context.Context, key []byte, delta uint32) (uint32, error)
	// Decr decrements the value for the given key.
	Decr(ctx context.Context, key []byte, delta uint32) (uint32, error)
	// GetCounter returns the value for the given key.
	GetCounter(ctx context.Context, key []byte) (uint32, error)
	// Delete deletes the value for the given key.
	Delete(ctx context.Context, key []byte) error
	// DropPrefix deletes all key-value pairs with the given prefix.
	DropPrefix(ctx context.Context, prefix []byte) error
	// Iterate iterates over all key-value pairs.
	Iterate(ctx context.Context, f func(key, val []byte) error) error
	// IteratePrefix iterates over all key-value pairs with the given prefix.
	IteratePrefix(ctx context.Context, prefix []byte, f func(key, val []byte) error) error
}

type Storage interface {
	io.Closer
	Selector

	Buckets() []Bucket

	SharedKV() SharedKV

	PURGE(storeUrl string, typ PurgeControl) error
}