feat(s3frontend): S3 surface — HEAD Range/Expires, ?partNumber, default checksum

- HEAD honors Range (206/Content-Range, 416 on unsatisfiable); carry the Expires header
- GET/HEAD by ?partNumber=N (part byte-span + x-amz-mp-parts-count)
- server-computed default CRC64NVME checksum when the client names none

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: frrist

bucket/cbor_gen.go

@@ -39,6 +39,13 @@ type ObjectManifest struct {
 	ContentLanguage    string `cborgen:"cl"`
 	CacheControl       string `cborgen:"cc"`
 
+	// Expires is the HTTP `Expires` caching header (RFC 7234) carried through
+	// PUT and replayed verbatim on GET/HEAD. Despite the name it is NOT object
+	// lifecycle/TTL — it never deletes the object; it is a passthrough system
+	// header like CacheControl. (Real S3 Lifecycle expiration is a separate,
+	// unimplemented feature — see docs/architecture.md §12.)
+	Expires string `cborgen:"ex"`
+
 	// Metadata is the user metadata map (the x-amz-meta-* headers, with
 	// the prefix stripped and keys lower-cased by the S3 layer). Nil when
 	// the object carries no user metadata.
@@ -60,6 +67,15 @@ type Body struct {
 	MD5    []byte    `cborgen:"m"`
 	Blobs  []BlobRef `cborgen:"bl"`
 
+	// PartSizes records the byte length of each multipart part, in upload order,
+	// segmenting [0, Size) into the parts the client completed. It lets a GET/HEAD
+	// with ?partNumber=N return part N's byte span and the x-amz-mp-parts-count
+	// header (the Blobs list alone cannot, since a part may span several blobs or
+	// share a blob boundary). Nil for a single-PUT object, which has no parts — a
+	// ?partNumber=1 there addresses the whole object and omits the parts count.
+	// The sum of PartSizes equals Size. See docs/architecture.md §7.2.
+	PartSizes []int64 `cborgen:"ps"`
+
 	// IndexRoot is reserved (nullable) for a future UnixFS + sharded-dag-index
 	// record that would make a multi-shard object reassemblable without Ingot
 	// ("credible exit"). It is unused this iteration; the flat Blobs list is

bucket/manifest.go

@@ -429,7 +429,9 @@ AbortMultipartUpload
 ```
 
 A completed multipart object is the ordered union of its parts' blobs plus a manifest of byte ranges;
-parts are not restitched.
+parts are not restitched. The commit also records each part's byte length (`Body.PartSizes`), so a
+later `GET`/`HEAD ?partNumber=N` can resolve part `N` to its byte span and report
+`x-amz-mp-parts-count` without re-deriving boundaries from the blob list.
 
 ### 7.3 The session latch (the Abort/Complete race)
 
@@ -750,9 +752,17 @@ The storage / delete / retrieval core is built and tested:
 - **Dedup + reference-counted delete** ([§5](#5-the-data-layer)–[§6](#6-the-forgechain-layer)) — `blob_refs`, overwrite-in-place, `DeleteObject`,
   `remove(digest)` at zero claims, `gc_candidates` (write-only).
 - **S3 correctness** ([§3](#3-the-s3-layer)) — conditional requests (`If-Match`/`If-None-Match`/`If-(Un)Modified-Since`,
-  re-checked at commit), additional checksums (`x-amz-checksum-*` validate + echo), `DeleteObjects`,
+  re-checked at commit), additional checksums (`x-amz-checksum-*` validate + echo, with a
+  server-computed full-object `CRC64NVME` default when the client names none — S3's
+  default-checksum-on-store), `DeleteObjects`,
   metadata-only `CopyObject`, multipart (`Create`/`UploadPart`/`Complete`/`Abort` with the
-  single-winner latch and the `-N` ETag), zero-byte objects.
+  single-winner latch and the `-N` ETag), zero-byte objects. Ranged reads return `206`/`Content-Range`
+  on **both** `GetObject` and `HeadObject` (`416` on an unsatisfiable range); the system headers
+  carried through PUT and replayed on GET/HEAD include `Content-Encoding`/`Disposition`/`Language`,
+  `Cache-Control`, and the `Expires` caching header. GET/HEAD also accept `?partNumber=N`: a completed
+  multipart object records each part's byte length on the manifest (`Body.PartSizes`), so part `N`
+  resolves to its byte span (`206` + `Content-Range` + `x-amz-mp-parts-count`); a single-PUT object
+  exposes the whole body as part 1 (no parts-count), and `N` past the part count is `416`.
 
 ### Deferred by deliberate scope decision
 
@@ -774,6 +784,15 @@ These are intentional simplifications of the target topology, not bugs:
   are recorded in a local Postgres `blob_locations` table behind a `Locator` seam, rather than read
   back through the indexing-service ([§5](#5-the-data-layer), [§8](#8-retrieval-addressing-when-bodies-need-a-sharded-dag-index)). The indexer-backed `Locator` is an `indexer-ready` swap-in.
 
+### Object lifecycle (not implemented)
+
+The `Expires` HTTP header *is* implemented — it is a passthrough caching header (RFC 7234) stored on
+the manifest and replayed on GET/HEAD, not a lifecycle control. True S3 **Lifecycle** management
+(`PutBucketLifecycleConfiguration` expiration/transition rules that actually delete or tier objects
+after N days, surfaced via the `x-amz-expiration` response header) is a separate, unimplemented
+feature. It would be its own subsystem — a per-bucket rule store plus a background sweeper driving the
+reference index — and is out of scope for this iteration.
+
 ### Deferred as forge-mode glue (validated live in smelt, not the in-process harness)
 
 The in-memory harness uses a no-op uploader and serves reads from the spool, so these forge-network

docs/architecture.md

@@ -19,7 +19,11 @@ type checksumSpec struct {
 // checksumFromInput derives the checksum to compute from a PutObject request.
 // An explicit x-amz-checksum-<alg> value takes precedence (and is validated);
 // otherwise x-amz-checksum-algorithm selects the algorithm to compute and echo.
-// Returns nil when the request carries no additional checksum.
+// When the request names no checksum at all, the server falls back to a
+// full-object CRC64NVME — S3's default-checksum-on-store behavior, which clients
+// (and the SDK) expect to read back even when they sent nothing. That fallback
+// is computed, not validated, since there is no client value. So this never
+// returns a nil spec: every stored object carries at least a CRC64NVME.
 func checksumFromInput(in s3response.PutObjectInput) (*checksumSpec, error) {
 	switch {
 	case in.ChecksumSHA256 != nil:
@@ -39,7 +43,8 @@ func checksumFromInput(in s3response.PutObjectInput) (*checksumSpec, error) {
 		}
 		return &checksumSpec{in.ChecksumAlgorithm, ht, ""}, nil
 	default:
-		return nil, nil
+		// No client checksum named → server-computed full-object CRC64NVME.
+		return &checksumSpec{types.ChecksumAlgorithmCrc64nvme, utils.HashTypeCRC64NVME, ""}, nil
 	}
 }
 

s3frontend/checksum.go

@@ -0,0 +1,63 @@
+package s3frontend
+
+import (
+	"testing"
+
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/versity/versitygw/s3api/utils"
+	"github.com/versity/versitygw/s3response"
+)
+
+// TestChecksumFromInput_DefaultsToCRC64NVME locks S3's default-checksum-on-store
+// behavior: a PutObject that names no checksum still computes (without
+// validating) a full-object CRC64NVME, while an explicitly named algorithm or
+// value takes precedence.
+func TestChecksumFromInput_DefaultsToCRC64NVME(t *testing.T) {
+	sha256 := "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="
+	algoOnly := types.ChecksumAlgorithmCrc32
+
+	cases := []struct {
+		name         string
+		in           s3response.PutObjectInput
+		wantAlgo     types.ChecksumAlgorithm
+		wantHash     utils.HashType
+		wantExpected string
+	}{
+		{
+			name:         "no checksum → default crc64nvme (compute, no validation)",
+			in:           s3response.PutObjectInput{},
+			wantAlgo:     types.ChecksumAlgorithmCrc64nvme,
+			wantHash:     utils.HashTypeCRC64NVME,
+			wantExpected: "",
+		},
+		{
+			name:         "explicit value wins over the default",
+			in:           s3response.PutObjectInput{ChecksumSHA256: &sha256},
+			wantAlgo:     types.ChecksumAlgorithmSha256,
+			wantHash:     utils.HashTypeSha256,
+			wantExpected: sha256,
+		},
+		{
+			name:         "named algorithm (no value) wins over the default",
+			in:           s3response.PutObjectInput{ChecksumAlgorithm: algoOnly},
+			wantAlgo:     types.ChecksumAlgorithmCrc32,
+			wantHash:     utils.HashTypeCRC32,
+			wantExpected: "",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			spec, err := checksumFromInput(tc.in)
+			if err != nil {
+				t.Fatalf("unexpected err: %v", err)
+			}
+			if spec == nil {
+				t.Fatal("spec = nil, want non-nil (every object carries at least a CRC64NVME)")
+			}
+			if spec.algo != tc.wantAlgo || spec.hashType != tc.wantHash || spec.expected != tc.wantExpected {
+				t.Fatalf("got {algo=%s hash=%v expected=%q}, want {algo=%s hash=%v expected=%q}",
+					spec.algo, spec.hashType, spec.expected, tc.wantAlgo, tc.wantHash, tc.wantExpected)
+			}
+		})
+	}
+}

s3frontend/checksum_test.go

@@ -85,13 +85,15 @@ func (b *Backend) CopyObject(ctx context.Context, input s3response.CopyObjectInp
 		dstMf.ContentDisposition = backend.GetStringFromPtr(input.ContentDisposition)
 		dstMf.ContentLanguage = backend.GetStringFromPtr(input.ContentLanguage)
 		dstMf.CacheControl = backend.GetStringFromPtr(input.CacheControl)
+		dstMf.Expires = backend.GetStringFromPtr(input.Expires)
 		dstMf.Metadata = input.Metadata
 	} else {
 		dstMf.ContentType = srcMf.ContentType
 		dstMf.ContentEncoding = srcMf.ContentEncoding
 		dstMf.ContentDisposition = srcMf.ContentDisposition
 		dstMf.ContentLanguage = srcMf.ContentLanguage
 		dstMf.CacheControl = srcMf.CacheControl
+		dstMf.Expires = srcMf.Expires
 		dstMf.Metadata = srcMf.Metadata
 	}
 

s3frontend/copy.go

@@ -158,6 +158,7 @@ func (b *Backend) CompleteMultipartUpload(ctx context.Context, input *s3.Complet
 	// Validate the requested parts (ascending, each matching a recorded part by
 	// number + ETag) and assemble the ordered body + the multipart ETag.
 	var blobs []msbucket.BlobRef
+	var partSizes []int64
 	var offset int64
 	etagHasher := md5.New()
 	prev := 0
@@ -178,6 +179,9 @@ func (b *Backend) CompleteMultipartUpload(ctx context.Context, input *s3.Complet
 			return s3response.CompleteMultipartUploadResult{}, "", s3err.GetAPIError(s3err.ErrInvalidPart)
 		}
 		etagHasher.Write(sp.ETagMD5)
+		// Record this part's byte span (it may span several blobs) so a later
+		// GET/HEAD ?partNumber=N can address it (§7.2).
+		partStart := offset
 		for _, d := range sp.BlobDigests {
 			in, err := b.intents.GetIntent(ctx, d)
 			if err != nil {
@@ -186,6 +190,7 @@ func (b *Backend) CompleteMultipartUpload(ctx context.Context, input *s3.Complet
 			blobs = append(blobs, msbucket.BlobRef{Digest: d, Offset: offset, Length: in.Size})
 			offset += in.Size
 		}
+		partSizes = append(partSizes, offset-partStart)
 	}
 
 	// Accept every part's blobs on Forge (no-op in the harness), then commit.
@@ -198,7 +203,7 @@ func (b *Backend) CompleteMultipartUpload(ctx context.Context, input *s3.Complet
 		Key:         key,
 		ContentType: sess.ContentType,
 		Created:     time.Now().Unix(),
-		Body:        msbucket.Body{Size: offset, Blobs: blobs},
+		Body:        msbucket.Body{Size: offset, Blobs: blobs, PartSizes: partSizes},
 		ETag:        etag,
 		Metadata:    sess.Metadata,
 	}