Initial Commit

packages/api-stack/api/api-ws-broker-redis/src/options/options.md

@@ -0,0 +1,95 @@
+# `options` — `RedisWsBrokerOptions` and defaults
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module defines the configuration shape consumed by
+`createRedisWsBroker(...)`. Every operational knob the broker exposes lives
+here — Redis URL, key/channel prefixes, event-buffer cap and TTL, payload
+compression threshold, command timeout, reconnect strategy, and the disable
+flags used by tests. The schema is strict: unknown keys at the wire-options
+boundary fail fast rather than landing as silently-ignored typos.
+
+The module also pins the `MAX_PAYLOAD_BYTES` 4 MiB hard cap. That ceiling is
+deliberately matched to typical Redis client defaults so the broker stays safe
+in shared deployments where one greedy publisher could otherwise flood the
+fan-out fabric.
+
+## Features
+
+- Single Zod schema (`redisWsBrokerOptionsSchema`) with `strict()` mode,
+  validated at the constructor boundary so misconfigurations never reach the
+  socket layer.
+- Documented defaults exported as constants (`DEFAULT_KEY_PREFIX`,
+  `DEFAULT_CHANNEL_PREFIX`, `DEFAULT_EVENT_BUFFER_TTL_SEC`,
+  `DEFAULT_EVENT_BUFFER_MAX_EVENTS`, `DEFAULT_COMPRESSION_THRESHOLD_BYTES`,
+  `DEFAULT_COMMAND_TIMEOUT_MS`, `DEFAULT_RECONNECT_STRATEGY`) so operators
+  can rebuild a known-good shape programmatically.
+- `resolveRedisWsBrokerOptions(opts)` returns a fully-defaulted bundle
+  (`ResolvedRedisWsBrokerOptions`) without any optional fields — internal
+  code never has to defend against `undefined`.
+- Partial `reconnectStrategy` overrides are honoured field-by-field; the
+  rest backfills from `DEFAULT_RECONNECT_STRATEGY`.
+- `randomHostId()` mints a per-host identifier when `hostId` is omitted,
+  so multi-host deployments can attribute broadcasts without any extra
+  configuration.
+
+## Usage: Basic
+
+```ts
+import { resolveRedisWsBrokerOptions } from "@suaveplan/api-ws-broker-redis/options";
+
+const opts = resolveRedisWsBrokerOptions({
+    connection: "redis://localhost:6379",
+});
+// opts.keyPrefix === "suaveplan:ws:"
+// opts.channelPrefix === "ws.broadcast."
+// opts.eventBufferTtlSec === 300
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    DEFAULT_RECONNECT_STRATEGY,
+    redisWsBrokerOptionsSchema,
+} from "@suaveplan/api-ws-broker-redis/options";
+
+const raw = JSON.parse(env.BROKER_CONFIG_JSON);
+const parsed = redisWsBrokerOptionsSchema.safeParse(raw);
+if (!parsed.success) throw new Error(parsed.error.message);
+
+const stagingStrategy = {
+    ...DEFAULT_RECONNECT_STRATEGY,
+    maxAttempts: 1_000,
+    maxDelayMs: 10_000,
+};
+```
+
+## API Reference
+
+- `RedisWsBrokerOptions` — public, wire-validated option shape.
+- `ResolvedRedisWsBrokerOptions` — fully-defaulted bundle used internally.
+- `RedisReconnectStrategy` — exponential-backoff configuration.
+- `redisWsBrokerOptionsSchema` — strict Zod schema.
+- `resolveRedisWsBrokerOptions(opts)` — apply defaults.
+- `MAX_PAYLOAD_BYTES` — 4 MiB hard cap.
+- `DEFAULT_*` — every documented default exported as a constant.
+
+## Implementation Notes
+
+The schema separates "wire options" (validated, strict) from "factory options"
+(broker-only knobs like `clientFactory` and `readyTimeoutMs`). The broker
+constructor strips the latter before parsing so the schema does not reject
+them, while still failing fast on unrecognised keys for the genuine wire
+shape. Tests cover both paths explicitly.
+
+`randomHostId()` uses `Math.random()` for the host suffix. This is fine for
+attribution — collisions on an 8-byte random tag are astronomically rare and
+the broker would still be correct under collision; it just becomes harder
+to attribute a publish on a dashboard. Operators with stricter requirements
+should pass an explicit `hostId` derived from their orchestrator's
+identifier.