~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
352 lines · 12.8 KB Raw History
// 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;
	}
}