feat(iavl): add KV data reader & writer, and mmap wrapper

go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/cosmos/gogoproto v1.7.2
 	github.com/cosmos/ledger-cosmos-go v1.0.0
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0
+	github.com/edsrzf/mmap-go v1.0.0
 	github.com/golang/protobuf v1.5.4
 	github.com/google/go-cmp v0.7.0
 	github.com/google/gofuzz v1.2.0

go.sum

@@ -280,6 +280,7 @@ github.com/eapache/go-xerial-snappy v0.0.0-20180814174437-776d5712da21/go.mod h1
 github.com/eapache/queue v1.1.0/go.mod h1:6eCeP0CKFpHLu8blIFXhExK/dRa7WDZfr6jVFPTqq+I=
 github.com/ebitengine/purego v0.9.1 h1:a/k2f2HQU3Pi399RPW1MOaZyhKJL9w/xFpKAg4q1s0A=
 github.com/ebitengine/purego v0.9.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/edsrzf/mmap-go v1.0.0 h1:CEBF7HpRnUCSJgGUb5h1Gm7e3VkmVDrR8lvWVLtrOFw=
 github.com/edsrzf/mmap-go v1.0.0/go.mod h1:YO35OhQPt3KJa3ryjFM5Bs14WD66h8eGKpfaBNrHW5M=
 github.com/emicklei/dot v1.8.0 h1:HnD60yAKFAevNeT+TPYr9pb8VB9bqdeSo0nzwIW6IOI=
 github.com/emicklei/dot v1.8.0/go.mod h1:DeV7GvQtIw4h2u73RKBkkFdvVAz0D9fzeJrgPW6gy/s=

iavl/internal/changeset_info.go

@@ -7,6 +7,17 @@ import (
 	"unsafe"
 )
 
+const (
+	sizeChangesetInfo = 32
+)
+
+func init() {
+	// Verify the size of ChangesetInfo is what we expect it to be at runtime.
+	if unsafe.Sizeof(ChangesetInfo{}) != sizeChangesetInfo {
+		panic(fmt.Sprintf("invalid ChangesetInfo size: got %d, want %d", unsafe.Sizeof(ChangesetInfo{}), sizeChangesetInfo))
+	}
+}
+
 // ChangesetInfo holds metadata about a changeset.
 // This mainly tracks the start and end version of the changeset and also contains statistics about orphans in the
 // changeset so that compaction can be efficiently scheduled.
