refactor(store/v2): Use Core Iterator (#18957)

Co-authored-by: marbar3778 <marbar3778@yahoo.com>
Co-authored-by: cool-developer <51834436+cool-develope@users.noreply.github.com>

core/store/store.go

@@ -30,32 +30,15 @@ type KVStore interface {
 	ReverseIterator(start, end []byte) (Iterator, error)
 }
 
-// Iterator represents an iterator over a domain of keys. Callers must call Close when done.
-// No writes can happen to a domain while there exists an iterator over it, some backends may take
-// out database locks to ensure this will not happen.
+// Iterator represents an iterator over a domain of keys. Callers must call
+// Close when done. No writes can happen to a domain while there exists an
+// iterator over it. Some backends may take out database locks to ensure this
+// will not happen.
 //
-// Callers must make sure the iterator is valid before calling any methods on it, otherwise
-// these methods will panic. This is in part caused by most backend databases using this convention.
-//
-// As with DB, keys and values should be considered read-only, and must be copied before they are
-// modified.
-//
-// Typical usage:
-//
-// var itr Iterator = ...
-// defer itr.Close()
-//
-//	for ; itr.Valid(); itr.Next() {
-//	  k, v := itr.Key(); itr.Value()
-//	  ...
-//	}
-//
-//	if err := itr.Error(); err != nil {
-//	  ...
-//	}
+// Callers must make sure the iterator is valid before calling any methods on it,
+// otherwise these methods will panic.
 type Iterator interface {
 	// Domain returns the start (inclusive) and end (exclusive) limits of the iterator.
-	// CONTRACT: start, end readonly []byte
 	Domain() (start, end []byte)
 
 	// Valid returns whether the current iterator is valid. Once invalid, the Iterator remains
@@ -67,12 +50,13 @@ type Iterator interface {
 	Next()
 
 	// Key returns the key at the current position. Panics if the iterator is invalid.
-	// CONTRACT: key readonly []byte
-	Key() (key []byte)
+	// Note, the key returned should be a copy and thus safe for modification.
+	Key() []byte
 
-	// Value returns the value at the current position. Panics if the iterator is invalid.
-	// CONTRACT: value readonly []byte
-	Value() (value []byte)
+	// Value returns the value at the current position. Panics if the iterator is
+	// invalid.
+	// Note, the value returned should be a copy and thus safe for modification.
+	Value() []byte
 
 	// Error returns the last error encountered by the iterator, if any.
 	Error() error
@@ -80,3 +64,15 @@ type Iterator interface {
 	// Close closes the iterator, releasing any allocated resources.
 	Close() error
 }
+
+// IteratorCreator defines an interface for creating forward and reverse iterators.
+type IteratorCreator interface {
+	// Iterator creates a new iterator for the given store name and domain, where
+	// domain is defined by [start, end). Note, both start and end are optional.
+	Iterator(storeKey string, start, end []byte) (Iterator, error)
+
+	// ReverseIterator creates a new reverse iterator for the given store name
+	// and domain, where domain is defined by [start, end). Note, both start and
+	// end are optional.
+	ReverseIterator(storeKey string, start, end []byte) (Iterator, error)
+}