beacon: relay directory page from firehose health data

Wire up the previously-orphaned `relays` collection (5,793 relays of
firehose health data) into a new sortable directory page.

- db: relaysDirectory({online,sort,limit}) returns {total,online,
  lastChecked,relays} with a tight health-field projection. Collection
  name configurable via MONGO_RELAY_DIRECTORY_COLLECTION (default relays).
- server: GET /api/relays-directory + /relays OGP shell route.
- ui: /relays SPA route — dense, client-sortable table (uptime, latency,
  writable, paid/auth badges, last-checked) with an online-only toggle
  and a 'last checked' freshness caveat (live monitoring is paused).
- topbar: add Relays nav link.

Closes #5

Author: melvincarvalho

.env.example

@@ -5,6 +5,8 @@ MONGO_DB=nostr
 MONGO_COLLECTION=beacon
 MONGO_FOLLOWS_COLLECTION=follows
 MONGO_RELAYS_COLLECTION=relay_lists
+# firehose relay-health directory (one doc per relay URL)
+MONGO_RELAY_DIRECTORY_COLLECTION=relays
 
 RELAYS=wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net
 PORT=3000

README.md

@@ -34,7 +34,8 @@ npm run serve               # read API only
 - `GET /api/profiles` — recent profiles
 - `GET /api/profile/:pubkey`
 - `GET /api/follows/:pubkey`
-- `GET /api/relays/:pubkey`
+- `GET /api/relays/:pubkey` — that pubkey's kind-10002 relay list
+- `GET /api/relays-directory` — relay-health directory (`?online=1`, `?sort=quality|latency|recent`, `?limit=`)
 
 ## Status
 

public/index.html

