@luckystack/core 0.4.1 → 0.5.0

package/docs/rate-limit-strategy.md

@@ -1,170 +1,170 @@
-# Rate Limit Strategy
-
-> Deep specs for the pluggable rate-limit dispatcher and built-in memory/Redis strategy. Source: `packages/core/src/rateLimiter.ts`. Bijgewerkt: 2026-05-20.
-
-## Overview
-
-Rate limiting in LuckyStack is a thin dispatcher backed by a swappable strategy. Framework code calls `checkRateLimit({ key, limit, windowMs })`; the active `RateLimitStrategy` decides how to count. The default strategy implements in-memory counters with optional Redis backing for multi-instance deployments and silently degrades to memory mode on Redis failure (with a one-shot warn log).
-
-Consumers can plug in their own backend (token-bucket, sliding-window, per-user tier limits, Cloudflare KV, no-op) by implementing the four `RateLimitStrategy` methods and calling `registerRateLimitStrategy(strategy)` at boot.
-
-The dispatcher also runs an internal cleanup timer that drops expired in-memory entries every `rateLimiting.cleanupIntervalMs`. The timer is `unref`'d so it never holds the process open.
-
-## Types
-
-```typescript
-export interface CheckRateLimitParams {
-  key: string;
-  limit: number;
-  windowMs?: number; // default 60_000
-}
-
-export interface RateLimitResult {
-  allowed: boolean;
-  remaining: number;
-  resetIn: number; // seconds until reset
-}
-
-export interface RateLimitStrategy {
-  name: string;
-  check(params: CheckRateLimitParams): Promise<RateLimitResult>;
-  getStatus(key: string, limit: number): Promise<RateLimitResult>;
-  clear(key: string): Promise<void>;
-  clearAll(): Promise<void>;
-}
-```
-
-## API Reference — Dispatcher
-
-### `checkRateLimit(params: CheckRateLimitParams): Promise<RateLimitResult>`
-
-**Behavior:** Delegates to `getRateLimitStrategy().check(params)`. Increments the counter as a side effect when allowed.
-
-**Example:**
-```typescript
-import { checkRateLimit } from '@luckystack/core';
-
-const { allowed, remaining, resetIn } = await checkRateLimit({
-  key: `user:${userId}:api:getData`,
-  limit: 60,
-});
-
-if (!allowed) {
-  return { status: 'error', errorCode: 'rateLimit.exceeded', httpStatus: 429 };
-}
-```
-
-### `getRateLimitStatus(key, limit): Promise<RateLimitResult>`
-
-**Behavior:** Read-only — does NOT increment. Useful for `X-RateLimit-Remaining` response headers.
-
-### `clearRateLimit(key): Promise<void>`
-
-Resets a single key. Useful for admin overrides or post-test cleanup.
-
-### `clearAllRateLimits(): Promise<void>`
-
-Wipes every key under the active strategy's namespace. Useful for tests / server restart.
-
-### `registerRateLimitStrategy(strategy: RateLimitStrategy): void`
-
-**Behavior:**
-- Replaces the active strategy (last-write-wins).
-- Logs `[RateLimiter] active strategy → <name>` at debug level.
-- Common use cases: token-bucket, sliding-window, per-tier user limits, edge-KV, no-op (tests).
-
-### `getRateLimitStrategy(): RateLimitStrategy`
-
-Returns the currently active strategy. Defaults to `defaultRateLimitStrategy`.
-
-## API Reference — Built-in Default Strategy
-
-### `defaultRateLimitStrategy: RateLimitStrategy`
-
-`name === 'default-memory-redis'`. Reads `projectConfig.rateLimiting.{enabled,store,redisKeyPrefix,windowMs}` at call time.
-
-#### `check(params)` flow
-
-1. If `rateLimiting.enabled === false` → returns `{ allowed: true, remaining: limit, resetIn: 0 }` without touching counters.
-2. If `rateLimiting.store === 'redis'`:
-   - Runs a Lua `INCR` + `PEXPIRE` script atomically against `<projectName>:<redisKeyPrefix>:<key>`.
-   - Returns `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil(ttl / 1000) }` when the script returns a valid pair.
-   - On any Redis error, logs a one-shot warn `[RateLimiter] Redis mode unavailable, falling back to in-memory mode` and falls through to the memory path.
-3. Memory path:
-   - First request in the window → create entry, return `allowed: true, remaining: limit - 1`.
-   - Subsequent requests → increment, return `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil((resetAt - now) / 1000) }`.
-
-#### `getStatus(key, limit)` flow
-
-Same dual-path shape but does NOT increment. The Redis path uses `MULTI` (`GET` + `PTTL`) to read current count + remaining TTL.
-
-#### `clear(key)` flow
-
-- Redis mode: `DEL <prefix>:<key>` (wrapped in `tryCatch`).
-- Always: deletes the in-memory entry as well.
-
-#### `clearAll()` flow
-
-- Redis mode: `SCAN` with `MATCH <prefix>:*`, `DEL` matched keys, repeat until cursor returns to `'0'`.
-- Always: clears the in-memory map.
-
-### Lua script (atomic increment)
-
-```lua
-local current = redis.call('INCR', KEYS[1])
-if current == 1 then
-  redis.call('PEXPIRE', KEYS[1], ARGV[1])
-end
-local ttl = redis.call('PTTL', KEYS[1])
-return { current, ttl }
-```
-
-### Cleanup timer
-
-A self-rescheduling `setTimeout(unref)` deletes expired in-memory entries every `rateLimiting.cleanupIntervalMs`. Re-reads the config each tick so a late `registerProjectConfig` is picked up. Logs `[RateLimiter] Cleaned N expired entries` at debug level when any are removed.
-
-## Edge cases
-
-- Negative or non-finite `windowMs` is normalized to `projectConfig.rateLimiting.windowMs`.
-- Concurrent strategy switches are allowed but the cleanup timer keeps running against the in-memory map regardless of the active strategy — fine because the map is only touched by the default strategy.
-- The default Redis script + scan path swallow errors via `tryCatch`; a network blip degrades to memory mode instead of throwing.
-- The disabled mode (`rateLimiting.enabled = false`) still calls `getStatus` happily — useful for showing meaningful headers in dev.
-
-## Hooks dispatched
-
-Rate limiting itself does not dispatch hooks from core. The api/sync packages dispatch `rateLimitExceeded` when their handlers translate a `RateLimitResult` rejection into the response envelope.
-
-## Config keys consumed
-
-| Key | Type | Default | Description |
-|---|---|---|---|
-| `rateLimiting.enabled` | `boolean` | `true` | Global kill-switch. |
-| `rateLimiting.store` | `'memory' \| 'redis'` | `'memory'` | Backend. |
-| `rateLimiting.redisKeyPrefix` | `string` | `'rate-limit'` | Prefixed with `<projectName>:`. |
-| `rateLimiting.defaultApiLimit` | `number \| false` | `60` | Default per-route cap (consumed by api package). |
-| `rateLimiting.defaultIpLimit` | `number \| false` | `100` | Default per-IP cap. |
-| `rateLimiting.windowMs` | `number` | `60_000` | Sliding window. |
-| `rateLimiting.cleanupIntervalMs` | `number` | `60_000` | Memory eviction cadence. |
-
-## Example — register a no-op strategy for tests
-
-```typescript
-import { registerRateLimitStrategy, type RateLimitStrategy } from '@luckystack/core';
-
-const noopStrategy: RateLimitStrategy = {
-  name: 'noop',
-  check: async ({ limit }) => ({ allowed: true, remaining: limit, resetIn: 0 }),
-  getStatus: async (_key, limit) => ({ allowed: true, remaining: limit, resetIn: 0 }),
-  clear: async () => undefined,
-  clearAll: async () => undefined,
-};
-
-registerRateLimitStrategy(noopStrategy);
-```
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `docs/ARCHITECTURE_API.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/rateLimiter.ts`
+# Rate Limit Strategy
+
+> Deep specs for the pluggable rate-limit dispatcher and built-in memory/Redis strategy. Source: `packages/core/src/rateLimiter.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+Rate limiting in LuckyStack is a thin dispatcher backed by a swappable strategy. Framework code calls `checkRateLimit({ key, limit, windowMs })`; the active `RateLimitStrategy` decides how to count. The default strategy implements in-memory counters with optional Redis backing for multi-instance deployments and silently degrades to memory mode on Redis failure (with a one-shot warn log).
+
+Consumers can plug in their own backend (token-bucket, sliding-window, per-user tier limits, Cloudflare KV, no-op) by implementing the four `RateLimitStrategy` methods and calling `registerRateLimitStrategy(strategy)` at boot.
+
+The dispatcher also runs an internal cleanup timer that drops expired in-memory entries every `rateLimiting.cleanupIntervalMs`. The timer is `unref`'d so it never holds the process open.
+
+## Types
+
+```typescript
+export interface CheckRateLimitParams {
+  key: string;
+  limit: number;
+  windowMs?: number; // default 60_000
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetIn: number; // seconds until reset
+}
+
+export interface RateLimitStrategy {
+  name: string;
+  check(params: CheckRateLimitParams): Promise<RateLimitResult>;
+  getStatus(key: string, limit: number): Promise<RateLimitResult>;
+  clear(key: string): Promise<void>;
+  clearAll(): Promise<void>;
+}
+```
+
+## API Reference — Dispatcher
+
+### `checkRateLimit(params: CheckRateLimitParams): Promise<RateLimitResult>`
+
+**Behavior:** Delegates to `getRateLimitStrategy().check(params)`. Increments the counter as a side effect when allowed.
+
+**Example:**
+```typescript
+import { checkRateLimit } from '@luckystack/core';
+
+const { allowed, remaining, resetIn } = await checkRateLimit({
+  key: `user:${userId}:api:getData`,
+  limit: 60,
+});
+
+if (!allowed) {
+  return { status: 'error', errorCode: 'rateLimit.exceeded', httpStatus: 429 };
+}
+```
+
+### `getRateLimitStatus(key, limit): Promise<RateLimitResult>`
+
+**Behavior:** Read-only — does NOT increment. Useful for `X-RateLimit-Remaining` response headers.
+
+### `clearRateLimit(key): Promise<void>`
+
+Resets a single key. Useful for admin overrides or post-test cleanup.
+
+### `clearAllRateLimits(): Promise<void>`
+
+Wipes every key under the active strategy's namespace. Useful for tests / server restart.
+
+### `registerRateLimitStrategy(strategy: RateLimitStrategy): void`
+
+**Behavior:**
+- Replaces the active strategy (last-write-wins).
+- Logs `[RateLimiter] active strategy → <name>` at debug level.
+- Common use cases: token-bucket, sliding-window, per-tier user limits, edge-KV, no-op (tests).
+
+### `getRateLimitStrategy(): RateLimitStrategy`
+
+Returns the currently active strategy. Defaults to `defaultRateLimitStrategy`.
+
+## API Reference — Built-in Default Strategy
+
+### `defaultRateLimitStrategy: RateLimitStrategy`
+
+`name === 'default-memory-redis'`. Reads `projectConfig.rateLimiting.{enabled,store,redisKeyPrefix,windowMs}` at call time.
+
+#### `check(params)` flow
+
+1. If `rateLimiting.enabled === false` → returns `{ allowed: true, remaining: limit, resetIn: 0 }` without touching counters.
+2. If `rateLimiting.store === 'redis'`:
+   - Runs a Lua `INCR` + `PEXPIRE` script atomically against `<projectName>:<redisKeyPrefix>:<key>`.
+   - Returns `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil(ttl / 1000) }` when the script returns a valid pair.
+   - On any Redis error, logs a one-shot warn `[RateLimiter] Redis mode unavailable, falling back to in-memory mode` and falls through to the memory path.
+3. Memory path:
+   - First request in the window → create entry, return `allowed: true, remaining: limit - 1`.
+   - Subsequent requests → increment, return `{ allowed: count <= limit, remaining: max(0, limit - count), resetIn: ceil((resetAt - now) / 1000) }`.
+
+#### `getStatus(key, limit)` flow
+
+Same dual-path shape but does NOT increment. The Redis path uses `MULTI` (`GET` + `PTTL`) to read current count + remaining TTL.
+
+#### `clear(key)` flow
+
+- Redis mode: `DEL <prefix>:<key>` (wrapped in `tryCatch`).
+- Always: deletes the in-memory entry as well.
+
+#### `clearAll()` flow
+
+- Redis mode: `SCAN` with `MATCH <prefix>:*`, `DEL` matched keys, repeat until cursor returns to `'0'`.
+- Always: clears the in-memory map.
+
+### Lua script (atomic increment)
+
+```lua
+local current = redis.call('INCR', KEYS[1])
+if current == 1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[1])
+end
+local ttl = redis.call('PTTL', KEYS[1])
+return { current, ttl }
+```
+
+### Cleanup timer
+
+A self-rescheduling `setTimeout(unref)` deletes expired in-memory entries every `rateLimiting.cleanupIntervalMs`. Re-reads the config each tick so a late `registerProjectConfig` is picked up. Logs `[RateLimiter] Cleaned N expired entries` at debug level when any are removed.
+
+## Edge cases
+
+- Negative or non-finite `windowMs` is normalized to `projectConfig.rateLimiting.windowMs`.
+- Concurrent strategy switches are allowed but the cleanup timer keeps running against the in-memory map regardless of the active strategy — fine because the map is only touched by the default strategy.
+- The default Redis script + scan path swallow errors via `tryCatch`; a network blip degrades to memory mode instead of throwing.
+- The disabled mode (`rateLimiting.enabled = false`) still calls `getStatus` happily — useful for showing meaningful headers in dev.
+
+## Hooks dispatched
+
+Rate limiting itself does not dispatch hooks from core. The api/sync packages dispatch `rateLimitExceeded` when their handlers translate a `RateLimitResult` rejection into the response envelope.
+
+## Config keys consumed
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `rateLimiting.enabled` | `boolean` | `true` | Global kill-switch. |
+| `rateLimiting.store` | `'memory' \| 'redis'` | `'memory'` | Backend. |
+| `rateLimiting.redisKeyPrefix` | `string` | `'rate-limit'` | Prefixed with `<projectName>:`. |
+| `rateLimiting.defaultApiLimit` | `number \| false` | `60` | Default per-route cap (consumed by api package). |
+| `rateLimiting.defaultIpLimit` | `number \| false` | `100` | Default per-IP cap. |
+| `rateLimiting.windowMs` | `number` | `60_000` | Sliding window. |
+| `rateLimiting.cleanupIntervalMs` | `number` | `60_000` | Memory eviction cadence. |
+
+## Example — register a no-op strategy for tests
+
+```typescript
+import { registerRateLimitStrategy, type RateLimitStrategy } from '@luckystack/core';
+
+const noopStrategy: RateLimitStrategy = {
+  name: 'noop',
+  check: async ({ limit }) => ({ allowed: true, remaining: limit, resetIn: 0 }),
+  getStatus: async (_key, limit) => ({ allowed: true, remaining: limit, resetIn: 0 }),
+  clear: async () => undefined,
+  clearAll: async () => undefined,
+};
+
+registerRateLimitStrategy(noopStrategy);
+```
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_EXTENSION_POINTS.md`, `docs/ARCHITECTURE_API.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/rateLimiter.ts`

