Add server-side filtering for KeyValue list operations

[TarasLykhenko]

Summary

Implements server-side filtering for KeyValue store list operations to address performance issues when working with large numbers of keys.

Fixes: #768

Changes

• Add watch_filtered() method for server-side multi-pattern filtering using filter_subjects
• Add list_keys() method with NATS pattern support (*, > wildcards)
• Refactor watch() to delegate to watch_filtered() for consistency
• Fix filter_subject vs filter_subjects conflict in subscribe() method
• Maintain backwards compatibility with existing keys() method
• Add tests: test_kv_list_keys() and test_kv_watch_filtered()

Implementation Details

The new list_keys() method uses filter_subjects in consumer configuration to perform server-side filtering, significantly reducing network traffic and server load compared to the client-side filtering in the existing keys() method.

Follows the Go client architecture pattern (nats.go WatchFiltered()) with watch_filtered() as the foundational method for filtered watch operations.

Why a new method instead of modifying keys()?

The existing keys() method uses substring matching: a filter "greet" matches both "greet" and "greeting". This behavior is tested and relied upon in the existing test suite (see test_kv_keys):

# Existing keys() behavior - substring matching
await kv.put("foo.bar", b'bar')
await kv.put("foo.baz", b'baz')
await kv.put("bar.foo", b'foo')

# Filter "foo" matches all three keys because "foo" is a substring
keys = await kv.keys(filters=["foo"])
assert len(keys) == 3  # Matches: foo.bar, foo.baz, bar.foo

The new list_keys() method uses NATS subject patterns: "foo" matches only "foo" exactly, while "foo.*" uses wildcard matching for structured keys:

Changing the behavior of keys() would break existing code that relies on substring matching, so a new method provides the performance benefits of server-side filtering while maintaining backwards compatibility.

Compatibility

• Backwards compatible: existing keys() method behavior unchanged

[swelborn]

+1 for this

[Copilot]

Pull Request Overview

This PR refactors the NATS KeyValue watch functionality to support server-side filtering using multiple NATS subject patterns. It introduces a new watch_filtered method and list_keys method while deprecating the old keys method.

Key changes:

• Introduced watch_filtered method to support multiple filter patterns with server-side filtering
• Added list_keys method as the recommended approach for retrieving filtered keys
• Refactored watch method to delegate to watch_filtered for consistency
• Deprecated keys method in favor of server-side filtering via list_keys
• Updated subscribe method to handle filter_subjects (multi-filter API) alongside legacy filter_subject
• Applied code formatting changes throughout client.py for consistency

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
nats/src/nats/js/kv.py	Refactored watch functionality to support server-side filtering with multiple patterns; added watch_filtered and list_keys methods; deprecated keys method
nats/src/nats/js/client.py	Added support for filter_subjects in consumer config; applied code formatting improvements
nats/tests/test_js.py	Added comprehensive tests for list_keys and watch_filtered methods with various filtering scenarios

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When ordered_consumer=True is set, the subscribe method will override the config.deliver_policy set on line 465. In the subscribe method (client.py:427-434), ordered consumer mode sets specific config values including flow_control, ack_policy, max_deliver, ack_wait, idle_heartbeat, num_replicas, and mem_storage. This means the deliver_policy configured on line 465 will be lost. Consider either removing the deliver_policy assignment or handling ordered consumer configuration before calling subscribe.

[Copilot]

Setting filter_subjects directly on the config object doesn't account for the case where a user might have already set filter_subject (singular) on a passed-in config. If a user passes a custom config object through kwargs with filter_subject already set, it would create inconsistency. Consider checking if the config already has filter_subject set and either raise an error or merge the values appropriately.

Suggested change

	config = api.ConsumerConfig()
	config = api.ConsumerConfig()
	if getattr(config, "filter_subject", None) is not None:
	raise ValueError("Cannot set filter_subjects when filter_subject is already set on config")