s3keys: export ParseBlobKey for offline blob-key consumers

The Phase 0a logical-backup decoder (internal/backup) needs to route
each !s3|blob| record to its assembled object body without holding a
live cluster. Today the package only exports parsers for object
manifests and upload parts; blob keys are constructable via
BlobKey / VersionedBlobKey but not parseable.

ParseBlobKey decodes the 6-component form (BlobKey output) and the
7-component form (VersionedBlobKey output with partVersion != 0)
into all components: bucket, generation, object, uploadID, partNo,
chunkNo, partVersion. Truncated keys, malformed segments, and trailers
that aren't either zero bytes or exactly one u64 are rejected with
ok=false.

Implementation is split into parseBlobKeyHead (the 6-component head)
and parseOptionalPartVersion (the trailer) so cyclomatic complexity
stays under the package cap without a //nolint marker.

Tests cover the un-versioned round-trip, versioned round-trip,
partVersion=0 fallback to un-versioned shape (matching
VersionedBlobKey's documented behaviour), rejection of non-blob keys
(bucket meta, object manifest, upload part, junk), and rejection of
trailing-garbage keys.

Author: bootjp

internal/s3keys/keys.go

@@ -241,6 +241,88 @@ func ObjectManifestScanStart(bucket string, generation uint64, objectPrefix stri
 	return out
 }
 
+// ParseBlobKey decodes a !s3|blob| key into its components. Both the
+// 6-component form produced by BlobKey and the 7-component form
+// produced by VersionedBlobKey (with partVersion != 0) are supported;
+// partVersion is reported as zero for the un-versioned form.
+//
+// Returns ok=false on any parse failure (truncated key, malformed
+// segment, junk trailer). Used by the offline backup decoder
+// (internal/backup) to route blob chunks to their assembled object,
+// and by future readers that need to walk the blob keyspace without
+// holding a live cluster.
+func ParseBlobKey(key []byte) (bucket string, generation uint64, object string, uploadID string, partNo uint64, chunkNo uint64, partVersion uint64, ok bool) {
+	if !bytes.HasPrefix(key, blobPrefixBytes) {
+		return "", 0, "", "", 0, 0, 0, false
+	}
+	parts, ok := parseBlobKeyHead(key)
+	if !ok {
+		return "", 0, "", "", 0, 0, 0, false
+	}
+	partVersion, ok = parseOptionalPartVersion(key, parts.next)
+	if !ok {
+		return "", 0, "", "", 0, 0, 0, false
+	}
+	return parts.bucket, parts.generation, parts.object, parts.uploadID, parts.partNo, parts.chunkNo, partVersion, true
+}
+
+// parsedBlobHead is the 6-component head of a blob key. The optional
+// partVersion trailer is parsed separately so cyclomatic complexity
+// stays under the package cap.
+type parsedBlobHead struct {
+	bucket     string
+	generation uint64
+	object     string
+	uploadID   string
+	partNo     uint64
+	chunkNo    uint64
+	next       int
+}
+
+func parseBlobKeyHead(key []byte) (parsedBlobHead, bool) {
+	var p parsedBlobHead
+	bucketRaw, next, ok := decodeSegment(key, len(blobPrefixBytes))
+	if !ok {
+		return p, false
+	}
+	if p.generation, next, ok = readU64(key, next); !ok {
+		return p, false
+	}
+	objectRaw, next, ok := decodeSegment(key, next)
+	if !ok {
+		return p, false
+	}
+	uploadIDRaw, next, ok := decodeSegment(key, next)
+	if !ok {
+		return p, false
+	}
+	if p.partNo, next, ok = readU64(key, next); !ok {
+		return p, false
+	}
+	if p.chunkNo, next, ok = readU64(key, next); !ok {
+		return p, false
+	}
+	p.bucket = string(bucketRaw)
+	p.object = string(objectRaw)
+	p.uploadID = string(uploadIDRaw)
+	p.next = next
+	return p, true
+}
+
+func parseOptionalPartVersion(key []byte, offset int) (uint64, bool) {
+	switch {
+	case offset == len(key):
+		return 0, true
+	case len(key)-offset == u64Bytes:
+		v, next, ok := readU64(key, offset)
+		if !ok || next != len(key) {
+			return 0, false
+		}
+		return v, true
+	}
+	return 0, false
+}
+
 func ParseObjectManifestKey(key []byte) (bucket string, generation uint64, object string, ok bool) {
 	if !bytes.HasPrefix(key, objectManifestPrefixBytes) {
 		return "", 0, "", false

internal/s3keys/keys_test.go

@@ -117,6 +117,76 @@ func TestParseUploadPartKey_ZeroBytesInSegments(t *testing.T) {
 	require.Equal(t, uint64(3), partNo)
 }
 
+func TestParseBlobKey_UnversionedRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	bucket := "photos"
+	gen := uint64(7)
+	object := "2026/04/img.jpg"
+	uploadID := "u-abc"
+	partNo := uint64(3)
+	chunkNo := uint64(5)
+
+	key := BlobKey(bucket, gen, object, uploadID, partNo, chunkNo)
+	gotBucket, gotGen, gotObject, gotUpload, gotPart, gotChunk, gotVersion, ok := ParseBlobKey(key)
+	require.True(t, ok)
+	require.Equal(t, bucket, gotBucket)
+	require.Equal(t, gen, gotGen)
+	require.Equal(t, object, gotObject)
+	require.Equal(t, uploadID, gotUpload)
+	require.Equal(t, partNo, gotPart)
+	require.Equal(t, chunkNo, gotChunk)
+	require.Equal(t, uint64(0), gotVersion, "unversioned blob key must report partVersion=0")
+}
+
+func TestParseBlobKey_VersionedRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	key := VersionedBlobKey("b", 1, "o", "u", 2, 3, 9)
+	_, _, _, _, gotPart, gotChunk, gotVersion, ok := ParseBlobKey(key)
+	require.True(t, ok)
+	require.Equal(t, uint64(2), gotPart)
+	require.Equal(t, uint64(3), gotChunk)
+	require.Equal(t, uint64(9), gotVersion)
+}
+
+func TestParseBlobKey_VersionedZeroFallsBackToUnversioned(t *testing.T) {
+	t.Parallel()
+
+	// VersionedBlobKey(partVersion=0) is documented to fall back to
+	// the un-versioned shape; ParseBlobKey must agree.
+	key := VersionedBlobKey("b", 1, "o", "u", 2, 3, 0)
+	require.True(t, bytes.Equal(key, BlobKey("b", 1, "o", "u", 2, 3)))
+	_, _, _, _, _, _, gotVersion, ok := ParseBlobKey(key)
+	require.True(t, ok)
+	require.Equal(t, uint64(0), gotVersion)
+}
+
+func TestParseBlobKey_RejectsNonBlob(t *testing.T) {
+	t.Parallel()
+
+	cases := [][]byte{
+		BucketMetaKey("b"),
+		ObjectManifestKey("b", 1, "o"),
+		UploadPartKey("b", 1, "o", "u", 1),
+		[]byte("not-a-key"),
+	}
+	for _, k := range cases {
+		_, _, _, _, _, _, _, ok := ParseBlobKey(k)
+		require.False(t, ok, "expected ParseBlobKey to reject %q", k)
+	}
+}
+
+func TestParseBlobKey_RejectsTrailingGarbage(t *testing.T) {
+	t.Parallel()
+
+	key := BlobKey("b", 1, "o", "u", 2, 3)
+	bad := append([]byte{}, key...)
+	bad = append(bad, 0x00, 0x00, 0x00, 0x00) // 4 trailing bytes -- not 0 and not u64Bytes
+	_, _, _, _, _, _, _, ok := ParseBlobKey(bad)
+	require.False(t, ok)
+}
+
 func TestParseUploadPartKey_RejectsNonPartKeys(t *testing.T) {
 	t.Parallel()