Redis-Cache
RedisCache ist die Redis-gestützte Cache-Implementierung.
Produktionsreif, Multi-Pod-sicher, mit Single-Round-Trip-Bulk-
Operationen.
import { RedisCache, RedisCacheOptions } from 'actor-ts/cache';
const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://redis.example.com:6379');const cache = new RedisCache( redisCacheOptions,);Wann Redis
Abschnitt betitelt „Wann Redis“Die meisten Multi-Pod-Produktionsfälle:
- Cache-Sharing über Pods — Pods sehen denselben Cache-State.
- Bulk-Operationen zählen — MGET / MSET in einem Round-Trip.
- Persistenz gewünscht — AOF / RDB überleben Redis-Neustarts.
- Du betreibst schon Redis — bestehende Infrastruktur wiederverwenden.
Für Single-Pod ist In-Memory einfacher.
Konfiguration
Abschnitt betitelt „Konfiguration“type RedisCacheOptionsType = { url?: string; // 'redis://host:port' host?: string; port?: number; password?: string; db?: number; keyPrefix?: string; client?: RedisClientLike; // vorgefertigter ioredis-Client};URL-Form:
const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://localhost:6379/0');new RedisCache(redisCacheOptions);const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');new RedisCache(redisCache2Options); // TLSconst redisCache3Options = RedisCacheOptions.create().withUrl('redis://user:pass@host:6379');new RedisCache(redisCache3Options);Feld-Form:
const redisCacheOptions = RedisCacheOptions.create() .withHost('redis.example.com') .withPort(6379) .withPassword(process.env.REDIS_PASS) .withDb(1) .withKeyPrefix('my-app:');new RedisCache( redisCacheOptions,);keyPrefix wird auf jeden Key angewendet — nützlich, wenn
du eine Redis-Instanz über mehrere Apps teilst:
keyPrefix: 'my-app:cache:'// → 'my-app:cache:user:42', 'my-app:cache:session:abc', ...Allein aus der Config
Abschnitt betitelt „Allein aus der Config“Das Framework registriert die Redis-Factory selbst; ein Cache kommt also
auf Redis hoch, ohne registerCache-Aufruf und ohne irgendein
new RedisCache(...) in deinem Code — es braucht nur eine Plugin-Id und
einen Block:
actor-ts.cache { sessions.plugin = "actor-ts.cache.redis" # cache('sessions') is Redis
redis { url = ${?REDIS_URL} # or host/port below db = 0 key-prefix = "my-app:" password = ${?REDIS_PASSWORD} }}Die Blätter sind die Felder aus RedisCacheOptionsType oben in
kebab-case. host und port werden gelesen, stehen in der
reference.conf aber als Kommentare:
url schließt sie gegenseitig aus, und ein ausgeliefertes
host = "localhost" wäre für jedes Deployment gesetzt und machte jede
url zu einem OptionsError. Ungesetzt nimmt ioredis sein eigenes
127.0.0.1:6379.
Ein leerer String bedeutet „nicht gesetzt”. url, key-prefix und
password werden als "" ausgeliefert, damit du die Form des Keys
siehst; der Reader verwirft sie, statt sie weiterzureichen. Explizite
Options stechen den Block, und der Block sticht die eingebauten Defaults.
Jeder benannte Cache kann eigene Verbindungs-Settings haben, Blatt für Blatt über den globalen Block gelegt — genau das lässt zwei Consumer sich einen Server teilen, ohne sich eine Datenbank zu teilen:
actor-ts.cache { redis.url = ${?REDIS_URL}
rate-limit { plugin = "actor-ts.cache.redis", redis.db = 1 } idempotency { plugin = "actor-ts.cache.redis", redis.db = 2 }}ioredis ist ein lazy geladener optionaler Peer, der Block kostet also
nichts, solange kein Cache tatsächlich darauf auflöst: Der Treiber wird
bei der ersten Cache-Operation importiert, nicht beim Start. Ein
ungültiger Wert wird beim ersten cache(name) mit einem OptionsError
abgelehnt, der das Feld benennt.
Cluster-Modus
Abschnitt betitelt „Cluster-Modus“import { Cluster } from 'ioredis';
const redisCacheOptions = RedisCacheOptions.create().withClient( new Cluster([ { host: 'redis-1', port: 6379 }, { host: 'redis-2', port: 6379 }, { host: 'redis-3', port: 6379 }, ]), );new RedisCache( redisCacheOptions,);ioredis übernimmt das Cluster-Protokoll (MOVED-/ASK-Redirects,
Slot-Tracking). Nimm Redis Cluster für horizontale Skalierung
über den Speicher eines einzelnen Redis-Servers hinaus.
const redisCacheOptions = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');new RedisCache(redisCacheOptions);// TLS wird über das URL-Schema `rediss://` gewählt:const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');new RedisCache(redisCache2Options);Das URL-Präfix rediss:// wählt TLS — oder gib einen
vorgefertigten TLS-Client via withClient mit. Cert-
Verifizierung läuft über Nodes TLS-Defaults; für selbstsignierte
Zertifikate im Dev brauchst du explizite ioredis-TLS-Optionen.
Bulk-Operationen sind echtes Bulk
Abschnitt betitelt „Bulk-Operationen sind echtes Bulk“const users = await cache.mget<User>(['user:1', 'user:2', 'user:3']);// ↑// ein MGET-Round-Tripmget auf RedisCache → ein einzelner Redis-MGET-Befehl →
ein Netzwerk-Round-Trip. Entscheidend für das Muster der
Hydratation gesharder Entitäten (State für viele Entitäten
beim Node-Start wieder aufbauen).
Atomare incr + setIfAbsent
Abschnitt betitelt „Atomare incr + setIfAbsent“Beide mappen auf Redis-Primitive:
incr→ RedisINCR(atomar, kein Race).setIfAbsent→ RedisSET NX(atomares CAS).
Wird von der Rate-Limit- + Idempotency-Key-Middleware des Frameworks genutzt. Sicher über Pods hinweg.
Redis ist das am besten geeignete Backend zum Locken: ein Key
lebt in einem logischen Keyspace, SET NX entscheidet ein Rennen
also für jeden Pod gleich. Siehe
acquireLock für das dazu passende
tokengeprüfte Release.
Pipelining
Abschnitt betitelt „Pipelining“// Nicht direkt im Cache exponiert; ioredis-Pipelining ist automatisch// für gebatcheten Aufrufe innerhalb desselben Ticks.ioredis pipelined Befehle, die im selben JS-Tick abgesetzt
werden, und sendet sie in einem einzigen TCP-Write. Das Cache-
Interface exponiert Pipelining nicht explizit; die Implementierung
des Frameworks nutzt Pipelining, wo hilfreich.
Peer-Dependency
Abschnitt betitelt „Peer-Dependency“npm install ioredis# oder: bun add ioredisioredis ist der zugrunde liegende Client. Versionen 5+ sind
getestet.
Redis-Persistenz-Settings
Abschnitt betitelt „Redis-Persistenz-Settings“Redis unterstützt zwei Persistenz-Modi:
- RDB — periodische Snapshots. Default in vielen Configs.
- AOF — Append-only-Log. Durabler, langsamer.
Der Cache des Frameworks kümmert sich nicht um Redis-seitige Persistenz-Config — Caches sind opportunistisch. Aber für Cache-Überleben über Redis-Neustarts aktiviere mindestens RDB.
TLS zu Managed-Redis
Abschnitt betitelt „TLS zu Managed-Redis“const redisCacheOptions = RedisCacheOptions.create().withUrl( 'rediss://default:password@my-cluster.cache.amazonaws.com:6380', );new RedisCache( redisCacheOptions,);AWS ElastiCache, GCP Memorystore, Azure Cache for Redis —
alle unterstützen rediss://-URLs. Nutze sie.
Cluster-Verbindungsverwaltung
Abschnitt betitelt „Cluster-Verbindungsverwaltung“import { Cluster } from 'ioredis';
const redisCacheOptions = RedisCacheOptions.create().withClient( new Cluster([...], { enableReadyCheck: true, redisOptions: { maxRetriesPerRequest: 3 }, }), );new RedisCache( redisCacheOptions,);Defaultet auf vernünftige ioredis-Defaults. Für sehr enge Latenz
oder spezifische Connection-Pool-Größen gib ioredis-artige
Optionen explizit mit.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Cache-Übersicht — das große Bild.
- In-Memory-Cache — für Single-Pod.
- Memcached-Cache — Alternative.
- HTTP-Middleware — primäre Konsumenten des Caches.