@@ -34,7 +45,7 @@ type ChangesetInfo struct {
 // RewriteChangesetInfo rewrites the info file with the given changeset info.
 // This method is okay to call the first time the file is created as well.
 func RewriteChangesetInfo(file *os.File, info *ChangesetInfo) error {
-	data := unsafe.Slice((*byte)(unsafe.Pointer(info)), int(unsafe.Sizeof(*info)))
+	data := unsafe.Slice((*byte)(unsafe.Pointer(info)), sizeChangesetInfo)
 	if _, err := file.WriteAt(data, 0); err != nil {
 		return fmt.Errorf("failed to write changeset info: %w", err)
 	}
@@ -45,8 +56,7 @@ func RewriteChangesetInfo(file *os.File, info *ChangesetInfo) error {
 // ReadChangesetInfo reads changeset info from a file. It returns an empty default struct if file is empty.
 func ReadChangesetInfo(file *os.File) (*ChangesetInfo, error) {
 	var info ChangesetInfo
-	size := int(unsafe.Sizeof(info))
-	data := unsafe.Slice((*byte)(unsafe.Pointer(&info)), size)
+	data := unsafe.Slice((*byte)(unsafe.Pointer(&info)), sizeChangesetInfo)
 
 	n, err := file.ReadAt(data, 0)
 	if err == io.EOF && n == 0 {
@@ -55,8 +65,8 @@ func ReadChangesetInfo(file *os.File) (*ChangesetInfo, error) {
 	if err != nil && err != io.EOF {
 		return nil, fmt.Errorf("failed to read changeset info: %w", err)
 	}
-	if n != size {
-		return nil, fmt.Errorf("info file has unexpected size: %d, expected %d", n, size)
+	if n != sizeChangesetInfo {
+		return nil, fmt.Errorf("info file has unexpected size: %d, expected %d", n, sizeChangesetInfo)
 	}
 
 	return &info, nil

iavl/internal/file_writer.go

@@ -0,0 +1,46 @@
+package internal
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+)
+
+// FileWriter is a buffered writer that tracks the number of bytes written.
+type FileWriter struct {
+	writer  *bufio.Writer
+	written int
+}
+
+// NewFileWriter creates a new FileWriter.
+// Currently, it uses a buffer size of 512kb.
+// If we want to make that configurable, we can add a constructor with a buffer size parameter in the future.
+func NewFileWriter(file *os.File) *FileWriter {
+	const defaultBufferSize = 512 * 1024 // 512kb
+	return &FileWriter{
+		writer: bufio.NewWriterSize(file, defaultBufferSize),
+	}
+}
+
+// Write writes data to the underlying buffered writer and updates the written byte count.
+func (f *FileWriter) Write(p []byte) (n int, err error) {
+	n, err = f.writer.Write(p)
+	f.written += n
+	return n, err
+}
+
+// Flush flushes the underlying buffered writer.
+func (f *FileWriter) Flush() error {
+	if err := f.writer.Flush(); err != nil {
+		return fmt.Errorf("failed to flush writer: %w", err)
+	}
+	return nil
+}
+
+// Size returns the total number of bytes written so far.
+func (f *FileWriter) Size() int {
+	return f.written
+}
+
+var _ io.Writer = (*FileWriter)(nil)

iavl/internal/kvdata_entry.go

@@ -0,0 +1,44 @@
+package internal
+
+// KVEntryType represents the type of entry in the KV data file.
+type KVEntryType byte
+
+const (
+	// KVEntryWALStart is the first entry in an uncompacted KV data file which indicates that this KV data file
+	// can be used for WAL replay restoration. It must immediately be followed by the varint-encoded version number
+	// corresponding to the first version in this changeset.
+	KVEntryWALStart KVEntryType = 0x0
+
+	// KVEntryWALSet indicates a set operation for a key-value pair.
+	// This should be followed by:
+	//   - varint key length + key bytes, OR if KVFlagCachedKey is set, a 32-bit LE offset to a cached key
+	//   - varint value length + value bytes
+	// Offsets point to the start of the varint length field, not the type byte.
+	KVEntryWALSet KVEntryType = 0x1
+
+	// KVEntryWALDelete indicates a delete operation for a key.
+	// This should be followed by:
+	//   - varint key length + key bytes, OR if KVFlagCachedKey is set, a 32-bit LE offset to a cached key
+	// Offsets point to the start of the varint length field, not the type byte.
+	KVEntryWALDelete KVEntryType = 0x2
+
+	// KVEntryWALCommit indicates the commit operation for a version.
+	// This must be followed by a varint-encoded version number.
+	KVEntryWALCommit KVEntryType = 0x3
+
+	// KVEntryKeyBlob indicates a standalone key data entry.
+	// This should be followed by varint length + raw bytes.
+	// Used for compacted (non-WAL) leaf or branch keys not already cached.
+	KVEntryKeyBlob KVEntryType = 0x4
+
+	// KVEntryValueBlob indicates a standalone value data entry.
+	// This should be followed by varint length + raw bytes.
+	// Used for compacted (non-WAL) leaf values.
+	// The main difference between KVEntryKeyBlob and KVEntryValueBlob is that key
+	// entries may be cached for faster access, while value entries are not cached.
+	KVEntryValueBlob KVEntryType = 0x5
+
+	// KVFlagCachedKey indicates that the key for this entry is cached and should be referenced by
+	// a 32-bit little-endian offset instead of being stored inline.
+	KVFlagCachedKey KVEntryType = 0x80
+)