# 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` — `ipBuckets` und `accountBuckets` als `Map` im API-Prozess - `apps/web/app/utils/auth/mfa/challenge-rate-limit.server.ts:1-9` — analoge Map für MFA-Challenges - `apps/api/src/idempotency/store.ts:231-306` — Memory-Fallback wenn Redis nicht konfiguriert - `apps/web/app/utils/services/.server/subscriptionService.ts:338-343` — `cachified` mit In-Memory-LRU - `apps/api/src/auth/session/session-store.ts:42-118` — Token-Storage im Prozess-Heap - `apps/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 blind - `02-observability/logging-migration.md` — Adapter loggt Operations via zentralem Logger statt `console.log` ## Blocks - `03-scaling-infrastructure/shared-store-migration.md` — Migration der 6 In-Process-Stores braucht das Interface - `03-scaling-infrastructure/pubsub-cache-invalidation.md` — Pub/Sub-Channel-Helpers kommen aus diesem Paket - `03-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/Sub - `07-chatbot/chatbot-mvp.md` — Conversation-State-Cache ## Approach **Neues Package `packages/shared-store/`** mit folgender Architektur: 1. **Adapter-Interface** (`SharedStoreAdapter`) — minimaler Surface-Area, der sich von Redis sauber abbilden lässt und in einer Map nachbaubar ist: - `get(key): Promise` - `set(key, value, opts?: { ttlSeconds?: number; nx?: boolean }): Promise` - `del(key): Promise` - `incr(key, by?): Promise` - `expire(key, ttlSeconds): Promise` - `mget(keys: string[]): Promise<(string | null)[]>` - `scan(pattern: string, opts?: { count?: number }): AsyncIterable` - `publish(channel, message): Promise` - `subscribe(channel, handler): Promise<() => Promise>` (returns unsubscribe) 2. **Zwei Implementations:** - `RedisAdapter` (über `ioredis`) — 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` + per-Key-`setTimeout` für TTL-Cleanup. Pub/Sub via lokaler `EventEmitter`. 3. **Factory `createSharedStore({ namespace, ttlDefault, redisUrl? })`** — wählt Adapter: - Wenn `redisUrl` (oder `process.env.REDIS_URL`) gesetzt → RedisAdapter - Sonst → MemoryAdapter (mit Warning-Log: „Running in single-process mode") - `namespace` wird allen Keys vorangestellt (`shared-store::`), verhindert Kollisionen zwischen Stores 4. **Higher-Level-Helpers** (alle auf SharedStoreAdapter aufbauend): - `createFixedWindowRateLimiter({ store, prefix, windowSeconds, max })` — klassisches Counter+Expire-Pattern via `incr` + `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({ store, prefix, ttlSeconds, serializer })` — get/set/delete mit JSON-Serialization, plus `invalidate(channel?)` der eine Pub/Sub-Message published - `createSessionStore({ store, prefix, ttlSeconds })` — getSession/setSession/destroySession - `createIdempotencyStore({ store, prefix, ttlSeconds })` — setIfNotExists (atomic via `set NX EX`), getResult, completeWithResult 5. **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:** - ❌ `cachified` direkt 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-redis` statt `ioredis`: 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 1. **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` 2. **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 via `setTimeout`-Cleanup (mit `unref()` 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` 3. **Redis-Adapter via ioredis** - Files: `src/adapters/redis.ts`, `src/adapters/redis.test.ts` - `RedisAdapter` mit 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` 4. **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` 5. **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` 6. **Cache-Store mit Pub/Sub-Invalidation** - Files: `src/helpers/cache.ts`, `src/helpers/cache.test.ts` - `createCacheStore({ store, prefix, ttlSeconds, serializer? })` mit `{ get, set, delete, invalidate, onInvalidate }` - `invalidate(key)` published auf Channel `:invalidate` - `onInvalidate(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` 7. **Session-Store** - Files: `src/helpers/session.ts`, `src/helpers/session.test.ts` - `createSessionStore({ store, prefix, ttlSeconds })` mit `getSession`, `setSession`, `destroySession`, `touchSession` (TTL-Refresh) - Tests: TTL-Refresh, Concurrent-Touch, Destroy-During-Read - Commit: `03-scaling/shared-store: add session store helper` 8. **Idempotency-Store** - Files: `src/helpers/idempotency.ts`, `src/helpers/idempotency.test.ts` - `createIdempotencyStore({ store, prefix, ttlSeconds })` mit `claim(key): Promise<{ claimed: boolean; existingResult?: unknown }>`, `completeWithResult(key, result)`, `getResult(key)` - Atomic-Claim via `set NX EX` in einem Roundtrip - Tests: Concurrent-Claim (nur einer wins), Result-Persistierung, Expiry - Commit: `03-scaling/shared-store: add idempotency store helper` 9. **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:integration` läuft mit `TEST_REDIS=1` - Commit: `03-scaling/shared-store: add testcontainers integration suite` 10. **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.ts` Public-Exports finalisieren - Commit: `03-scaling/shared-store: add package readme and observability docs stub` ## 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.ts` mit zwei Adapter-Instances gegen einen Redis-Container — beweist Multi-Replica-Konsistenz - **Coverage-Target:** ≥ 90 % lines/branches im neuen Package - **Test-Files:** `.test.ts` co-located; Integration in `src/__integration__/` - **CI-Setup:** Integration-Tests gated über `TEST_REDIS=1` Env-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, `SharedStoreAdapter` Type - [ ] 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 test` grün - [ ] `docs/observability/redis-stores.md` Stub angelegt mit DB-Index-Mapping (Index 0 = BullMQ, Index 1 = Shared-Store, Index 2 = Pub/Sub) - [ ] `packages/shared-store/README.md` mit 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 ` 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_URL` darf nie geloggt werden (kann Passwort enthalten). Adapter maskiert URL in Logs via `new 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.md` wenn nötig ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + Stichproben aus `apps/api/src/auth/login-rate-limit.ts` und `apps/api/src/idempotency/store.ts` als Input — soll Adapter-Surface gegen reale Call-Sites validieren - **Research:** `Explore`-Subagent mit Auftrag „suche existierende Redis-Wrapper-Patterns in `packages/queue` und `packages/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-verifier` prüft Acceptance-Criteria-Checkliste; Coverage-Gate-Check via `pnpm --filter @toolctrl/shared-store test -- --coverage` - **Code-Review:** `gsd-code-reviewer` nach Schritt 10, mit Fokus auf Adapter-Interface-Konsistenz und Lua-Script-Sicherheit ## Staging-Deployment-Steps 1. Branch `agent/03-shared-store-package` pushen 2. 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) 3. **Redis-Container auf Staging hochziehen** (falls noch nicht aus #38 vorhanden): ```yaml # 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: ``` 4. `REDIS_URL=redis://redis:6379` in Coolify-Env setzen 5. Smoke-Test: SSH auf Staging-Server, `redis-cli -h -p 6379 INFO server` → erwarte Redis 7.x 6. 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-mock` fü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); nur `SCRIPT LOAD` fehlt, was der Adapter automatisch via EVAL-Fallback umgeht. - **Docs-Stub:** `docs/observability/redis-stores.md` wurde 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. `c8` liefert 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-mock` shares a process-wide keyspace across `new RedisMock()` instances; tests must call `flushall` in `beforeEach` to get a clean slate. - ioredis 5.x typing under `module: NodeNext` requires the named `Redis` import (`import { Redis } from "ioredis"`); the default-export form trips TS2351 "not constructable". - Memory-adapter `eval()` cannot interpret Lua, so helpers register a TS equivalent via `MemoryAdapter.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.