A local-first multi-agent app development platform, built on PenguinHarness
/**
* The same-origin server proxy: `/server/<machineId>/api/…` on THIS server forwards to that
* machine's server through the forward held to it.
*
* Addressed by the machine's OWN id, not the ssh alias it was reached through: an alias is a
* line in one config file, and renaming it would change every URL below. Only `/api/` paths
* are forwarded — the frontend stays local and re-points its API calls by prefix.
*
* ONE IDENTITY. The caller is this server's admin, and this server's admin is that
* machine's admin: the ssh access that installed the program there is what authorizes it,
* and the session presented to the machine is one this server mints over that access
* (remote-token.ts). The browser's own cookies never travel, and the machine's never come
* back — so this mounts INSIDE this server's auth middleware, for admins.
*/
import http from "node:http";
import { Readable } from "node:stream";
/** Path prefix of the proxy: `/server/<id>/api/…`. */
export const SERVER_PROXY_PREFIX = "/server/";
/** A parsed proxy path: which machine, and the remote-side path to request. */
interface ProxyPath {
machineId: string;
/** The path forwarded to the remote, always starting `/api/`. */
remotePath: string;
}
/** Parses `/server/<machineId>/api/…` (query preserved by the caller); null for anything else. */
export function parseProxyPath(pathname: string): ProxyPath | null {
if (!pathname.startsWith(SERVER_PROXY_PREFIX)) return null;
const rest = pathname.slice(SERVER_PROXY_PREFIX.length);
const slash = rest.indexOf("/");
if (slash <= 0) return null;
const machineId = decodeURIComponent(rest.slice(0, slash));
const remotePath = rest.slice(slash);
if (!remotePath.startsWith("/api/") && remotePath !== "/api") return null;
return { machineId, remotePath };
}
/** An absolute-path Location from the remote, re-rooted under the proxy prefix. */
export function rewriteLocation(header: string, machineId: string): string {
return header.startsWith("/")
? `${SERVER_PROXY_PREFIX}${encodeURIComponent(machineId)}${header}`
: header;
}
/**
* Hop-by-hop and identity headers that must not cross.
*
* `authorization` among them: the proxy speaks to the machine as ITS admin, with a session
* this server mints over ssh, and a caller's own bearer is a credential for THIS server. Sent
* on, it would both hand that credential to another machine and outrank the cookie just
* minted, since the remote's auth reads a bearer first.
*/
const DROP_REQUEST_HEADERS = new Set([
"host",
"cookie",
"authorization",
"connection",
"keep-alive",
"upgrade",
]);
const DROP_RESPONSE_HEADERS = new Set(["set-cookie", "location", "connection", "keep-alive"]);
/**
* How long a forwarded read may wait for the machine's first answer (its headers), the dial
* included. Under the browser's own 20 s (web api/socket.ts), so the browser hears this answer
* rather than giving up first; over the SOCKS handshake deadline (transport/socks.ts), so a
* stalled session is reported in that layer's words, not this one's.
*/
export const FORWARD_ANSWER_TIMEOUT_MS = 15_000;
/**
* Forwards one request to the machine's server and streams the answer back — both
* directions are pipes, so SSE and long downloads flow as they arrive. The socket is the
* agent's: a dial through the machine's session (transport/connection.ts). node:http rather
* than fetch: the Host header must be the canonical app host (`localhost:<port>`), and the
* socket is not one fetch could be handed.
*
* A READ the machine does not start answering within `answerTimeoutMs` — its headers, dial
* included — is answered 504 here: a channel the machine accepted and never answers would
* otherwise hold the request, and every retry the browser makes of it, for good. Only reads:
* a write may rightly take long, and cutting one would have the browser repeat its effect.
*/
function proxyThroughSession(
request: Request,
path: ProxyPath,
agent: http.Agent,
port: number,
cookie: string,
answerTimeoutMs: number,
report?: ProxyReport,
): Promise<Response> {
return new Promise((resolve) => {
const url = new URL(request.url);
const headers: Record<string, string> = {};
request.headers.forEach((value, name) => {
if (!DROP_REQUEST_HEADERS.has(name.toLowerCase())) headers[name] = value;
});
headers["host"] = `localhost:${port}`;
headers["cookie"] = cookie;
const upstream = http.request(
{
agent,
host: "127.0.0.1",
port,
path: `${path.remotePath}${url.search}`,
method: request.method,
headers,
},
(res) => {
clearTimeout(answering);
report?.(path.machineId, { ok: true });
const out = new Headers();
for (const [name, value] of Object.entries(res.headers)) {
if (value === undefined || DROP_RESPONSE_HEADERS.has(name.toLowerCase())) continue;
out.set(name, Array.isArray(value) ? value.join(", ") : value);
}
if (res.headers.location !== undefined) {
out.set("location", rewriteLocation(res.headers.location, path.machineId));
}
resolve(
new Response(
res.statusCode === 204 || res.statusCode === 304
? null
: (Readable.toWeb(res) as ReadableStream),
{ status: res.statusCode ?? 502, headers: out },
),
);
},
);
// Reads only: see the doc above. A write waits for the machine however long it takes.
const reads = request.method === "GET" || request.method === "HEAD";
let timedOut = false;
const answering = !reads
? undefined
: setTimeout(() => {
timedOut = true;
const detail = `no answer to ${request.method} ${path.remotePath} in ${answerTimeoutMs} ms`;
report?.(path.machineId, { ok: false, detail });
upstream.destroy();
resolve(
Response.json(
{
error: { code: "machine_not_answering", message: `${path.machineId}: ${detail}.` },
},
{ status: 504 },
),
);
}, answerTimeoutMs);
answering?.unref?.();
upstream.on("error", (err) => {
clearTimeout(answering);
if (timedOut) return; // answered above; this is the teardown
report?.(path.machineId, { ok: false, detail: err.message });
resolve(
Response.json(
{
error: {
code: "server_unreachable",
message: `The connection to ${path.machineId} did not answer: ${err.message}`,
},
},
{ status: 502 },
),
);
});
if (request.body !== null) {
Readable.fromWeb(request.body as import("node:stream/web").ReadableStream).pipe(upstream);
} else {
upstream.end();
}
});
}
/**
* The seam handler: `/server/<id>/api/…` → that machine, or a clear answer when there is
* nothing to forward to. `resolve` is the machines service's lookup: a dial through the
* session, the port over there and a session cookie, or null when it is not connected.
*/
/**
* Told what each forwarded request learned: the machine's API answered, or the forward had
* nowhere to deliver. The machines service stamps it into the list's `api` fact — passive
* measurement, riding traffic that flows anyway (api/types.ts on MachineInfo.api).
*/
export type ProxyReport = (
machineId: string,
outcome: { ok: true } | { ok: false; detail: string },
) => void;
export function machinesProxy(
resolve: (
machineId: string,
) => Promise<{ agent: http.Agent; port: number; cookie: string } | null>,
report?: ProxyReport,
/** Test hook: how long a forwarded read may wait for its answer (FORWARD_ANSWER_TIMEOUT_MS). */
options: { answerTimeoutMs?: number } = {},
): (request: Request) => Promise<Response | null> {
const answerTimeoutMs = options.answerTimeoutMs ?? FORWARD_ANSWER_TIMEOUT_MS;
return async (request) => {
const path = parseProxyPath(new URL(request.url).pathname);
if (path === null) return null;
const target = await resolve(path.machineId);
if (target === null) {
return Response.json(
{
error: {
code: "not_connected",
message: `No live forward to ${path.machineId}; connect to it first.`,
},
},
{ status: 503 },
);
}
return proxyThroughSession(
request,
path,
target.agent,
target.port,
target.cookie,
answerTimeoutMs,
report,
);
};
}