Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/03-scaling-infrastructure/shared-store-package.md
T

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 — 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):
    # 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.