@@ -107,12 +107,42 @@
   .cta:disabled{opacity:.55;cursor:default}
   .link-status{width:100%;font-size:.88rem;color:var(--muted);margin-top:.5rem;line-height:1.5}
   .link-status.ok{color:#1c8c6b} .link-status.err{color:#c0392b}
+
+  /* relay directory */
+  .relays-head{display:flex;flex-wrap:wrap;align-items:baseline;gap:.6rem 1rem;margin:.4rem 0 1rem}
+  .relays-head h2{font-family:var(--serif);font-size:1.7rem;font-weight:600}
+  .relays-head .sub{color:var(--muted);font-size:.9rem}
+  .relays-controls{display:flex;flex-wrap:wrap;gap:.5rem;margin:.2rem 0 1rem}
+  .toggle{font-size:.82rem;font-weight:500;border:1px solid var(--line);background:#fff;color:var(--muted);
+    padding:.4rem .85rem;border-radius:999px;cursor:pointer;transition:border-color .15s,color .15s,background .15s}
+  .toggle:hover{border-color:var(--accent);color:var(--accent)}
+  .toggle.on{background:var(--accent-soft);border-color:#dcd8f5;color:var(--accent)}
+  .caveat{font-size:.8rem;color:var(--faint);background:#fff;border:1px solid var(--line);border-radius:10px;padding:.55rem .8rem;margin-bottom:1rem}
+  .rtable{width:100%;border-collapse:collapse;background:var(--surface);border:1px solid var(--line);border-radius:14px;overflow:hidden;font-size:.86rem}
+  .rtable thead th{text-align:left;font-size:.7rem;font-weight:700;letter-spacing:.06em;text-transform:uppercase;color:var(--faint);
+    padding:.7rem .8rem;border-bottom:1px solid var(--line);white-space:nowrap;cursor:pointer;user-select:none}
+  .rtable thead th:hover{color:var(--accent)}
+  .rtable thead th.num{text-align:right}
+  .rtable th .arrow{color:var(--accent);font-size:.65rem}
+  .rtable tbody td{padding:.6rem .8rem;border-bottom:1px solid var(--line);vertical-align:middle}
+  .rtable tbody tr:last-child td{border-bottom:none}
+  .rtable tbody tr:hover{background:#faf9ff}
+  .rtable td.num{text-align:right;font-family:var(--mono);font-size:.8rem}
+  .rtable .url{font-family:var(--mono);font-size:.82rem;word-break:break-all}
+  .rdot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:.45rem;vertical-align:middle}
+  .rdot.up{background:#1c8c6b;box-shadow:0 0 6px rgba(28,140,107,.5)} .rdot.down{background:#c0392b}
+  .rbadge{display:inline-block;font-size:.68rem;font-weight:600;padding:.12rem .45rem;border-radius:6px;margin-left:.3rem;white-space:nowrap}
+  .rbadge.ok{background:#e6f5ef;color:#1c8c6b} .rbadge.no{background:#f3eef0;color:#9a6a76}
+  .rbadge.pay{background:#fff3e0;color:#b26a00} .rbadge.auth{background:#fdeef0;color:#c0392b}
+  .ubar{display:inline-block;width:46px;height:6px;border-radius:3px;background:var(--line);vertical-align:middle;margin-left:.5rem;overflow:hidden}
+  .ubar>i{display:block;height:100%;background:linear-gradient(90deg,var(--accent2),var(--accent))}
 </style>
 </head>
 <body>
 <header class="topbar">
   <a class="tb-brand" href="/"><span class="dot"></span> nostr.social</a>
   <nav class="tb-nav">
+    <a href="/relays">Relays</a>
     <a href="/link">Link your pod</a>
   </nav>
 </header>
@@ -319,6 +349,84 @@ <h2>${esc(c.name || short(pk))}</h2>
   };
 }
 
+// ---- relay directory (firehose health data) ----
+const relaysState = { online: true, sortKey: 'uptime', dir: -1, rows: [], meta: {} };
+const RCOLS = [
+  { key: 'relay', label: 'Relay', num: false },
+  { key: 'online', label: 'Status', num: false },
+  { key: 'uptime', label: 'Uptime', num: true },
+  { key: 'responseTime', label: 'Latency', num: true },
+  { key: 'acceptsEvents', label: 'Writable', num: false },
+  { key: 'lastChecked', label: 'Checked', num: true },
+];
+
+function ageStr(iso) {
+  if (!iso) return '—';
+  const t = new Date(iso).getTime(); if (isNaN(t)) return '—';
+  const s = (Date.now() - t) / 1000;
+  for (const [sec, lbl] of [[31536000, 'y'], [2592000, 'mo'], [86400, 'd'], [3600, 'h'], [60, 'm']]) {
+    if (s >= sec) return Math.floor(s / sec) + lbl;
+  }
+  return 'now';
+}
+
+function cmpRelay(a, b, key, dir) {
+  let av = a[key], bv = b[key];
+  const an = av == null, bn = bv == null;        // unknown values always sort last
+  if (an && bn) return 0; if (an) return 1; if (bn) return -1;
+  if (typeof av === 'string') return dir * av.localeCompare(bv);
+  if (typeof av === 'boolean') { av = av ? 1 : 0; bv = bv ? 1 : 0; }
+  return dir * (av - bv);
+}
+
+function relayRow(r) {
+  const flags = (r.requiresPayment ? '<span class="rbadge pay">paid</span>' : '')
+    + (r.requiresAuth ? '<span class="rbadge auth">auth</span>' : '');
+  const up = r.uptime == null ? '—'
+    : `${Math.round(r.uptime)}%<span class="ubar"><i style="width:${Math.max(0, Math.min(100, r.uptime))}%"></i></span>`;
+  return `<tr>
+    <td class="url">${esc(r.relay)}${flags}</td>
+    <td><span class="rdot ${r.online ? 'up' : 'down'}"></span>${r.online ? 'online' : 'offline'}</td>
+    <td class="num">${up}</td>
+    <td class="num">${r.responseTime == null ? '—' : r.responseTime + 'ms'}</td>
+    <td>${r.acceptsEvents === true ? '<span class="rbadge ok">yes</span>' : r.acceptsEvents === false ? '<span class="rbadge no">no</span>' : '—'}</td>
+    <td class="num">${ageStr(r.lastChecked)}</td>
+  </tr>`;
+}
+
+function renderRelays() {
+  const { rows, meta, sortKey, dir, online } = relaysState;
+  const sorted = [...rows].sort((a, b) => cmpRelay(a, b, sortKey, dir));
+  const head = RCOLS.map((c) => `<th class="${c.num ? 'num' : ''}" data-key="${c.key}">${c.label}${sortKey === c.key ? ` <span class="arrow">${dir < 0 ? '▼' : '▲'}</span>` : ''}</th>`).join('');
+  view.innerHTML = `<div class="detail">
+    <div class="back" id="back">← all identities</div>
+    <div class="relays-head"><h2>Relay directory</h2>
+      <span class="sub"><strong>${fmt(meta.online)}</strong> online of <strong>${fmt(meta.total)}</strong> known relays</span></div>
+    <div class="caveat">Health snapshot · relays last checked <strong>${esc(meta.lastChecked ? ageStr(meta.lastChecked) + ' ago' : 'unknown')}</strong>. Live monitoring is paused, so these figures reflect that snapshot.</div>
+    <div class="relays-controls"><button class="toggle ${online ? 'on' : ''}" id="r-online">Online only</button></div>
+    <div style="overflow-x:auto"><table class="rtable"><thead><tr>${head}</tr></thead><tbody>${sorted.map(relayRow).join('')}</tbody></table></div>
+    <div class="caveat" style="margin-top:1rem">Showing ${sorted.length} relays. Click a column to sort.</div>
+  </div>`;
+  $('#back').onclick = () => navigate('/');
+  $('#r-online').onclick = () => { relaysState.online = !relaysState.online; relaysView(); };
+  view.querySelectorAll('.rtable thead th').forEach((th) => { th.onclick = () => {
+    const k = th.dataset.key;
+    if (relaysState.sortKey === k) relaysState.dir = -relaysState.dir;
+    else { relaysState.sortKey = k; relaysState.dir = k === 'relay' ? 1 : -1; }
+    renderRelays();
+  }; });
+}
+
+async function relaysView() {
+  if ($('#q')) $('#q').value = '';
+  $('#stat').innerHTML = '';
+  view.innerHTML = '<div class="loading">loading relay directory…</div>';
+  const data = await fetch(`/api/relays-directory?limit=2000${relaysState.online ? '&online=1' : ''}`).then((r) => r.json()).catch(() => null);
+  if (!data || !Array.isArray(data.relays)) { view.innerHTML = '<div class="loading">Could not load the relay directory.</div>'; return; }
+  relaysState.rows = data.relays; relaysState.meta = data;
+  renderRelays();
+}
+
 function navigate(path) { if (location.pathname !== path) history.pushState({}, '', path); route(); }
 
 let searchTimer;
@@ -330,6 +438,7 @@ <h2>${esc(c.name || short(pk))}</h2>
 
 function route() {
   if (location.pathname === '/link') return linkView();
+  if (location.pathname === '/relays') return relaysView();
   const m = location.pathname.match(/^\/([0-9a-f]{64})$/i);
   if (m) return profile(m[1].toLowerCase());
   const h = location.hash.slice(1);                 // legacy #<hex> links still resolve

src/db.js

@@ -19,6 +19,10 @@ export const COLLECTIONS = {
   10002: process.env.MONGO_RELAYS_COLLECTION || 'relay_lists',
 };
 
+// Firehose relay-health directory (one doc per relay URL, written by the
+// nostr-beacon monitor). Distinct from `relay_lists` (per-pubkey kind 10002).
+const RELAY_DIRECTORY = process.env.MONGO_RELAY_DIRECTORY_COLLECTION || 'relays';
+
 let db, client;
 
 export async function connect() {
@@ -103,6 +107,35 @@ export async function searchProfiles(q, limit = 24) {
     .limit(Math.min(limit, 50)).toArray();
 }
 
+// ---- relay directory (firehose health data) --------------------------------
+
+// Fields the directory page needs — keep the projection tight; the raw docs
+// also carry publish-test internals and error strings we don't surface in v0.
+const RELAY_FIELDS = {
+  _id: 0, relay: 1, online: 1, uptime: 1, responseTime: 1, acceptsEvents: 1,
+  requiresAuth: 1, requiresPayment: 1, lastChecked: 1, checksOnline: 1, checksTotal: 1,
+};
+
+/**
+ * Read the relay-health directory. Returns a summary (for the freshness caveat)
+ * plus the matching rows. `online` filters to live relays; `sort` is one of
+ * 'quality' (uptime desc, latency asc), 'latency', or 'recent' (last checked).
+ */
+export async function relaysDirectory({ online = false, sort = 'quality', limit = 300 } = {}) {
+  const col = (await connect()).collection(RELAY_DIRECTORY);
+  const filter = online ? { online: true } : {};
+  const sortSpec = sort === 'recent' ? { lastChecked: -1 }
+    : sort === 'latency' ? { responseTime: 1 }
+    : { uptime: -1, responseTime: 1 }; // 'quality'
+  const [total, onlineCount, newest, relays] = await Promise.all([
+    col.estimatedDocumentCount(),
+    col.countDocuments({ online: true }),
+    col.find({}, { projection: { _id: 0, lastChecked: 1 } }).sort({ lastChecked: -1 }).limit(1).toArray(),
+    col.find(filter, { projection: RELAY_FIELDS }).sort(sortSpec).limit(Math.min(Number(limit) || 300, 2000)).toArray(),
+  ]);
+  return { total, online: onlineCount, lastChecked: newest[0]?.lastChecked || null, relays };
+}
+
 // ---- graph metrics ---------------------------------------------------------
 
 export async function stats() {

src/server.js

@@ -3,7 +3,7 @@ import express from 'express';
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { getProfile, getFollows, getRelays, recentProfiles, connect, stats, searchProfiles, enrichCounts, followerCount } from './db.js';
+import { getProfile, getFollows, getRelays, recentProfiles, connect, stats, searchProfiles, enrichCounts, followerCount, relaysDirectory } from './db.js';
 import { buildDidDocument } from './diddoc.js';
 import 'dotenv/config';
 
@@ -58,6 +58,13 @@ export async function startServer(port = process.env.PORT || 3000) {
     url: `${SITE}/link`,
   })));
 
+  // relay directory shell
+  app.get('/relays', (_req, res) => res.type('html').send(renderShell({
+    title: 'Relay directory · nostr.social',
+    description: 'A health-checked directory of Nostr relays — uptime, latency, write-acceptance, and paid/auth requirements.',
+    url: `${SITE}/relays`,
+  })));
+
   // per-profile shell at /<pubkey> with that identity's OGP (crawlable canonical
   // URL). RegExp route constrained to 64-hex, so it never collides with /api,
   // /healthz, /.well-known, or static assets.
@@ -120,6 +127,17 @@ export async function startServer(port = process.env.PORT || 3000) {
     try { res.json(await getRelays(req.params.pubkey)); } catch (e) { next(e); }
   });
 
+  // relay-health directory (firehose data): { total, online, lastChecked, relays }
+  app.get('/api/relays-directory', async (req, res, next) => {
+    try {
+      res.json(await relaysDirectory({
+        online: req.query.online === '1' || req.query.online === 'true',
+        sort: req.query.sort,
+        limit: req.query.limit,
+      }));
+    } catch (e) { next(e); }
+  });
+
   // did:nostr resolution — build the conformant DID document from the index
   const resolve = async (pubkey) => {
     const [profile, follows, relays] = await Promise.all([