rea-agents 0.3.0 → 0.4.0

package/dist/application/LinuxHopper.js

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execFileAsync = promisify(execFile);
+const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
+const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
+const MAX_PACKAGE_BYTES = 100_000_000;
+/** Parse an os-release document without executing its shell syntax. */
+export const parseLinuxDistribution = (text) => {
+    const fields = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^([A-Z_]+)=(.*)$/u.exec(line.trim());
+        if (match === null)
+            continue;
+        const key = match[1];
+        const encoded = match[2];
+        if (key === undefined || encoded === undefined)
+            continue;
+        const value = encoded.startsWith('"') && encoded.endsWith('"')
+            ? encoded.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\")
+            : encoded;
+        fields.set(key, value);
+    }
+    const id = (fields.get("ID") ?? "unknown").toLowerCase();
+    const versionId = fields.get("VERSION_ID");
+    const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
+    const supported = id === "arch" ||
+        (id === "ubuntu" && versionAtLeast(versionId, 24)) ||
+        (id === "fedora" && versionAtLeast(versionId, 41));
+    return {
+        id,
+        ...(versionId === undefined ? {} : { versionId }),
+        packageFamily,
+        supported,
+    };
+};
+/** Read and classify the current Linux distribution. */
+export const readLinuxDistribution = async () => {
+    try {
+        return parseLinuxDistribution(await readFile("/etc/os-release", "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Download, verify, install, and read back the official Hopper Linux package. */
+export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(), options = {}) => {
+    if (options.signal?.aborted === true)
+        return { status: "failed", reason: "cancelled" };
+    const distribution = await host.distribution();
+    if (distribution?.supported !== true ||
+        distribution.packageFamily === undefined)
+        return { status: "failed", reason: "unsupported_host" };
+    let temporary;
+    try {
+        const metadataDownload = await host.download(RELEASES_URL, options);
+        if (!metadataDownload.ok)
+            return { status: "failed", reason: "release_metadata" };
+        const releases = parseReleases(metadataDownload.bytes);
+        if (releases === undefined)
+            return { status: "failed", reason: "release_metadata" };
+        const release = releases[releaseKey(distribution.packageFamily)];
+        if (!release.filename.startsWith(DOWNLOAD_PREFIX))
+            return { status: "failed", reason: "release_metadata" };
+        const archiveDownload = await host.download(release.filename, options);
+        if (!archiveDownload.ok)
+            return { status: "failed", reason: "download" };
+        if (!packageIntegrityMatches(archiveDownload.bytes, release))
+            return { status: "failed", reason: "integrity" };
+        temporary = await host.createTemporaryDirectory();
+        const archive = join(temporary, `hopper.${distribution.packageFamily}`);
+        await host.writeArchive(archive, archiveDownload.bytes);
+        if (!(await host.installPackage(distribution.packageFamily, archive)))
+            return { status: "failed", reason: "authorization_or_package_manager" };
+        const launcherPath = "/opt/hopper/bin/Hopper";
+        if (!(await host.launcherReady(launcherPath)))
+            return { status: "failed", reason: "launcher_missing" };
+        return { status: "installed", launcherPath };
+    }
+    catch (cause) {
+        if (isAbortCause(cause))
+            return { status: "failed", reason: "cancelled" };
+        return { status: "failed", reason: "download" };
+    }
+    finally {
+        if (temporary !== undefined)
+            await host.cleanup(temporary);
+    }
+};
+/** Canonical launcher path for a legacy user-local Linux Hopper installation. */
+export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/hopper/bin/Hopper");
+const systemLinuxHopperInstallHost = () => ({
+    distribution: readLinuxDistribution,
+    async download(url, options) {
+        const response = await fetch(url, {
+            headers: { accept: "application/json", "user-agent": "rea-installer" },
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        return {
+            ok: response.ok,
+            bytes: new Uint8Array(await response.arrayBuffer()),
+        };
+    },
+    createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
+    writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
+    installPackage: installSystemPackage,
+    async launcherReady(path) {
+        try {
+            await access(path);
+            const linked = await execFileAsync("ldd", [path]);
+            return linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`);
+        }
+        catch {
+            return false;
+        }
+    },
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
+});
+/** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
+export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
+const installSystemPackage = async (family, archive) => {
+    try {
+        const command = linuxPackageManagerCommand(family, archive, process.getuid?.() === 0);
+        await execFileAsync(command.executable, command.args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Select the native package manager and authorization boundary without shell evaluation. */
+export const linuxPackageManagerCommand = (family, archive, isRoot) => {
+    const command = family === "deb"
+        ? ["apt-get", "install", "-y", archive]
+        : family === "rpm"
+            ? ["dnf", "install", "-y", archive]
+            : ["pacman", "-U", "--noconfirm", archive];
+    const executable = isRoot ? command[0] : "pkexec";
+    if (executable === undefined)
+        throw new Error("package command is empty");
+    return { executable, args: isRoot ? command.slice(1) : command };
+};
+const parseReleases = (bytes) => {
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        const result = releasesSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
+    bytes.byteLength <= MAX_PACKAGE_BYTES &&
+    createHash("sha1").update(bytes).digest("hex") === release.file_hash;
+const packageFamilyFor = (id, idLike) => {
+    const identities = new Set([
+        id,
+        ...(idLike?.toLowerCase().split(/\s+/u) ?? []),
+    ]);
+    if (identities.has("ubuntu") || identities.has("debian"))
+        return "deb";
+    if (identities.has("fedora") || identities.has("rhel"))
+        return "rpm";
+    if (identities.has("arch"))
+        return "arch";
+    return undefined;
+};
+const versionAtLeast = (version, minimum) => version !== undefined &&
+    Number.parseInt(version.split(".")[0] ?? "0", 10) >= minimum;
+const releaseKey = (family) => family === "deb" ? "Ubuntu / Mint" : family === "rpm" ? "Fedora" : "Arch";
+const isAbortCause = (cause) => cause instanceof Error && cause.name === "AbortError";
+const releaseSchema = z.object({
+    filename: z.string().url(),
+    file_length: z.string().regex(/^\d+$/u),
+    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
+});
+const releasesSchema = z.object({
+    "Ubuntu / Mint": releaseSchema,
+    Fedora: releaseSchema,
+    Arch: releaseSchema,
+});

package/dist/application/LoopbackReplay.js

@@ -1,34 +1,171 @@
-import { createServer } from "node:http";
+import { createServer, } from "node:http";
 import { WebSocketServer } from "ws";
-const closeServer = async (server) => new Promise((resolveClose, rejectClose) => {
-    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
-});
-/** Start bounded HTTP and WebSocket replay endpoints bound only to IPv4 loopback. */
-export const startLoopbackReplay = async (scenario) => {
-    const events = [];
-    const record = (event) => {
-        if (events.length < 10_000)
-            events.push({ sequence: events.length, ...event });
-    };
-    const server = createServer((request, response) => {
+class ReplayRecorder {
+    scenario;
+    events = [];
+    started = Date.now();
+    truncated = false;
+    constructor(scenario) {
+        this.scenario = scenario;
+    }
+    atMs() {
+        return (Math.floor((Date.now() - this.started) /
+            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
+    }
+    record(event) {
+        if (this.events.length < this.scenario.limits.protocol_events)
+            this.events.push({ sequence: this.events.length, ...event });
+        else
+            this.truncated = true;
+    }
+}
+const readRequestBody = async (request, limit) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += value.byteLength;
+        if (bytes > limit)
+            return undefined;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+};
+const createHttpHandler = (recorder) => {
+    const calls = new Map();
+    return async (request, response) => {
         const method = request.method ?? "GET";
         const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
-        record({ protocol: "http", direction: "request", method, path, data: "" });
-        const route = scenario.replay.http.find((candidate) => candidate.method === method && candidate.path === path);
-        response.statusCode = route?.status ?? 404;
-        const body = route?.body ?? "";
-        response.end(body);
-        record({
+        const body = await readRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
+        if (body === undefined) {
+            recorder.truncated = true;
+            response.statusCode = 413;
+            response.end();
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "http",
+                direction: "request",
+                method,
+                path,
+                data: "<body-over-limit>",
+                outcome: "unmatched",
+            });
+            return;
+        }
+        const index = recorder.scenario.replay.http.findIndex((route) => {
+            if (route.method !== method || route.path !== path)
+                return false;
+            if (route.request_body !== undefined && route.request_body !== body)
+                return false;
+            return Object.entries(route.request_headers).every(([name, value]) => request.headers[name.toLowerCase()] === value);
+        });
+        const route = recorder.scenario.replay.http[index];
+        const used = index < 0 ? 0 : (calls.get(index) ?? 0);
+        const outcome = route === undefined
+            ? "unmatched"
+            : used >= route.max_calls
+                ? "script_exhausted"
+                : "matched";
+        recorder.record({
+            at_ms: recorder.atMs(),
+            protocol: "http",
+            direction: "request",
+            method,
+            path,
+            data: body.length === 0 ? "" : "<redacted-request-body>",
+            outcome,
+        });
+        if (route === undefined || outcome === "script_exhausted") {
+            response.statusCode = route === undefined ? 404 : 409;
+            response.end();
+            return;
+        }
+        calls.set(index, used + 1);
+        if (route.delay_ms > 0)
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, route.delay_ms));
+        if (route.disconnect) {
+            response.destroy();
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "http",
+                direction: "response",
+                method,
+                path,
+                data: "",
+                outcome: "disconnected",
+            });
+            return;
+        }
+        response.statusCode = route.status;
+        for (const [name, value] of Object.entries(route.response_headers))
+            response.setHeader(name, value);
+        response.end(route.body);
+        recorder.record({
+            at_ms: recorder.atMs(),
             protocol: "http",
             direction: "response",
             method,
             path,
-            data: body,
+            data: route.body,
+            outcome: "matched",
         });
-    });
+    };
+};
+const sendWebSocketScript = async (client, connection, recorder) => {
+    const scripts = recorder.scenario.replay.websocket_connections;
+    const script = scripts[connection - 1];
+    if (scripts.length > 0 && script === undefined) {
+        recorder.record({
+            at_ms: recorder.atMs(),
+            protocol: "websocket",
+            direction: "sent",
+            method: null,
+            path: "/ws",
+            data: "",
+            outcome: "script_exhausted",
+        });
+        client.terminate();
+        return;
+    }
+    const messages = script?.messages ??
+        recorder.scenario.replay.websocket_messages.map((data) => ({
+            data,
+            delay_ms: 0,
+        }));
+    for (const message of messages) {
+        if (message.delay_ms > 0)
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, message.delay_ms));
+        if (client.readyState !== 1)
+            return;
+        client.send(message.data);
+        recorder.record({
+            at_ms: recorder.atMs(),
+            protocol: "websocket",
+            direction: "sent",
+            method: null,
+            path: "/ws",
+            data: message.data,
+            outcome: "matched",
+        });
+    }
+    if (script?.disconnect_after === true) {
+        client.close();
+        recorder.record({
+            at_ms: recorder.atMs(),
+            protocol: "websocket",
+            direction: "sent",
+            method: null,
+            path: "/ws",
+            data: "",
+            outcome: "disconnected",
+        });
+    }
+};
+const createWebSocketReplay = (server, recorder) => {
+    let connections = 0;
     const websocket = new WebSocketServer({
         noServer: true,
-        maxPayload: 1_000_000,
+        maxPayload: recorder.scenario.limits.protocol_body_bytes,
         clientTracking: true,
     });
     server.on("upgrade", (request, socket, head) => {
@@ -39,25 +176,27 @@ export const startLoopbackReplay = async (scenario) => {
         websocket.handleUpgrade(request, socket, head, (client) => websocket.emit("connection", client, request));
     });
     websocket.on("connection", (client) => {
+        connections += 1;
+        if (connections > recorder.scenario.limits.connections) {
+            recorder.truncated = true;
+            client.terminate();
+            return;
+        }
         client.on("error", () => undefined);
-        client.on("message", (value) => record({
+        client.on("message", (value) => recorder.record({
+            at_ms: recorder.atMs(),
             protocol: "websocket",
             direction: "received",
             method: null,
             path: "/ws",
             data: value.toString(),
+            outcome: "matched",
         }));
-        for (const message of scenario.replay.websocket_messages) {
-            client.send(message);
-            record({
-                protocol: "websocket",
-                direction: "sent",
-                method: null,
-                path: "/ws",
-                data: message,
-            });
-        }
+        void sendWebSocketScript(client, connections, recorder);
     });
+    return websocket;
+};
+const listen = async (server) => {
     await new Promise((resolveListen, rejectListen) => {
         server.once("error", rejectListen);
         server.listen(0, "127.0.0.1", () => {
@@ -66,14 +205,33 @@ export const startLoopbackReplay = async (scenario) => {
         });
     });
     const address = server.address();
-    if (address === null || typeof address === "string") {
-        await closeServer(server);
+    if (address === null || typeof address === "string")
         throw new Error("loopback replay did not acquire a TCP port");
+    return address.port;
+};
+const closeServer = (server) => new Promise((resolveClose, rejectClose) => {
+    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
+});
+/** Start bounded HTTP and WebSocket replay endpoints on IPv4 loopback only. */
+export const startLoopbackReplay = async (scenario) => {
+    const recorder = new ReplayRecorder(scenario);
+    const server = createServer(createHttpHandler(recorder));
+    const websocket = createWebSocketReplay(server, recorder);
+    let port;
+    try {
+        port = await listen(server);
+    }
+    catch (cause) {
+        await closeServer(server).catch(() => undefined);
+        throw cause;
     }
     return {
-        httpUrl: `http://127.0.0.1:${String(address.port)}`,
-        websocketUrl: `ws://127.0.0.1:${String(address.port)}/ws`,
-        events,
+        httpUrl: `http://127.0.0.1:${String(port)}`,
+        websocketUrl: `ws://127.0.0.1:${String(port)}/ws`,
+        events: recorder.events,
+        get truncated() {
+            return recorder.truncated;
+        },
         async close() {
             for (const client of websocket.clients)
                 client.terminate();