# `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.