storage

type AdminReader interface {
	// GetTree returns the tree corresponding to treeID or an error.
	GetTree(ctx context.Context, treeID int64) (*trillian.Tree, error)

	// ListTreeIDs returns the IDs of all trees in storage.
	// Note that there's no authorization restriction on the IDs returned,
	// so it should be used with caution in production code.
	ListTreeIDs(ctx context.Context) ([]int64, error)

	// ListTrees returns all trees in storage.
	// Note that there's no authorization restriction on the trees returned,
	// so it should be used with caution in production code.
	ListTrees(ctx context.Context) ([]*trillian.Tree, error)
}

type AdminStorage interface {
	// Snapshot starts a read-only transaction.
	// A transaction must be explicitly committed before the data read by it
	// is considered consistent.
	Snapshot(ctx context.Context) (ReadOnlyAdminTX, error)

	// Begin starts a read/write transaction.
	// A transaction must be explicitly committed before the data read by it
	// is considered consistent.
	Begin(ctx context.Context) (AdminTX, error)
}

type AdminTX interface {
	ReadOnlyAdminTX
	AdminWriter
}

type AdminWriter interface {
	// CreateTree inserts the specified tree in storage, returning a tree
	// with all storage-generated fields set.
	// Note that treeID and timestamps will be automatically generated by
	// the storage layer, thus may be ignored by the implementation.
	// Remaining fields must be set to valid values.
	// Returns an error if the tree is invalid or creation fails.
	CreateTree(ctx context.Context, tree *trillian.Tree) (*trillian.Tree, error)

	// UpdateTree updates the specified tree in storage, returning a tree
	// with all storage-generated fields set.
	// updateFunc is called to perform the desired tree modifications. Refer
	// to trillian.Tree for details on which fields are mutable and what is
	// considered valid.
	// Returns an error if the tree is invalid or the update cannot be
	// performed.
	UpdateTree(ctx context.Context, treeID int64, updateFunc func(*trillian.Tree)) (*trillian.Tree, error)
}

type DatabaseChecker interface {
	// CheckDatabaseAccessible returns nil if the database is accessible, error otherwise.
	CheckDatabaseAccessible(context.Context) error
}

type Error struct {
	ErrType int
	Detail  string
	Cause   error
}

type Getter interface {
	// Get retrieves the values associates with the keyHashes, if any, at the
	// specified revision.
	// Setting revision to -1 will fetch the latest revision.
	// The returned array of MapLeaves will only contain entries for which values
	// exist.  i.e. requesting a set of unknown keys would result in a
	// zero-length array being returned.
	Get(ctx context.Context, revision int64, keyHashes [][]byte) ([]trillian.MapLeaf, error)
}

type LeafDequeuer interface {
	// DequeueLeaves will return between [0, limit] leaves from the queue.
	// Leaves which have been dequeued within a Rolled-back Tx will become available for dequeing again.
	// Leaves queued more recently than the cutoff time will not be returned. This allows for
	// guard intervals to be configured.
	DequeueLeaves(ctx context.Context, limit int, cutoffTime time.Time) ([]*trillian.LogLeaf, error)
	UpdateSequencedLeaves(ctx context.Context, leaves []*trillian.LogLeaf) error
}

type LeafQueuer interface {
	// QueueLeaves enqueues leaves for later integration into the tree.
	// If error is nil, the returned slice of leaves will be the same size as the
	// input, and each entry will hold:
	//  - the existing leaf entry if a duplicate has been submitted
	//  - nil otherwise.
	// Duplicates are only reported if the underlying tree does not permit duplicates, and are
	// considered duplicate if their leaf.LeafIdentityHash matches.
	QueueLeaves(ctx context.Context, leaves []*trillian.LogLeaf, queueTimestamp time.Time) ([]*trillian.LogLeaf, error)
}

