@openmeet/snowglobe 0.3.0 → 0.5.0

package/lib/config.mjs

@@ -37,11 +37,22 @@ export const RESERVED = [
 // The lexicon authority's account, made on its PDS before any account in the file.
 const AUTHORITY_ACCOUNT = 'lex-authority';
 
-// The domain a file that names none gets. It is ours and its DNS points at 127.0.0.1, so a name
-// that escapes a globe lands on this machine, not on someone else's server. A domain under .test,
-// .local, .localhost, .invalid or .example would fail sign-in: a PDS refuses an OAuth client there,
-// and group hosts and PDSls are OAuth clients at their own names.
-export const DEFAULT_DOMAIN = 'local.snowglobe.at';
+// The zone every local snowglobe's domain is under. It is ours and its public DNS answers every
+// name under it, at any depth, with 127.0.0.1, where the name router listens (lib/router.mjs), so
+// a name that escapes a globe lands on this machine, not on someone else's server. The user's CA
+// vouches for names under it (lib/certs.mjs). A domain under .test, .local, .localhost, .invalid or
+// .example would fail sign-in: a PDS refuses an OAuth client there, and group hosts and PDSls are
+// OAuth clients at their own names.
+export const LOCAL_ZONE = 'local.snowglobe.at';
+// The same zone under its name from before each snowglobe had a domain of its own (0.5.0);
+// snowglobe-cloud reads it to refuse a hosted globe under the local zone.
+export const DEFAULT_DOMAIN = LOCAL_ZONE;
+
+/**
+ * The domain a file that names none gets: one of its own, <globe>.local.snowglobe.at, so the
+ * name router can tell it from every other snowglobe on the machine by name alone.
+ */
+export const localDomain = (globe) => `${globe}.${LOCAL_ZONE}`;
 
 // Names nginx answers whatever the domain: the stand-in for the real PLC directory at exactly
 // plc.directory. A domain that is it, or above it, would share it. (Apps on this machine are
@@ -131,10 +142,12 @@ export function checkGlobe(doc, { baseDir } = {}) {
   else if (typeof doc.globe !== 'string' || !GLOBE_RE.test(doc.globe))
     err('globe', `${show(doc.globe)} must be lowercase letters and digits, starting with a letter, at most 31`);
   else if (GLOBE_KEPT.includes(doc.globe)) err('globe', `"${doc.globe}" is a folder snowglobe keeps for itself; pick another name`);
-  const domain = doc.domain ?? DEFAULT_DOMAIN;
+  // A globe name that is refused above gets the zone itself as a stand-in, so its error is the only one.
+  const named = typeof doc.globe === 'string' && GLOBE_RE.test(doc.globe);
+  const domain = doc.domain ?? (named ? localDomain(doc.globe) : LOCAL_ZONE);
   const domainOk = typeof domain === 'string' && DOMAIN_RE.test(domain) && domain.length <= NAME_MAX;
   if (!domainOk)
-    err('domain', `${show(domain)} must be a domain name, such as ${DEFAULT_DOMAIN}`);
+    err('domain', `${show(domain)} must be a domain name, such as ${localDomain('mine')}`);
   else {
     const fixed = FIXED_DOMAINS.find(
       ({ name, wildcard }) => name === domain || name.endsWith(`.${domain}`) || (wildcard && domain.endsWith(`.${name}`)),
@@ -231,11 +244,13 @@ export function checkGlobe(doc, { baseDir } = {}) {
       }
     }
   }
-  // Without a relay Jetstream and TAP follow one PDS's own firehose, and the others' writes
-  // are seen by nothing.
-  if (services.relay === 'auto') services.relay = pds.length > 1;
+  // Without a relay TAP follows one PDS's own firehose, and the others' writes are seen by
+  // nothing. Jetstream needs the relay even with one PDS: at start it asks the relay for the
+  // network's hosts (com.atproto.sync.listHosts), which a PDS refuses.
+  if (services.relay === 'auto') services.relay = pds.length > 1 || services.jetstream;
   else if (services.relay === false && pds.length > 1)
     err('services.relay', 'cannot be off with more than one PDS: only one PDS would be followed');
+  else if (services.relay === false && services.jetstream) err('services.jetstream', 'needs the relay');
   // Slingshot reads this network's Jetstream.
   if (services.slingshot && !services.jetstream) err('services.slingshot', 'needs jetstream');
 

package/lib/env.mjs

@@ -5,13 +5,27 @@
 
 import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { request } from 'node:https';
 import net from 'node:net';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_DOMAIN } from './config.mjs';
+import { localDomain } from './config.mjs';
+
+// The name router's address (lib/router.mjs): public DNS answers every name under
+// local.snowglobe.at with it, and the router passes each connection on to the snowglobe whose
+// domain the name is under. No snowglobe it routes to publishes here.
+export const ROUTER_ADDRESS = '127.0.0.1';
+
+/**
+ * Whether this machine runs the name router: on Linux, unless SG_ROUTER=off. Elsewhere (and with
+ * it off) a new snowglobe takes the first free address from 127.0.0.1 as before 0.5.0, one that
+ * kept an address keeps it, and only the one on 127.0.0.1 is reached by name.
+ */
+export function routerRuns({ root = ROOT, env = process.env, platform = process.platform } = {}) {
+  return platform === 'linux' && setting('SG_ROUTER', { root, env }) !== 'off';
+}
 
 // A mistake in how a command was called, as opposed to one the globe answered with.
 export class UsageError extends Error {}
@@ -85,8 +99,6 @@ export function paths(root = ROOT, state) {
     admin: join(data, 'admin.env'),
     // App routes, "<name> <port> [<ending>]" per line (snowglobe app).
     apps: join(https, 'apps'),
-    // Handles run maps to nginx, one per line (snowglobe account and up).
-    names: join(https, 'names'),
     // The rendered globe (bin/snowglobe.mjs render). Nothing in it is secret.
     globe,
     globeEnv: join(globe, 'globe.env'),
@@ -218,7 +230,8 @@ export function setting(name, { root = ROOT, env = process.env } = {}) {
 }
 
 // The domain every globe name sits under: SG_DOMAIN from the environment or .env; else the
-// rendered globe's, which is the file's unless one of those replaced it; empty means DEFAULT_DOMAIN.
+// rendered globe's, which is the file's unless one of those replaced it; else the globe's own,
+// <name of its state folder>.local.snowglobe.at.
 // A setting that differs from the rendered globe's means the render is stale: refused, unless
 // this run is about to render again (rendering). `set` is the setting alone, for render --domain.
 export function resolveDomain({ root = ROOT, state, env = process.env, rendering = false } = {}) {
@@ -227,7 +240,7 @@ export function resolveDomain({ root = ROOT, state, env = process.env, rendering
   const rendered = envGet('SG_DOMAIN', p.globeEnv);
   if (set && rendered && set !== rendered && !rendering)
     throw new Error(`SG_DOMAIN=${set}, but the globe in ${p.globe} was rendered for ${rendered}; run snowglobe up`);
-  const domain = set || rendered || DEFAULT_DOMAIN;
+  const domain = set || rendered || localDomain(basename(state));
   // A domain name and nothing else. This also refuses ${...} in .env, which compose would
   // expand and these scripts do not.
   if (/[^A-Za-z0-9.-]/.test(domain) || domain.startsWith('.') || domain.endsWith('.') || domain.includes('..'))
@@ -293,24 +306,31 @@ export function ownNginxUp(project, env = process.env) {
  * The loopback address this snowglobe publishes on, chosen once and kept in its state folder, so a
  * second snowglobe on the machine starts beside the first with no settings: it takes the first
  * 127.0.0.N that no other snowglobe in the same user folder has kept and nothing answers on 443 or any other port it publishes.
+ * Where the name router runs (routerRuns), that starts at 127.0.0.2: 127.0.0.1 is the router's.
  * SG_BIND, where set, wins and nothing is written. A snowglobe that is already running with no
- * address kept was made before this and is on 127.0.0.1, so it keeps that. Returns the address.
+ * address kept was made before this and is on 127.0.0.1, so it keeps that. One that kept
+ * 127.0.0.1 before the router existed moves to a free address when it is not running: what it
+ * holds depends on its domain, not its address. Returns the address.
  */
-export async function chooseBind({ root = ROOT, state, project, env = process.env, listening = (a) => addressBusy(a, { root, env }), ownUp = ownNginxUp } = {}) {
+export async function chooseBind({ root = ROOT, state, project, env = process.env, listening = (a) => addressBusy(a, { root, env }), ownUp = ownNginxUp, platform = process.platform } = {}) {
   const p = paths(root, state);
-  if (setting('SG_BIND', { root, env }) || existsSync(p.bind)) return resolveBind({ root, state, env });
+  if (setting('SG_BIND', { root, env })) return resolveBind({ root, state, env });
+  const routed = routerRuns({ root, env, platform });
+  const keep = () => existsSync(p.bind) && !(routed && resolveBind({ root, state, env }) === ROUTER_ADDRESS && !ownUp(project, env));
+  if (keep()) return resolveBind({ root, state, env });
   // Choosing reads the other bind files, waits on probes, then writes ours, so two first starts at
   // once would both pick the same address and keep it. One at a time, under a lock beside the state folders.
   return withLock(join(dirname(state), '.bind-lock'), async () => {
-    if (existsSync(p.bind)) return resolveBind({ root, state, env });
-    return pickBind({ p, state, project, env, listening, ownUp });
+    if (keep()) return resolveBind({ root, state, env });
+    return pickBind({ p, state, project, env, listening, ownUp, first: routed ? 2 : 1 });
   });
 }
 
 // Run `fn` holding a lock directory (mkdir is atomic). A lock older than `stale` ms was left by a
 // process that died. It is not taken over, since two starts taking it over at once could both
-// hold it; up stops and names the folder to remove.
-async function withLock(dir, fn, { stale = 60000, wait = 30000 } = {}) {
+// hold it; up stops and names the folder to remove. `doing` says what the lock guards, for those
+// messages.
+export async function withLock(dir, fn, { stale = 60000, wait = 30000, doing = 'choosing an address' } = {}) {
   mkdirSync(dirname(dir), { recursive: true });
   const until = Date.now() + wait;
   for (;;) {
@@ -325,8 +345,8 @@ async function withLock(dir, fn, { stale = 60000, wait = 30000 } = {}) {
       } catch {
         continue; // released between the two calls
       }
-      if (age > stale) throw new Error(`a snowglobe that stopped while choosing an address left ${dir}; remove that folder, then up again`);
-      if (Date.now() > until) throw new Error(`another snowglobe is choosing an address (${dir}); remove that folder if none is`);
+      if (age > stale) throw new Error(`a snowglobe that stopped while ${doing} left ${dir}; remove that folder, then run the command again`);
+      if (Date.now() > until) throw new Error(`another snowglobe is ${doing} (${dir}); remove that folder if none is`);
       await new Promise((r) => setTimeout(r, 25));
     }
   }
@@ -337,7 +357,7 @@ async function withLock(dir, fn, { stale = 60000, wait = 30000 } = {}) {
   }
 }
 
-async function pickBind({ p, state, project, env, listening, ownUp }) {
+async function pickBind({ p, state, project, env, listening, ownUp, first }) {
   const used = new Set();
   const top = dirname(state);
   for (const d of existsSync(top) ? readdirSync(top) : []) {
@@ -347,11 +367,11 @@ async function pickBind({ p, state, project, env, listening, ownUp }) {
   let bind = '127.0.0.1';
   if (!ownUp(project, env)) {
     bind = '';
-    for (let n = 1; n <= 50 && !bind; n++) {
+    for (let n = first; n <= 50 && !bind; n++) {
       const a = `127.0.0.${n}`;
       if (!used.has(a) && !(await listening(a))) bind = a;
     }
-    if (!bind) throw new Error('every loopback address from 127.0.0.1 to 127.0.0.50 is in use; set SG_BIND to one that is free');
+    if (!bind) throw new Error(`every loopback address from 127.0.0.${first} to 127.0.0.50 is in use; set SG_BIND to one that is free`);
   }
   writeFileSync(p.bind, `${bind}\n`);
   return bind;
@@ -389,14 +409,6 @@ export function loginsFile(file) {
   return file;
 }
 
-// Add a handle to the names run maps to nginx; a process already running under it picks a
-// new one up when it restarts.
-export function addName(host, { root = ROOT, state } = {}) {
-  const p = paths(root, state);
-  mkdirSync(p.https, { recursive: true });
-  if (!lines(p.names).includes(host)) appendFileSync(p.names, `${host}\n`);
-}
-
 // The secrets a snowglobe's services start with: the PDSes' admin password, JWT secret and PLC
 // rotation key, the relay's admin password and the PLC database's. `up` makes each one random,
 // once, per snowglobe (ensureSecrets); the compose files take them as ${SG_...:?}, so none has a

package/lib/render.mjs

@@ -46,6 +46,7 @@ const BUILT = {
   'snowglobe-dns': ['stack/https/dns', ['Dockerfile', 'dns.sh']],
   'snowglobe-proxy': ['stack/https/proxy', ['Dockerfile', 'server.mjs']],
   'snowglobe-pdsls': ['stack/pdsls', ['Dockerfile', 'network.patch', 'server.mjs']],
+  'snowglobe-jetstream': ['stack/jetstream', ['Dockerfile']],
 };
 
 /** The base compose files' services, which the globe's shared services start from. */
@@ -100,7 +101,8 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
   // init seeds alice, bob and the invite code on the PDS with bare handles, else the first.
   const seed = globe.pds.find((p) => p.bare_handles) ?? globe.pds[0];
   const on = globe.services;
-  // Where Jetstream and TAP read: the relay, or with one PDS that PDS's own firehose.
+  // Where Jetstream and TAP read: the relay, or with one PDS and no relay, that PDS's own
+  // firehose (TAP only: Jetstream always has the relay, see config.mjs).
   const feed = on.relay ? 'http://relay:2470' : `http://${svc(globe.pds[0])}:${PDS_PORT}`;
   const copy = (o) => structuredClone(o);
 
@@ -154,8 +156,9 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
         // 1918 one, which the SSRF-protected fetch would refuse.
         PDS_DISABLE_SSRF_PROTECTION: 'true',
         NODE_EXTRA_CA_CERTS: '/https/ca.crt',
-        // <name>.app.<domain> resolves to nginx inside each PDS (https/app-names.cjs).
-        SG_RESOLVE_DOMAIN: `app.${D}`,
+        // Every name under the domain resolves to nginx inside each PDS (https/app-names.cjs):
+        // an app at <name>.app.<domain>, and a client the globe serves itself, such as PDSls.
+        SG_RESOLVE_DOMAIN: D,
         NODE_OPTIONS: '--require /https/app-names.cjs',
       },
       volumes: [`${svc(p)}-data:/pds/data`, CA, APP_NAMES],
@@ -259,13 +262,14 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
   }
 
   if (on.jetstream) {
+    // Its first backfill asks each PDS for its repos at the PDS's https name, through nginx.
     services.jetstream = {
       ...copy(base.base.jetstream),
-      depends_on: on.relay ? { relay: healthy } : { [svc(globe.pds[0])]: healthy },
-      environment: {
-        ...copy(base.base.jetstream.environment),
-        JETSTREAM_WS_URL: `${feed.replace(/^http/, 'ws')}/xrpc/com.atproto.sync.subscribeRepos`,
-      },
+      build: './stack/jetstream',
+      image: base.tags['snowglobe-jetstream'],
+      depends_on: { relay: healthy },
+      environment: { ...copy(base.base.jetstream.environment), JETSTREAM_RELAY_URL: feed },
+      volumes: [...base.base.jetstream.volumes, GO_CA],
       ports: [
         '${SG_BIND:-127.0.0.1}:${SG_JETSTREAM_PORT:-6008}:6008',
         '${SG_BIND:-127.0.0.1}:${SG_JETSTREAM_METRICS_PORT:-6009}:6009',
@@ -539,7 +543,7 @@ export function renderGlobe(globe, base, { stateDir, globeDir = join(stateDir ??
         g.name,
         `Holds groups, which are accounts of their own, with handles under ${host(g)} (${g.image ? shortImage(g.image) : 'built locally'})`,
       ]),
-      ['PLC directory', 'plc', 'plc', 'Resolves each did:plc to its keys and PDS; also plc.directory under snowglobe run'],
+      ['PLC directory', 'plc', 'plc', 'Resolves each did:plc to its keys and PDS'],
       on.relay && ['Relay', 'relay', 'relay', "Crawls each PDS and merges their changes into one firehose"],
       on.jetstream && ['Jetstream', 'jetstream', 'jetstream', "The relay's firehose as JSON, for apps (and this page)"],
       on.slingshot && ['Slingshot', 'slingshot', 'slingshot', 'Resolves handles, DIDs and records from this network only'],

package/lib/router.mjs

@@ -0,0 +1,214 @@
+// The name router: one per machine, in front of every local snowglobe on it.
+//
+// Each snowglobe has a domain of its own (<globe>.local.snowglobe.at unless its file names one),
+// and public DNS answers every name under local.snowglobe.at, at any depth, with 127.0.0.1. The
+// router listens there on 443, reads the name a TLS connection asks for (SNI) and passes the
+// connection, still encrypted, to the snowglobe whose domain the name is under, on that
+// snowglobe's own 127.0.0.N. Each snowglobe's nginx keeps serving its own certificate. So a browser
+// reaches every snowglobe at once by name, and a handle made at any time resolves, with nothing to
+// map: as on a hosted globe, where the cluster's Gateway routes by name.
+//
+// It is a stock nginx (the image each snowglobe's nginx runs), in a container named
+// snowglobe-router on the host's network. Its folder is ~/.local/share/snowglobe/.router whatever
+// XDG_DATA_HOME says, because the container serves the whole machine: a snowglobe kept in another
+// state folder (a test's copy, say) is routed by the same router. In the folder: nginx.conf, written
+// from routes/, one file per compose project it routes ("<domain> <address> <globe>"); compose
+// project names are what is unique on a machine. up writes a snowglobe's route and down removes
+// it, each under the router's lock, then brings the container in line (syncRouter).
+// The longest domain wins, so a snowglobe still on the shared local.snowglobe.at keeps working
+// beside ones under it. A name under no routed domain is closed. Linux only for now (routerRuns
+// in lib/env.mjs); SG_ROUTER=off turns it off.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ROUTER_ADDRESS, withLock } from './env.mjs';
+
+export const ROUTER_CONTAINER = 'snowglobe-router';
+// The image each snowglobe's own nginx runs (lib/render.mjs), so the router pulls nothing new.
+export const ROUTER_IMAGE = 'nginx:1.30-alpine';
+// Where the router's folder is mounted in its container. A folder, not the file: up and down
+// replace nginx.conf by renaming over it, and a file mount would keep the old one.
+const MOUNT = '/etc/snowglobe-router';
+
+/** The router's folder: a dot folder beside the default state folders, so no snowglobe can be named for it. */
+export const routerDir = (env = process.env) => join(env.HOME || homedir(), '.local', 'share', 'snowglobe', '.router');
+
+const ROUTE_RE = /^([a-z0-9.-]+) (127\.[0-9]+\.[0-9]+\.[0-9]+) ([a-z0-9]+)$/;
+
+/**
+ * The routes in `dir`: [{ project, domain, bind, globe }], by project. A file that does not read as
+ * one is skipped, and so is one removed while they are read (ls reads them without the lock).
+ */
+export function readRoutes(dir) {
+  const routes = join(dir, 'routes');
+  if (!existsSync(routes)) return [];
+  return readdirSync(routes)
+    .filter((f) => !f.startsWith('.'))
+    .sort()
+    .flatMap((project) => {
+      let text;
+      try {
+        text = readFileSync(join(routes, project), 'utf8');
+      } catch (e) {
+        if (e.code === 'ENOENT' || e.code === 'EISDIR') return [];
+        throw e;
+      }
+      const m = text.trim().match(ROUTE_RE);
+      return m ? [{ project, domain: m[1], bind: m[2], globe: m[3] }] : [];
+    });
+}
+
+// Written aside and renamed, so nginx never reads half a file. The file aside is a dot file, which
+// readRoutes skips, so a write that stops half way leaves no second route.
+function put(file, text) {
+  const aside = join(dirname(file), `.${basename(file)}.tmp.${process.pid}`);
+  writeFileSync(aside, text);
+  renameSync(aside, file);
+}
+
+/** Route `domain` and every name under it to `bind`, for the compose project `project` (the snowglobe `globe`). */
+export function writeRoute(dir, { project, domain, bind, globe }) {
+  mkdirSync(join(dir, 'routes'), { recursive: true });
+  put(join(dir, 'routes', project), `${domain} ${bind} ${globe}\n`);
+}
+
+/** Stop routing to the compose project `project`. Returns whether it had a route. */
+export function dropRoute(dir, project) {
+  const file = join(dir, 'routes', project);
+  if (!existsSync(file)) return false;
+  unlinkSync(file);
+  return true;
+}
+
+/**
+ * Write `route` ({ project, domain, bind, globe }) in `dir`, unless another project's route at the
+ * same domain is up (`isUp(project)`): that route is returned and nothing is written. Another's
+ * route there whose project is not up was left by a snowglobe stopped without snowglobe down; it is
+ * dropped, since nginx refuses the whole config with two routes at one domain. Returns null once
+ * written. Run it under the router's lock, as syncRouter's `change`.
+ */
+export function claimDomain(dir, route, isUp, log = () => {}) {
+  const others = readRoutes(dir).filter((r) => r.project !== route.project && r.domain === route.domain);
+  const live = others.find((r) => isUp(r.project));
+  if (live) return live;
+  for (const r of others) {
+    dropRoute(dir, r.project);
+    log(`Dropped the route ${r.globe} (compose project ${r.project}) left at ${r.domain}: it is not up`);
+  }
+  writeRoute(dir, route);
+  return null;
+}
+
+/**
+ * The router's nginx.conf for `routes`: a domain and every name under it (nginx's ".domain" form)
+ * to that snowglobe's 443, the longest domain first (nginx prefers it whatever the order).
+ */
+export function routerConfig(routes) {
+  const map = [...routes]
+    .sort((a, b) => b.domain.length - a.domain.length || a.domain.localeCompare(b.domain))
+    .map((r) => `    .${r.domain} ${r.bind}:443;  # ${r.project}`);
+  return [
+    '# The snowglobe name router (lib/router.mjs). Written by snowglobe up and down from routes/; edits are lost.',
+    'worker_processes 1;',
+    'events { worker_connections 1024; }',
+    'stream {',
+    '  map $ssl_preread_server_name $snowglobe {',
+    '    hostnames;',
+    ...map,
+    // A name under no routed domain: nothing listens there, so the connection is closed.
+    '    default unix:/run/snowglobe-router-none.sock;',
+    '  }',
+    '  server {',
+    `    listen ${ROUTER_ADDRESS}:443;`,
+    '    ssl_preread on;',
+    '    proxy_pass $snowglobe;',
+    '  }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+const dockerCli = (env) => (args) => spawnSync('docker', args, { encoding: 'utf8', env });
+
+/**
+ * The router container: { state: 'running' | 'stopped' | 'missing', dir }, dir being the folder
+ * it reads ('' when Docker does not say). `docker` runs a docker command (spawnSync's result).
+ */
+export function routerState(docker = dockerCli(process.env)) {
+  const res = docker(['inspect', '-f', `{{.State.Running}}|{{range .Mounts}}{{if eq .Destination "${MOUNT}"}}{{.Source}}{{end}}{{end}}`, ROUTER_CONTAINER]);
+  if (res.error || res.status !== 0) return { state: 'missing', dir: '' };
+  const [running = '', dir = ''] = (res.stdout ?? '').trim().split('|');
+  return { state: running === 'true' ? 'running' : running === 'false' ? 'stopped' : 'missing', dir };
+}
+
+// The same folder, though the two may be spelled differently (a HOME reached through a link).
+// Docker reports a mount's folder as it was given; one this machine cannot see is compared as text.
+function sameFolder(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+}
+
+/**
+ * Bring the router in line with the routes in `dir`: write nginx.conf, then reload a running
+ * router, start a stopped one, or make it; with no routes left, remove it. A router that reads
+ * another folder (started under another HOME) is refused, since it would never see these routes.
+ * `change`, run first under the same lock, changes the routes (claimDomain, dropRoute); when it
+ * returns false nothing changed and the router is left as it is. `docker` runs a docker command
+ * (spawnSync's result); `wait` is how long a router just started gets before it is checked.
+ */
+export async function syncRouter({ dir = routerDir(), env = process.env, docker = dockerCli(env), log = () => {}, wait = 1000, change = () => true } = {}) {
+  // Two ups at once would both make the router, or one would write a config without the other's
+  // route, or both take one domain; one at a time, under a lock in the router's folder.
+  return withLock(
+    join(dir, '.lock'),
+    async () => {
+      if ((await change()) !== false) await sync({ dir, docker, log, wait });
+    },
+    { doing: 'updating the name router' },
+  );
+}
+
+async function sync({ dir, docker, log, wait }) {
+  const routes = readRoutes(dir);
+  const now = routerState(docker);
+  if (now.state !== 'missing' && now.dir && !sameFolder(now.dir, dir))
+    throw new Error(`the name router on this machine reads ${now.dir}, not ${dir} (it was started under another HOME); bring snowglobes up under that one, or docker rm -f ${ROUTER_CONTAINER} once none of its snowglobes is up`);
+  const must = (args) => {
+    const res = docker(args);
+    if (res.error) throw res.error;
+    if (res.status !== 0) throw new Error(`docker ${args.slice(0, 2).join(' ')} for the name router failed: ${(res.stderr ?? '').trim()}`);
+  };
+  if (!routes.length) {
+    if (now.state !== 'missing') {
+      must(['rm', '-f', ROUTER_CONTAINER]);
+      log('Removed the name router: no snowglobe is routed');
+    }
+    return;
+  }
+  mkdirSync(dir, { recursive: true });
+  put(join(dir, 'nginx.conf'), routerConfig(routes));
+  // With -c the reload reads this config before it signals, and fails when nginx would refuse it.
+  // Without it, it reads the image's own config and says nothing, while the router keeps the old routes.
+  if (now.state === 'running') return must(['exec', ROUTER_CONTAINER, 'nginx', '-s', 'reload', '-c', `${MOUNT}/nginx.conf`]);
+  if (now.state === 'stopped') must(['start', ROUTER_CONTAINER]);
+  else
+    must([
+      'run', '-d', '--name', ROUTER_CONTAINER, '--label', 'snowglobe.router=1', '--restart', 'unless-stopped',
+      '--network', 'host', '-v', `${dir}:${MOUNT}:ro`,
+      ROUTER_IMAGE, 'nginx', '-g', 'daemon off;', '-c', `${MOUNT}/nginx.conf`,
+    ]);
+  // nginx that cannot listen exits at once; give it a moment, then look.
+  await sleep(wait);
+  if (routerState(docker).state !== 'running')
+    throw new Error(
+      `the name router did not stay up (docker logs ${ROUTER_CONTAINER} says why). Something else may hold ${ROUTER_ADDRESS}:443, ` +
+        'such as a snowglobe made before 0.5.0 that kept that address: snowglobe down it, and up it again to move it.',
+    );
+  log(`Started the name router on ${ROUTER_ADDRESS}:443`);
+}

package/lib/up.mjs

@@ -1,6 +1,7 @@
 // What snowglobe up decides without Docker: the app routes the file adds, whether the globe's
 // PDSes clash with an app's handle ending, the env names the file's accounts keep their logins
-// under. Pure: inputs in, text or lists out (lib/commands/up.mjs runs the globe).
+// under, whether the relay restarts. Pure: inputs in, text or lists out (lib/commands/up.mjs runs
+// the globe).
 
 const envName = (label) => label.toUpperCase().replace(/-/g, '_');
 
@@ -52,3 +53,15 @@ export function endingClash(pdsNames, apps) {
   }
   return null;
 }
+
+/**
+ * The first of `dialed` (service name -> its containers' start times) with a container that started
+ * after the relay did (`relay`, its containers' start times), or null. The times are Docker's
+ * State.StartedAt. The relay dials each PDS through nginx, and one that was running when either
+ * went away can stop picking up what the PDS sends, so up restarts it.
+ */
+export function startedAfterRelay(relay, dialed) {
+  const since = Math.max(...relay.map((t) => Date.parse(t)));
+  for (const [service, times] of Object.entries(dialed)) if (times.some((t) => Date.parse(t) > since)) return service;
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmeet/snowglobe",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Standalone, testable ATProto development network for local development and CI",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@peculiar/asn1-schema": "2.11.0",
-    "@peculiar/asn1-x509": "2.11.0",
+    "@peculiar/asn1-schema": "^2.11.0",
+    "@peculiar/asn1-x509": "^2.11.0",
     "@peculiar/x509": "2.2.0",
     "reflect-metadata": "0.2.2",
     "yaml": "^2.9.1"

package/snowglobe.default.yml

@@ -7,15 +7,14 @@
 # The whole thing, three PDSes, a relay and a lexicon authority:
 #   https://github.com/OpenMeet-Team/snowglobe/blob/main/docs/examples/atmo.yml
 
-globe: snowglobe
-domain: local.snowglobe.at     # every name below is under it
+globe: snowglobe               # every name below is under snowglobe.local.snowglobe.at, the globe's own domain
 
 pds:
-  - name: main                 # https://main.local.snowglobe.at
+  - name: main                 # https://main.snowglobe.local.snowglobe.at
     image: ghcr.io/bluesky-social/pds:0.4.5037    # a current release
-    bare_handles: true         # its handles are <account>.local.snowglobe.at
-  # A second PDS, with handles <name>.other.local.snowglobe.at. With more than one PDS the
-  # relay turns on, so Jetstream sees every PDS's writes.
+    bare_handles: true         # its handles are <account>.snowglobe.local.snowglobe.at
+  # A second PDS, with handles <name>.other.snowglobe.local.snowglobe.at. The relay crawls it too, so
+  # Jetstream sees its writes.
   # - name: other
   #   image: ghcr.io/bluesky-social/pds:0.4.5009
   #
@@ -28,16 +27,16 @@ pds:
 services:                      # these are the defaults, each true or false
   jetstream: true
   slingshot: true              # answers a handle's DID and PDS inside the network; needs jetstream
-  pdsls: true                  # https://pdsls.local.snowglobe.at, a browser for the network's records
+  pdsls: true                  # https://pdsls.snowglobe.local.snowglobe.at, a browser for the network's records
   tap: false                   # sends an app the events of one collection (true, or a map; see snowglobe.md above)
-  # relay: auto                # auto: on when there is more than one PDS
+  # relay: auto                # auto: on with Jetstream, which reads it, or more than one PDS
 
 # Where every PDS resolves lexicons (NSIDs) from. Name a PDS that is in this file.
 # lexicons:
 #   authority: alpha
 #   publish: lexicons          # a folder next to this file; up publishes every lexicon in it
 
-# A group host runs beside the PDSes, at https://gh.local.snowglobe.at.
+# A group host runs beside the PDSes, at https://gh.snowglobe.local.snowglobe.at.
 # grouphosts:
 #   - name: gh
 #     kind: opensocial
@@ -47,7 +46,7 @@ accounts:                      # <name>@<pds>; up makes each one
   - alice@main
   - bob@main
 
-# Your app, reached at https://myapp.app.local.snowglobe.at, with settings from the snowglobe.
+# Your app, reached at https://myapp.app.snowglobe.local.snowglobe.at, with settings from the snowglobe.
 # `snowglobe env` hands them over. The names:
 #   https://github.com/OpenMeet-Team/snowglobe/blob/main/docs/your-app.md
 # apps:

package/stack/docker-compose.test.yml

@@ -22,7 +22,8 @@ services:
       retries: 10
 
   maildev:
-    image: maildev/maildev:latest
+    # Pinned: 3.0.0 moved the health check to /api/healthz (stack/page/snowglobe.conf asks there).
+    image: maildev/maildev:3.0.0
     restart: unless-stopped
     ports:
       - "${SG_MAILDEV_WEB_PORT:-${DEVNET_MAILDEV_WEB_PORT:-1081}}:1080"

package/stack/docker-compose.yml

@@ -98,17 +98,21 @@ services:
       timeout: 3s
       retries: 10
 
-  # ── Jetstream (JSON event stream from PDS firehose) ──────────────
+  # ── Jetstream (JSON event stream from the relay's firehose) ──────
+  # Built from stack/jetstream: the pinned Jetstream, plus busybox for the health check. It reads
+  # a relay, not a PDS: at start it asks the relay for the network's hosts, which a PDS refuses.
   jetstream:
-    image: ghcr.io/bluesky-social/jetstream:sha-05c89f0
+    build: ./jetstream
+    image: snowglobe-jetstream
     restart: unless-stopped
-    depends_on:
-      pds:
-        condition: service_healthy
     environment:
-      JETSTREAM_WS_URL: ws://pds:3000/xrpc/com.atproto.sync.subscribeRepos
-      JETSTREAM_DATA_DIR: /data
-      JETSTREAM_LIVENESS_TTL: 86400s
+      JETSTREAM_RELAY_URL: http://relay:2470
+      JETSTREAM_PLC_URL: http://plc:2582
+      # A folder of its own: a volume from an older snowglobe holds the older Jetstream's files.
+      JETSTREAM_DATA_DIR: /data/v2
+      JETSTREAM_ADDR: ":6008"
+      # Metrics, at /metrics.
+      JETSTREAM_DEBUG_ADDR: ":6009"
     volumes:
       - jetstream-data:/data
     ports:
@@ -116,11 +120,15 @@ services:
       - "${SG_JETSTREAM_METRICS_PORT:-${DEVNET_JETSTREAM_METRICS_PORT:-6009}}:6009"
     networks:
       - atproto-devnet
+    # Healthy once it serves: its archive answers 503 until then, as its streams do. The debug
+    # port's /readyz says only that it is listening.
     healthcheck:
-      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/127.0.0.1/6008'"]
+      test: ["CMD", "/busybox", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:6008/xrpc/network.bsky.jetstream.listSegments?limit=1"]
       interval: 5s
       timeout: 3s
       retries: 10
+      # A new snowglobe's first start takes a minute or two (docs/how-it-works.md).
+      start_period: 120s
 
   # ── TAP (repo sync + backfill) ───────────────────────────────────
   tap: