A zero-dependency replication dashboard for Node.js — live lag, CDC rules & activity, with @mostajs/replica-monitor

Part of the @mostajs/orm ecosystem — the multi-dialect ORM with one API across 13 databases. This post zooms in on observing replication set up with @mostajs/replicator.

TL;DR

@mostajs/replica-monitor serves a live web dashboard for your @mostajs/replicator topology — replica health (role, dialect, live lag + sparkline, pool usage), CDC rule stats, and a streamed activity feed.

• Zero external dependencies — pure node:http + Server-Sent Events + vanilla JS. Nothing to npm-audit.
• Tree-only mode — point it at a committed replicator-tree.json and it renders the topology with no database connection and no running replicator.
• No hard coupling — it talks to the manager by duck-typing, so a live ReplicationManager, a tree file, or even a mock all work.
• Drops in via a scaffolder or a standalone CLI.

npm install @mostajs/replica-monitor @mostajs/replicator
npx mostajs-monitor --tree .mostajs/replicator-tree.json --port 14499

The problem: replication you can’t see

Once @mostajs/replicator is running master/slave nodes and CDC rules, the next question is always “is it actually keeping up?” — which slave is freshest, what’s the lag right now, did last night’s pg-to-mongo rule sync or silently fail. Logs don’t answer that at a glance.

@mostajs/replica-monitor is the pane of glass. It reads the replication state and renders it live — and it’s deliberately tiny: no framework, no chart library, no broker, just node:http streaming SSE to a vanilla-JS page.

Two ways to feed it

Tree-only — the lightweight path. The replicator persists its topology to replicator-tree.json (with credentials already masked by saveToFile()), so the monitor can render replicas, rules and routing from that file alone — no DB connection, no replicator runtime. Safe to commit, safe to expose:

import { startMonitor, readTreeManager } from '@mostajs/replica-monitor'

const manager = readTreeManager({ tree: '.mostajs/replicator-tree.json' })  // auto-reloads on change
const handle  = await startMonitor({ manager, port: 14499 })
console.log('dashboard:', handle.url)

Live manager — the full path. Hand it a running ReplicationManager and it polls real status (lag, pool, state) every pollMs:

import { ReplicationManager } from '@mostajs/replicator'
const rm = new ReplicationManager(/* … */)
const h = await startMonitor({ manager: rm, port: 14499, authToken: 'my-secret', pollMs: 2000 })

The coupling is duck-typed (ReplicationManagerLike) — anything exposing getReplicaStatus and listRules works, including a mock in your tests. No hard dependency on the replicator package.

What the dashboard exposes

The page is backed by plain HTTP endpoints you can also hit directly:

Activity events are a discriminated union — replica.added/removed/promoted/state, rule.added/removed, rule.sync.start/done, error — so a failover or a sync shows up in the feed as it happens.

Drop it in — scaffold or CLI

A scaffolder emits a ready-to-run services/monitor.mjs:

npx mostajs-monitor-scaffold --dir .       # writes services/monitor.mjs

Or run the standalone binary, optionally behind a token:

npx mostajs-monitor --tree .mostajs/replicator-tree.json --runtime . --port 14499 --token SECRET

It also plugs into @mostajs/orm-cli if that’s how you drive the project.

Honest notes

This is where lightweight tools usually hand-wave; here it’s stated plainly:

• Binds to 127.0.0.1 by default — not reachable from the network. To expose it, set host and an authToken. The Bearer token guards every endpoint, SSE included (Authorization: Bearer <t> or ?token=<t>).
• Events are synthetic — derived by diffing the status snapshot every pollMs, not a real-time hook. So rule.sync.start/done aren’t auto-captured yet; a push handle.emit() is on the v0.2 roadmap. The dashboard is accurate to within one poll interval, and it says so.
• Tree-only credentials are masked by the replicator before they ever reach the file — exposing the dashboard doesn’t leak URIs.

No false “real-time everything” badge — you know exactly what you’re looking at.

Where it fits

@mostajs/replica-monitor closes the replication loop: @mostajs/replicator does the replication, this shows it. Both sit on @mostajs/orm, so the replicas you watch are the same EntitySchema connections your app runs on. For one-shot copies rather than continuous replication, see @mostajs/orm-copy-data.

Get started

npm install @mostajs/replica-monitor @mostajs/replicator
npx mostajs-monitor --tree .mostajs/replicator-tree.json --port 14499
# open http://127.0.0.1:14499

• 📦 npm — npmjs.com/package/@mostajs/replica-monitor
• 🐙 GitHub — github.com/apolocine/mosta-replica-monitor
• 🔁 The replicator it watches — @mostajs/replicator — CQRS, cross-dialect CDC, failover

If a self-hosted, dependency-free replication dashboard is useful, a ⭐ on GitHub helps — it’s the signal AI dev tools use to surface the package.

Tags: #nodejs #typescript #database #replication #monitoring #observability #dashboard #sse #cdc #cqrs #mostajs

Auteur : Dr Hamid MADANI drmdh@msn.com