Proposal: Deprecate List in favor of RangeScan

[mattisonchao]

Summary

Deprecate the List operation in the clients and make RangeScan the only way to read a range of keys.

List returns all the keys of a range at once: the client holds the whole result in memory before the application sees the first key, and the application can't slow the server down or stop early. RangeScan is already a stream with a callback (Java) or a channel (Go), and the Java client already applies backpressure to the server through gRPC flow control. What RangeScan lacks is a way to skip the values, which is the only reason to call List today.

The proposal:

1. A keys-only option on RangeScan, so a scan returns keys and versions without the values.
2. Close the gaps of RangeScan that would make the migration a regression: timeouts on long scans and resuming after a leader change. Ordering becomes explicit: records are in key order within a shard by default, and ordering across shards is an option.
3. Deprecate List in the Go and Java clients, and move the CLI and other callers to RangeScan.
4. Remove List from the client APIs in the next major release. The server keeps serving the List RPC for older clients.

Target release: 0.19.

Motivation

The client can't bound the memory of a list

Both clients collect the whole list before returning it:

• Java: AsyncOxiaClient.list() returns a CompletableFuture<List<String>>. Each shard collects its keys into an ArrayList (internalShardlist), the multi-shard path waits for all the shards with allOf, concatenates them and sorts the result (internalListMultiShards). Nothing reaches the application until the last shard is done.
• Go: SyncClient.List() returns a []string built by appending every batch. AsyncClient.List() streams batches on a channel, but they come from all the shards at once in no order, so most callers collect them anyway.

On the server, List batches keys up to 2 MiB per response with no limit on the count (maxTotalListKeyCount = 0). A list over a large range is as large as the range: the size depends on the data, not on the caller. A prefix with millions of keys is a few hundred MiB on the heap of the client, and there is nothing the caller can do about it except not calling List.

RangeScan already streams

	List	RangeScan
Go async	channel of batches, unordered across shards	channel of records, merged in key order across shards (aggregateAndSortRangeScanAcrossShards); Java interleaves the shards
Go sync	[]string, fully buffered	same channel as async
Java async	CompletableFuture<List<String>>, fully buffered, sorted	RangeScanConsumer callback, onNext returns false to stop and cancel the streams
Java sync	List<String>, fully buffered	CloseableIterable<GetResult> with manual gRPC flow control (FlowControlledRangeScanConsumer): a stream isn't asked for its next response until the buffer is drained
Server batch	2 MiB of keys, no count limit	1000 records or 2 MiB of values
Early stop	no	yes
Backpressure	no	yes (Go: blocked channel → HTTP/2 window; Java: manual flow control)

Both RPCs share the same request shape (shard, start_inclusive, end_exclusive, secondary_index_name, include_internal_keys, end_inclusive) and the same iterator on the leader. Keeping two operations doubles every feature added to range reads: end_inclusive was added to both, and #1612 proposes a session filter on List.

Proposal

1. Keys-only range scans

Add a field to RangeScanRequest:

message RangeScanRequest {
  ...
  // Return the key and version of each record, without its value.
  bool keys_only = 7;
}

The leader leaves GetResponse.value empty. RangeScanResponse doesn't change, and no feature flag is needed: an older server ignores the field and sends the values, and the client keeps consuming the responses and drops the values. The scan returns the same keys either way; against an older server it only costs the transfer of the values.

With keys only, the server sizes the batches by the key length instead of the value length. Today the RangeScan batcher counts only len(response.Value), so the 2 MiB limit doesn't account for the keys; that should be fixed for both modes.

Keys-only also returns the version of each key (version_id, modifications_count, session_id...), which List never returned. That's useful by itself: for example #1612's "keys attached to a session" could be a filter on a keys-only scan.

Client options:

• Go: oxia.KeysOnly() as a RangeScanOption.
• Java: RangeScanOption.KeysOnly().

2. Close the gaps of RangeScan

Migrating callers from List to RangeScan must not make them worse. Two gaps:

• Go: a long scan hits the request timeout. rangeScanFromShard wraps the whole stream in context.WithTimeout(ctx, requestTimeout) (30s by default). With backpressure, a slow consumer makes a scan last longer than that and it fails. The timeout should bound the time to the first response (or between responses), not the whole scan; the caller's ctx already bounds the whole scan. The Java client doesn't apply the request timeout to range scans.
• Both: a scan fails if the leader changes mid-stream. The executors retry only until the first response (verified); after that, a leader election ends the scan with an error. Since the client knows the last key it delivered, it can restart the shard's scan after that key on the new leader. This matters more for scans than for lists, because they're expected to be long.

Ordering

Today the clients disagree: the Go client merges the shards with a heap, so a multi-shard scan comes out in key order, while the Java CompositeRangeScanConsumer interleaves the shards in arrival order. The proposal makes the ordering a documented feature, the same in both clients:

1. Default: ordering within a shard. The records of each shard come in key order, and the shards are interleaved. A scan with a partition key reads one shard, so it's fully ordered. The client doesn't wait on the slowest shard, and doesn't need to buffer a response per shard.
2. Option: ordering across shards. A RangeScanOption (Go: oxia.OrderedAcrossShards(), Java: RangeScanOption.OrderedAcrossShards()) merges the shards in key order, which costs one buffered response per shard and runs at the pace of the slowest shard. In Go it's the existing heap merge; in Java it's a merge on top of the flow-controlled streams.

The option is not a blocker for the deprecation: callers that need a sorted multi-shard result, as Java's list() gives today, keep using the deprecated List until it's available. In Go, the default changes from the merged order to the per-shard order, and callers that rely on the merge pass the option.

3. Deprecate List

• Go: mark AsyncClient.List and SyncClient.List with // Deprecated: use RangeScan with KeysOnly.
• Java: @Deprecated on AsyncOxiaClient.list and SyncOxiaClient.list, and on ListOption.
• The deprecated methods keep their current implementation on the List RPC, so their behavior (including the order across shards) doesn't change while they exist and they keep working against older servers.
• No helper that collects a scan into a list is added: an application that needs the whole range in memory collects the scan itself.
• Move the internal callers: the oxia client list CLI command, and the docs and examples.
• Notify the main downstream users (for example the Pulsar metadata store, whose getChildren uses list).

4. Remove List from the clients

In the next major release of each client. The List RPC stays in client.proto and on the server so that old clients keep working; it's marked deprecated = true in the proto. Removing the RPC from the server is out of scope. The server-side ListBlock used by the session manager is internal and is not affected.

Release plan

Target: 0.19, the server and the Go and Java client releases that go with it.

• In 0.19: keys_only on the server, the keys-only option in both clients, per-shard ordering as the default, the timeout and resume fixes, the deprecation of List in both clients, and the move of the CLI.
• In 0.19 or later: the option to order across shards. It doesn't block the 0.19 release.
• In the next major release: the removal of List from the client APIs.

Compatibility

• New clients against old servers: a keys-only scan works, the server sends the values and the client drops them.
• Old clients against new servers: unchanged, the List RPC is still served.
• Callers that need the whole list in memory can still collect a scan; the difference is that it's their choice.