// The world the e2e flows run in: the reference PDS and PLC with alice, // bob and carol (harness/pds.mjs), alice's profile and posts written to // her repository, and `target/debug/hud serve` over it with sign-in on, // behind the https front (harness/tls-proxy.mjs) at the harness's hostname // for HUD, which the PDS fetches HUD's client metadata from and sends the // browser back to. Everything on free ports (HUD's from 8791 up), its data // in a directory of its own; HUD's log in target/e2e/hud.log. Its image // CDN (`imageCdn`) answers nothing, at a port nothing listens on, so every // public image falls back to the blob proxy (harness/e2e/images.spec.mjs). // With HUD_DEV_ENV naming the spaces alpha (harness/pds.mjs), the PDS // serves spaces and HUD keeps canvases in them (HUD_SPACES=on); no relay // lists everyone's themes (HUD_RELAY empty): an account's alone. HUD is // served with the operator's apps the harnesses use (HUD_APPS, // harness/apps.mjs). // // const world = await start(); ... world.stop(); import { spawn } from 'node:child_process'; import { createServer as createHttpServer } from 'node:http'; import { createWriteStream, mkdirSync, mkdtempSync, rmSync } from 'node:fs'; import { createServer } from 'node:net'; import { tmpdir } from 'node:os'; import { dirname, join, resolve } from 'node:path'; import { createInterface } from 'node:readline'; import { fileURLToPath } from 'node:url'; import { deflateSync } from 'node:zlib'; import { apps } from '../apps.mjs'; export const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); /// The first line `child` prints, or its failure. function firstLine(child, what) { return new Promise((done, fail) => { const lines = createInterface({ input: child.stdout }); lines.once('line', (line) => { lines.close(); done(line); }); child.once('exit', (code) => fail(new Error(`${what} exited (${code}) before it was ready`))); }); } /// A port nothing listens on, from `from` up: free on IPv6's any address /// as on IPv4's loopback, as a server elsewhere on `::` takes loopback's /// connections too, and would answer for HUD. On a host with no IPv6 /// nothing can listen on `::`, so a port is free there. async function freePort(from) { const free = (port, host) => new Promise((done) => { const server = createServer(); server.once('error', (e) => done(e.code === 'EAFNOSUPPORT')); server.listen(port, host, () => server.close(() => done(true))); }); for (let port = from; port < from + 100; port++) { if ((await free(port, '127.0.0.1')) && (await free(port, '::'))) return port; } throw new Error(`no free port from ${from}`); } /// Until `url` answers 200, or `child` exits. async function healthy(url, child, what) { let exited = null; child.once('exit', (code) => (exited = code)); for (let i = 0; i < 300; i++) { if (exited !== null) throw new Error(`${what} exited (${exited}); see target/e2e/hud.log`); const ok = await fetch(url).then( (r) => r.ok, () => false, ); if (ok) return; await new Promise((r) => setTimeout(r, 100)); } throw new Error(`${what} did not answer ${url}`); } /// A session of `account` on `pds`, by its password, as an app writes. async function session(pds, account) { const res = await fetch(`${pds}/xrpc/com.atproto.server.createSession`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ identifier: account.did, password: account.password }), }); if (!res.ok) throw new Error(`createSession ${account.handle}: ${await res.text()}`); return (await res.json()).accessJwt; } /// Writes a record of `collection` to `account`'s repository: its at:// URI. export async function createRecord(pds, account, collection, record, rkey) { const jwt = await session(pds, account); const res = await fetch(`${pds}/xrpc/com.atproto.repo.createRecord`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${jwt}` }, body: JSON.stringify({ repo: account.did, collection, record, ...(rkey ? { rkey } : {}) }), }); if (!res.ok) throw new Error(`createRecord ${collection}: ${await res.text()}`); return (await res.json()).uri; } /// Uploads `bytes` of `mimeType` as `account`'s blob: its blob ref. async function uploadBlob(pds, account, bytes, mimeType) { const jwt = await session(pds, account); const res = await fetch(`${pds}/xrpc/com.atproto.repo.uploadBlob`, { method: 'POST', headers: { 'content-type': mimeType, authorization: `Bearer ${jwt}` }, body: bytes, }); if (!res.ok) throw new Error(`uploadBlob: ${await res.text()}`); return (await res.json()).blob; } /// `seconds` of a quiet tone as a WAV (8 kHz, 8-bit, mono): audio any /// browser plays, small enough to upload. function wav(seconds) { const rate = 8000; const n = rate * seconds; const out = Buffer.alloc(44 + n); out.write('RIFF', 0); out.writeUInt32LE(36 + n, 4); out.write('WAVEfmt ', 8); out.writeUInt32LE(16, 16); out.writeUInt16LE(1, 20); out.writeUInt16LE(1, 22); out.writeUInt32LE(rate, 24); out.writeUInt32LE(rate, 28); out.writeUInt16LE(1, 32); out.writeUInt16LE(8, 34); out.write('data', 36); out.writeUInt32LE(n, 40); for (let i = 0; i < n; i++) out[44 + i] = 128 + Math.round(8 * Math.sin((2 * Math.PI * 440 * i) / rate)); return out; } /// A `size`×`size` PNG of one colour (`rgb`): a picture any browser draws, /// small enough to upload. function png(size, rgb) { const crc = (bytes) => { let c = ~0; for (const byte of bytes) { c ^= byte; for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1)); } return ~c >>> 0; }; const chunk = (type, data) => { const out = Buffer.alloc(12 + data.length); out.writeUInt32BE(data.length, 0); out.write(type, 4, 'latin1'); data.copy(out, 8); out.writeUInt32BE(crc(out.subarray(4, 8 + data.length)), 8 + data.length); return out; }; const header = Buffer.alloc(13); header.writeUInt32BE(size, 0); header.writeUInt32BE(size, 4); header[8] = 8; // bits per sample header[9] = 2; // RGB const row = Buffer.from([0, ...Array.from({ length: size }, () => rgb).flat()]); const pixels = deflateSync(Buffer.concat(Array.from({ length: size }, () => row))); return Buffer.concat([Buffer.from('\x89PNG\r\n\x1a\n', 'latin1'), chunk('IHDR', header), chunk('IDAT', pixels), chunk('IEND', Buffer.alloc(0))]); } /// Carol's profile, with an avatar: a public image, served by the image CDN, /// or failing that the blob proxy (harness/e2e/images.spec.mjs). async function seedAvatar(net) { const carol = net.accounts[2]; const avatar = await uploadBlob(net.pds, carol, png(64, [200, 80, 40]), 'image/png'); await createRecord(net.pds, carol, 'app.bsky.actor.profile', { $type: 'app.bsky.actor.profile', displayName: 'Carol', avatar }, 'self'); return avatar.ref.$link; } /// Carol's plyr.fm tracks, each with its audio uploaded to her PDS, and /// her likes of them: a playlist HUD plays through its blob proxy /// (harness/e2e/player.spec.mjs). async function seedTracks(net) { const carol = net.accounts[2]; const audioBlob = await uploadBlob(net.pds, carol, wav(120), 'audio/wav'); const jwt = await session(net.pds, carol); for (const title of ['Track two', 'Track one']) { const uri = await createRecord(net.pds, carol, 'fm.plyr.track', { $type: 'fm.plyr.track', title, artist: 'carol', fileType: 'wav', duration: 120, audioBlob, createdAt: new Date().toISOString(), }); const { cid } = await fetch( `${net.pds}/xrpc/com.atproto.repo.getRecord?repo=${carol.did}&collection=fm.plyr.track&rkey=${uri.split('/').pop()}`, { headers: { authorization: `Bearer ${jwt}` } }, ).then((r) => r.json()); await createRecord(net.pds, carol, 'fm.plyr.like', { $type: 'fm.plyr.like', subject: { uri, cid }, createdAt: new Date().toISOString(), }); } } /// What the flows read: alice's profile, and two posts of hers, the second /// a reply to the first, so a post opens a thread. (Carol's tracks are /// `seedTracks`'.) async function seed(net) { const [alice] = net.accounts; const now = () => new Date().toISOString(); await createRecord( net.pds, alice, 'app.bsky.actor.profile', { $type: 'app.bsky.actor.profile', displayName: 'Alice', description: 'Testing HUD' }, 'self', ); const first = await createRecord(net.pds, alice, 'app.bsky.feed.post', { $type: 'app.bsky.feed.post', text: 'Hello from the harness', createdAt: now(), }); const jwt = await session(net.pds, alice); const { cid } = await fetch( `${net.pds}/xrpc/com.atproto.repo.getRecord?repo=${alice.did}&collection=app.bsky.feed.post&rkey=${first.split('/').pop()}`, { headers: { authorization: `Bearer ${jwt}` } }, ).then((r) => r.json()); const ref = { uri: first, cid }; const reply = await createRecord(net.pds, alice, 'app.bsky.feed.post', { $type: 'app.bsky.feed.post', text: 'A reply in the thread', reply: { root: ref, parent: ref }, createdAt: now(), }); return { posts: [first, reply] }; } /// A PLC directory in front of `local`: what it knows, else what /// plc.directory does, so HUD resolves the world's accounts and public /// ones alike (harness/e2e/memory.spec.mjs reads public data). Its URL, /// and its server, to close. async function plcBoth(local) { const server = createHttpServer(async (req, res) => { for (const base of [local, 'https://plc.directory']) { const got = await fetch(`${base}${req.url}`).catch(() => null); if (!got || (got.status === 404 && base === local)) continue; res.writeHead(got.status, { 'content-type': got.headers.get('content-type') ?? 'application/json' }); res.end(Buffer.from(await got.arrayBuffer())); return; } res.writeHead(404).end(); }); await new Promise((done) => server.listen(0, '127.0.0.1', done)); return { url: `http://127.0.0.1:${server.address().port}`, server }; } /// The world, started: { base, hudUrl, hudPid, host, cert, pds, plc, /// spaces, accounts, posts, dir, stop }. `base` is HUD as the browser and the PDS /// reach it, at `host` with `cert`; `hudUrl` as the harness does, over /// plain http on loopback. Options: `binary`, the `hud` run /// (target/debug/hud); `env`, more of its environment; `publicPlc`, HUD /// resolving DIDs the world does not know at plc.directory. export async function start({ binary = 'target/debug/hud', env = {}, publicPlc = false } = {}) { const out = join(root, 'target/e2e'); mkdirSync(out, { recursive: true }); const pdsChild = spawn(process.execPath, [join(root, 'harness/pds.mjs')], { cwd: join(root, 'harness'), stdio: ['pipe', 'pipe', 'inherit'], }); const children = [pdsChild]; const servers = []; const dir = mkdtempSync(join(tmpdir(), 'hud-e2e-')); const stop = () => { for (const child of children.reverse()) { child.stdin?.end(); child.kill('SIGTERM'); } for (const server of servers) server.close(); rmSync(dir, { recursive: true, force: true }); }; try { const net = JSON.parse(await firstLine(pdsChild, 'harness/pds.mjs')); const { posts } = await seed(net); await seedTracks(net); const avatar = await seedAvatar(net); let plc = net.plc; if (publicPlc) { const both = await plcBoth(net.plc); servers.push(both.server); plc = both.url; } const port = await freePort(8791); const proxy = spawn( process.execPath, [join(root, 'harness/tls-proxy.mjs'), net.hud.cert, net.hud.key, String(port)], { stdio: ['pipe', 'pipe', 'inherit'] }, ); children.push(proxy); const front = (await firstLine(proxy, 'harness/tls-proxy.mjs')).trim(); const base = `https://${net.hud.host}:${front}`; // An image CDN nothing answers at: every public image falls back. const imageCdn = `https://${net.hud.host}:${await freePort(port + 100)}/img`; const log = createWriteStream(join(out, 'hud.log')); const hud = spawn(resolve(root, binary), ['serve'], { env: { ...process.env, HUD_PORT: String(port), HUD_BIND: '127.0.0.1', HUD_PUBLIC_URL: base, HUD_DATA_DIR: join(dir, 'data'), HUD_CACHE_DIR: join(dir, 'cache'), HUD_PLC_URL: plc, // `.test` handles resolve nowhere but at the PDS that made them. HUD_HANDLE_RESOLVER: net.pds, // Create one makes its account there too. HUD_SIGN_UP_PDS: net.pds, // The PDS and PLC are on loopback, over http. HUD_ALLOW_PRIVATE: '1', HUD_BACKLINKS: 'none', HUD_APPS: apps, HUD_FAVICONS: '', HUD_IMAGE_CDN: imageCdn, HUD_RELAY: '', HUD_SPACES: net.spaces ? 'on' : 'off', RUST_LOG: process.env.RUST_LOG ?? 'info', ...env, }, stdio: ['ignore', 'pipe', 'pipe'], }); children.push(hud); hud.stdout.pipe(log); hud.stderr.pipe(log); const hudUrl = `http://127.0.0.1:${port}`; await healthy(`${hudUrl}/_health`, hud, 'hud serve'); return { hudPid: hud.pid, base, hudUrl, host: net.hud.host, cert: net.hud.cert, ca: net.hud.ca, pds: net.pds, plc: net.plc, spaces: net.spaces, accounts: net.accounts, lexicons: net.lexicons, posts, avatar, imageCdn, dir, stop, }; } catch (e) { stop(); throw e; } }