Skip to content

Redis cluster support Phase 1: connection config + client factory + key-schema-version fail-fast #8

Description

@zhchxiao123

What to build

Introduce a unified Redis connection configuration model supporting both standalone and cluster deployment modes, selected via config/env vars, with no behavior change when cluster mode isn't configured. Add a mode field (standalone/cluster, reserving space for a future sentinel value that is not implemented in this phase), a cluster_nodes list, and the existing standalone fields (host/port/db/auth/timeouts/pool size). Add a factory that constructs the correct client type (Jedis vs JedisCluster) based on mode.

Separately, introduce a KEY_SCHEMA_VERSION concept (v1 default = current unprefixed key format, v2 = a new hash-tag-based format that a later issue will define) controlled by its own env var, independent of mode.

Add a hard fail-fast check at client-construction time: if mode=cluster and the key schema version is not v2, the factory (RedisClient) must synchronously raise a configuration error before attempting any network connection — v1 keys have no Cluster hash tags and will hit CROSSSLOT errors under Cluster. This check must not require a live Redis connection to trigger (verify with an unreachable host so it can't be masked by connection retry/timeout behavior).

Acceptance criteria

  • New connection config supports mode: standalone|cluster (reserved-but-unimplemented space for a future sentinel mode), cluster_nodes, and all existing standalone fields, with standalone as the default and zero change to existing default behavior
  • Env vars: REDIS_MODE, REDIS_HOST/REDIS_PORT/REDIS_DB, REDIS_CLUSTER_NODES (comma-separated host:port), REDIS_USERNAME/REDIS_PASSWORD
  • Factory builds the correct client type per mode without leaking mode-specific branching into business code
  • KEY_SCHEMA_VERSION (v1 default / v2) added, controlled independently of mode via REDIS_KEY_SCHEMA_VERSION
  • Fail-fast: mode=cluster + key schema version not v2 raises a clear config error synchronously, with no network I/O attempted
  • Unit tests (mocked/fake clients, no real Cluster) cover: correct client type per mode; fail-fast fires without connecting; fail-fast does NOT fire for mode=cluster+v2 (construction proceeds — real cluster connectivity is validated in a later phase, not here)
  • No existing standalone behavior changes when cluster config is untouched

Blocked by

#7

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions