feat(session): a unified Redis session client that supports switching between underlying clients (#611)

## AgentScope-Java Version

1.0.8-SNAPSHOT

## Description

releted to #610 

### Background

The current JedisSeesion uses JedisPool, which only supports standalone
scenarios. In production environments, users mostly use more complex
deployment methods, such as sentinels, clusters, and master-slave
setups. Furthermore, in a Java environment, users may use different
Redis client implementations, such as `Jedis`, `Lettuce`, and
`Redisson`. If each is used independently, scaling up with different
Redis client implementations would result in `a lot of duplicate code`.
Moreover, naming conventions like JedisSeesion are unclear, as they are
all essentially types of Redis clients.

### New Feature

- **Unified the RedisSession client**: using the adapter pattern to
implement different underlying Redis clients, and consolidated the
duplicate code that was originally scattered across various client
implementations into the RedisSession.
- **Various Redis deployment modes**: Jedis, Lettuce, Redisson adopt
more modern APIs and support various deployment modes such as
standalone, sentinel, cluster, and master-slave.
- **README**: Add a README introduction for the
`agentscope-extensions-session-redis` module

The newly added codes all have complete javadoc documentation and the
`mvn test` has passed.

### Modify

- Added lettuce dependency
- Add the "deprecated" tag to the old versions of JedisSession and
RedissonSession, and update the corresponding javadoc.

### New Usage

#### Jedis Usage Examples

- Jedis Standalone (using RedisClient):

```java
// Create Jedis RedisClient (new API)
RedisClient redisClient = RedisClient.create("redis://localhost:6379");

// Build RedisSession
Session session = RedisSession.builder()
    .jedisClient(redisClient)
    .build();
```

- Jedis Cluster (using RedisClusterClient)

```java
// Create Jedis RedisClusterClient
Set<HostAndPort> nodes = new HashSet<>();
nodes.add(new HostAndPort("localhost", 7000));
nodes.add(new HostAndPort("localhost", 7001));
nodes.add(new HostAndPort("localhost", 7002));
RedisClusterClient redisClusterClient = RedisClusterClient.create(nodes);

// Build RedisSession
Session session = RedisSession.builder()
    .jedisClient(redisClusterClient)
    .build();
```

- Jedis Sentinel (using RedisSentinelClient)

```java
// Create Jedis RedisSentinelClient
Set<String> sentinelNodes = new HashSet<>();
sentinelNodes.add("localhost:26379");
sentinelNodes.add("localhost:26380");
RedisSentinelClient redisSentinelClient = RedisSentinelClient.create("mymaster", sentinelNodes);

// Build RedisSession
Session session = RedisSession.builder()
    .jedisClient(redisSentinelClient)
    .build();
```

#### Lettuce Usage Examples

- Lettuce Standalone

```java
// Create Lettuce RedisClient
RedisClient redisClient = RedisClient.create("redis://localhost:6379");

// Build RedisSession
Session session = RedisSession.builder()
    .lettuceClient(redisClient)
    .build();
```

- Lettuce Cluster

```java
// Create Lettuce RedisClient for cluster
RedisURI clusterUri = RedisURI.create("redis://localhost:7000");
RedisClient redisClient = RedisClient.create(clusterUri);

// Build RedisSession
Session session = RedisSession.builder()
    .lettuceClient(redisClient)
    .build();
```

- Lettuce Sentinel

```java
// Create Lettuce RedisClient for sentinel
RedisURI sentinelUri = RedisURI.builder()
    .withSentinelMasterId("mymaster")
    .withSentinel("localhost", 26379)
    .withSentinel("localhost", 26380)
    .build();
RedisClient redisClient = RedisClient.create(sentinelUri);

// Build RedisSession
Session session = RedisSession.builder()
    .lettuceClient(redisClient)
    .build();
```

#### Redisson Usage Example

```java
// Create RedissonClient (configure as needed for your deployment mode)
Config config = new Config();
config.useSingleServer().setAddress("redis://localhost:6379");
// or for cluster: config.useClusterServers().addNodeAddress("redis://localhost:7000");
// or for sentinel: config.useSentinelServers().setMasterName("mymaster").addSentinelAddress("redis://localhost:26379");

RedissonClient redissonClient = Redisson.create(config);

// Build RedisSession
Session session = RedisSession.builder()
    .redissonClient(redissonClient)
    .build();
```

## Checklist

Please check the following items before code is ready to be reviewed.

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

Author: benym

agentscope-dependencies-bom/pom.xml

@@ -99,6 +99,7 @@
         <a2a-server-common.version>0.3.3.Final</a2a-server-common.version>
         <a2a-transport-jsonrpc.version>0.3.3.Final</a2a-transport-jsonrpc.version>
         <jedis.version>7.2.1</jedis.version>
+        <lettuce.version>6.4.2.RELEASE</lettuce.version>
         <xxl-job.version>3.3.2</xxl-job.version>
         <quartz.version>2.5.2</quartz.version>
         <spring.version>7.0.5</spring.version>
@@ -378,6 +379,13 @@
                 <version>${jedis.version}</version>
             </dependency>
 
+            <!-- Lettuce client for Redis-based session implementation -->
+            <dependency>
+                <groupId>io.lettuce</groupId>
+                <artifactId>lettuce-core</artifactId>
+                <version>${lettuce.version}</version>
+            </dependency>
+
             <!-- XXL-JOB Core -->
             <dependency>
                 <groupId>com.xuxueli</groupId>

agentscope-extensions/agentscope-extensions-session-redis/README.md

@@ -0,0 +1,244 @@
+# Redis Session Extension
+
+Redis-based session implementation for AgentScope supporting multiple Redis clients.
+
+## Overview
+
+This extension provides a Redis-based session storage implementation for AgentScope, supporting multiple Redis client libraries and deployment modes.
+
+## Supported Redis Clients
+
+- **Jedis** - Standalone, Cluster, Sentinel
+- **Lettuce** - Standalone, Cluster, Sentinel
+- **Redisson** - Standalone, Cluster, Sentinel, Master/Slave
+
+## Maven Dependency
+
+```xml
+<dependency>
+    <groupId>io.agentscope</groupId>
+    <artifactId>agentscope-extensions-session-redis</artifactId>
+    <version>${agentscope.version}</version>
+</dependency>
+```
+
+## Usage Examples
+
+### Jedis
+
+#### Standalone
+
+```java
+import redis.clients.jedis.RedisClient;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Jedis RedisClient
+RedisClient redisClient = RedisClient.create("redis://localhost:6379");
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .jedisClient(redisClient)
+    .build();
+```
+
+#### Cluster
+
+```java
+import redis.clients.jedis.RedisClusterClient;
+import redis.clients.jedis.HostAndPort;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Jedis RedisClusterClient
+Set<HostAndPort> nodes = new HashSet<>();
+nodes.add(new HostAndPort("localhost", 7000));
+nodes.add(new HostAndPort("localhost", 7001));
+nodes.add(new HostAndPort("localhost", 7002));
+RedisClusterClient clusterClient = RedisClusterClient.create(nodes);
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .jedisClient(clusterClient)
+    .build();
+```
+
+#### Sentinel
+
+```java
+import redis.clients.jedis.RedisSentinelClient;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Jedis RedisSentinelClient
+Set<String> sentinelNodes = new HashSet<>();
+sentinelNodes.add("localhost:26379");
+sentinelNodes.add("localhost:26380");
+RedisSentinelClient sentinelClient = RedisSentinelClient.create("mymaster", sentinelNodes);
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .jedisClient(sentinelClient)
+    .build();
+```
+
+### Lettuce
+
+#### Standalone
+
+```java
+import io.lettuce.core.RedisClient;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Lettuce RedisClient
+RedisClient redisClient = RedisClient.create("redis://localhost:6379");
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .lettuceClient(redisClient)
+    .build();
+```
+
+#### Cluster
+
+```java
+import io.lettuce.core.RedisClient;
+import io.lettuce.core.RedisURI;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Lettuce RedisClusterClient for cluster
+RedisClusterClient clusterClient = RedisClusterClient.create("redis://localhost:7000");
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .lettuceClusterClient(clusterClient)
+    .build();
+```
+
+#### Sentinel
+
+```java
+import io.lettuce.core.RedisClient;
+import io.lettuce.core.RedisURI;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Lettuce RedisClient for sentinel
+RedisURI sentinelUri = RedisURI.builder()
+    .withSentinelMasterId("mymaster")
+    .withSentinel("localhost", 26379)
+    .withSentinel("localhost", 26380)
+    .build();
+RedisClient redisClient = RedisClient.create(sentinelUri);
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .lettuceClient(redisClient)
+    .build();
+```
+
+### Redisson
+
+```java
+import org.redisson.api.RedissonClient;
+import org.redisson.config.Config;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create RedissonClient
+Config config = new Config();
+config.useSingleServer().setAddress("redis://localhost:6379");
+// cluster: config.useClusterServers().addNodeAddress("redis://localhost:7000");
+// sentinel: config.useSentinelServers().setMasterName("mymaster").addSentinelAddress("redis://localhost:26379");
+
+RedissonClient redissonClient = Redisson.create(config);
+
+// Build RedisSession
+Session session = RedisSession.builder()
+    .redissonClient(redissonClient)
+    .build();
+```
+
+### Custom Key Prefix
+
+```java
+import redis.clients.jedis.RedisClient;
+import io.agentscope.core.session.redis.RedisSession;
+
+// Create Redis client
+RedisClient redisClient = RedisClient.create("redis://localhost:6379");
+
+// Build RedisSession with custom key prefix
+Session session = RedisSession.builder()
+    .jedisClient(redisClient)
+    .keyPrefix("myapp:session:")
+    .build();
+```
+
+## Key Structure
+
+The session state is stored in Redis with following key structure:
+
+- Single state: `{prefix}{sessionId}:{stateKey}` - Redis String containing JSON
+- List state: `{prefix}{sessionId}:{stateKey}:list` - Redis List containing JSON items
+- List hash: `{prefix}{sessionId}:{stateKey}:list:_hash` - Hash for change detection
+- Session marker: `{prefix}{sessionId}:_keys` - Redis Set tracking all state keys
+
+## Core Functionality
+
+### Save Single
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+TestState state = new TestState("value", 42);
+
+session.save(sessionKey, "testModule", state);
+```
+
+### Get Single
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+Optional<TestState> state = session.get(sessionKey, "testModule", TestState.class);
+```
+
+### Save List
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+List<TestState> states = List.of(
+    new TestState("value1", 1),
+    new TestState("value2", 2)
+);
+
+session.save(sessionKey, "testList", states);
+```
+
+### Get List
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+List<TestState> states = session.getList(sessionKey, "testList", TestState.class);
+```
+
+### Check Session Existence
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+boolean exists = session.exists(sessionKey);
+```
+
+### Delete Session
+
+```java
+SessionKey sessionKey = SimpleSessionKey.of("session1");
+session.delete(sessionKey);
+```
+
+### List All Sessions
+
+```java
+Set<SessionKey> sessionKeys = session.listSessionKeys();
+```
+
+### Clear All Sessions
+
+```java
+Mono<Integer> deletedCount = session.clearAllSessions();
+long count = deletedCount.block();
+```