chadtmiller.com/hud
A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts
place.hud.hudkit 0.4.0 Latest 5 packages
0
0
// 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;
}
}