Report listing checksums consistently, add WithRestoreStatus

[klauspost]

S3 returns <ChecksumAlgorithm> and <ChecksumType> on ListObjects, ListObjectsV2 and ListObjectVersions for every object that has a checksum. It is ungated — no header or query parameter — and the checksum value itself is never returned. AiStor additionally returns the values when listing with WithMetadata.

Changes

• Fix: xxhash checksums were silently dropped from non-versioned listings. ObjectInfo was missing the all-caps ChecksumXXHASH64/3/128 xml tags that Version, ObjectPart and CompletePart already carry. encoding/xml matches element names case-sensitively, so <ChecksumXXHASH64> never matched. The fields were dead; no server has ever emitted the mixed-case spelling.
• Fill in ObjectInfo.ChecksumAlgorithm from the checksum value when the server does not name the algorithm. AWS never sends x-amz-checksum-algorithm on HEAD/GET, so StatObject left it empty while listings set it. A server-supplied value is never overwritten.
• Add ObjectInfo.Checksum(ChecksumType) string, matching the existing ObjectPart.Checksum.
• Add ListObjectsOptions.WithRestoreStatus, which sends x-amz-optional-object-attributes: RestoreStatus on all three list APIs and reports the reply in ObjectInfo.Restore — the field StatObject already fills from x-amz-restore. Caller headers set via ListObjectsOptions.Set are cloned, not mutated.

No API breakage: ObjectInfo is decode-only (xml.Marshal on it already fails on StringMap), JSON keys are unchanged, and the new fields and method are additive.

Verified

Against AWS S3 (us-east-2) and AiStor.

• x-amz-optional-object-attributes accepts only RestoreStatus; Checksum is rejected with InvalidArgument. Checksum algorithm and type come back on plain listings with no header.
• Objects stored under CRC32/CRC32C/SHA1/SHA256/CRC64NVME/MD5/SHA512/XXHASH64/XXHASH3/XXHASH128 report the right algorithm and mode on all three list APIs; a multipart upload reports COMPOSITE. AiStor with WithMetadata returns matching values, xxhash included.
• WithRestoreStatus against a GLACIER object mid-restore returns OngoingRestore: true, and after an expedited restore completed, OngoingRestore: false with ExpiryTime set. Absent when not requested. Same on V1, V2 and versions. AiStor ignores the header and returns a normal listing.

New unit tests: TestListObjectsChecksums, TestListObjectsWithRestoreStatus, TestToObjectInfoChecksumAlgorithm. New functional test: testListObjectsChecksums, plus a WithRestoreStatus variant in testListObjects.

Summary by CodeRabbit

• New Features

  • Added support for requesting restore status when listing objects and object versions.
  • Added restore status and expiry details to object metadata.
  • Added access to XXHash checksum values and automatic checksum algorithm detection.
  • Checksum information is now available across standard, versioned, multipart, and metadata-enabled listings.

• Bug Fixes

  • Improved parsing of restore and checksum fields from service responses.

• Tests

  • Added coverage for restore status requests and checksum handling across listing APIs.

[klauspost]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 1cba0655-953f-4e1f-ae48-f540e6c37a84

📥 Commits

Reviewing files that changed from the base of the PR and between 03d1c6d and 21d1d63.

⛔ Files ignored due to path filters (2)

• examples/minio/go.sum is excluded by !**/*.sum
• examples/s3/go.sum is excluded by !**/*.sum

📒 Files selected for processing (3)

• examples/minio/go.mod
• examples/s3/go.mod
• functional_tests.go

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds restore-status request support and XML mappings across listing APIs. It adds checksum lookup and algorithm derivation for object metadata, propagates restore data from version listings, and expands unit and functional test coverage.

Changes

Listing metadata support

Layer / File(s)	Summary
Metadata contracts and restore request options api-datatypes.go, api-s3-datatypes.go, constants.go, api-list.go, api-list_test.go, functional_tests.go	Restore and checksum fields now use service XML names. ListObjectsOptions.WithRestoreStatus adds the optional restore-status header without mutating caller headers. Tests cover request headers and restore parsing.
Listing response propagation api-list.go, api-list_test.go	Regular, V2, and versioned listings propagate restore metadata and derive checksum algorithms for each ObjectInfo.
Checksum conversion and integration validation checksum.go, utils.go, utils_test.go, functional_tests.go, examples/*/go.mod	ObjectInfo.Checksum and checksum algorithm derivation support object conversion and listing results. Unit and functional tests cover checksum modes, values, multipart objects, listing variants, and updated example dependencies.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ListObjectsOptions
  participant ListingAPI
  participant ObjectInfo
  Client->>ListObjectsOptions: Set WithRestoreStatus
  ListObjectsOptions->>ListingAPI: Add RestoreStatus request header
  ListingAPI->>ObjectInfo: Parse restore and checksum XML fields
  ObjectInfo->>ObjectInfo: Derive ChecksumAlgorithm
  ListingAPI-->>Client: Yield populated ObjectInfo

Loading

Merge Risk: ⚪ Minimal · up to 21d1d

No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes both primary changes: consistent checksum reporting for listings and the addition of WithRestoreStatus.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 8 files. (3 skipped: 2 u…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Warning

Some tools did not complete. Review the errors below.

🔧 golangci-lint (2.13.2)

level=error msg="Running error: context loading failed: no go files to analyze: running go mod tidy may solve the problem"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{I twitch my nose at RestoreStatus bright
Checksum fields now parse just right
Through versioned lists the values flow
Algorithms bloom where headers show
Tests hop lightly, ears held high
Clean metadata dances by
A carrot toast beneath the sky}

_{Comment @coderabbitai help to get the list of available commands.}