package/docs/redis-adapter.md

@@ -1,111 +1,111 @@
-# Redis Adapter
-
-> Deep specs for the Redis client proxy, connection options helper, and the Socket.io cross-instance adapter. Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`. Bijgewerkt: 2026-05-20.
-
-## Overview
-
-Core ships a single Redis client that the entire framework shares for session storage, rate limiting, OAuth state, password-reset tokens, boot UUIDs, and the Socket.io pub/sub adapter. The `redis` export is a `Proxy` that defers resolution to call time so a consumer can `registerRedisClient(customClient)` after this module is imported and still win.
-
-`attachSocketRedisAdapter(io)` wires `@socket.io/redis-adapter` with two duplicated pub/sub connections so room broadcasts span multiple Node processes — without it, `io.to(room).emit(...)` only reaches clients connected to the same instance.
-
-`getRedisConnectionOptions()` exposes the same `{ host, port, username?, password? }` shape that the framework's default ioredis client uses. `@luckystack/router` reuses it for short-lived cross-env probes so a config rename never drifts between writer and reader.
-
-## API Reference
-
-### `redis: RedisClient` (proxy)
-
-**Signature:**
-```typescript
-export const redis: RedisClient
-export default redis
-```
-
-**Behavior:**
-- Every method/property access is forwarded to whatever `getRedisClient()` currently returns.
-- When the consumer has called `registerRedisClient(...)`, that client wins.
-- Otherwise the proxy lazily constructs a default ioredis instance from `env.REDIS_HOST` / `env.REDIS_PORT` (plus optional `REDIS_USER` / `REDIS_PASSWORD`) on first access.
-- The default client installs a `connect` listener that logs `"Connected to Redis"` via `getLogger().info` and an `error` listener that routes to `getLogger().error`.
-- The default client uses an exponential `retryStrategy(times => Math.min(times * 50, 2000))`.
-
-**Edge cases:**
-- Method results are auto-bound to the underlying client to keep `this` correct for chained calls (`redis.multi().get(...).exec()` works).
-- The `has` trap checks against the live client so `'eval' in redis` reports whatever the registered client supports.
-
-**Example:**
-```typescript
-import { redis } from '@luckystack/core';
-
-await redis.set(`${prefix}:foo`, 'bar', 'EX', 60);
-const value = await redis.get(`${prefix}:foo`);
-```
-
-### `getRedisConnectionOptions(): RedisConnectionOptions`
-
-**Signature:**
-```typescript
-export interface RedisConnectionOptions {
-  host: string;
-  port: number;
-  username?: string;
-  password?: string;
-}
-
-export const getRedisConnectionOptions = (): RedisConnectionOptions
-```
-
-**Behavior:**
-- Reads `env.REDIS_HOST` and parses `env.REDIS_PORT` to a number.
-- Includes `username` only when `process.env.REDIS_USER` is non-empty.
-- Includes `password` only when `process.env.REDIS_PASSWORD` is non-empty.
-- Read at call time so dotenv timing doesn't capture stale values.
-
-**Example:**
-```typescript
-import Redis from 'ioredis';
-import { getRedisConnectionOptions } from '@luckystack/core';
-
-// router-side: open a short-lived probe with the same params
-const probe = new Redis({ ...getRedisConnectionOptions(), lazyConnect: true });
-```
-
-### `attachSocketRedisAdapter(io: SocketIOServer): void`
-
-**Signature:**
-```typescript
-export const attachSocketRedisAdapter = (io: SocketIOServer): void
-```
-
-**Behavior (in order):**
-1. Calls `redis.duplicate()` twice to obtain dedicated pub + sub clients (ioredis blocks non-pub/sub commands on a connection in subscribe mode, so duplicating is required).
-2. Installs `error` listeners on both clients that log to `console.error` with the `[socket-redis-adapter]` prefix.
-3. Calls `io.adapter(createAdapter(pubClient, subClient))` to wire `@socket.io/redis-adapter`.
-
-**Edge cases:**
-- Calling this after `io` has already accepted connections is allowed but races with in-flight broadcasts — wire it before `io.listen` / connection handlers in the boot sequence.
-- The duplicated clients inherit the active registered client (or the default).
-
-**Example:**
-```typescript
-import { Server } from 'socket.io';
-import { attachSocketRedisAdapter, setIoInstance } from '@luckystack/core';
-
-const io = new Server(httpServer, { /* ... */ });
-attachSocketRedisAdapter(io);
-setIoInstance(io);
-```
-
-## Config keys consumed
-
-| Env var | Default | Purpose |
-|---|---|---|
-| `REDIS_HOST` | `'127.0.0.1'` | Default client + `getRedisConnectionOptions`. |
-| `REDIS_PORT` | `'6379'` | Same. |
-| `REDIS_USER` | (unset) | Optional ioredis auth. |
-| `REDIS_PASSWORD` | (unset) | Optional ioredis auth. |
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_SOCKET.md`, `docs/HOSTING.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`, `clients.ts`
+# Redis Adapter
+
+> Deep specs for the Redis client proxy, connection options helper, and the Socket.io cross-instance adapter. Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+Core ships a single Redis client that the entire framework shares for session storage, rate limiting, OAuth state, password-reset tokens, boot UUIDs, and the Socket.io pub/sub adapter. The `redis` export is a `Proxy` that defers resolution to call time so a consumer can `registerRedisClient(customClient)` after this module is imported and still win.
+
+`attachSocketRedisAdapter(io)` wires `@socket.io/redis-adapter` with two duplicated pub/sub connections so room broadcasts span multiple Node processes — without it, `io.to(room).emit(...)` only reaches clients connected to the same instance.
+
+`getRedisConnectionOptions()` exposes the same `{ host, port, username?, password? }` shape that the framework's default ioredis client uses. `@luckystack/router` reuses it for short-lived cross-env probes so a config rename never drifts between writer and reader.
+
+## API Reference
+
+### `redis: RedisClient` (proxy)
+
+**Signature:**
+```typescript
+export const redis: RedisClient
+export default redis
+```
+
+**Behavior:**
+- Every method/property access is forwarded to whatever `getRedisClient()` currently returns.
+- When the consumer has called `registerRedisClient(...)`, that client wins.
+- Otherwise the proxy lazily constructs a default ioredis instance from `env.REDIS_HOST` / `env.REDIS_PORT` (plus optional `REDIS_USER` / `REDIS_PASSWORD`) on first access.
+- The default client installs a `connect` listener that logs `"Connected to Redis"` via `getLogger().info` and an `error` listener that routes to `getLogger().error`.
+- The default client uses an exponential `retryStrategy(times => Math.min(times * 50, 2000))`.
+
+**Edge cases:**
+- Method results are auto-bound to the underlying client to keep `this` correct for chained calls (`redis.multi().get(...).exec()` works).
+- The `has` trap checks against the live client so `'eval' in redis` reports whatever the registered client supports.
+
+**Example:**
+```typescript
+import { redis } from '@luckystack/core';
+
+await redis.set(`${prefix}:foo`, 'bar', 'EX', 60);
+const value = await redis.get(`${prefix}:foo`);
+```
+
+### `getRedisConnectionOptions(): RedisConnectionOptions`
+
+**Signature:**
+```typescript
+export interface RedisConnectionOptions {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+}
+
+export const getRedisConnectionOptions = (): RedisConnectionOptions
+```
+
+**Behavior:**
+- Reads `env.REDIS_HOST` and parses `env.REDIS_PORT` to a number.
+- Includes `username` only when `process.env.REDIS_USER` is non-empty.
+- Includes `password` only when `process.env.REDIS_PASSWORD` is non-empty.
+- Read at call time so dotenv timing doesn't capture stale values.
+
+**Example:**
+```typescript
+import Redis from 'ioredis';
+import { getRedisConnectionOptions } from '@luckystack/core';
+
+// router-side: open a short-lived probe with the same params
+const probe = new Redis({ ...getRedisConnectionOptions(), lazyConnect: true });
+```
+
+### `attachSocketRedisAdapter(io: SocketIOServer): void`
+
+**Signature:**
+```typescript
+export const attachSocketRedisAdapter = (io: SocketIOServer): void
+```
+
+**Behavior (in order):**
+1. Calls `redis.duplicate()` twice to obtain dedicated pub + sub clients (ioredis blocks non-pub/sub commands on a connection in subscribe mode, so duplicating is required).
+2. Installs `error` listeners on both clients that log to `console.error` with the `[socket-redis-adapter]` prefix.
+3. Calls `io.adapter(createAdapter(pubClient, subClient))` to wire `@socket.io/redis-adapter`.
+
+**Edge cases:**
+- Calling this after `io` has already accepted connections is allowed but races with in-flight broadcasts — wire it before `io.listen` / connection handlers in the boot sequence.
+- The duplicated clients inherit the active registered client (or the default).
+
+**Example:**
+```typescript
+import { Server } from 'socket.io';
+import { attachSocketRedisAdapter, setIoInstance } from '@luckystack/core';
+
+const io = new Server(httpServer, { /* ... */ });
+attachSocketRedisAdapter(io);
+setIoInstance(io);
+```
+
+## Config keys consumed
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `REDIS_HOST` | `'127.0.0.1'` | Default client + `getRedisConnectionOptions`. |
+| `REDIS_PORT` | `'6379'` | Same. |
+| `REDIS_USER` | (unset) | Optional ioredis auth. |
+| `REDIS_PASSWORD` | (unset) | Optional ioredis auth. |
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_SOCKET.md`, `docs/HOSTING.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/redis.ts`, `socketRedisAdapter.ts`, `clients.ts`