blob

type BackupValidator interface {
	ValidateBackup(ctx context.Context, r io.Reader) error
}

type Backuper interface {
	// Backup streams a backup of the current contents of the store to w.
	Backup(ctx context.Context, w io.Writer) error
}

type BlobStore interface {
	// Transaction management
	Close() error
	NewTransaction(bool) types.Txn

	// KV operations (plugins map these to their internals with transaction context)
	Get(txn types.Txn, key []byte) ([]byte, error)
	Set(txn types.Txn, key, val []byte) error
	Delete(txn types.Txn, key []byte) error
	NewIterator(
		txn types.Txn,
		opts types.BlobIteratorOptions,
	) types.BlobIterator

	// Commit timestamp management
	GetCommitTimestamp() (int64, error)
	// SetCommitTimestamp stores the last commit timestamp; parameter order is
	// (timestamp, txn) to keep the transaction as the final parameter.
	SetCommitTimestamp(int64, types.Txn) error

	// Block operations
	SetBlock(
		txn types.Txn,
		slot uint64,
		hash []byte,
		cbor []byte,
		id uint64,
		blockType uint,
		height uint64,
		prevHash []byte,
	) error
	GetBlock(
		txn types.Txn,
		slot uint64,
		hash []byte,
	) ([]byte, types.BlockMetadata, error)
	DeleteBlock(txn types.Txn, slot uint64, hash []byte, id uint64) error
	// TombstoneBlock replaces the block's CBOR with an expired-history
	// marker while leaving index pointers (bi, bh) and metadata in place.
	// GetBlock and iterator ValueCopy must return types.ErrHistoryExpired
	// for the block so archive wrappers can proxy it if configured.
	// DeleteBlock continues to fully remove a block for orphan rollbacks
	// where there is no retained history entry.
	TombstoneBlock(txn types.Txn, slot uint64, hash []byte) error
	GetBlockURL(
		ctx context.Context,
		txn types.Txn,
		point ocommon.Point,
	) (types.SignedURL, types.BlockMetadata, error)
	// UTxO operations
	SetUtxo(txn types.Txn, txId []byte, outputIdx uint32, cbor []byte) error
	GetUtxo(txn types.Txn, txId []byte, outputIdx uint32) ([]byte, error)
	DeleteUtxo(txn types.Txn, txId []byte, outputIdx uint32) error

	// Transaction operations
	SetTx(txn types.Txn, txHash []byte, offsetData []byte) error
	GetTx(txn types.Txn, txHash []byte) ([]byte, error)
	DeleteTx(txn types.Txn, txHash []byte) error

	// DiskSize returns the on-disk size of the blob store in bytes.
	// Returns 0 for cloud-backed stores where local size is not meaningful.
	DiskSize() (int64, error)

	// Sync flushes everything committed so far to durable storage, so it
	// survives an unclean shutdown of the process or host.
	//
	// This exists because committing a blob transaction is not the same as
	// making it durable. The combined blob+metadata commit in database.Txn
	// deliberately commits blob first so the blob store can only ever be ahead
	// of the metadata tip, never behind -- startup reconciliation knows how to
	// trim a blob store that is ahead (cleanupOrphanedBlobs) but cannot
	// reconstruct blocks the metadata tip already references. That ordering
	// only holds on disk if the blob commit is durable before the metadata
	// commit is, so Txn.Commit calls Sync between the two. Skipping it inverts
	// the invariant on an unclean host shutdown, because the two stores flush on
	// very different schedules: SQLite reaches disk at WAL checkpoints (every
	// 1000 pages by default) while Badger can hold committed writes in a 128MiB
	// memtable for hours at chain tip. The metadata tip then survives while the
	// blocks it references are silently discarded.
	//
	// Implementations whose writes are already durable on commit (remote
	// object stores) may return nil.
	Sync() error
}

type LocalBlockReader interface {
	GetBlockLocal(
		txn types.Txn,
		slot uint64,
		hash []byte,
	) ([]byte, types.BlockMetadata, error)
}

type ProviderDependencies struct {
	DataDir      string
	RunMode      string
	StorageMode  string
	Logger       *slog.Logger
	PromRegistry prometheus.Registerer
}

type Resettable interface {
	Reset(ctx context.Context) error
}

type Restorer interface {
	// Restore replaces the store's contents with the backup read from r.
	Restore(ctx context.Context, r io.Reader) error
}

type TxnBudget interface {
	// RemainingTxnEntries reports how many further mutations, each costing
	// entryBytes of key plus value, txn will still accept. Staging all of
	// them fills the transaction, so a caller with anything left to write
	// into it afterwards -- and every combined transaction has the commit
	// timestamp -- keeps headroom of its own.
	//
	// The bool is false when the store cannot answer for this transaction
	// -- a nil, finished, or foreign handle -- which callers read the same
	// way as a store that does not implement the interface at all.
	RemainingTxnEntries(txn types.Txn, entryBytes int) (int, bool)
}