251 lines
18 KiB
Markdown
251 lines
18 KiB
Markdown
# 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<string, Bucket>` 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<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)
|
|
|
|
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<string, { value: string; expiresAt?: number }>` + 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:<namespace>:<key>`), 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<T>({ 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<T>({ store, prefix, ttlSeconds, serializer? })` mit `{ get, set, delete, invalidate, onInvalidate }`
|
|
- `invalidate(key)` published auf Channel `<prefix>: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:** `<source>.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 <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_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 <host> -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.
|