Redis
Cache, sessions, rate-limit & pub/sub backbone
Redis is the second mandatory dependency. Nucleus leans on it for everything that must be fast, shared across instances, or expiring on a timer — so a single Redis instance quietly powers a surprising amount of the framework.
You can connect in one of two ways: directly over the wire with ioredis, or through a Dapr state-store component when you run inside Kubernetes. The redis block selects between them and supplies the coordinates.
Like the database, connection fields hold environment-variable names rather than literal values, so the same config travels safely between environments.
Direct connection#
The default mode. Provide either a single url or a host + port pair. Each of these is the NAME of an environment variable — Nucleus resolves process.env[...] at startup, so secrets stay out of your config file. A REDIS_PASSWORD env var is picked up automatically when present.
1{2 "redis": {3 "url": "REDIS_URL",4 "withDapr": false5 }6}urlstringOptionalName of an env var holding a full Redis URL (redis://… or rediss://…). When set it takes precedence over host/port. Resolved via process.env at boot.
Example: "REDIS_URL"
hoststringOptionalName of an env var holding the Redis hostname. Used together with port when url is not provided. If neither url nor host resolve, ioredis falls back to its 127.0.0.1:6379 default.
Example: "REDIS_HOST"
portstringOptionalName of an env var holding the Redis port. Parsed to an integer at startup; an unparseable value is ignored in favour of the ioredis default.
Example: "REDIS_PORT"
Dapr state-store mode#
When running under Dapr (typically in Kubernetes), Nucleus talks to Redis through the Dapr sidecar's state-store building block instead of a direct socket. This decouples your service from connection management and lets the platform own credentials and TLS.
1{2 "redis": {3 "withDapr": "USE_DAPR",4 "stateStoreName": "statestore"5 }6}withDaprboolean | stringOptionalSelects the transport. A boolean is used directly. A string is treated as an env-var name and resolved at runtime — it counts as enabled unless the resolved value is exactly "false", which is handy for toggling Dapr on in the cluster and off locally from the same config.
falsestateStoreNamestringOptionalThe name of the Dapr state-store component to bind to (e.g. "statestore"). Required whenever withDapr resolves true — startup throws if it is missing. Ignored in direct mode.
Example: "statestore"
What Redis powers#
Understanding the breadth of Redis usage helps you size and secure it correctly. A single store underpins all of the following, namespaced by your appId so multiple services can share one instance without collisions.
Under the hood — RedisManager#
Both transports hide behind one RedisManager (a process-wide singleton) implementing a small IStateStore interface, so the rest of the framework calls the same methods whether you run direct ioredis or the Dapr state store. It is more than a key-value wrapper — it also provides the coordination primitives Nucleus relies on.
create / read / update / remove / existsRedisResult<T>OptionalJSON-serialising CRUD that never throws — each returns { success, data } | { success:false, error }. create takes an optional TTL (SET … EX); update defaults to KEEPTTL so refreshing a value preserves its remaining expiry rather than resetting it.
acquireLock / releaseLock / waitForLockdistributed lockOptionalacquireLock uses SET key 1 EX ttl NX for an atomic, self-expiring lock in direct mode (a check-then-set fallback under Dapr). waitForLock polls until a lock frees or a timeout elapses. These guard single-flight operations across instances — most visibly refreshAccessTokenWithLock, which serialises concurrent refresh-token rotation so a burst of tabs can't double-rotate.
getOrWaitpoll-until-presentOptionalReads a key, and if absent polls until it appears or a timeout elapses — the building block behind async hand-offs (e.g. waiting for a value another worker is about to write).
reauthenticate(username, password)rotating credsOptionalIssues a fresh AUTH on the live ioredis client without reconnecting — the Redis counterpart to the database's async password, for AAD / rotating-secret deployments.
keys(pattern)direct mode onlyOptionalPattern scans work over a direct connection but are intentionally disabled under Dapr (the state-store building block has no KEYS); the method logs a warning and returns []. Code paths that enumerate keys therefore assume direct mode.
Related sections