Skip to content

feat: decide client-side cache eligibility from command metadata - #4272

Merged
petyaslavova merged 7 commits into
masterfrom
ps_csc_evaluate_cachable_commands_through_metadata
Aug 21, 2026
Merged

petyaslavova merged 7 commits into
masterfrom
ps_csc_evaluate_cachable_commands_through_metadata

Conversation

@petyaslavova

@petyaslavova petyaslavova commented Aug 18, 2026 •

Copy link
Copy Markdown
Collaborator

Change summary

Client-side-cache eligibility came from the hardcoded CacheConfig.DEFAULT_ALLOW_LIST while
cluster routing came from STATIC_POLICIES - two hand-maintained views of the same COMMAND
reply. They had drifted: the allow list admits XPENDING, TS.INFO and XREAD, all three of
which the server reports as not cacheable. The new redis/commands/metadata.py makes command
metadata the single source for both. CommandMetadata carries the routing policies plus the
cacheability inputs (readonly, blocking, key argument, nondeterministic_output,
script_runner, dont_cache, metadata completeness); _is_client_side_cacheable is the only
implementation of the rules and every field fails closed, so unknown commands are never cached.
MetadataResolver serves records by name, chains through with_fallback, and answers routing
(resolve_policies) and caching (is_cacheable) off the same record, memoized per name.
_STATIC_COMMAND_METADATA is the shipped table, validated against a live Redis 8.10 stack reply
(and slightly updated to reflect some library restrictions in the current code).

redis/_parsers/commands.py gains get_command_metadata() and builds both views from one
traversal, so they cannot disagree; the policy resolvers become the routing projection of a
metadata resolver. metadata_resolver= is plumbed through Redis, ConnectionPool,
RedisCluster, NodesManager and ClusterPipeline, built once per client, shared with every
node client, and injected into CacheConfig - into a copy for cache_config=, in place for
cache=/cache_factory=.
The resolver classes are mirrored in async, but the async clients take no metadata_resolver yet, since the async stack has no client-side cache available. The metadata logic is used the same way for policy resolvers in async as in sync implementation.

Compatibility, against 7.1.0:

  • Cacheable set changes by +FT.SUGGET, +FT.SUGLEN and -XPENDING, -TS.INFO, -XREAD.
  • CacheProxyConnection.send_command no longer raises ValueError("Cannot create cache key.")
    when an eligible command carries no keys; it sends normally and caches nothing.
  • STATIC_POLICIES, DEFAULT_ALLOW_LIST and get_command_policies() are deprecated and unread.
  • RequestPolicy, ResponsePolicy, CommandPolicies, PolicyRecords moved to
    redis.commands.metadata, re-exported from redis._parsers.commands.
  • policy_resolver defaults to None and is built per client; an explicit one still wins over
    metadata_resolver for routing.
  • RedisCluster._get_command_keys raises RedisClusterException instead of AttributeError
    when there is no default node.

Test coverage

New tests/test_command_metadata.py and its async mirror cover each eligibility rule as an
independent veto, the unknown/incomplete-metadata refusals, withheld routing policies for the
movablekeys reads, case-insensitive lookup, memoization and its cap, fallback chains, and the
deprecation warnings; the resolver tests from tests/test_command_policies.py moved here and
were extended. Live-server tests assert the shipped table still matches a real COMMAND reply
and that each recorded divergence is still needed. tests/test_cache.py and
tests/test_connection.py cover the eligibility path and the resolver-injection matrix,
tests/test_cluster.py and its async mirror cover per-client resolvers, pipeline routing,
policy_resolver precedence and the new missing-default-node error. Docs updated in
docs/resp3_features.rst.


Note

High Risk
Touches cluster command routing and client-side cache eligibility, including which commands are cached and how movablekeys reads are dispatched. Compatibility shims exist, but wrong metadata would misroute or cache incorrectly.

Overview
Makes command metadata the single source of truth for both client-side cache eligibility and cluster routing, replacing the drifted CacheConfig.DEFAULT_ALLOW_LIST and unread STATIC_POLICIES table.

Adds redis.commands.metadata with frozen CommandMetadata records, fail-closed _is_client_side_cacheable rules, and chainable MetadataResolvers (static/dynamic, sync/async). Policy resolvers become a routing projection of that metadata; movablekeys reads withhold policies so the client still resolves keys itself.

metadata_resolver= is plumbed through sync Redis, ConnectionPool, RedisCluster, NodesManager, and pipelines (async clients skip the arg until CSC exists). Cache eligibility now asks the resolver; missing keys= on a cacheable command skips caching instead of raising. Cacheable set shifts by +FT.SUGGET/FT.SUGLEN and -XPENDING/TS.INFO/XREAD.

get_command_policies(), STATIC_POLICIES, and DEFAULT_ALLOW_LIST are deprecated. Policy types move to metadata.py with re-exports. RedisCluster._get_command_keys raises RedisClusterException when there is no default node.

Reviewed by Cursor Bugbot for commit 5310f9f. Bugbot is set up for automated code reviews on this repo. Configure here.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ’‘ Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aed1e96085

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with πŸ‘.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread redis/commands/metadata.py Resolved
Comment thread redis/commands/policies.py Resolved
Comment thread redis/connection.py Resolved
Comment thread redis/cache.py Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit aed1e96. Configure here.

Comment thread redis/_parsers/commands.py Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ’‘ Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f74141cbed

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with πŸ‘.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread redis/commands/metadata.py Resolved
Comment thread redis/_parsers/commands.py Resolved
Comment thread redis/commands/metadata.py Resolved
Comment thread redis/commands/metadata.py Resolved
@petyaslavova
petyaslavova force-pushed the ps_csc_evaluate_cachable_commands_through_metadata branch from b821b72 to a316666 Compare August 20, 2026 11:21
@petyaslavova petyaslavova mentioned this pull request Aug 21, 2026
5 tasks done

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ’‘ Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5310f9f474

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with πŸ‘.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread redis/commands/metadata.py Resolved
@petyaslavova
petyaslavova merged commit 081923b into master Aug 21, 2026
368 checks passed
@petyaslavova
petyaslavova deleted the ps_csc_evaluate_cachable_commands_through_metadata branch August 21, 2026 09:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants