galaxy-game/gateway/docs/redis-config.md

Decision: Redis configuration shape

Captures the standing rules adopted by Edge Gateway when it joined the project-wide Redis topology described in ARCHITECTURE.md.

Context

Gateway intentionally stays Redis-light. The only Redis state served by gateway is the replay reservation namespace (short-lived SETNX per authenticated request, bounded by GATEWAY_REPLAY_REDIS_RESERVE_TIMEOUT). Session lookup goes through backend's REST surface, and inbound events are delivered through the gRPC Push.SubscribePush consumer (see gateway/internal/backendclient).

The shared rule is: every Galaxy service uses one master plus zero-or-more replicas with a mandatory password, no TLS, and no Redis ACL username; the connection is configured by the shared pkg/redisconn helper.

Decisions

One shared *redis.Client owned by the runtime

cmd/gateway/main.go constructs a single *redis.Client via internal/redisclient.NewClient, attaches OpenTelemetry tracing and metrics via internal/redisclient.InstrumentClient, performs one bounded PING via internal/redisclient.Ping, and registers client.Close for shutdown. The replay store is the only adapter backed by Redis.

One env-var prefix for the connection

Connection topology is loaded from a single GATEWAY_REDIS_* group via redisconn.LoadFromEnv("GATEWAY"):

• GATEWAY_REDIS_MASTER_ADDR (required)
• GATEWAY_REDIS_REPLICA_ADDRS (optional, comma-separated; currently unused, reserved for future read-routing)
• GATEWAY_REDIS_PASSWORD (required)
• GATEWAY_REDIS_DB (default 0)
• GATEWAY_REDIS_OPERATION_TIMEOUT (default 250ms)

Per-subsystem behavior env vars (namespace and timing only):

• GATEWAY_REPLAY_REDIS_KEY_PREFIX, GATEWAY_REPLAY_REDIS_RESERVE_TIMEOUT

Retired env vars (hard removal)

The following variables are no longer read or honored:

• GATEWAY_SESSION_CACHE_REDIS_ADDR — replaced by GATEWAY_REDIS_MASTER_ADDR.
• GATEWAY_SESSION_CACHE_REDIS_USERNAME — Redis ACL not used.
• GATEWAY_SESSION_CACHE_REDIS_PASSWORD — replaced by GATEWAY_REDIS_PASSWORD.
• GATEWAY_SESSION_CACHE_REDIS_DB — replaced by GATEWAY_REDIS_DB.
• GATEWAY_SESSION_CACHE_REDIS_TLS_ENABLED — TLS disabled by policy.

pkg/redisconn.LoadFromEnv rejects GATEWAY_REDIS_TLS_ENABLED and GATEWAY_REDIS_USERNAME at startup with a clear error pointing to ARCHITECTURE.md §Persistence Backends.

Compound legacy prefixes (GATEWAY_SESSION_CACHE_REDIS_USERNAME etc.) are not actively rejected. pkg/redisconn's deprecated-env detector only watches the canonical GATEWAY_REDIS_* form. The compound legacy vars become silently inert. The architecture rule explicitly accepts this ("no backward-compat shim — fresh project, no production deploys to migrate"); operators upgrading should remove the variables from their deployment manifests.

Telemetry

redisconn.Instrument wires redisotel.InstrumentTracing (with WithDBStatement(false)) and redisotel.InstrumentMetrics. This is the first gateway release that emits Redis tracing and connection-pool metrics; downstream dashboards will start populating without further changes.

Consequences

• Gateway test code constructs one shared client and passes it to the replay-store adapter under test (see internal/replay/redis_test.go).
• Operators must set GATEWAY_REDIS_PASSWORD. A passwordless local Redis is still acceptable as long as a placeholder password is supplied to the binary; Redis without requirepass accepts AUTH unconditionally.
• The integration test harness passes GATEWAY_REDIS_PASSWORD = "integration" alongside GATEWAY_REDIS_MASTER_ADDR (see integration/internal/harness/gatewayservice.go).