type LeafReader interface {
	// GetSequencedLeafCount returns the total number of leaves that have been integrated into the
	// tree via sequencing.
	GetSequencedLeafCount(ctx context.Context) (int64, error)
	// GetLeavesByIndex returns leaf metadata and data for a set of specified sequenced leaf indexes.
	GetLeavesByIndex(ctx context.Context, leaves []int64) ([]*trillian.LogLeaf, error)
	// GetLeavesByHash looks up sequenced leaf metadata and data by their Merkle leaf hash. If the
	// tree permits duplicate leaves callers must be prepared to handle multiple results with the
	// same hash but different sequence numbers. If orderBySequence is true then the returned data
	// will be in ascending sequence number order.
	GetLeavesByHash(ctx context.Context, leafHashes [][]byte, orderBySequence bool) ([]*trillian.LogLeaf, error)
}

type LogMetadata interface {
	// GetActiveLogs returns a list of the IDs of all the logs that are configured in storage
	GetActiveLogIDs(ctx context.Context) ([]int64, error)
	// GetActiveLogIDsWithPendingWork returns a list of IDs of logs that have
	// pending queued leaves that need to be integrated into the log.
	GetActiveLogIDsWithPendingWork(ctx context.Context) ([]int64, error)
}

type LogRootReader interface {
	// LatestSignedLogRoot returns the most recent SignedLogRoot, if any.
	LatestSignedLogRoot(ctx context.Context) (trillian.SignedLogRoot, error)
}

type LogRootWriter interface {
	// StoreSignedLogRoot stores a freshly created SignedLogRoot.
	StoreSignedLogRoot(ctx context.Context, root trillian.SignedLogRoot) error
}

type LogStorage interface {
	ReadOnlyLogStorage

	// BeginForTree starts a transaction for the specified treeID.
	// Either Commit or Rollback must be called when the caller is finished with
	// the returned object, and values read through it should only be propagated
	// if Commit returns without error.
	BeginForTree(ctx context.Context, treeID int64) (LogTreeTX, error)
}

type LogTreeTX interface {
	TreeTX
	LogRootReader
	LogRootWriter
	LeafReader
	LeafQueuer
	LeafDequeuer
	LogMetadata
}

type MapRootReader interface {
	// GetSignedMapRoot returns the SignedMapRoot associated with the
	// specified revision.
	GetSignedMapRoot(ctx context.Context, revision int64) (trillian.SignedMapRoot, error)
	// LatestSignedMapRoot returns the most recently created SignedMapRoot.
	LatestSignedMapRoot(ctx context.Context) (trillian.SignedMapRoot, error)
}

type MapRootWriter interface {
	// StoreSignedMapRoot stores root.
	StoreSignedMapRoot(ctx context.Context, root trillian.SignedMapRoot) error
}

type MapStorage interface {
	ReadOnlyMapStorage
	// BeginForTree starts a new Map transaction.
	// Either Commit or Rollback must be called when the caller is finished with
	// the returned object, and values read through it should only be propagated
	// if Commit returns without error.
	BeginForTree(ctx context.Context, treeID int64) (MapTreeTX, error)
}

type MapTreeTX interface {
	TreeTX
	MapRootReader
	MapRootWriter
	Getter
	Setter
}

type MockAdminStorage struct {
	// contains filtered or unexported fields
}

type MockAdminTX struct {
	// contains filtered or unexported fields
}

type MockLogStorage struct {
	// contains filtered or unexported fields
}

type MockLogTreeTX struct {
	// contains filtered or unexported fields
}

type MockMapStorage struct {
	// contains filtered or unexported fields
}

type MockMapTreeTX struct {
	// contains filtered or unexported fields
}

type MockReadOnlyAdminTX struct {
	// contains filtered or unexported fields
}

type MockReadOnlyLogTX struct {
	// contains filtered or unexported fields
}

type MockReadOnlyLogTreeTX struct {
	// contains filtered or unexported fields
}

type MockReadOnlyMapTreeTX struct {
	// contains filtered or unexported fields
}

type Node struct {
	NodeID       NodeID
	Hash         []byte
	NodeRevision int64
}

type NodeID struct {
	// path is effectively a BigEndian bit set, with path[0] being the MSB
	// (identifying the root child), and successive bits identifying the lower
	// level children down to the leaf.
	Path []byte
	// PrefixLenBits is the number of MSB in Path which are considered part of
	// this NodeID.
	//
	// e.g. if Path contains two bytes, and PrefixLenBits is 9, then the 8 bits
	// in Path[0] are included, along with the lowest bit of Path[1]
	PrefixLenBits int
	PathLenBits   int
}

