Skip to content

Commit f3338e3

Browse files
committed
docs(agent): correct the response-checksum rationale
The comment on the s3.Client options claimed ResponseChecksumValidation is "the only server-side integrity signal the restore path has, since downloadS3 runs with SkipHashCheck". Both halves were wrong: - SkipHashCheck is a field of etcdutl's snapshot.RestoreConfig (restore.go), covering etcd's own appended snapshot hash. downloadS3 passes no such option and has no equivalent. - The signal it credits is inert for objects this agent writes: response validation fires only when the backend returns an x-amz-checksum-* header, and pinning requests to WhenRequired means no checksum is ever stored. Leaving ResponseChecksumValidation at the SDK default is still right, so the decision stands; only the reason changes. The same wrong text was duplicated in the test comment and is corrected there too. Also trim the rationale to one home on s3RequestChecksumCalculation with pointers from the use sites, drop a commit hash that will not survive a squash-merge, and use os.DevNull instead of a hardcoded /dev/null. No behavior change: both mutation checks still fail closed (drop the client option and the single-part test fails; drop the uploader option and the multipart test fails). Assisted-By: Claude Opus 4.8 (1M context) Signed-off-by: Timofei Larkin <[email protected]>
1 parent 562193d commit f3338e3

4 files changed

Lines changed: 29 additions & 37 deletions

File tree

‎internal/agent/agent.go‎

Lines changed: 17 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -163,11 +163,9 @@ func (d destination) localPath(name string) string {
163163
// WhenSupported and never reads the client option, so setting only the client
164164
// option leaves the multipart path broken.
165165
//
166-
// Both sites are load-bearing — the client option for the single-part path and
167-
// HeadObject, the uploader option for multipart parts — and the two MUST agree.
168-
// Deriving both from this single constant is what keeps them from silently
169-
// drifting (delete either site and the RGW failure returns — for the multipart
170-
// case, invisibly).
166+
// Both sites are load-bearing and MUST agree; deriving them from this one
167+
// constant is what keeps them from drifting. Delete either and the RGW failure
168+
// returns — for the multipart case, invisibly.
171169
//
172170
// Why WhenRequired: since early 2025 aws-sdk-go-v2 defaults to WhenSupported,
173171
// which stamps a CRC32 on every PutObject/UploadPart — over HTTPS that rides as a
@@ -196,23 +194,21 @@ func (d destination) s3Client(ctx context.Context) (*s3.Client, error) {
196194
o.BaseEndpoint = aws.String(d.s3Endpoint)
197195
}
198196
o.UsePathStyle = d.s3PathStyle
199-
// Request-checksum policy for this client. This is only ONE of the two
200-
// sites that need it — the transfer manager carries its own copy for the
201-
// multipart path (see s3RequestChecksumCalculation and newSnapshotUploader).
202-
// LoadDefaultConfig would otherwise populate this from
203-
// AWS_REQUEST_CHECKSUM_CALCULATION, but the agent's environment is a closed
204-
// list built by the controller (no operator can set that var on the Pod),
205-
// so we pin it here unconditionally rather than leave an escape hatch that
206-
// nothing can reach.
207-
//
208-
// The response side (ResponseChecksumValidation) is deliberately left at
209-
// the SDK default (WhenSupported): it validates a checksum only when the
210-
// backend returns one and skips composite (multipart) checksums, so it does
211-
// not break S3-compatible backends — and it is the only server-side
212-
// integrity signal the restore path has, since downloadS3 runs with
213-
// SkipHashCheck. Pinning it to WhenRequired would silently discard that
214-
// signal, so we don't.
197+
// One of the two sites that must pin this; see
198+
// s3RequestChecksumCalculation for the full rationale and
199+
// newSnapshotUploader for the other. Pinned unconditionally because
200+
// LoadDefaultConfig would otherwise take it from
201+
// AWS_REQUEST_CHECKSUM_CALCULATION, and the agent's environment is a closed
202+
// list built by the controller — nothing can set that var on the Pod.
215203
o.RequestChecksumCalculation = s3RequestChecksumCalculation
204+
// ResponseChecksumValidation is deliberately left at the SDK default
205+
// (WhenSupported): it validates only a checksum the backend actually
206+
// returns and skips composite (multipart) ones, so it cannot break an
207+
// S3-compatible backend. It is not an integrity guarantee for restore
208+
// either — WhenRequired above means the agent stores no checksum, so for
209+
// objects it wrote there is nothing to validate and the setting is inert.
210+
// Left alone because there is no reason to change it, not because it
211+
// protects anything.
216212
}), nil
217213
}
218214

