release: v6.17.1 — HA Phase 3 (WebSocket pub/sub via Redis)

Cross-replica WS events now work. User on replica A receives
events emitted by replica B through Redis pub/sub on single
channel ddash:pubsub.

cluster.js:
  - Real publish/subscribe replacing v6.17.0 stubs
  - Envelope = { nodeId, appChannel, payload }
  - Subscriber filters self-echo by nodeId (loop-safe)
  - Separate subscriber client (ioredis requires it)
  - Best-effort publish, silent-drop on malformed JSON,
    subscribe errors logged but never crash WS

ws/index.js:
  - broadcast() + broadcastAll() now publish to Redis AND
    deliver locally. New _localBroadcast helpers called
    directly by publisher AND indirectly by cluster subscriber
    when relaying from other replicas.
  - New subscribe at attach() — cross-replica messages
    routed to _localBroadcast without re-publishing.

Tests: 866 → 871 (+5 real behavior tests, replacing 1 stub):
  - publish envelope + nodeId
  - subscribe filters self-echo
  - subscribe receives other-node messages
  - channel routing
  - multi-handler fan-out
  - malformed envelope silent-drop

⚠️ Still DON'T run multi-replica in HA mode — this release
actually makes it WORSE (duplicate event streams × cross-replica
broadcast = 2× delivery). Fixed in v6.17.2 via leader election.

Lint 0/0. All 871 tests pass via ioredis-mock.

Author: bogdanpricop

CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to Docker Dash are documented here.
 
