HDDS-15356. Addendum: Make multi-buffer chunk checksum allocation-free

[smengcl]

What changes were proposed in this pull request?

This is a follow-up to #10350.

The checksum walkers process each underlying ByteBuffer from its current position to its limit. Therefore, the input ChunkBuffer must be prepared for reading, and these ranges must represent the logical checksum data.

This change:

• documents the read-ready ChunkBuffer requirement;
• validates that the underlying readable ranges match ChunkBuffer.remaining();
• validates cached input before an early return or cache mutation;
• prevents invalid input from returning stale cached checksums or corrupting reusable cache state; and
• adds regression tests for direct and cached checksum calculation.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-15356

How was this patch tested?

• 31 checksum unit tests passed: TestChecksum, TestChecksumCache, and TestChecksumMultiBuffer.
• Checkstyle passed all 58 goals.
• The -Pdist Javadoc lifecycle passed all 148 goals with warnings treated as errors and source release 25.
• SpotBugs completed with zero findings.
• git diff --check passed.

Generated-by: Codex (GPT-5.6 Sol)

[Copilot]

Pull request overview

This PR is a follow-up to HDDS-15356 that hardens multi-buffer ChunkBuffer checksum computation by documenting and enforcing the “read-ready” contract, and by adding regression tests to ensure invalid buffer states cannot return stale cached checksums or corrupt cache state.

Changes:

• Documented that Checksum.computeChecksum(ChunkBuffer, ...) expects underlying ByteBuffer ranges [position(), limit()) to represent the logical checksum data.
• Added runtime validation that ChunkBuffer.remaining() matches the sum of remaining() across underlying buffers (both direct and cached checksum paths).
• Added unit tests covering invalid incremental/write-mode buffers and ensuring cache state is not modified on rejected input.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
hadoop-hdds/common/src/main/java/org/apache/hadoop/ozone/common/ChecksumCache.java	Validates readable underlying buffer ranges before using/returning cached checksums.
hadoop-hdds/common/src/main/java/org/apache/hadoop/ozone/common/Checksum.java	Documents the read-ready input requirement and validates processed bytes in the direct (no-cache) walker.
hadoop-hdds/common/src/test/java/org/apache/hadoop/ozone/common/TestChecksumCache.java	Adds regression tests for rejecting invalid buffers and ensuring rejection does not mutate cache.
hadoop-hdds/common/src/test/java/org/apache/hadoop/ozone/common/TestChecksum.java	Adds a regression test ensuring incremental buffers in write mode are rejected (cached and uncached).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jojochuang]

The PR makes computeChecksum(ChunkBuffer) fail fast when the buffer’s logical byte count doesn’t match what its underlying ByteBuffers actually expose as readable, so callers can’t get wrong or stale checksums after passing an unprepared (typically mid-write incremental) buffer.

This PR tightens up the contract of the chunk buffer. Not strictly a regression because we don't have code that uses the incremental chunk buffer in write mode.

[jojochuang]

it would be a nice-to-have to refactor this check into a helper method and let ChecksumCache to reuse it too.

static void validateReadableChunkBuffer(ChunkBuffer data) {
  final int expected = data.remaining();
  long readable = 0;
  for (ByteBuffer buffer : data.asByteBufferList()) {
    readable += buffer.remaining();
  }
  Preconditions.checkState(readable == expected,
      "ChunkBuffer remaining byte count is %s, but its underlying buffers expose %s bytes",
      expected, readable);
}