‎internal/agent/agent_test.go‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ package agent
1212

1313
import (
1414
"context"
15+
"os"
1516
"testing"
1617

1718
"github.com/aws/aws-sdk-go-v2/aws"
@@ -43,8 +44,8 @@ func TestObjectKey(t *testing.T) {
4344
// region so signing never reaches the EC2/ECS metadata endpoint.
4445
func hermeticAWSEnv(t *testing.T) {
4546
t.Helper()
46-
t.Setenv("AWS_CONFIG_FILE", "/dev/null")
47-
t.Setenv("AWS_SHARED_CREDENTIALS_FILE", "/dev/null")
47+
t.Setenv("AWS_CONFIG_FILE", os.DevNull)
48+
t.Setenv("AWS_SHARED_CREDENTIALS_FILE", os.DevNull)
4849
t.Setenv("AWS_PROFILE", "")
4950
t.Setenv("AWS_ACCESS_KEY_ID", "test")
5051
t.Setenv("AWS_SECRET_ACCESS_KEY", "test")
@@ -77,12 +78,10 @@ func TestS3ClientChecksumWhenRequired(t *testing.T) {
7778
t.Errorf("RequestChecksumCalculation = %v, want WhenRequired (%v)",
7879
o.RequestChecksumCalculation, aws.RequestChecksumCalculationWhenRequired)
7980
}
80-
// The response side is deliberately left at the SDK default (WhenSupported):
81-
// it validates only a checksum the backend actually returns and skips composite
82-
// (multipart) checksums, so it neither breaks S3-compatible backends nor needs
83-
// pinning — and it is the only server-side integrity signal the restore path
84-
// has (downloadS3 runs with SkipHashCheck). This asserts we do NOT pin it to
85-
// WhenRequired; doing so would silently discard that signal.
81+
// The response side stays at the SDK default (WhenSupported): it validates only
82+
// a checksum the backend actually returns and skips composite (multipart) ones,
83+
// so it cannot break an S3-compatible backend and needs no pinning. This asserts
84+
// we do NOT pin it, so a future "symmetry" change has to justify itself.
8685
if o.ResponseChecksumValidation != aws.ResponseChecksumValidationWhenSupported {
8786
t.Errorf("ResponseChecksumValidation = %v, want the SDK default WhenSupported (%v)",
8887
o.ResponseChecksumValidation, aws.ResponseChecksumValidationWhenSupported)

‎internal/agent/snapshot.go‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -246,12 +246,9 @@ func uploadS3Stream(ctx context.Context, dest destination, key string, body io.R
246246

247247
// newSnapshotUploader builds the S3 transfer manager for snapshot uploads.
248248
//
249-
// manager.Uploader carries its OWN RequestChecksumCalculation (NewUploader
250-
// hardcodes it to WhenSupported) and never consults the s3.Client option, so the
251-
// multipart path — taken for any body over the 5-MiB part size, i.e. every
252-
// snapshot of a non-trivial cluster — would re-stamp the CRC32 trailer that the
253-
// client option was set to avoid. Pin it here too, from the same constant
254-
// s3Client uses, so the two knobs cannot drift. See s3RequestChecksumCalculation.
249+
// manager.Uploader carries its OWN RequestChecksumCalculation and never consults
250+
// the s3.Client option, so the multipart path needs the same pin the client got.
251+
// See s3RequestChecksumCalculation for why, and why both sites are load-bearing.
255252
func newSnapshotUploader(client *s3.Client) *manager.Uploader {
256253
return manager.NewUploader(client, func(u *manager.Uploader) {
257254
u.RequestChecksumCalculation = s3RequestChecksumCalculation

‎internal/agent/snapshot_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,8 +220,8 @@ func TestUploadS3StreamMultipartNoChecksumTrailer(t *testing.T) {
220220
// than multipart. There the s3.Client option (not the uploader's) is the only
221221
// thing keeping the CRC32 trailer off — so this pins the client-side setting
222222
// end-to-end. A struct-field check on s3.Options (agent_test.go) stays green even
223-
// when the real request carries the trailer, which is exactly how commit 61144d4
224-
// looked correct while every real snapshot was broken.
223+
// when the real request carries the trailer — that gap is how a client-only pin
224+
// can look correct while every upload is still broken on the wire.
225225
func TestUploadS3StreamSinglePartNoChecksumTrailer(t *testing.T) {
226226
hermeticAWSEnv(t)
227227
endpoint, captured := startS3CaptureServer(t)

0 commit comments

Comments
 (0)