`options` — `RedisWsBrokerOptions` and defaults

(no submodules)

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

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

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.

3.7 KiB Raw Blame History

options — RedisWsBrokerOptions and defaults