fix(extensions-redis): ERR 'EVAL' command keys must in same slot` in Redis Cluster

[BG0527]

关联 issue

• Fixes [Bug]:ERR 'EVAL' command keys must in same slot in Redis Cluster #2165

AgentScope-Java Version

v2.0.0

Description

Background

The RedisStore implementation fails when running against a Redis Cluster. The put operation executes a Lua script (EVAL) involving two keys: the item hash key and the namespace index key. Since these keys have different prefixes (item: vs idx:), they are hashed to different slots in the cluster, causing the EVAL command to fail with ERR 'EVAL' command keys must in same slot.

Root Cause

跨 key 原子操作 vs Redis Cluster 的 slot 分片机制 。

需要两个 key（item hash + namespace index ZSET）在一个 Lua 脚本中原子更新。但 key 命名中类型前缀 item: 和 idx: 不同，导致 CRC16 哈希到不同 slot。Redis Cluster 要求 EVAL 中所有 key 必须在同一 slot，因此报错。

Fix

在 key 中使用 Redis Hash Tag {...} 语法，让 CRC16 只计算 {} 内的内容。确保同一 namespace 下的 item hash 和 namespace index 落入同一 slot，Lua EVAL 脚本在 Redis Cluster 下不再报错。

Changed files:

1. RedisStore.java

Key layout 变更 （第240-248行）：

• itemKey : prefix:item:\0 → prefix:item:{}\0
• indexKey : prefix:idx: → prefix:idx:{}

Namespace 校验增强 （第258-266行）：

• 新增：禁止 namespace 段包含 { 或 } ，防止 hash tag 解析被干扰
• 新增：禁止 namespace 段包含 NUL 字符，防止 namespace 路径歧义

2. RedisStoreTest.java

42 个测试覆盖：

• Hash tag key 生成正确性（itemKey 和 indexKey 共享同一 hash tag）
• Namespace 段校验（ { 、 } 、NUL、null）
• Key 校验（null、空、NUL）
• 构造器（prefix 归一化、空 prefix 回退）
• get/put/putIfVersion/search/delete 全流程 mock 测试
• 序列化边界（null value、空 JSON、非法 JSON）

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR fixes the ERR 'EVAL' command keys must in same slot error in Redis Cluster by wrapping the namespace portion of Redis keys in hash tags ({<ns>}). The approach is correct and well-documented — using Redis hash tags to ensure the item hash key and namespace index key always map to the same slot is the standard solution for cross-slot Lua script issues. The namespace segment validation for {, }, and NUL is appropriate. The 42 new unit tests provide excellent coverage. However, there are two issues that should be addressed: (1) the key prefix is not validated for {/} characters, which can silently break the hash tag mechanism, and (2) the key format change is a silent breaking change with no migration path for existing deployments.

[AgentScopeJavaBot]

🤖 AI Review

This PR fixes the ERR 'EVAL' command keys must in same slot error in Redis Cluster by wrapping the namespace portion of Redis keys in hash tags ({<ns>}). The approach is correct and well-documented — using Redis hash tags to ensure the item hash key and namespace index key always map to the same slot is the standard solution for cross-slot Lua script issues. The namespace segment validation for {, }, and NUL is appropriate. The 42 new unit tests provide excellent coverage. However, there are two issues that should be addressed: (1) the key prefix is not validated for {/} characters, which can silently break the hash tag mechanism, and (2) the key format change is a silent breaking change with no migration path for existing deployments.