[feat][bk] Add per-read no-read-ahead hint

[Denovo1998]

Descriptions of the changes in this PR:

Fix #xyz

Main Issue: #xyz

BP: #xyz

Motivation

Pulsar delayed delivery uses BucketDelayedDeliveryTracker when there are too many delayed messages to keep all delayed indexes in broker memory. In that mode, delayed indexes are persisted as bucket snapshot segments in BookKeeper, and the broker lazily loads the next snapshot segment entry only after the current segment has been drained by time-driven delivery.

This access pattern is a sparse point-read workload, not a normal sequential scan. A single lazy-load read for snapshot entry N can currently trigger bookie-side dbStorage_readAheadCache prefill for N+1, N+2, and later entries, but those entries may not be read until much later, or may be evicted before use. This can waste bookie IO and direct memory, and can pollute the read-ahead cache needed by ordinary sequential reads such as backlog consumption, catch-up reads, and ledger scans.

This change adds a per-read no-read-ahead hint so callers such as Pulsar can opt out only for these point-read paths while preserving the default read-ahead behavior for normal sequential workloads.

Changes

• Add ReadOptions with ReadOptions.DEFAULT and ReadOptions.builder().disableReadAhead(true).build() for request-scoped read options.
• Add ReadOptions overloads to ReadHandle and LedgerHandle, including legacy callback APIs and unconfirmed read APIs that share the same internal read path.
• Propagate the hint from PendingReadOp to bookies through a new BookieProtocol.FLAG_NO_READ_AHEAD bit.
• Extend v3 protobuf read requests with ReadRequest.readFlags so bitmask-style read flags can coexist with the existing single-value ReadRequest.flag enum.
• Pass the no-read-ahead hint through v2/v3 read processors into Bookie.readEntry(..., noReadAhead).
• Add bookie, ledger descriptor, and ledger storage read overloads while keeping existing methods defaulting to normal read-ahead behavior.
• Update DbLedgerStorage / SingleDirectoryDbLedgerStorage so noReadAhead=true still uses and populates the target entry cache, but skips the extra fillReadAheadCache(...) prefill for following entries.
• Add focused tests for storage read-cache behavior, protocol flag propagation, request processor handling, and client-side PendingReadOp flag construction.

[Denovo1998]

@zymap @lhotari @merlimat @nodece @hangc0276
PTAL. This is my first contribution to the BookKeeper code repository. Please point out any issues, and thank you all for your help.

[hangc0276]

Does the prefetch logic have any performance impacts on BookKeeper? Reading by delay message is not a common case and I prefer not to introduce the complex on BookKeeper protocol to support the rare case.

[Denovo1998]

@hangc0276
I agree that delayed-message delivery alone may not be common enough to justify protocol complexity.
But the proposed option is not specific to delayed messages. It is a generic per-read access-pattern hint for point-read/probe-read workloads.

BookKeeper read-ahead is very useful for sequential catch-up reads, backlog consumption, and ledger scans. The problem is that some Pulsar/KoP read paths are not sequential streams. They use BookKeeper entries as lookup probes or sparse snapshot segments. In these cases, prefetching N+1/N+2 can have low hit rate and can pollute the read-ahead cache used by normal sequential readers.

Examples:

1. BucketDelayedDeliveryTracker snapshot segment lazy loading.

2. KoP FETCH/ListOffsets/seek path, where a Kafka offset must be mapped to a Pulsar MessageId before normal reading.

3. BrokerEntryMetadata.index based position lookup, where entries are read as index probes, potentially with binary-search-like access patterns.

So the intent is not to optimize a rare delayed-message path, but to let callers distinguish sequential data reads from point lookup reads while keeping read-ahead as the default behavior.