*: add BlobFileID

Add a BlobFileID type for identifying blob files. When we introduce rewriting
and replacing blob files, a BlobReference's file identifier may not translate
directly to a file on disk, so we should not use DiskFileNum.

Informs #112.

Author: jbowens

checkpoint.go

@@ -14,6 +14,7 @@ import (
 	"github.com/cockroachdb/pebble/internal/base"
 	"github.com/cockroachdb/pebble/internal/manifest"
 	"github.com/cockroachdb/pebble/record"
+	"github.com/cockroachdb/pebble/sstable/blob"
 	"github.com/cockroachdb/pebble/vfs"
 	"github.com/cockroachdb/pebble/vfs/atomicfs"
 )
@@ -265,7 +266,7 @@ func (d *DB) Checkpoint(
 	}
 
 	var excludedTables map[manifest.DeletedTableEntry]*manifest.TableMetadata
-	var includedBlobFiles map[base.DiskFileNum]struct{}
+	var includedBlobFiles map[base.BlobFileID]struct{}
 	var remoteFiles []base.DiskFileNum
 	// Set of TableBacking.DiskFileNum which will be required by virtual sstables
 	// in the checkpoint.
@@ -309,12 +310,17 @@ func (d *DB) Checkpoint(
 			// Copy any referenced blob files that have not already been copied.
 			if len(f.BlobReferences) > 0 {
 				if includedBlobFiles == nil {
-					includedBlobFiles = make(map[base.DiskFileNum]struct{})
+					includedBlobFiles = make(map[base.BlobFileID]struct{})
 				}
 				for _, ref := range f.BlobReferences {
-					if _, ok := includedBlobFiles[ref.FileNum]; !ok {
-						includedBlobFiles[ref.FileNum] = struct{}{}
-						ckErr = copyFile(base.FileTypeBlob, ref.FileNum)
+					if _, ok := includedBlobFiles[ref.FileID]; !ok {
+						includedBlobFiles[ref.FileID] = struct{}{}
+
+						// TODO(jackson): Perform a translation to the
+						// appropriate disk file number once we support blob
+						// file replacement.
+						diskFileNum := blob.DiskFileNumTODO(ref.FileID)
+						ckErr = copyFile(base.FileTypeBlob, diskFileNum)
 						if ckErr != nil {
 							return ckErr
 						}
@@ -352,8 +358,9 @@ func (d *DB) Checkpoint(
 	if len(includedBlobFiles) < len(versionBlobFiles) {
 		excludedBlobFiles = make(map[base.DiskFileNum]*manifest.BlobFileMetadata, len(versionBlobFiles)-len(includedBlobFiles))
 		for _, blobFile := range versionBlobFiles {
-			if _, ok := includedBlobFiles[blobFile.FileNum]; !ok {
-				excludedBlobFiles[blobFile.FileNum] = blobFile
+			if _, ok := includedBlobFiles[blobFile.FileID]; !ok {
+				diskFileNum := blob.DiskFileNumTODO(blobFile.FileID)
+				excludedBlobFiles[diskFileNum] = blobFile
 			}
 		}
 	}

compaction.go

@@ -2488,10 +2488,10 @@ func (d *DB) cleanupVersionEdit(ve *manifest.VersionEdit) {
 		obsoleteFiles.AddBlob(ve.NewBlobFiles[i])
 		d.mu.versions.zombieBlobs.Add(objectInfo{
 			fileInfo: fileInfo{
-				FileNum:  ve.NewBlobFiles[i].FileNum,
+				FileNum:  base.DiskFileNum(ve.NewBlobFiles[i].FileID),
 				FileSize: ve.NewBlobFiles[i].Size,
 			},
-			isLocal: objstorage.IsLocalBlobFile(d.objProvider, ve.NewBlobFiles[i].FileNum),
+			isLocal: objstorage.IsLocalBlobFile(d.objProvider, base.DiskFileNum(ve.NewBlobFiles[i].FileID)),
 		})
 	}
 	for i := range ve.NewTables {

data_test.go

@@ -927,7 +927,7 @@ func runDBDefineCmdReuseFS(td *datadriven.TestData, opts *Options) (*DB, error)
 	// them to the final version edit.
 	valueSeparator := &defineDBValueSeparator{
 		pbr:   &preserveBlobReferences{},
-		metas: make(map[base.DiskFileNum]*manifest.BlobFileMetadata),
+		metas: make(map[base.BlobFileID]*manifest.BlobFileMetadata),
 	}
 
 	var mem *memTable
@@ -1173,8 +1173,8 @@ func runDBDefineCmdReuseFS(td *datadriven.TestData, opts *Options) (*DB, error)
 			return nil, err
 		}
 		for f, stats := range fileStats {
-			valueSeparator.metas[f].Size = stats.FileLen
-			valueSeparator.metas[f].ValueSize = stats.UncompressedValueBytes
+			valueSeparator.metas[base.BlobFileID(f)].Size = stats.FileLen
+			valueSeparator.metas[base.BlobFileID(f)].ValueSize = stats.UncompressedValueBytes
 		}
 
 		ve.NewBlobFiles = slices.Collect(maps.Values(valueSeparator.metas))
@@ -1640,7 +1640,7 @@ func describeLSM(d *DB, verbose bool) string {
 	if blobFileMetas := d.mu.versions.blobFiles.Metadatas(); len(blobFileMetas) > 0 {
 		buf.WriteString("Blob files:\n")
 		for _, meta := range blobFileMetas {
-			fmt.Fprintf(&buf, "  %s: %d physical bytes, %d value bytes\n", meta.FileNum, meta.Size, meta.ValueSize)
+			fmt.Fprintf(&buf, "  %s: %d physical bytes, %d value bytes\n", meta.FileID, meta.Size, meta.ValueSize)
 		}
 	}
 	return buf.String()

event.go

@@ -19,6 +19,7 @@ import (
 	"github.com/cockroachdb/pebble/internal/manifest"
 	"github.com/cockroachdb/pebble/objstorage"
 	"github.com/cockroachdb/pebble/objstorage/remote"
+	"github.com/cockroachdb/pebble/sstable/blob"
 	"github.com/cockroachdb/pebble/vfs"
 	"github.com/cockroachdb/redact"
 )
@@ -1234,8 +1235,9 @@ func (d *DB) reportCorruption(meta any, err error) error {
 	case *manifest.TableMetadata:
 		return d.reportFileCorruption(base.FileTypeTable, meta.TableBacking.DiskFileNum, meta.UserKeyBounds(), err)
 	case *manifest.BlobFileMetadata:
+		diskFileNum := blob.DiskFileNumTODO(meta.FileID)
 		// TODO(jackson): Add bounds for blob files.
-		return d.reportFileCorruption(base.FileTypeBlob, meta.FileNum, base.UserKeyBounds{}, err)
+		return d.reportFileCorruption(base.FileTypeBlob, diskFileNum, base.UserKeyBounds{}, err)
 	default:
 		panic(fmt.Sprintf("unknown metadata type: %T", meta))
 	}

internal/base/filenames.go

@@ -44,6 +44,21 @@ func PhysicalTableFileNum(f DiskFileNum) TableNum {
 	return TableNum(f)
 }
 
+// BlobFileID is an internal identifier for a blob file.
+//
+// Initially there exists a physical blob file with a DiskFileNum that equals
+// the value of the BlobFileID. However, if the blob file is replaced, the
+// manifest.Version may re-map the BlobFileID to a new DiskFileNum.
+type BlobFileID uint64
+
+// String returns a string representation of the blob file ID.
+func (id BlobFileID) String() string { return fmt.Sprintf("%06d", id) }
+
+// SafeFormat implements redact.SafeFormatter.
+func (id BlobFileID) SafeFormat(w redact.SafePrinter, _ rune) {
+	w.Printf("%06d", redact.SafeUint(id))
+}
+
 // A DiskFileNum identifies a file or object with exists on disk.
 type DiskFileNum uint64
 

internal/base/lazy_value.go

@@ -163,9 +163,9 @@ type LazyFetcher struct {
 	Fetcher ValueFetcher
 	// Attribute includes the short attribute and value length.
 	Attribute AttributeAndLen
-	// BlobFileNum identifies the blob file containing the value. It is only
+	// BlobFileID identifies the blob file containing the value. It is only
 	// populated if the value is stored in a blob file.
-	BlobFileNum DiskFileNum
+	BlobFileID BlobFileID
 }
 
 // ValueFetcher is an interface for fetching a value.
@@ -182,7 +182,7 @@ type ValueFetcher interface {
 	// will allocate a new slice for the value. In either case it will set
 	// callerOwned to true.
 	Fetch(
-		ctx context.Context, handle []byte, blobFileNum DiskFileNum, valLen uint32, buf []byte,
+		ctx context.Context, handle []byte, blobFileID BlobFileID, valLen uint32, buf []byte,
 	) (val []byte, callerOwned bool, err error)
 }
 
@@ -193,7 +193,7 @@ func (lv *LazyValue) Value(buf []byte) (val []byte, callerOwned bool, err error)
 		return lv.ValueOrHandle, false, nil
 	}
 	return f.Fetcher.Fetch(context.TODO(),
-		lv.ValueOrHandle, f.BlobFileNum, f.Attribute.ValueLen, buf)
+		lv.ValueOrHandle, f.BlobFileID, f.Attribute.ValueLen, buf)
 }
 
 // Len returns the length of the value.
@@ -237,9 +237,9 @@ func (lv *LazyValue) Clone(buf []byte, fetcher *LazyFetcher) (LazyValue, []byte)
 	var lvCopy LazyValue
 	if lv.Fetcher != nil {
 		*fetcher = LazyFetcher{
-			Fetcher:     lv.Fetcher.Fetcher,
-			Attribute:   lv.Fetcher.Attribute,
-			BlobFileNum: lv.Fetcher.BlobFileNum,
+			Fetcher:    lv.Fetcher.Fetcher,
+			Attribute:  lv.Fetcher.Attribute,
+			BlobFileID: lv.Fetcher.BlobFileID,
 			// Not copying anything that has been extracted.
 		}
 		lvCopy.Fetcher = fetcher
@@ -266,8 +266,8 @@ var _ ValueFetcher = errValueFetcher{}
 
 // Fetch implements base.ValueFetcher.
 func (e errValueFetcher) Fetch(
-	_ context.Context, _ []byte, blobFileNum DiskFileNum, valLen uint32, _ []byte,
+	_ context.Context, _ []byte, blobFileID BlobFileID, valLen uint32, _ []byte,
 ) (val []byte, callerOwned bool, err error) {
-	err = AssertionFailedf("unexpected blob value: %d-byte from %s", valLen, blobFileNum)
+	err = AssertionFailedf("unexpected blob value: %d-byte from %s", valLen, blobFileID)
 	return nil, false, err
 }

internal/base/lazy_value_test.go

@@ -14,12 +14,12 @@ import (
 )
 
 type valueFetcherFunc func(
-	handle []byte, blobFileNum DiskFileNum, valLen uint32, buf []byte) (val []byte, callerOwned bool, err error)
+	handle []byte, blobFileID BlobFileID, valLen uint32, buf []byte) (val []byte, callerOwned bool, err error)
 
 func (v valueFetcherFunc) Fetch(
-	ctx context.Context, handle []byte, blobFileNum DiskFileNum, valLen uint32, buf []byte,
+	ctx context.Context, handle []byte, blobFileID BlobFileID, valLen uint32, buf []byte,
 ) (val []byte, callerOwned bool, err error) {
-	return v(handle, blobFileNum, valLen, buf)
+	return v(handle, blobFileID, valLen, buf)
 }
 
 func TestLazyValue(t *testing.T) {
@@ -54,15 +54,15 @@ func TestLazyValue(t *testing.T) {
 			ValueOrHandle: []byte("foo-handle"),
 			Fetcher: &LazyFetcher{
 				Fetcher: valueFetcherFunc(
-					func(handle []byte, blobFileNum DiskFileNum, valLen uint32, buf []byte) ([]byte, bool, error) {
+					func(handle []byte, blobFileID BlobFileID, valLen uint32, buf []byte) ([]byte, bool, error) {
 						numCalls++
 						require.Equal(t, []byte("foo-handle"), handle)
 						require.Equal(t, uint32(3), valLen)
-						require.Equal(t, DiskFileNum(90), blobFileNum)
+						require.Equal(t, BlobFileID(90), blobFileID)
 						return fooBytes1, callerOwned, nil
 					}),
-				Attribute:   AttributeAndLen{ValueLen: 3, ShortAttribute: 7},
-				BlobFileNum: 90,
+				Attribute:  AttributeAndLen{ValueLen: 3, ShortAttribute: 7},
+				BlobFileID: 90,
 			},
 		}
 		require.Equal(t, []byte("foo"), getValue(fooLV3, callerOwned))

internal/base/value.go

@@ -31,7 +31,7 @@ func MakeInPlaceValue(val []byte) InternalValue {
 // to a value stored externally in a blob file.
 func (v *InternalValue) IsBlobValueHandle() bool {
 	f := v.lazyValue.Fetcher
-	return f != nil && f.BlobFileNum > 0
+	return f != nil && f.BlobFileID > 0
 }
 
 // IsInPlaceValue returns true iff the value was stored in-place and does not

internal/blobtest/handles.go

@@ -26,8 +26,8 @@ import (
 type Values struct {
 	References References
 
-	mostRecentFileNum base.DiskFileNum
-	mostRecentHandles map[base.DiskFileNum]blob.Handle
+	mostRecentBlobFileID base.BlobFileID
+	mostRecentHandles    map[base.BlobFileID]blob.Handle
 	// trackedHandles maps from a blob handle to its value. The value may be nil
 	// if the value was not specified (in which case Fetch will
 	// deterministically derive a random value from the handle itself.)
@@ -36,18 +36,18 @@ type Values struct {
 
 // Fetch returns the value corresponding to the given handle.
 func (bv *Values) Fetch(
-	ctx context.Context, handleSuffix []byte, blobFileNum base.DiskFileNum, valLen uint32, _ []byte,
+	ctx context.Context, handleSuffix []byte, blobFileID base.BlobFileID, valLen uint32, _ []byte,
 ) (val []byte, callerOwned bool, err error) {
 	if bv.trackedHandles == nil {
 		return nil, false, errors.New("no tracked handles")
 	}
 
 	decodedHandleSuffix := blob.DecodeHandleSuffix(handleSuffix)
 	decodedHandle := blob.Handle{
-		FileNum:  blobFileNum,
-		ValueLen: valLen,
-		BlockID:  decodedHandleSuffix.BlockID,
-		ValueID:  decodedHandleSuffix.ValueID,
+		BlobFileID: blobFileID,
+		ValueLen:   valLen,
+		BlockID:    decodedHandleSuffix.BlockID,
+		ValueID:    decodedHandleSuffix.ValueID,
 	}
 
 	value, ok := bv.trackedHandles[decodedHandle]
@@ -64,7 +64,7 @@ func (bv *Values) Fetch(
 }
 
 func deriveValueFromHandle(handle blob.Handle) []byte {
-	rng := rand.New(rand.NewPCG((uint64(handle.FileNum)<<32)|uint64(handle.BlockID), uint64(handle.ValueID)))
+	rng := rand.New(rand.NewPCG((uint64(handle.BlobFileID)<<32)|uint64(handle.BlockID), uint64(handle.ValueID)))
 	b := make([]byte, handle.ValueLen)
 	for i := range b {
 		b[i] = 'a' + byte(rng.IntN(26))
@@ -97,7 +97,7 @@ func (bv *Values) ParseInternalValue(input string) (base.InternalValue, error) {
 				// TODO(jackson): Support user-specified short attributes.
 				ShortAttribute: base.ShortAttribute(h.ValueLen & 0x07),
 			},
-			BlobFileNum: h.FileNum,
+			BlobFileID: h.BlobFileID,
 		},
 	}), nil
 }
@@ -113,7 +113,7 @@ func IsBlobHandle(input string) bool {
 func (bv *Values) Parse(input string) (h blob.Handle, remaining string, err error) {
 	if bv.trackedHandles == nil {
 		bv.trackedHandles = make(map[blob.Handle]string)
-		bv.mostRecentHandles = make(map[base.DiskFileNum]blob.Handle)
+		bv.mostRecentHandles = make(map[base.BlobFileID]blob.Handle)
 	}
 
 	defer func() {
@@ -136,7 +136,7 @@ func (bv *Values) Parse(input string) (h blob.Handle, remaining string, err erro
 			done = true
 		case "fileNum":
 			p.Expect("=")
-			h.FileNum = p.DiskFileNum()
+			h.BlobFileID = base.BlobFileID(p.Uint64())
 			fileNumSet = true
 		case "blockID":
 			p.Expect("=")
@@ -162,13 +162,13 @@ func (bv *Values) Parse(input string) (h blob.Handle, remaining string, err erro
 	}
 
 	if !fileNumSet {
-		h.FileNum = bv.mostRecentFileNum
+		h.BlobFileID = bv.mostRecentBlobFileID
 	}
 	if !blockIDSet {
-		h.BlockID = bv.mostRecentHandles[h.FileNum].BlockID
+		h.BlockID = bv.mostRecentHandles[h.BlobFileID].BlockID
 	}
 	if !valueIDSet {
-		if recentHandle, ok := bv.mostRecentHandles[h.FileNum]; ok {
+		if recentHandle, ok := bv.mostRecentHandles[h.BlobFileID]; ok {
 			h.ValueID = recentHandle.ValueID + 1
 		} else {
 			h.ValueID = 0
@@ -181,8 +181,8 @@ func (bv *Values) Parse(input string) (h blob.Handle, remaining string, err erro
 			h.ValueLen = 12
 		}
 	}
-	bv.mostRecentFileNum = h.FileNum
-	bv.mostRecentHandles[h.FileNum] = h
+	bv.mostRecentBlobFileID = h.BlobFileID
+	bv.mostRecentHandles[h.BlobFileID] = h
 	bv.trackedHandles[h] = value
 	return h, p.Remaining(), nil
 }
@@ -201,7 +201,7 @@ func (bv *Values) ParseInlineHandle(
 	}
 	h = blob.InlineHandle{
 		InlineHandlePreface: blob.InlineHandlePreface{
-			ReferenceID: bv.References.MapToReferenceID(fullHandle.FileNum),
+			ReferenceID: bv.References.MapToReferenceID(fullHandle.BlobFileID),
 			ValueLen:    fullHandle.ValueLen,
 		},
 		HandleSuffix: blob.HandleSuffix{
@@ -223,7 +223,8 @@ func (bv *Values) WriteFiles(
 	// Organize the handles by file number.
 	files := make(map[base.DiskFileNum][]blob.Handle)
 	for handle := range bv.trackedHandles {
-		files[handle.FileNum] = append(files[handle.FileNum], handle)
+		diskFileNum := base.DiskFileNum(handle.BlobFileID)
+		files[diskFileNum] = append(files[diskFileNum], handle)
 	}
 
 	stats := make(map[base.DiskFileNum]blob.FileWriterStats)
@@ -251,10 +252,10 @@ func (bv *Values) WriteFiles(
 			prevID++
 			for prevID < int(handle.ValueID) {
 				writer.AddValue(deriveValueFromHandle(blob.Handle{
-					FileNum:  fileNum,
-					BlockID:  handle.BlockID,
-					ValueID:  blob.BlockValueID(prevID),
-					ValueLen: 12,
+					BlobFileID: base.BlobFileID(fileNum),
+					BlockID:    handle.BlockID,
+					ValueID:    blob.BlockValueID(prevID),
+					ValueLen:   12,
 				}))
 				prevID++
 			}
@@ -287,17 +288,17 @@ func errFromPanic(r any) error {
 // each file number to a reference index (encoded within the
 // blob.InlineHandlePreface).
 type References struct {
-	fileNums []base.DiskFileNum
+	fileIDs []base.BlobFileID
 }
 
 // MapToReferenceID maps the given file number to a reference ID.
-func (b *References) MapToReferenceID(fileNum base.DiskFileNum) blob.ReferenceID {
-	for i, fn := range b.fileNums {
-		if fn == fileNum {
+func (b *References) MapToReferenceID(fileID base.BlobFileID) blob.ReferenceID {
+	for i, fn := range b.fileIDs {
+		if fn == fileID {
 			return blob.ReferenceID(i)
 		}
 	}
-	i := uint32(len(b.fileNums))
-	b.fileNums = append(b.fileNums, fileNum)
+	i := uint32(len(b.fileIDs))
+	b.fileIDs = append(b.fileIDs, fileID)
 	return blob.ReferenceID(i)
 }