type NodeReader interface {
	// GetMerkleNodes looks up the set of nodes identified by ids, at treeRevision, and returns them.
	GetMerkleNodes(ctx context.Context, treeRevision int64, ids []NodeID) ([]Node, error)
}

type NodeWriter interface {
	// SetMerkleNodes stores the provided nodes, at the transaction's writeRevision.
	SetMerkleNodes(ctx context.Context, nodes []Node) error
}

type PopulateSubtreeFunc func(*storagepb.SubtreeProto) error

type PrepareSubtreeWriteFunc func(*storagepb.SubtreeProto) error

type ReadOnlyAdminTX interface {
	AdminReader

	// Commit applies the operations performed to the underlying storage, or
	// returns an error.
	// A commit must be performed before any reads from storage are
	// considered consistent.
	Commit() error

	// Rollback aborts any performed operations, or returns an error.
	// See Close() for a way to automatically manage transactions.
	Rollback() error

	// IsClosed returns true if the transaction is closed.
	// A transaction is closed when either Commit() or Rollback() are
	// called.
	IsClosed() bool

	// Close rolls back the transaction if it's not yet closed.
	// It's advisable to call "defer tx.Close()" after the creation of
	// transaction to ensure that it's always rolled back if not explicitly
	// committed.
	Close() error
}

type ReadOnlyLogStorage interface {
	DatabaseChecker

	// Snapshot starts a read-only transaction not tied to any particular tree.
	Snapshot(ctx context.Context) (ReadOnlyLogTX, error)

	// SnapshotForTree starts a read-only transaction for the specified treeID.
	// Commit must be called when the caller is finished with the returned object,
	// and values read through it should only be propagated if Commit returns
	// without error.
	SnapshotForTree(ctx context.Context, treeID int64) (ReadOnlyLogTreeTX, error)
}

type ReadOnlyLogTX interface {
	LogMetadata

	// Commit ensures the data read by the TX is consistent in the database. Only after Commit the
	// data read should be regarded as valid.
	Commit() error

	// Rollback discards the read-only TX.
	Rollback() error

	// Close attempts to Rollback the TX if it's open, it's a noop otherwise.
	Close() error
}

type ReadOnlyLogTreeTX interface {
	ReadOnlyTreeTX
	LeafReader
	LogRootReader
}

type ReadOnlyMapStorage interface {
	DatabaseChecker

	// Snapshot starts a read-only transaction not tied to any particular tree.
	Snapshot(ctx context.Context) (ReadOnlyMapTX, error)

	// SnapshotForTree starts a new read-only transaction.
	// Commit must be called when the caller is finished with the returned object,
	// and values read through it should only be propagated if Commit returns
	// without error.
	SnapshotForTree(ctx context.Context, treeID int64) (ReadOnlyMapTreeTX, error)
}

type ReadOnlyMapTX interface {
	// Commit ensures the data read by the TX is consistent in the database. Only after Commit the
	// data read should be regarded as valid.
	Commit() error

	// Rollback discards the read-only TX.
	Rollback() error

	// Close attempts to Rollback the TX if it's open, it's a noop otherwise.
	Close() error
}

type ReadOnlyMapTreeTX interface {
	ReadOnlyTreeTX
	MapRootReader
	Getter
}

type ReadOnlyTreeTX interface {
	NodeReader

	// ReadRevision returns the tree revision that was current at the time this
	// transaction was started.
	ReadRevision() int64

	// Commit attempts to commit any reads performed under this transaction.
	Commit() error

	// Rollback aborts this transaction.
	Rollback() error

	// Close attempts to Rollback the TX if it's open, it's a noop otherwise.
	Close() error

	// Open indicates if this transaction is open. An open transaction is one for which
	// Commit() or Rollback() has never been called. Implementations must do all clean up
	// in these methods so transactions are assumed closed regardless of the reported success.
	IsOpen() bool
}

type Setter interface {
	// Set sets key to leaf
	Set(ctx context.Context, keyHash []byte, value trillian.MapLeaf) error
}

type TreeTX interface {
	ReadOnlyTreeTX
	NodeWriter

	// WriteRevision returns the tree revision that any writes through this TreeTX will be stored at.
	WriteRevision() int64
}