// fronts-diag — the freeze signature must be visible without reading the source.
//
// The failure this exists for: a node pinned to a co-owner whose firehose is short, while every other
// surface reports health. So the assertions below are mostly about the SUMMARY fields — onHighestRev and
// behindBy — because those are what an operator reads at 2am, and a diagnostic that requires interpreting
// a raw list is the situation we were already in.
//
// Run: node test/fronts-diag.test.mjs
import { frontsDiag } from '../lib/fronts-diag.js'
const assert = (cond, msg) => { if (!cond) throw new Error('FAIL: ' + msg); console.log(' ok -', msg) }
// A fake router with the same shape the real one exposes. Deliberately a fake: the point is to pin the
// REPORTING, and standing up two real co-owners would test replication instead.
function mkRouter ({ fronts, liveKeys = [], chosen = null }) {
const did = 'did:plc:x'
const set = new Map()
for (const f of fronts) {
set.set(f.key, {
_firehoseKey: f.key,
head: f.rev ? { rev: f.rev } : null,
seq: f.len == null ? null : { core: { length: f.len } }
})
}
const live = new Map()
for (const k of liveKeys) live.set(k, {})
return {
_fronts: new Map([[did, set]]),
_byDid: new Map([[did, live]]),
_freshestFront: () => (chosen ? set.get(chosen) : null)
}
}
console.log('\n# the healthy case')
let d = frontsDiag(mkRouter({
fronts: [{ key: 'aaa1', rev: '3lx200', len: 151 }, { key: 'bbb2', rev: '3lx100', len: 140 }],
liveKeys: ['aaa1', 'bbb2'],
chosen: 'aaa1'
})).dids[0]
assert(d.frontCount === 2, 'both fronts reported')
assert(d.chosen === 'aaa1', 'the chosen front is named')
assert(d.onHighestRev === true, 'and it IS the highest-rev line')
assert(d.behindBy === 0, 'behindBy 0 — nothing better on offer')
assert(d.fronts[0].rev === '3lx200', 'fronts are sorted highest-rev first, the order the ranking sees')
console.log('\n# THE FREEZE SIGNATURE — pinned to a shorter line while a longer one is visible')
d = frontsDiag(mkRouter({
fronts: [{ key: 'good', rev: '3lx900', len: 151 }, { key: 'stale', rev: '3lx100', len: 70 }],
liveKeys: ['good', 'stale'],
chosen: 'stale'
})).dids[0]
assert(d.chosen === 'stale', 'the chosen front is the short one')
assert(d.onHighestRev === false, 'onHighestRev:false is the one-line alarm')
assert(d.behindBy === 81, 'behindBy quantifies it — 81 frames of the visible line are not being read')
assert(d.fronts[0].chosen === false && d.fronts[1].chosen === true, 'and the chosen flag sits on the row that is NOT at the top')
console.log('\n# an unverified front is invisible to the ranking, which is itself a cause')
d = frontsDiag(mkRouter({
fronts: [{ key: 'noheadfront', rev: null, len: 900 }, { key: 'ok', rev: '3lx100', len: 70 }],
liveKeys: ['noheadfront', 'ok'],
chosen: 'ok'
})).dids[0]
const unver = d.fronts.find((f) => f.firehoseKey === 'noheadfront')
assert(unver.verified === false, 'a front with no head reads verified:false')
assert(d.onHighestRev === true, 'and does not count as "better" — only verified fronts are ranked')
assert(unver.firehoseLength === 900, 'but its length is still shown, so a long UNVERIFIED line is visible')
console.log('\n# liveness is distinguished from mere knowledge of a front')
d = frontsDiag(mkRouter({
fronts: [{ key: 'known', rev: '3lx900', len: 151 }, { key: 'connected', rev: '3lx100', len: 70 }],
liveKeys: ['connected'],
chosen: 'connected'
})).dids[0]
assert(d.fronts.find((f) => f.firehoseKey === 'known').live === false, 'an announced-but-not-connected front reads live:false')
assert(d.fronts.find((f) => f.firehoseKey === 'connected').live === true, 'the connected one reads live:true')
assert(d.onHighestRev === false, 'still flagged — preferring a live front is WHY we can sit on a shorter line')
console.log('\n# degrades instead of throwing')
assert(frontsDiag(null).error === 'no router', 'no router')
assert(frontsDiag({}).error === 'no router', 'a router without _fronts')
d = frontsDiag(mkRouter({ fronts: [{ key: 'a', rev: '3lx1', len: null }], liveKeys: [], chosen: null })).dids[0]
assert(d.chosen === null && d.behindBy === null, 'no chosen front and no lengths → nulls, not a throw')
assert(d.fronts[0].firehoseLength === null, 'a front with no seq reports null length')
const filtered = frontsDiag(mkRouter({ fronts: [{ key: 'a', rev: '1', len: 1 }], chosen: 'a' }), ['did:plc:absent'])
assert(filtered.dids.length === 1 && filtered.dids[0].frontCount === 0, 'an unknown did reports zero fronts rather than failing')
console.log('\nall fronts-diag assertions passed')