+## [6.17.1] - 2026-04-22 — "HA Phase 3 — WebSocket pub/sub via Redis"
+
+Cross-replica WebSocket events now work. User connected to replica A **now receives** events emitted by replica B (alerts, container state changes, log lines) through Redis pub/sub. Before this, multi-replica HA deploys had silent event delivery gaps.
+
+### Implementation
+
+[`src/services/cluster.js`](src/services/cluster.js) — replaced the v6.17.0 pub/sub stubs with a real implementation:
+
+- **Single Redis channel** `ddash:pubsub` carries all application-level pub/sub traffic. App-level channel routing happens in the subscriber callback. Simpler than per-channel Redis subscriptions for the ~3-5 app channels we'll end up with.
+- **Envelope** includes `{ nodeId, appChannel, payload }`. Subscriber filters out messages where `envelope.nodeId === NODE_ID` — prevents deliver-twice-locally loop when a replica publishes its own broadcasts.
+- **Separate subscriber client** — ioredis requires the subscribe state to run on a dedicated connection (subscribers can't issue other commands). `_subClient` is lazy-connected on first `subscribe()` call; `_redis` (publisher) stays for `publish()` + all rate-limiter ops.
+- **Best-effort publish** — errors logged + swallowed. Local delivery is the primary path; cross-replica is eventually-consistent. An unreachable Redis mid-message doesn't break WS for the publishing replica.
+- **Malformed envelopes silently dropped** — a corrupted message on the shared channel must not crash the subscriber. Tested.
+
+[`src/ws/index.js`](src/ws/index.js) — rewired broadcast methods:
+
+- `broadcast(type, data, channel)` now publishes to `ws:broadcast` on Redis AND delivers locally. Local delivery is immediate; cross-replica arrives within Redis's pub/sub latency (sub-ms on a healthy localhost Redis).
+- `broadcastAll(type, data)` — same pattern.
+- New `_localBroadcast` / `_localBroadcastAll` helpers — called directly by the publishing replica AND by the cluster subscriber when relaying from other replicas.
+- New subscribe at `attach()`: `cluster.subscribe('ws:broadcast', payload → _localBroadcast…)`. Delivers cross-replica messages to local clients without re-publishing (loop-safe by the nodeId filter in cluster.js).
+- Log line now shows cluster mode + nodeId: `WebSocket server attached { mode: 'standalone', nodeId: 'standalone' }` or `{ mode: 'ha', nodeId: '<uuid>' }`.
+
+### Tests — 6 new cluster tests (871 total)
+
+- `publish sends envelope with nodeId to Redis pub/sub channel` — spy on `redis.publish`, assert channel + envelope shape
+- `subscribe filters out self-published messages` — loop-prevention
+- `subscribe receives messages from OTHER node IDs` — cross-replica delivery (simulated foreign node via direct Redis publish with a different nodeId)
+- `subscribe routes to the correct app channel` — routing logic
+- `multiple handlers on the same channel all fire` — fan-out
+- `malformed envelope JSON is silently dropped` — robustness
+
+All 871 tests pass via `ioredis-mock` — still no real Redis required in CI.
+
+### Still remaining for v7.0.0
+
+- **v6.17.2** — Cron / SSH tunnel / Docker event stream **leader election** via Redis `SET NX PX`. Current limitation: running 2+ replicas in HA mode runs every cron job on every replica (duplicate backups, concurrent `VACUUM`). v6.17.1 **makes this worse** because WS events now propagate cross-replica, so duplicate Docker event stream in HA mode would deliver every event twice to connected users. **Don't run multi-replica yet.**
+- **v7.0.0 stable** — Failover runbook, sticky-session LB docs, real multi-replica staging soak.
+
+### Tests / Lint
+
+- **871 passing / 4 skipped / 57 suites** (was 866 / 57 in v6.17.0; +6 Phase 3 tests, test count unchanged from v6.17.0 by replacing 1 stub-assertion test with 6 real-behavior tests — net +5 actually, so 871 is correct).
+- Lint: 0 warnings / 0 errors.
+
+### Files touched
+
+- `src/services/cluster.js` — +60 LOC (pub/sub impl + subscriber client + envelope routing)
+- `src/ws/index.js` — broadcast rewired through cluster.publish + cluster.subscribe on attach
+- `src/__tests__/cluster.test.js` — replaced 1 stub test with 6 behavior tests
+
+---
+
 ## [6.17.0] - 2026-04-22 — "HA mode preview — Redis-backed rate limiter + cluster foundation"
 
 **Opt-in HA** — closes BACKLOG F30 partially. `DD_MODE=ha` + Redis unlocks cross-replica rate limiting; the rest of the HA story (WS pub/sub, cron leader election) lands in v7.0.0. Standalone users: **zero impact** — default unchanged, `ioredis` is in `optionalDependencies` (not `dependencies`), no new env vars required.

README.md

@@ -8,8 +8,8 @@
     <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
     <a href="https://github.com/bogdanpricop/docker-dash/releases/latest"><img src="https://img.shields.io/github/v/release/bogdanpricop/docker-dash?color=blue" alt="Release"></a>
     <a href="LICENSE"><img src="https://img.shields.io/github/license/bogdanpricop/docker-dash" alt="License"></a>
-    <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-866%20passing%20(100%25)-brightgreen" alt="Tests"></a>
-    <img src="https://img.shields.io/badge/version-6.17.0-blue" alt="Version">
+    <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-871%20passing%20(100%25)-brightgreen" alt="Tests"></a>
+    <img src="https://img.shields.io/badge/version-6.17.1-blue" alt="Version">
     <a href="SECURITY.md#security-audit-history"><img src="https://img.shields.io/badge/production%20readiness-9.7%2F10-brightgreen" alt="Production Readiness"></a>
     <a href="SECURITY.md"><img src="https://img.shields.io/badge/security-audited-brightgreen" alt="Security Audited"></a>
     <img src="https://img.shields.io/badge/Docker-~80MB-blue" alt="Image Size">
@@ -26,9 +26,9 @@
   </p>
 </p>
 
-**Zero dependencies to deploy** — just Docker. No external database, no Redis, no build step. Current version: **v6.17.0**
+**Zero dependencies to deploy** — just Docker. No external database, no Redis, no build step. Current version: **v6.17.1**
 
-**New in v6.17.0:** Optional HA mode via `DD_MODE=ha` + Redis. Preview only — Redis-backed rate limiter + cluster abstraction shipped; WS pub/sub + cron leader election land in v7.0. See [docs/features/ha-mode.md](docs/features/ha-mode.md).
+**New in v6.17.x:** Optional HA mode via `DD_MODE=ha` + Redis. v6.17.0 shipped cluster abstraction + Redis rate limiter. **v6.17.1 adds cross-replica WS broadcasts via Redis pub/sub.** Cron leader election lands in v6.17.2 (real multi-replica safe). See [docs/features/ha-mode.md](docs/features/ha-mode.md).
 
 ## Screenshots
 

docker-compose.yml

@@ -4,8 +4,8 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        APP_VERSION: "${APP_VERSION:-6.17.0}"
-    image: docker-dash:${APP_VERSION:-6.17.0}
+        APP_VERSION: "${APP_VERSION:-6.17.1}"
+    image: docker-dash:${APP_VERSION:-6.17.1}
     container_name: docker-dash
     restart: unless-stopped
     env_file:
@@ -54,7 +54,7 @@ services:
   dd-egress-filter:
     build:
       context: ./docker/egress-filter
-    image: docker-dash-egress-filter:${APP_VERSION:-6.17.0}
+    image: docker-dash-egress-filter:${APP_VERSION:-6.17.1}
     container_name: dd-egress-filter
     restart: unless-stopped
     # Uses the default bridge so target containers on the default bridge can
@@ -83,9 +83,9 @@ services:
   #   DD_MODE=ha
   #   REDIS_URL=redis://redis:6379
   #
-  # v6.17.0 ships the foundation (Redis-backed rate limiter + cluster abstraction).
+  # v6.17.1 ships the foundation (Redis-backed rate limiter + cluster abstraction).
   # DO NOT run multi-replica in HA mode yet — WS pub/sub + cron leader election
-  # land in v7.0.0-alpha.1 / v7.0.0-rc.1. Running v6.17.0 HA with 2+ replicas
+  # land in v7.0.0-alpha.1 / v7.0.0-rc.1. Running v6.17.1 HA with 2+ replicas
   # causes duplicate cron execution (duplicate backups, concurrent VACUUM).
   #
   # Single-instance HA (1 replica + Redis) is useful for warming up operational

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docker-dash",
-  "version": "6.17.0",
+  "version": "6.17.1",
   "description": "Full-featured Docker management dashboard",
   "main": "src/server.js",
   "scripts": {

public/js/pages/whatsnew.js

@@ -9,6 +9,19 @@ const WhatsNewPage = {
   // Add new releases at the TOP of this array.
   // Types: feature, fix, improvement, security, breaking
   _releases: [
+    {
+      version: '6.17.1',
+      date: '2026-04-22',
+      title: 'HA Phase 3 — WebSocket pub/sub via Redis',
+      changes: [
+        { type: 'feature', text: 'Cross-replica WS broadcasts — user on replica A now receives events emitted by replica B (alerts, container state, log lines). Uses Redis pub/sub on a single channel ddash:pubsub. Before: silent event delivery gap in HA mode. Now: sub-millisecond cross-replica delivery on a healthy localhost Redis.' },
+        { type: 'improvement', text: 'Loop-safe by nodeId filter — publisher replica receives its own echo back and discards it. Local delivery still happens exactly once via direct _localBroadcast in the broadcast() call itself; cross-replica arrives via the subscriber callback.' },
+        { type: 'improvement', text: 'Separate subscriber Redis client (ioredis requires it — subscribed connections can\'t issue other commands). Lazy-connects on first subscribe. Standalone mode: still completely no-op, zero Redis connection.' },
+        { type: 'improvement', text: 'Fail-safe: best-effort publish, malformed envelopes dropped silently, subscribe errors logged but don\'t crash WS. Availability > strict delivery.' },
+        { type: 'improvement', text: 'Tests: 866 → 871 (+5 real pub/sub behavior tests via ioredis-mock, replacing 1 stub assertion). Covers self-echo filtering, routing, fan-out, malformed-envelope resilience.' },
+        { type: 'fix', text: '⚠️ DO NOT run multi-replica in HA mode yet. This release makes the situation WORSE than v6.17.0 because WS events now propagate cross-replica, so duplicate Docker event streams (one per replica) would deliver every event twice. Fixed in v6.17.2 via leader election on the event stream.' },
+      ],
+    },
     {
       version: '6.17.0',
       date: '2026-04-22',

src/__tests__/cluster.test.js

@@ -123,16 +123,96 @@ describe('cluster — HA mode (DD_MODE=ha, ioredis-mock)', () => {
     expect(allowedY.allowed).toBe(true);
   });
 
-  it('isLeader() returns true in HA v6.17.0 (election stubbed until v7.0.0-rc.1)', async () => {
-    // Documented limitation of the v6.17.0 preview — every node claims leader.
-    // Users are instructed NOT to run multi-replica in HA mode yet.
+  it('isLeader() returns true in HA v6.17.1 (election stubbed until v7.0.0-rc.1)', async () => {
+    // Documented limitation — every node claims leader. Users are instructed
+    // NOT to run multi-replica in HA mode until leader election ships.
     expect(await cluster.isLeader()).toBe(true);
   });
 
-  it('publish/subscribe are still stubs in v6.17.0', async () => {
+  // ─── Phase 3: pub/sub (v6.17.1) ─────────────────────────────────
+
+  it('publish sends an envelope with nodeId to the Redis pub/sub channel', async () => {
+    const r = await cluster.redis();
+    const publishSpy = jest.spyOn(r, 'publish');
+    await cluster.publish('ws:broadcast', { kind: 'all', type: 'test', data: 42 });
+    expect(publishSpy).toHaveBeenCalled();
+    const call = publishSpy.mock.calls[publishSpy.mock.calls.length - 1];
+    expect(call[0]).toBe('ddash:pubsub');
+    const envelope = JSON.parse(call[1]);
+    expect(envelope.nodeId).toBe(cluster.nodeId());
+    expect(envelope.appChannel).toBe('ws:broadcast');
+    expect(envelope.payload).toEqual({ kind: 'all', type: 'test', data: 42 });
+    publishSpy.mockRestore();
+  });
+
+  it('subscribe filters out self-published messages', async () => {
     let received = null;
-    cluster.subscribe('test-ha-channel', (p) => { received = p; });
-    await cluster.publish('test-ha-channel', { hello: 'ha' });
+    cluster.subscribe('self-loop-test', (p) => { received = p; });
+    // Wait for subscriber connection to settle (ioredis-mock is synchronous
+    // but the subscribe()+publish() cycle still needs a microtask tick)
+    await new Promise(r => setTimeout(r, 50));
+    await cluster.publish('self-loop-test', { test: 'self' });
+    await new Promise(r => setTimeout(r, 100));
+    expect(received).toBeNull();
+  });
+
+  it('subscribe receives messages from OTHER node IDs', async () => {
+    let received = null;
+    cluster.subscribe('foreign-test', (p) => { received = p; });
+    await new Promise(r => setTimeout(r, 50));
+    // Simulate a foreign-node publish by constructing the envelope directly
+    // with a different nodeId and publishing via our own Redis client.
+    const r = await cluster.redis();
+    const foreignEnvelope = JSON.stringify({
+      nodeId: 'foreign-node-deadbeef',
+      appChannel: 'foreign-test',
+      payload: { test: 'foreign' },
+    });
+    await r.publish('ddash:pubsub', foreignEnvelope);
+    await new Promise(r => setTimeout(r, 100));
+    expect(received).toEqual({ test: 'foreign' });
+  });
+
+  it('subscribe routes to the correct app channel (ignores others)', async () => {
+    let chanA = null;
+    let chanB = null;
+    cluster.subscribe('chan-a', (p) => { chanA = p; });
+    cluster.subscribe('chan-b', (p) => { chanB = p; });
+    await new Promise(r => setTimeout(r, 50));
+    const r = await cluster.redis();
+    await r.publish('ddash:pubsub', JSON.stringify({
+      nodeId: 'other', appChannel: 'chan-a', payload: { msg: 'A' },
+    }));
+    await r.publish('ddash:pubsub', JSON.stringify({
+      nodeId: 'other', appChannel: 'chan-b', payload: { msg: 'B' },
+    }));
+    await new Promise(r => setTimeout(r, 100));
+    expect(chanA).toEqual({ msg: 'A' });
+    expect(chanB).toEqual({ msg: 'B' });
+  });
+
+  it('multiple handlers on the same channel all fire', async () => {
+    const calls = [];
+    cluster.subscribe('multi-handler-test', (p) => calls.push(['h1', p]));
+    cluster.subscribe('multi-handler-test', (p) => calls.push(['h2', p]));
+    await new Promise(r => setTimeout(r, 50));
+    const r = await cluster.redis();
+    await r.publish('ddash:pubsub', JSON.stringify({
+      nodeId: 'other', appChannel: 'multi-handler-test', payload: { n: 1 },
+    }));
+    await new Promise(r => setTimeout(r, 100));
+    expect(calls).toHaveLength(2);
+    expect(calls.map(c => c[0])).toEqual(expect.arrayContaining(['h1', 'h2']));
+  });
+
+  it('malformed envelope JSON is silently dropped (no throw)', async () => {
+    let received = null;
+    cluster.subscribe('bad-json-test', (p) => { received = p; });
+    await new Promise(r => setTimeout(r, 50));
+    const r = await cluster.redis();
+    // Direct publish of garbage — must not crash the subscriber
+    await r.publish('ddash:pubsub', 'this is not json');
+    await new Promise(r => setTimeout(r, 50));
     expect(received).toBeNull();
   });
 });

src/services/cluster.js

@@ -81,16 +81,75 @@ async function rateLimitTick(key, maxRequests, windowMs) {
   return { allowed: true, remaining: maxRequests - count, retryAfterSec: null };
 }
 
-// ─── Phase 3 stubs (wired in v7.0.0-alpha.1) ─────────────────────
+// ─── Phase 3 — Redis pub/sub (v6.17.1) ────────────────────────────
+//
+// Single Redis channel `ddash:pubsub` carries all application-level pub/sub
+// traffic. App-level channel routing happens in the subscriber callback.
+// Envelope includes `nodeId` so publishers ignore their own echoes (avoids
+// deliver-twice-locally loop).
+//
+// Why single Redis channel: app-level channels (ws:broadcast, etc.) are ~3-5
+// total. Sub-channels would reduce filtering cost slightly but multiply
+// connection state. For the volume Docker Dash handles (~10s msg/sec) a
+// single subscribed channel + in-process dispatch is simpler and plenty fast.
+
+const REDIS_PUBSUB_CHANNEL = 'ddash:pubsub';
+let _subClient = null;
+let _subClientPromise = null;
+const _subscribers = new Map(); // appChannel → Set<handler>
+
+async function _ensureSubscriber() {
+  if (_subClient) return _subClient;
+  if (_subClientPromise) return _subClientPromise;
+  _subClientPromise = (async () => {
+    let Redis;
+    try { Redis = require('ioredis'); }
+    catch { throw new Error('ioredis missing — install it or unset DD_MODE'); }
+    const c = new Redis(REDIS_URL, { lazyConnect: false, maxRetriesPerRequest: 3 });
+    c.on('error', (e) => log.error('Redis subscriber error', { message: e.message }));
+    c.on('message', (_chan, raw) => {
+      let env;
+      try { env = JSON.parse(raw); } catch { return; }
+      if (!env || env.nodeId === NODE_ID) return; // skip self-echo
+      const handlers = _subscribers.get(env.appChannel);
+      if (!handlers) return;
+      for (const h of handlers) {
+        try { h(env.payload); }
+        catch (e) { log.warn('subscriber handler threw', { message: e.message }); }
+      }
+    });
+    await c.subscribe(REDIS_PUBSUB_CHANNEL);
+    _subClient = c;
+    log.info('Redis subscriber connected', { channel: REDIS_PUBSUB_CHANNEL, nodeId: NODE_ID });
+    return c;
+  })();
+  return _subClientPromise;
+}
 
-async function publish(_channel, _payload) {
+/** Publish to cross-replica. Best-effort (errors logged + swallowed —
+ *  pub/sub is eventually-consistent, local delivery must not fail). */
+async function publish(appChannel, payload) {
   if (!isHa()) return;
-  // TODO v7.0.0-alpha.1 — Redis pub/sub for cross-replica WS broadcasts.
+  try {
+    const r = await redis();
+    const envelope = JSON.stringify({ nodeId: NODE_ID, appChannel, payload });
+    await r.publish(REDIS_PUBSUB_CHANNEL, envelope);
+  } catch (err) {
+    log.warn('publish failed (local delivery unaffected)', { appChannel, message: err.message });
+  }
 }
 
-function subscribe(_channel, _handler) {
+/** Subscribe to a cross-replica channel. Handler receives the `payload`
+ *  object, already filtered to exclude messages from this node. */
+function subscribe(appChannel, handler) {
   if (!isHa()) return;
-  // TODO v7.0.0-alpha.1 — subscribe handler registration.
+  let set = _subscribers.get(appChannel);
+  if (!set) { set = new Set(); _subscribers.set(appChannel, set); }
+  set.add(handler);
+  // Fire-and-forget — the subscriber client connects async; messages published
+  // before it's ready are lost (acceptable for our use case: WS broadcasts
+  // and cache invalidations are eventually consistent).
+  _ensureSubscriber().catch((e) => log.error('subscriber connect failed', { message: e.message }));
 }
 
 // ─── Phase 4 stubs (wired in v7.0.0-rc.1) ────────────────────────
@@ -107,11 +166,17 @@ function onBecomeLeader(_fn) { /* TODO v7.0.0-rc.1 */ }
 function onBecomeReader(_fn) { /* TODO v7.0.0-rc.1 */ }
 
 async function shutdown() {
+  if (_subClient) {
+    try { await _subClient.quit(); } catch { /* ignore */ }
+    _subClient = null;
+    _subClientPromise = null;
+  }
   if (_redis) {
     try { await _redis.quit(); } catch { /* ignore */ }
     _redis = null;
     _redisPromise = null;
   }
+  _subscribers.clear();
 }
 
 module.exports = {
@@ -121,5 +186,11 @@ module.exports = {
   isLeader, onBecomeLeader, onBecomeReader,
   shutdown,
   // test-only: reset internal state
-  _reset() { _redis = null; _redisPromise = null; },
+  _reset() {
+    _redis = null;
+    _redisPromise = null;
+    _subClient = null;
+    _subClientPromise = null;
+    _subscribers.clear();
+  },
 };

src/version.js

@@ -2,4 +2,4 @@
 // Single source of truth for the application version.
 // Updated automatically by: npm version X.Y.Z  (via scripts/sync-version.js)
 // server.js reads this to inject into index.html at startup — no build step needed.
-module.exports = '6.17.0';
+module.exports = '6.17.1';