# Decision: Redis configuration shape

PG_PLAN.md §7. Captures the standing rules adopted by Edge Gateway when it
joined the project-wide Redis topology defined in
`ARCHITECTURE.md §Persistence Backends`.

## Context

Gateway intentionally stays Redis-only. All gateway state Redis serves is
TTL-bounded or runtime-coordination state:

- the session cache is a read-through projection of authsession's
  source-of-truth session records (rebuildable via re-authentication);
- the replay store is a short-lived `SETNX` reservation namespace per
  authenticated request (`GATEWAY_REPLAY_REDIS_RESERVE_TIMEOUT`);
- the session-events stream is a runtime fan-out of session lifecycle
  updates;
- the client-events stream is a runtime push fan-out.

Stage 7 brought gateway in line with the steady-state rules established in
Stage 0: 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 session cache, replay store, session-events subscriber, and
client-events subscriber all receive this same client.

Adapters no longer build or own a Redis client. Their `Config` structs hold
only behavior settings (key prefix, stream name, per-subsystem timeouts).
Adapter constructors take `(*redis.Client, …)`. The stream subscribers'
`Close`/`Shutdown` methods became no-ops; the runtime's context cancellation
unblocks the `XRead` loop and the runtime closes the shared client.

### 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 keep their existing prefixes — they do not
describe connection topology, only namespace and timing:

- `GATEWAY_SESSION_CACHE_REDIS_KEY_PREFIX`,
  `GATEWAY_SESSION_CACHE_REDIS_LOOKUP_TIMEOUT`
- `GATEWAY_REPLAY_REDIS_KEY_PREFIX`,
  `GATEWAY_REPLAY_REDIS_RESERVE_TIMEOUT`
- `GATEWAY_SESSION_EVENTS_REDIS_STREAM`,
  `GATEWAY_SESSION_EVENTS_REDIS_READ_BLOCK_TIMEOUT`
- `GATEWAY_CLIENT_EVENTS_REDIS_STREAM`,
  `GATEWAY_CLIENT_EVENTS_REDIS_READ_BLOCK_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 that previously constructed a Redis client per adapter
  must now construct one client and pass it to every adapter under test
  (see `internal/session/redis_test.go`, `internal/replay/redis_test.go`,
  `internal/events/subscriber_test.go`,
  `internal/events/client_subscriber_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`).