@openmeet/snowglobe 0.4.0 → 0.5.0

package/README.md

@@ -19,9 +19,9 @@ One file, `snowglobe.yml`, says what a snowglobe runs. [`snowglobe.default.yml`]
 is the one to start from. It gives you:
 
 - one current PDS (personal data server, where an account's records live and where it signs in), at
-  `https://main.local.snowglobe.at`, with two test accounts, `alice` and `bob`;
-- a PLC directory, the phone book that says which PDS holds each `did:plc` account; it also answers as
-  `plc.directory` for your app;
+  `https://main.snowglobe.local.snowglobe.at`, with two test accounts, `alice` and `bob`;
+- a PLC directory, the phone book that says which PDS holds each `did:plc` account; your app is told
+  its address;
 - Jetstream, a simple stream of every write on the network, for apps that follow it;
 - Slingshot, which looks up a handle's DID and PDS inside the network;
 - PDSls, to browse the network's records;
@@ -39,36 +39,32 @@ The file also holds commented examples for adding more, up to a full setup:
 [`docs/examples/atmo.yml`](docs/examples/atmo.yml) is a larger file, with three PDSes, a relay and a
 lexicon authority, that [Example: atmo](docs/examples/atmo.md) builds on.
 
-Every name is under one domain, `local.snowglobe.at`, served by nginx with a certificate from a
-local CA that the snowglobe makes for itself. There is no AppView and no feed generator.
+Every name is under the snowglobe's own domain, `<globe>.local.snowglobe.at`, served by nginx with a
+certificate from a local CA that the snowglobe makes for itself. There is no AppView and no feed generator.
 [The snowglobe](docs/snowglobe.md) shows the whole file and what each part does.
 
 ## What you need
 
-Every service in a snowglobe has its own https name under `local.snowglobe.at`, such as
-`alice.local.snowglobe.at`. Handles, sign-in (OAuth) and DID documents all carry those names, so
-your computer has to send the names to the snowglobe, and trust its certificate. Here is what to do.
+Every service in a snowglobe has its own https name under the snowglobe's domain, such as
+`alice.snowglobe.local.snowglobe.at` for the default file. Handles, sign-in (OAuth) and DID documents
+all carry those names, so your computer has to send the names to the snowglobe, and trust its
+certificate. Here is what to do.
 
-**Before you start it:**
-
-1. Install Docker with Compose, and Node 20 or newer. Use Linux, or Windows with WSL 2.
-2. To run a command against the snowglobe from your machine (`snowglobe run`: your own app, its
-   tests, or the `curl` example below), also install
-   [bubblewrap](https://github.com/containers/bubblewrap): `sudo apt install bubblewrap` on Debian or
-   Ubuntu. You do not need it to bring a snowglobe up or to look at one in a browser.
+**Before you start it:** install Docker with Compose, and Node 20 or newer. Use Linux, or Windows with
+WSL 2.
 
 **After it is up, to open it in a browser or reach it from an app:**
 
-3. Make the names reach the snowglobe.
-   - Docker and your browser on the same computer: you usually do nothing, because public DNS answers
-     every name under `local.snowglobe.at` with `127.0.0.1`. If the browser says "server not found",
-     your router is dropping that answer. See
+1. The names reach the snowglobe on their own. Public DNS answers every name under
+   `local.snowglobe.at` with `127.0.0.1`, where `snowglobe up` starts a name router that passes each
+   connection to the snowglobe the name is under, so every snowglobe on the machine answers at once.
+   - If the browser says "server not found", your router is dropping that answer. See
      [When the browser cannot open it](docs/browser.md#when-the-browser-cannot-open-it).
-   - Docker in a dev container, or on another machine: the snowglobe's proxy runs with every `up`, on
-     `127.0.0.1:1080`; point your browser at it ([From a browser on your own computer](docs/browser.md)).
-   - A command started with `snowglobe run`: you do nothing, it sets the names up itself.
-4. Trust the snowglobe's certificate authority (CA). Run `snowglobe trust` on the machine that runs
-   Docker. For another machine, see [From a browser on your own computer](docs/browser.md).
+   - With Docker in a dev container, or on another machine, forward its port 443 to your computer
+     ([From a browser on your own computer](docs/browser.md)).
+2. Trust the snowglobe's certificate authority (CA). Run `snowglobe trust` on the machine that runs
+   Docker. For another machine, see [From a browser on your own computer](docs/browser.md). A
+   command started with `snowglobe run` trusts it without this.
 
 **Why not just use ports?** The PDSes are not published on ports at all: only nginx (443), the proxy,
 the PLC, Jetstream and MailDev are. A PDS's address is its name, and that name is what a DID document, a
@@ -93,25 +89,25 @@ To keep the command with one project instead, run `npm install --save-dev @openm
 `snowglobe.yml` (copy it from `node_modules/@openmeet/snowglobe/snowglobe.default.yml`). Either
 command also fits in a `package.json` script.
 
-Now try it. `snowglobe run` runs a command that can reach the snowglobe by name, and `--cacert`
-gives curl the snowglobe's certificate authority (CA), so it trusts the snowglobe's https:
+Now try it. The snowglobe's names work for any program on the machine, and `--cacert` gives curl the
+snowglobe's certificate authority (CA), so it trusts the snowglobe's https:
 
 ```bash
 # Sign up a new account, then look up alice's account through Slingshot
 snowglobe account carol CAROL                # CAROL: the prefix of her login variables, such as CAROL_PASSWORD
-snowglobe run curl -s --cacert ~/.local/share/snowglobe/ca/ca.crt \
-  'https://slingshot.local.snowglobe.at/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=alice.local.snowglobe.at'
+curl -s --cacert ~/.local/share/snowglobe/ca/ca.crt \
+  'https://slingshot.snowglobe.local.snowglobe.at/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=alice.snowglobe.local.snowglobe.at'
 ```
 
 To look around in a browser, you need two things: the browser has to trust the snowglobe's
 certificate, and it has to be able to find the snowglobe. If Docker runs on the same computer as your
-browser, run `snowglobe trust` and open `https://local.snowglobe.at/`, the network's page,
+browser, run `snowglobe trust` and open `https://snowglobe.local.snowglobe.at/`, the network's page,
 which lists every service, account and write. If Docker runs in a dev container or on another
-machine, your browser also needs the snowglobe's small proxy, which sends the snowglobe's names to
-it; [From a browser on your own computer](docs/browser.md) walks through both.
+machine, also forward its port 443 to your computer;
+[From a browser on your own computer](docs/browser.md) walks through both.
 
 The default snowglobe comes with one app to look at, [PDSls](docs/snowglobe.md#pdsls-browsing-the-networks-records),
-the record browser. `https://pdsls.local.snowglobe.at/at://alice.local.snowglobe.at` shows alice's repo,
+the record browser. `https://pdsls.snowglobe.local.snowglobe.at/at://alice.snowglobe.local.snowglobe.at` shows alice's repo,
 once your browser can reach the snowglobe as above.
 
 Stop the snowglobe with `snowglobe down`. Add `-v` to delete its data too, every account
@@ -123,10 +119,10 @@ To run your own app inside of a snowglobe, see [Your app in a snowglobe](docs/yo
 
 ## Platforms
 
-Snowglobe runs on Linux, and on Windows under WSL 2. Both are tested. macOS is not supported, but we'd love to.
+Snowglobe runs on Linux, and on Windows under WSL 2. Both are tested. macOS is not supported yet.
 If you try it on a Mac, please
 [open an issue](https://github.com/OpenMeet-Team/snowglobe/issues) with what broke, or that it
-worked, and we'd love to experiment with you.
+worked.
 
 ## Documentation
 
@@ -134,11 +130,13 @@ worked, and we'd love to experiment with you.
   down, and what it writes.
 - [Your app in a snowglobe](docs/your-app.md): `snowglobe run`, and the tools that make an app's
   accounts, invite codes, lexicons and routes.
-- [From a browser on your own computer](docs/browser.md): the proxy, launch flags, and trusting the
-  CA.
+- [From a browser on your own computer](docs/browser.md): the name router, Docker on another
+  machine, and trusting the CA.
 - [How it works](docs/how-it-works.md): what runs and how it is wired, Slingshot, and the relay build.
 - [Configuration](docs/configuration.md): the settings.
 - [Testing Snowglobe](docs/testing.md): the test suite and the smoke run.
+- [Example: Statusphere](docs/examples/statusphere.md): the atproto example app on a snowglobe, with
+  two small changes. CI runs it end to end.
 - [Example: atmo](docs/examples/atmo.md): an events app on a local snowglobe.
 - The older plain-http stack (`npm run up`) is not in this version. Its code and README are in the
   [v0.2.0 tag](https://github.com/OpenMeet-Team/snowglobe/tree/v0.2.0) (v0.1.0 has the first version of it).

package/bin/snowglobe.mjs

@@ -13,7 +13,7 @@
 //   app       routes https://<name>.app.<domain> to a port on this machine
 //   up        brings the globe up, as the compose project named for its file (or <name>, -f <file>)
 //   down      stops it (the same ways)
-//   run       runs a command with the app's settings, and plc.directory pointed at the snowglobe
+//   run       runs a command with the app's settings and the snowglobe's CA
 //
 // A snowglobe is the snowglobe.yml in the folder you are in or the nearest one above (else
 // SG_FILE, else the default). Its state is kept per user, not in a checkout: ~/.local/share/

package/lib/certs.mjs

@@ -9,14 +9,15 @@
 // Delete the CA's ca.* to start over, and then trust the new ca.crt again everywhere the old one
 // was trusted.
 //
-// The CA can only vouch for servers under the default domain, the domain it was made for
+// The CA can only vouch for servers under local.snowglobe.at (the zone every snowglobe's own
+// domain is under, <globe>.local.snowglobe.at), a domain outside it that it was made for,
 // and plc.directory (name constraints, serverAuth only, no IP addresses), so
 // trusting it on a host cannot put any other site at risk, even if ca.key leaks. A name outside
-// those is refused before the leaf is touched; widening the list, or a snowglobe on another
-// domain made after the CA, means a new CA, trusted again.
+// those is refused before the leaf is touched; widening the list, or a snowglobe on a domain
+// outside the zone made after the CA, means a new CA, trusted again.
 //
-// A TLS wildcard covers one label, so *.local.snowglobe.at does not cover a handle on the PDS
-// named regular (<name>.regular.local.snowglobe.at); each handle domain has its own.
+// A TLS wildcard covers one label, so *.mine.local.snowglobe.at does not cover a handle on the PDS
+// named regular (<name>.regular.mine.local.snowglobe.at); each handle domain has its own.
 
 import 'reflect-metadata';
 import { AsnConvert } from '@peculiar/asn1-schema';
@@ -25,7 +26,7 @@ import * as x509 from '@peculiar/x509';
 import { X509Certificate as NodeCertificate, createPrivateKey, randomBytes, webcrypto } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { DEFAULT_DOMAIN } from './config.mjs';
+import { LOCAL_ZONE } from './config.mjs';
 
 x509.cryptoProvider.set(webcrypto);
 
@@ -104,9 +105,11 @@ async function makeCa(domain, now) {
   const name = `snowglobe local CA ${now.toISOString().slice(0, 10)} ${randomBytes(3).toString('hex')}`;
   const subtree = (gn) => new GeneralSubtree({ base: new GeneralName(gn) });
   const constraints = new NameConstraints({
-    // One CA serves every snowglobe, so the default domain is always in, whatever domain the
-    // snowglobe that makes it is on.
-    permittedSubtrees: new GeneralSubtrees([...new Set([DEFAULT_DOMAIN, domain, ...FIXED])].map((d) => subtree({ dNSName: d }))),
+    // One CA serves every snowglobe, so the local zone is always in, whatever domain the
+    // snowglobe that makes it is on; a domain inside the zone needs no subtree of its own.
+    permittedSubtrees: new GeneralSubtrees(
+      [...new Set([LOCAL_ZONE, ...(within(domain, [LOCAL_ZONE]) ? [] : [domain]), ...FIXED])].map((d) => subtree({ dNSName: d })),
+    ),
     excludedSubtrees: new GeneralSubtrees([subtree({ iPAddress: '0.0.0.0/0' }), subtree({ iPAddress: '::/0' })]),
   });
   const cert = await x509.X509CertificateGenerator.createSelfSigned({

package/lib/commands/account.mjs

@@ -2,13 +2,13 @@
 //
 // account creates or finds <name> on <pds> (the PDS with bare handles, else the seed PDS):
 // <name>.<domain> there, <name>.<pds>.<domain> on the others. Its login goes into ACCOUNTS_FILE
-// (accounts.env in the snowglobe's state folder by default, mode 600) as <PREFIX>_HANDLE, _DID, _PASSWORD and _PDS, its
-// handle into the names bin/snowglobe.mjs run maps (restart a process under it to pick one up), and
-// its DID alone to stdout. A rerun finds it. It reads the rendered globe, and prints no secret
+// (accounts.env in the snowglobe's state folder by default, mode 600) as <PREFIX>_HANDLE, _DID, _PASSWORD and _PDS, and
+// its DID alone to stdout. The handle resolves at once: it is under the snowglobe's domain, which
+// the name router serves. A rerun finds it. It reads the rendered globe, and prints no secret
 // (lib/xrpc.mjs).
 
 import { randomBytes } from 'node:crypto';
-import { ROOT, UsageError, addName, envGet, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
+import { ROOT, UsageError, envGet, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
 import { session } from '../state.mjs';
 import { mintInvite, why, xrpc } from '../xrpc.mjs';
 
@@ -31,7 +31,7 @@ export async function run({ positionals: [name, prefix, pds] }) {
 /**
  * Create, or find, the account <name> on the globe's PDS `pds` (the one with bare handles, else
  * the seed PDS, by default), and keep its login in `file` as <prefix>_HANDLE, _DID, _PASSWORD and
- * _PDS. Its handle is added to the names snowglobe run maps. Resolves to the DID. A rerun signs in
+ * _PDS. Resolves to the DID. A rerun signs in
  * with the kept password and finds the account; a PDS that takes invite codes is sent one
  * (SG_INVITE_CODE, else a single-use code minted for this account), the others none.
  */
@@ -64,7 +64,6 @@ export async function account({ name, prefix, pds, file, root = ROOT, state, env
     const res = await xrpc(pdsUrl, 'com.atproto.server.createSession', { body: { identifier: handle, password: kept }, ...opts });
     if (res.ok && typeof res.json.did === 'string') {
       if (envGet(`${prefix}_DID`, accounts) !== res.json.did) save(res.json.did, kept);
-      addName(handle, { root, state });
       log(`Found ${handle} -> ${res.json.did}`);
       return res.json.did;
     }
@@ -79,7 +78,6 @@ export async function account({ name, prefix, pds, file, root = ROOT, state, env
   const res = await xrpc(pdsUrl, 'com.atproto.server.createAccount', { body, ...opts });
   if (!res.ok || typeof res.json.did !== 'string') throw new Error(`createAccount ${handle} on ${pdsUrl} failed: ${why(res)}`);
   save(res.json.did, password);
-  addName(handle, { root, state });
   log(`Created ${handle} on ${pdsUrl} -> ${res.json.did}`);
   return res.json.did;
 }

package/lib/commands/down.mjs

@@ -11,9 +11,14 @@
 // alice and bob and rewrites accounts.env from scratch, dropping the logins the tools wrote there
 // (their accounts are gone too), and the lexicon authority is made again. The fixed secrets an
 // older snowglobe kept for its data (secrets.env) are dropped with it, so up makes random ones. The CA, the leaf and
-// the app routes stay either way. The project is guarded as up guards it.
+// the app routes stay either way. The project is guarded as up guards it. Once the project is
+// down, the name router stops routing to it, and is removed when no snowglobe is left to route
+// (lib/router.mjs).
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { ROOT, dc, dropLegacySecrets, guardProject } from '../env.mjs';
+import { dropRoute, routerDir, syncRouter } from '../router.mjs';
 import { byName, pointedAt, session } from '../state.mjs';
 
 export const command = {
@@ -27,7 +32,7 @@ export function run({ values, positionals: [word] }) {
   return down({ volumes: values.volumes, ...pointedAt({ file: values.file, word }) });
 }
 
-export function down({ volumes = false, file, name, root = ROOT, env = process.env } = {}) {
+export async function down({ volumes = false, file, name, root = ROOT, env = process.env, log = (m) => console.error(m) } = {}) {
   // The shared devnet is refused before anything is looked up, even by a file that is not there.
   if (env.SG_PROJECT) guardProject(env);
   const found = name ? byName(name, { env }) : session({ file, env });
@@ -36,5 +41,9 @@ export function down({ volumes = false, file, name, root = ROOT, env = process.e
   if (res.error) throw res.error;
   // The data the fixed secrets were kept for is gone only once compose says it removed it.
   if (volumes && res.status === 0) dropLegacySecrets({ root, state: found.state });
+  // Only a snowglobe the router routes to touches it. The route is dropped under the router's
+  // lock; when another down got there first, the router is already in line.
+  const rdir = routerDir(env);
+  if (res.status === 0 && existsSync(join(rdir, 'routes', project))) await syncRouter({ dir: rdir, env, log, change: () => dropRoute(rdir, project) });
   return res.status ?? 1;
 }

package/lib/commands/ls.mjs

@@ -1,16 +1,19 @@
 // bin/snowglobe.mjs ls
 //
 // ls lists the snowglobes on this machine: every folder in the state root (lib/env.mjs stateRoot;
-// ca/, the one CA, is not one) with its name, the domain it was rendered for, whether its compose
-// project is running, and the file that owns it. Take the name to `up`, `down`, or a file to -f.
+// ca/, the one CA, and dot folders such as the name router's .router are not ones) with its name,
+// the domain it was rendered for, whether its compose project is running, and the file that owns
+// it. Take the name to `up`, `down`, or a file to -f.
 // "up" is a project with a container running (the one-shot init and relay-init have exited by
 // then), "down" is none, or no project yet; "unknown" is what it says when Docker did not answer.
+// When the name router routes any snowglobe, a last line says whether it is running and to which.
 // Reads only; nothing is started.
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { ROOT, envGet, paths, stateRoot } from '../env.mjs';
+import { ROOT, ROUTER_ADDRESS, envGet, paths, stateRoot } from '../env.mjs';
+import { readRoutes, routerDir, routerState } from '../router.mjs';
 import { ownerOf } from '../state.mjs';
 
 export const command = {
@@ -44,7 +47,7 @@ export function list({ root = ROOT, env = process.env, statuses = projectStatuse
   const base = stateRoot(env);
   if (!existsSync(base)) return [];
   return readdirSync(base, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && e.name !== 'ca')
+    .filter((e) => e.isDirectory() && e.name !== 'ca' && !e.name.startsWith('.'))
     .map((e) => {
       const state = join(base, e.name);
       const owner = ownerOf(state);
@@ -58,15 +61,26 @@ export function list({ root = ROOT, env = process.env, statuses = projectStatuse
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// The last line: whether the name router runs and what it routes, when it routes anything. Shown
+// with no snowglobe listed too, since a route can outlive its state folder.
+function routerLine() {
+  const routes = readRoutes(routerDir());
+  if (!routes.length) return;
+  const word = { running: 'running', stopped: 'stopped', missing: 'not running' }[routerState().state];
+  console.log(`\nName router on ${ROUTER_ADDRESS}:443: ${word}, routing ${routes.map((r) => `${r.domain} to ${r.globe}`).join(', ')}`);
+}
+
 export function run() {
   const rows = list();
   if (!rows.length) {
     console.log(`No snowglobes in ${stateRoot()}. snowglobe up in a folder with a snowglobe.yml makes one.`);
+    routerLine();
     return 0;
   }
   const head = { name: 'NAME', domain: 'DOMAIN', state: 'STATE', file: 'FILE' };
   const cols = Object.keys(head);
   const width = Object.fromEntries(cols.map((c) => [c, Math.max(head[c].length, ...rows.map((r) => r[c].length))]));
   for (const r of [head, ...rows]) console.log(cols.map((c, i) => (i === cols.length - 1 ? r[c] : r[c].padEnd(width[c]))).join('  '));
+  routerLine();
   return 0;
 }

package/lib/commands/run.mjs

@@ -1,14 +1,10 @@
 // bin/snowglobe.mjs run [--app <name>] [--] <cmd> [args...]
 //
-// run runs a command with the snowglobe around it, for that command's process tree only:
+// run runs a command with the snowglobe's settings:
 //   - it is handed the app's settings, the apps[].env of the snowglobe.yml (lib/commands/env.mjs;
 //     the same as snowglobe env, secrets included, none printed). They win over a value already in
 //     the environment, and one line names the ones they replaced. --app picks the app when the
 //     file lists several;
-//   - the globe's names (its page, each PDS, its services and plc.directory, from the rendered
-//     globe), every handle in https/names (account and up add them) and every app in
-//     https/apps, as <name>.app.<domain>, resolve to SG_BIND, where nginx answers on
-//     443 (lib/hosts.mjs). HTTPS_RUN_EXTRA_NAMES adds names (space-separated);
 //   - Node trusts the globe's CA (NODE_EXTRA_CA_CERTS=<state root>/ca/ca.crt), on top of its own
 //     roots. Miniflare passes the same file on to workerd.
 //
@@ -17,20 +13,18 @@
 // e.g. bin/snowglobe.mjs run node scripts/https-probe.mjs
 //      (cd ../myapp && ../snowglobe/bin/snowglobe.mjs run npm run dev)
 //
-// How: bubblewrap gives the command its own mount namespace with a generated hosts file bound
-// over /etc/hosts. Nothing else changes: same filesystem, same network, same user. Outside,
-// every name resolves as usual. The names are read when the command starts, so a handle or app
-// added later needs a restart of the command. Linux only: a Mac has no bubblewrap, and reaches
-// the globe through snowglobe env instead (the names resolve through public DNS, and the CA is in
-// NODE_EXTRA_CA_CERTS).
+// Nothing maps names. Each snowglobe has a domain of its own under local.snowglobe.at, whose
+// public DNS answers every name with 127.0.0.1, where the name router passes each connection to
+// the snowglobe the name is under (lib/router.mjs). So every name resolves as it does anywhere on
+// the machine, a handle made after the command started included. plc.directory is the real one:
+// an app takes the snowglobe's PLC directory as a setting (${services.plc.url}), as it must on a
+// hosted globe. A domain of your own, outside local.snowglobe.at, has to resolve to 127.0.0.1 the
+// same way.
 
 import { spawn } from 'node:child_process';
-import { accessSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { constants as os } from 'node:os';
-import { delimiter, join } from 'node:path';
-import { readApps } from '../apps.mjs';
-import { ROOT, paths, resolveBind, resolveDomain } from '../env.mjs';
-import { hostsFile, runNames } from '../hosts.mjs';
+import { ROOT, paths, resolveDomain } from '../env.mjs';
 import { session } from '../state.mjs';
 import { appSettings } from './env.mjs';
 
@@ -48,48 +42,25 @@ export const command = {
   },
 };
 
-// The first `name` on PATH that can be run, or null.
-function onPath(name, env) {
-  for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
-    try {
-      accessSync(join(dir, name), constants.X_OK);
-      return join(dir, name);
-    } catch {}
-  }
-  return null;
-}
-
 export const run = ({ cmd, app }) => runUnder(cmd, { settings: appSettings({ app, secrets: true }).vars });
 
 /**
- * Run `cmd` (a word list) under the globe's names with `settings` ([{ name, value }], from
- * appSettings) in its environment; resolves to its exit code. A setting replaces a value of the same
- * name already in `env`, and `log` is told which.
+ * Run `cmd` (a word list) with `settings` ([{ name, value }], from appSettings) and the globe's CA
+ * in its environment; resolves to its exit code. A setting replaces a value of the same name
+ * already in `env`, and `log` is told which.
  */
 export function runUnder(cmd, { root = ROOT, env = process.env, state = session({ env }).state, settings = [], log = (m) => console.error(m) } = {}) {
-  if (process.platform !== 'linux')
-    throw new Error('run needs Linux (bubblewrap) for now; on this system eval "$(snowglobe env)" hands the app the same settings');
   const p = paths(root, state);
   if (!existsSync(p.ca)) throw new Error(`no ${p.ca}; run snowglobe up (or certs) first`);
-  if (!existsSync(p.leafNames)) throw new Error(`no ${p.leafNames}; run snowglobe up first`);
-  const bwrap = onPath('bwrap', env);
-  if (!bwrap) throw new Error('bwrap (bubblewrap) is not installed, or not on PATH');
-  // Refuses a SG_DOMAIN the render is not for, and a SG_BIND that is not loopback.
-  const { domain } = resolveDomain({ root, state, env });
-  const bind = resolveBind({ root, state, env });
-
-  const read = (f) => (existsSync(f) ? readFileSync(f, 'utf8') : '');
-  const names = runNames({ leafNames: read(p.leafNames), handles: read(p.names), apps: readApps(p), domain, extra: env.HTTPS_RUN_EXTRA_NAMES });
-  // Written aside and renamed, so a run already holding the old file is undisturbed.
-  const hosts = join(p.https, 'hosts');
-  writeFileSync(`${hosts}.tmp.${process.pid}`, hostsFile(read('/etc/hosts'), names, bind), { mode: 0o644 });
-  renameSync(`${hosts}.tmp.${process.pid}`, hosts);
+  if (!existsSync(p.globeEnv)) throw new Error(`no ${p.globeEnv}; run snowglobe up first`);
+  // Refuses a SG_DOMAIN the render is not for.
+  resolveDomain({ root, state, env });
 
   // Never the values: a setting may be a login.
   const replaced = settings.filter((x) => !x.auto && env[x.name] !== undefined && env[x.name] !== x.value).map((x) => x.name);
   if (replaced.length) log(`snowglobe run: the snowglobe's settings replaced ${replaced.join(', ')} from the environment`);
 
-  const child = spawn(bwrap, ['--dev-bind', '/', '/', '--ro-bind', hosts, '/etc/hosts', '--die-with-parent', '--', ...cmd], {
+  const child = spawn(cmd[0], cmd.slice(1), {
     stdio: 'inherit',
     env: { ...env, NODE_EXTRA_CA_CERTS: p.ca, ...Object.fromEntries(settings.map((x) => [x.name, x.value])) },
   });

package/lib/commands/up.mjs

@@ -23,7 +23,9 @@
 //      group host built from a folder is built again (Docker's cache keeps that quick)
 //   4. pass 1: up. The base init seeds alice, bob and SG_INVITE_CODE into
 //      data/accounts.env on the PDS with bare handles (else the first), as it does for the
-//      http stacks.
+//      http stacks. Then the name router (lib/router.mjs) sends the globe's domain and every name
+//      under it to the globe's own address, and is started if it is not running. A domain another
+//      running snowglobe is routed at is refused before anything starts.
 //   5. the lexicon authority, lex-authority on the file's lexicons.authority PDS
 //      (LEX_AUTHORITY_* in data/accounts.env), then pass 2: up with
 //      SG_LEXICON_AUTHORITY_DID, which recreates the PDSes with it
@@ -48,8 +50,9 @@ import { dirname, join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { appEnding, appEndingMessage, formatApps, readApps, renderRoutes, writeApps } from '../apps.mjs';
 import { loadGlobe } from '../config.mjs';
-import { ROOT, addName, chooseBind, dc, ensureSecrets, projectHasData, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, paths, renamedDefaultNotice, resolveBind, resolveDomain } from '../env.mjs';
+import { ROOT, ROUTER_ADDRESS, chooseBind, dc, ensureSecrets, projectHasData, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, ownNginxUp, paths, renamedDefaultNotice, resolveBind, resolveDomain, routerRuns } from '../env.mjs';
 import { prebuilt } from '../prebuilt.mjs';
+import { claimDomain, readRoutes, routerDir, syncRouter } from '../router.mjs';
 import { byName, claimState, pointedAt, session } from '../state.mjs';
 import { accountPrefixes, endingClash, mergeRoutes, startedAfterRelay } from '../up.mjs';
 import { account } from './account.mjs';
@@ -126,7 +129,23 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   if (took) log(took);
   // Its own loopback address for every published port, chosen once, so a second snowglobe starts beside this one.
   const bind = await chooseBind({ root, state, project, env });
-  if (bind !== '127.0.0.1') log(`${found.name} publishes its ports on ${bind}`);
+  if (bind !== ROUTER_ADDRESS) log(`${found.name} publishes its ports on ${bind}`);
+  // Routed by name unless it holds the router's own address (SG_BIND, or kept while it runs).
+  const routed = routerRuns({ root, env }) && bind !== ROUTER_ADDRESS;
+  if (routerRuns({ root, env }) && !routed)
+    log(`${found.name} is on ${ROUTER_ADDRESS}, the name router's address, so the router is not started and no other snowglobe is reached by name while it runs. To move it: snowglobe down, then up${env.SG_BIND ? ' without SG_BIND' : ''}`);
+  const rdir = routerDir(env);
+  const taken = (other) =>
+    new Error(
+      `${other.globe} (compose project ${other.project}) is up at ${globe.domain} already, and the name router sends a name to one snowglobe only: take it down first, or leave the domain line out of ${path} so ${found.name} gets its own`,
+    );
+  // Asked before anything starts; asked again under the router's lock when the route is written,
+  // for another up at the same domain in between.
+  const isUp = (other) => ownNginxUp(other, env);
+  if (routed) {
+    const other = readRoutes(rdir).find((r) => r.project !== project && r.domain === globe.domain && isUp(r.project));
+    if (other) throw taken(other);
+  }
   // Checked before the render changes, so a refused file leaves the running globe's render.
   const kept = readApps(p);
   const badEnding = appEnding(kept);
@@ -172,10 +191,12 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
       throw new Error(`docker compose ${args.join(' ')} failed (exit ${res.status}). If a container crash-loops after you updated snowglobe, an image built earlier may be stale (the slingshot image is tagged by its commit, so a changed stack/slingshot/ folder alone does not rebuild it): run snowglobe down (without -v, which keeps your data), remove the image with docker rmi, then run up again`);
     return res;
   };
-  // The nginx template as the running nginx last started with it (stamped after a restart here).
-  const templateFile = join(root, 'stack/https/nginx.conf.template');
+  // The files nginx mounts one by one from the checkout, as the running nginx last started with
+  // them (stamped after a restart here): its template, and the network page and its config. A
+  // mounted file keeps the content it had when nginx started, so a new one needs a restart.
+  const templateFiles = ['stack/https/nginx.conf.template', 'stack/page/snowglobe.conf', 'stack/page/index.html'].map((f) => join(root, f));
   const templateStamp = join(p.https, 'nginx-template.sha256');
-  const templateHash = createHash('sha256').update(existsSync(templateFile) ? readFileSync(templateFile) : '').digest('hex');
+  const templateHash = templateFiles.reduce((h, f) => h.update(existsSync(f) ? readFileSync(f) : '').update('\0'), createHash('sha256')).digest('hex');
   const templateChanged = !existsSync(templateStamp) || readFileSync(templateStamp, 'utf8').trim() !== templateHash;
   const put = (file, text) => {
     writeFileSync(`${file}.tmp`, `${text}\n`);
@@ -231,8 +252,16 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   composeEnv.SG_LEXICON_AUTHORITY_DID = envGet('LEX_AUTHORITY_DID', p.accounts);
   log(`Pass 1: up (project ${project})`);
   await upStack();
-  // A running nginx keeps the certificate files it started with, and the template it was started
-  // with (the image fills it in at start); new ones need a restart, whether or not the leaf was
+  if (routed) {
+    const change = () => {
+      const other = claimDomain(rdir, { project, domain, bind, globe: found.name }, isUp, log);
+      if (other) throw taken(other);
+    };
+    await syncRouter({ dir: rdir, env, log, change });
+    log(`The name router sends ${domain} and every name under it to ${bind}`);
+  }
+  // A running nginx keeps the certificate files it started with, and the template and page files
+  // it was started with (the image fills the template in at start); new ones need a restart, whether or not the leaf was
   // reissued. The globe's servers may have changed with the render, so a running nginx reloads them.
   if (newCerts || templateChanged) {
     compose(['restart', 'nginx'], { stdio: 'ignore' });
@@ -273,12 +302,6 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
     }
   }
 
-  // init's accounts are on the seed PDS; run maps their handles.
-  for (const prefix of ['ALICE', 'BOB']) {
-    const handle = envGet(`${prefix}_HANDLE`, p.accounts);
-    if (handle) addName(handle, { root, state });
-  }
-
   // What the file seeds. A rerun finds each account by its kept login.
   for (const a of seedAccounts) await account({ ...a, file: p.accounts, root, state, env, log });
   if (globe.lexicons.publish) await lexicons({ dir: resolve(dirname(path), globe.lexicons.publish), root, state, env, log });

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}`)),

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

@@ -156,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],
@@ -542,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmeet/snowglobe",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Standalone, testable ATProto development network for local development and CI",
   "type": "module",
   "bin": {

package/snowglobe.default.yml

@@ -7,14 +7,13 @@
 # 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. The relay crawls it too, so
+    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,7 +27,7 @@ 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 with Jetstream, which reads it, or more than one PDS
 
@@ -37,7 +36,7 @@ services:                      # these are the defaults, each true or false
 #   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/https/app-names.cjs

@@ -1,13 +1,14 @@
 // Preloaded into each PDS (NODE_OPTIONS=--require, in the globe bin/snowglobe.mjs render writes), so a PDS can
-// reach an app at https://<name>.app.<domain>: it fetches a confidential client's
-// metadata and keys from there. Docker's DNS has no wildcard names, so every such name is
+// reach an OAuth client under the globe's domain, an app at https://<name>.app.<domain> or
+// PDSls at https://pdsls.<domain>: it fetches the client's metadata and keys from there.
+// Docker's DNS has no wildcard names, so every such name is
 // looked up as nginx instead, which routes it by name (stack/https/nginx.conf.template). Only
 // the address lookup changes: the request still carries the app's name, and TLS still
 // checks the certificate for it against the snowglobe CA. Every other name resolves as usual.
 //
-// SG_RESOLVE_DOMAIN sets the domain whose names, itself included, go to nginx. Each PDS sets it
-// to app.<domain>, where the apps are; a group host sets it to the globe's domain: it resolves its members' handles, which Docker's DNS does
-// not know.
+// SG_RESOLVE_DOMAIN sets the domain whose names, itself included, go to nginx. Each PDS and
+// each group host sets it to the globe's domain; a group host also resolves its members'
+// handles there, which Docker's DNS does not know.
 'use strict';
 const dns = require('dns');
 

package/stack/page/snowglobe.conf

@@ -37,7 +37,7 @@ location = /health/relay     { proxy_pass $relay/xrpc/_health; }
 location = /health/jetstream { proxy_pass $jetstream/; }
 location = /health/slingshot { proxy_pass $slingshot/; }
 location = /health/sync      { proxy_pass $tap/health; }
-location = /health/mail      { proxy_pass $maildev/healthz; }
+location = /health/mail      { proxy_pass $maildev/api/healthz; }
 location = /health/pdsls     { proxy_pass $pdsls/_health; }
 
 # Health and accounts for each account server (/health/<name>, /people/<name>/listRepos and

package/lib/hosts.mjs

@@ -1,36 +0,0 @@
-// The names snowglobe run maps to nginx, and the hosts file it binds over /etc/hosts. Pure:
-// lib/commands/run.mjs reads the files and runs the command.
-
-const NAME_RE = /^[A-Za-z0-9.-]+$/;
-const words = (text) => (text ?? '').split(/\s+/).filter(Boolean);
-
-/**
- * Every name a process under run should reach nginx at: the rendered globe's leaf names that are
- * not wildcards (its page, each PDS, its services, plc.directory), each handle in `handles`
- * (data/https/names), <name>.app.<domain> for each app in `apps`, and `extra`
- * (HTTPS_RUN_EXTRA_NAMES, space-separated). In that order, each once.
- */
-export function runNames({ leafNames, handles, apps, domain, extra }) {
-  return [
-    ...new Set([
-      ...words(leafNames).filter((n) => !n.startsWith('*')),
-      // One per line; a line that is not a name is skipped whole.
-      ...(handles ?? '').split('\n').filter((n) => NAME_RE.test(n)),
-      ...apps.map((a) => `${a.name}.app.${domain}`),
-      ...words(extra),
-    ]),
-  ];
-}
-
-/**
- * The hosts file: `etcHosts` (the machine's) without any line naming one of `names`, then each
- * name on `bind`.
- */
-export function hostsFile(etcHosts, names, bind) {
-  const ours = new Set(names);
-  const kept = etcHosts
-    .split('\n')
-    .filter((l, i, all) => i < all.length - 1 || l !== '')
-    .filter((l) => !l.trim().split(/\s+/).slice(1).some((n) => ours.has(n)));
-  return [...kept, '# snowglobe (bin/snowglobe.mjs run)', ...names.map((n) => `${bind} ${n}`), ''].join('\n');
-}