Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,250 @@
# 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.