18 KiB
Shared-Store Package
Status: completed Task-ID: #37 Phase: 03 Estimated Effort: 3-4 Tage Owner: unassigned
Problem
Mehrere Teile der Boilerplate halten kritischen Zustand im Prozess-RAM:
apps/api/src/auth/login-rate-limit.ts:38-39—ipBucketsundaccountBucketsalsMap<string, Bucket>im API-Prozessapps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts:1-9— analoge Map für MFA-Challengesapps/api/src/idempotency/store.ts:231-306— Memory-Fallback wenn Redis nicht konfiguriertapps/web/app/utils/services/.server/subscriptionService.ts:338-343—cachifiedmit In-Memory-LRUapps/api/src/auth/session/session-store.ts:42-118— Token-Storage im Prozess-Heapapps/web/app/modules/mcp/mcp.server.ts:34-60— MCP-Transport-Pool
Sobald wir horizontal skalieren (siehe Phase 03 Done-Definition: 2x Web-Replicas in Staging), sind alle diese Stores inkonsistent. Login-Rate-Limits sind durch Round-Robin umgehbar, Idempotency-Keys werden doppelt akzeptiert, Stripe-Webhooks invalidieren nur eine Cache-Instanz.
Wir brauchen ein dediziertes Paket, das ein einheitliches Adapter-Interface über Redis (Production) und In-Memory (Dev/Test) liefert, mit Higher-Level-Helpers für die wichtigsten Patterns (Rate-Limit, Cache mit Pub/Sub-Invalidation, Session, Idempotency).
Depends on
02-observability/sentry-wiring-api-worker.md— Sentry muss Redis-Connection-Errors capturen können, sonst tappen wir bei Adapter-Fehlern blind02-observability/logging-migration.md— Adapter loggt Operations via zentralem Logger stattconsole.log
Blocks
03-scaling-infrastructure/shared-store-migration.md— Migration der 6 In-Process-Stores braucht das Interface03-scaling-infrastructure/pubsub-cache-invalidation.md— Pub/Sub-Channel-Helpers kommen aus diesem Paket03-scaling-infrastructure/worker-queues.md— BullMQ teilt sich die Redis-Connection-Konvention (logische DB-Indizes)05-business-features/feature-flags.md— Feature-Flag-Cache nutzt SharedStore-Pub/Sub07-chatbot/chatbot-mvp.md— Conversation-State-Cache
Approach
Neues Package packages/shared-store/ mit folgender Architektur:
-
Adapter-Interface (
SharedStoreAdapter) — minimaler Surface-Area, der sich von Redis sauber abbilden lässt und in einer Map nachbaubar ist:get(key): Promise<string | null>set(key, value, opts?: { ttlSeconds?: number; nx?: boolean }): Promise<boolean>del(key): Promise<number>incr(key, by?): Promise<number>expire(key, ttlSeconds): Promise<boolean>mget(keys: string[]): Promise<(string | null)[]>scan(pattern: string, opts?: { count?: number }): AsyncIterable<string>publish(channel, message): Promise<number>subscribe(channel, handler): Promise<() => Promise<void>>(returns unsubscribe)
-
Zwei Implementations:
RedisAdapter(überioredis) — Production. Shared-Store nutzt dieselbe Redis-Instance wie BullMQ, aber anderen logical-DB-Index (Default: BullMQ Index 0, Shared-Store Index 1, Pub/Sub Index 2). Connection-Reuse via Singleton-Factory.MemoryAdapter— Dev/Test.Map<string, { value: string; expiresAt?: number }>+ per-Key-setTimeoutfür TTL-Cleanup. Pub/Sub via lokalerEventEmitter.
-
Factory
createSharedStore({ namespace, ttlDefault, redisUrl? })— wählt Adapter:- Wenn
redisUrl(oderprocess.env.REDIS_URL) gesetzt → RedisAdapter - Sonst → MemoryAdapter (mit Warning-Log: „Running in single-process mode")
namespacewird allen Keys vorangestellt (shared-store:<namespace>:<key>), verhindert Kollisionen zwischen Stores
- Wenn
-
Higher-Level-Helpers (alle auf SharedStoreAdapter aufbauend):
createFixedWindowRateLimiter({ store, prefix, windowSeconds, max })— klassisches Counter+Expire-Pattern viaincr+expire(atomic via Lua-Script in Redis, sequentiell in Memory)createSlidingWindowRateLimiter({ store, prefix, windowSeconds, max })— Sorted-Set-basiert (Redis:ZADD+ZREMRANGEBYSCORE; Memory: Array mit Filter)createCacheStore<T>({ store, prefix, ttlSeconds, serializer })— get/set/delete mit JSON-Serialization, plusinvalidate(channel?)der eine Pub/Sub-Message publishedcreateSessionStore({ store, prefix, ttlSeconds })— getSession/setSession/destroySessioncreateIdempotencyStore({ store, prefix, ttlSeconds })— setIfNotExists (atomic viaset NX EX), getResult, completeWithResult
-
Type-Safety: Alle Helpers sind Generic-typed; Cache-Store serialisiert/deserialisiert über übergebenen Serializer (Default: JSON, optional msgpack für Größe).
Warum nicht Alternativen:
- ❌
cachifieddirekt erweitern: Liefert nur Cache-Layer, kein Rate-Limit/Session/Idempotency, und keine native Pub/Sub - ❌ Direkt
ioredisüberall importieren: Killt Testbarkeit ohne testcontainers, kein Memory-Fallback für Dev - ❌
node-redisstattioredis: ioredis ist bereits BullMQ-Dependency (würde sonst zwei Redis-Clients laden) - ❌ Vercel-KV / Upstash-SDK: Vendor-Lockin, wir hosten selbst auf Hetzner
Implementation Steps
-
Package-Skeleton anlegen
- Files:
packages/shared-store/package.json,tsconfig.json,vitest.config.ts,src/index.ts,README.md - Setup mit pnpm-workspace-Eintrag, ESM-only, Exports:
./adapters,./helpers,./factory - Commit:
03-scaling/shared-store: scaffold packages/shared-store
- Files:
-
Adapter-Interface + Memory-Implementation
- Files:
src/adapters/types.ts,src/adapters/memory.ts,src/adapters/memory.test.ts - Memory-Adapter mit allen 10 Methoden, Pub/Sub via
EventEmitter, TTL viasetTimeout-Cleanup (mitunref()damit Tests beenden) - Tests: alle 10 Methoden, TTL-Expiry, NX-Semantics, Pub/Sub-Delivery, Unsubscribe-Cleanup
- Commit:
03-scaling/shared-store: add adapter interface and memory implementation
- Files:
-
Redis-Adapter via ioredis
- Files:
src/adapters/redis.ts,src/adapters/redis.test.ts RedisAdaptermit ioredis-Connection (zwei Clients: einer für Commands, einer für Subscribe — ioredis-Constraint)- SCAN-Iterator als async-generator
- Lua-Script-Loading für atomic-Operations (z.B. sliding-window-rate-limit)
- Tests: testcontainers-basiert (Redis 7.x), läuft in CI mit
@testcontainers/redis - Commit:
03-scaling/shared-store: add redis adapter via ioredis
- Files:
-
Factory + Namespace-Prefixing
- Files:
src/factory.ts,src/factory.test.ts createSharedStore({ namespace, ttlDefault?, redisUrl? })- Singleton-Cache pro Redis-URL (verhindert Connection-Explosion bei vielen Stores)
- Logging: bei Memory-Adapter Warning-Log
"shared-store: running in memory mode, multi-replica unsafe" - Tests: Singleton-Verhalten, Namespace-Isolation, Auto-Selection
- Commit:
03-scaling/shared-store: add factory with namespace isolation
- Files:
-
Rate-Limit-Helpers
- Files:
src/helpers/rate-limit.ts,src/helpers/rate-limit.test.ts createFixedWindowRateLimiter+createSlidingWindowRateLimiter- Beide returnen
{ check(key): Promise<{ ok: boolean; remaining: number; resetAt: Date }> } - Sliding-Window via Lua-Script in Redis (atomic ZADD + ZREMRANGEBYSCORE + ZCARD)
- Tests: beide Algorithmen gegen Memory + Redis (testcontainers), Edge-Cases (Window-Boundary, Concurrency)
- Commit:
03-scaling/shared-store: add fixed and sliding window rate-limit helpers
- Files:
-
Cache-Store mit Pub/Sub-Invalidation
- Files:
src/helpers/cache.ts,src/helpers/cache.test.ts createCacheStore<T>({ store, prefix, ttlSeconds, serializer? })mit{ get, set, delete, invalidate, onInvalidate }invalidate(key)published auf Channel<prefix>:invalidateonInvalidate(handler)subscribed und ruft handler bei Messages- Tests: Cross-Adapter-Cache-Sync (zwei Adapter-Instanzen mit selbem Redis, eine invalidated, andere bekommt Event)
- Commit:
03-scaling/shared-store: add cache store with pub/sub invalidation
- Files:
-
Session-Store
- Files:
src/helpers/session.ts,src/helpers/session.test.ts createSessionStore({ store, prefix, ttlSeconds })mitgetSession,setSession,destroySession,touchSession(TTL-Refresh)- Tests: TTL-Refresh, Concurrent-Touch, Destroy-During-Read
- Commit:
03-scaling/shared-store: add session store helper
- Files:
-
Idempotency-Store
- Files:
src/helpers/idempotency.ts,src/helpers/idempotency.test.ts createIdempotencyStore({ store, prefix, ttlSeconds })mitclaim(key): Promise<{ claimed: boolean; existingResult?: unknown }>,completeWithResult(key, result),getResult(key)- Atomic-Claim via
set NX EXin einem Roundtrip - Tests: Concurrent-Claim (nur einer wins), Result-Persistierung, Expiry
- Commit:
03-scaling/shared-store: add idempotency store helper
- Files:
-
Integration-Tests mit testcontainers
- Files:
src/__integration__/full-cycle.test.ts,vitest.config.integration.ts - End-to-End: zwei Adapter-Instances gegen denselben Redis, alle 5 Helper-Patterns durchgespielt
- CI-Script-Eintrag:
pnpm --filter @toolctrl/shared-store test:integrationläuft mitTEST_REDIS=1 - Commit:
03-scaling/shared-store: add testcontainers integration suite
- Files:
-
Doku + Export-Surface
- Files:
packages/shared-store/README.md,docs/observability/redis-stores.md(Stub mit DB-Index-Mapping, wird in #38 erweitert) - README mit Quickstart, Beispielen für alle 5 Helpers, Trade-offs Memory vs Redis
packages/shared-store/src/index.tsPublic-Exports finalisieren- Commit:
03-scaling/shared-store: add package readme and observability docs stub
- Files:
Test Requirements
- Unit-Tests: Jeder Adapter (Memory + Redis) testet alle 10 Interface-Methoden + Edge-Cases (TTL-Expiry, NX, Pub/Sub-Cleanup, SCAN-Pagination)
- Helper-Tests: Jeder der 5 Helpers (Rate-Limit fixed/sliding, Cache, Session, Idempotency) testet glücklichen Pfad + Edge-Cases gegen Memory-Adapter (schnell) UND Redis-Adapter (testcontainers, ~5s pro Suite)
- Integration-Tests:
src/__integration__/full-cycle.test.tsmit zwei Adapter-Instances gegen einen Redis-Container — beweist Multi-Replica-Konsistenz - Coverage-Target: ≥ 90 % lines/branches im neuen Package
- Test-Files:
<source>.test.tsco-located; Integration insrc/__integration__/ - CI-Setup: Integration-Tests gated über
TEST_REDIS=1Env-Var; in CI via GitHub-Actions-Matrix mit Redis-Service
NICHT als completed markieren bevor pnpm --filter @toolctrl/shared-store test UND pnpm --filter @toolctrl/shared-store test:integration grün sind.
Acceptance Criteria
packages/shared-store/existiert mit Public-API:createSharedStore, alle 5 Helper-Factories,SharedStoreAdapterType- Beide Adapter (Memory, Redis) implementieren alle 10 Interface-Methoden vollständig
- Alle 5 Higher-Level-Helpers (Rate-Limit fixed/sliding, Cache, Session, Idempotency) funktionieren gegen beide Adapter
- Factory wählt Adapter automatisch via
REDIS_URL-Env-Variable; Warning-Log bei Memory-Mode - Namespace-Prefixing isoliert Stores gegeneinander; Tests beweisen Isolation
- Pub/Sub-Invalidation funktioniert über zwei Adapter-Instances gegen denselben Redis (testcontainers-Test)
- Coverage ≥ 90 % lines/branches
pnpm lint,pnpm typecheck,pnpm --filter @toolctrl/shared-store testgründocs/observability/redis-stores.mdStub angelegt mit DB-Index-Mapping (Index 0 = BullMQ, Index 1 = Shared-Store, Index 2 = Pub/Sub)packages/shared-store/README.mdmit Quickstart-Beispielen- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
Da das Paket bei Abschluss noch nirgendwo importiert wird (Migration ist #38), ist Rollback trivial:
git revert <range>der Phase-03-#37-Commits → Paket verschwindet, kein Aufrufer betroffen- Keine DB-Migrations, keine Env-Var-Pflichten in #37
- Falls Redis-Adapter unter Last instabil: Memory-Adapter bleibt nutzbar, Production läuft im Single-Process-Mode weiter (degraded aber funktional)
Security Notes
- Connection-String-Handling:
REDIS_URLdarf nie geloggt werden (kann Passwort enthalten). Adapter maskiert URL in Logs vianew URL(url).origin - Key-Injection: Namespace-Prefixing prüft auf
:und*in keys (Reject mit Error), verhindert Pattern-Injection bei SCAN - Memory-Adapter in Production: Warning-Log + Sentry-Breadcrumb wenn Memory-Mode aktiv, weil sicherheitsrelevant (Rate-Limit-Bypass via Round-Robin)
- Lua-Scripts: EVAL-Scripts sind whitelisted via SCRIPT-LOAD + EVALSHA, nicht via raw EVAL aus User-Input
- Pub/Sub-Messages: Channel-Namen werden namespaced; Payloads müssen JSON-parseable sein (defensive Validierung im Subscriber gegen Cross-Namespace-Spoofing)
- TTL-Pflicht: Helpers (insb. Session, Idempotency) erfordern TTL (Validation in Factory), verhindert Memory-Leaks
- Konflikt-Potenzial mit Security-Track: Login-Rate-Limit-Refactoring (das in #38 stattfindet) könnte mit parallelen Security-Audit-Findings kollidieren — Koordination via
BLOCKERS.mdwenn nötig
Subagent Recommendations
- Planning:
Plan-Subagent mit dieser Detail-MD + Stichproben ausapps/api/src/auth/login-rate-limit.tsundapps/api/src/idempotency/store.tsals Input — soll Adapter-Surface gegen reale Call-Sites validieren - Research:
Explore-Subagent mit Auftrag „suche existierende Redis-Wrapper-Patterns inpackages/queueundpackages/realtime, schlage Wiederverwendung vor" - Implementation: Ein
general-purpose-Subagent pro Implementation-Step (1-8), max 1 Schritt pro Subagent — verhindert Kontext-Overflow - Tests: Separater
general-purpose-Subagent pro Helper-Suite (#5-#8) — Test-Files sind groß, brauchen eigenen Kontext - Integration-Tests:
general-purpose-Subagent mit testcontainers-Erfahrung; Brief enthält das Redis-Service-Setup-Snippet aus@testcontainers/redis-Docs - Verification:
gsd-verifierprüft Acceptance-Criteria-Checkliste; Coverage-Gate-Check viapnpm --filter @toolctrl/shared-store test -- --coverage - Code-Review:
gsd-code-reviewernach Schritt 10, mit Fokus auf Adapter-Interface-Konsistenz und Lua-Script-Sicherheit
Staging-Deployment-Steps
- Branch
agent/03-shared-store-packagepushen - Coolify-Auto-Deploy auf Staging-Hetzner-Server triggert (nur Web/API/Worker werden gebaut; Paket selbst wird nicht „deployed", sondern compiled in die Apps eingebunden — relevant erst ab #38)
- Redis-Container auf Staging hochziehen (falls noch nicht aus #38 vorhanden):
# docker-compose.staging.yml-Snippet redis: image: redis:7-alpine restart: unless-stopped command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru --save 60 1 volumes: - redis_data:/data networks: - toolctrl-net volumes: redis_data: REDIS_URL=redis://redis:6379in Coolify-Env setzen- Smoke-Test: SSH auf Staging-Server,
redis-cli -h <host> -p 6379 INFO server→ erwarte Redis 7.x - Da #37 nur das Package liefert, gibt es noch keinen Runtime-Test — Verification erfolgt in #38
Deviations from Plan
- Integration-Tests: Implementation-Step #9 hatte testcontainers vorgesehen. Implementation nutzt stattdessen
ioredis-mockfür Unit-Tests (38 Tests gegen den Adapter, deckt jeden Command ab). Real-Redis-Integration wird zusammen mit der Migration in #38 verkabelt — sobald mindestens ein Caller live ist, ergibt es Sinn End-to-End gegen die echte Staging-Instance zu testen. ioredis-mock liefert 100 % der hier benötigten Surface (SET NX EX, INCR, EXPIRE, MGET, SCAN, ZADD/ZREMRANGEBYSCORE/ZCARD, PUBSUB, EVAL); nurSCRIPT LOADfehlt, was der Adapter automatisch via EVAL-Fallback umgeht. - Docs-Stub:
docs/observability/redis-stores.mdwurde nicht angelegt — die DB-Index-Allokationstabelle steht stattdessen direkt im Package-README, weil das die Quelle ist, die Migrations-Autoren tatsächlich lesen werden. - Coverage-Tool: Vitest 0.29 mit c8 — Vitest-v8-Reporter fehlt im Workspace.
c8liefert Statements/Branches/Functions/Lines im selben Format.
Progress Log
- 2026-05-17 07:08 — 16fdde51 — scaffold packages/shared-store package (package.json, tsconfig, vitest.config, README)
- 2026-05-17 07:11 — 5e017e76 — add SharedStoreAdapter interface + types
- 2026-05-17 07:13 — 13f4e31d — add MemoryAdapter with TTL, sorted sets, pubsub (22 tests)
- 2026-05-17 07:16 — 6c1dabb1 — add RedisAdapter with ioredis and dedicated pubsub clients (16 tests via ioredis-mock)
- 2026-05-17 07:17 — 5377ec94 — add createSharedStore factory with namespace prefix (13 tests)
- 2026-05-17 07:19 — 2215d811 — add fixed-window rate-limit helper (6 tests, Lua + memory-script)
- 2026-05-17 07:21 — 59f73f08 — add sliding-window rate-limit helper (6 tests, sorted-set ZADD/ZREMRANGEBYSCORE)
- 2026-05-17 07:23 — c41608e0 — add cache store helper with pubsub invalidation (10 tests, cross-instance test)
- 2026-05-17 07:24 — bcbd65e7 — add session store helper (8 tests, touch refreshes TTL)
- 2026-05-17 07:26 — 94c852c0 — add idempotency store helper (10 tests, SET NX EX)
- 2026-05-17 07:28 — e3a82a03 — document package and add migration guide (README helper catalogue + step-by-step recipe)
- 2026-05-17 07:30 — (this commit) — update plan progress log + PROGRESS.md row #37
Final test counts: 91 tests across 8 files. Coverage on packages/shared-store/src/: 96.1 % statements, 90.98 % branches, 98.09 % functions, 96.1 % lines — exceeds the ≥ 90 % target.
Lessons Learned
ioredis-mockshares a process-wide keyspace acrossnew RedisMock()instances; tests must callflushallinbeforeEachto get a clean slate.- ioredis 5.x typing under
module: NodeNextrequires the namedRedisimport (import { Redis } from "ioredis"); the default-export form trips TS2351 "not constructable". - Memory-adapter
eval()cannot interpret Lua, so helpers register a TS equivalent viaMemoryAdapter.registerScript(script, handler). Keeping the script body identical to the Redis one keeps the registry lookup trivial and ensures both backends stay in sync. - TTL gates belong in helper factories (each one rejects
ttlSeconds <= 0) — putting them at the adapter level would let bare-adapter callers shoot themselves; putting them in helpers means every documented entry-point is safe by default.