@botiverse/porthole 0.0.1 → 0.1.1

package/dist/conformance/oracles.js

@@ -0,0 +1,77 @@
+import { createSocket } from "node:dgram";
+import { createServer } from "node:http";
+const PIXEL = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64");
+/** What the oracle answers, by the path's extension: real enough for each kind of load to finish. */
+function body(path) {
+    if (/\.m?js(\?|$)/u.test(path)) {
+        return {
+            type: "text/javascript",
+            data: "globalThis.__portholeOracleScript = (globalThis.__portholeOracleScript || 0) + 1;",
+        };
+    }
+    if (/\.css(\?|$)/u.test(path)) {
+        return { type: "text/css", data: "html { --porthole-oracle: 1; }" };
+    }
+    if (/\.(png|gif|jpg)(\?|$)/u.test(path)) {
+        return { type: "image/png", data: PIXEL };
+    }
+    if (/\.html(\?|$)/u.test(path)) {
+        return {
+            type: "text/html",
+            data: "<!doctype html><title>oracle</title><p id=oracle>oracle</p>",
+        };
+    }
+    return { type: "text/plain", data: "oracle" };
+}
+export async function httpOracle(files = {}) {
+    const heard = [];
+    let connections = 0;
+    const server = createServer((request, response) => {
+        heard.push({
+            method: request.method ?? "GET",
+            path: request.url ?? "/",
+            origin: request.headers.origin,
+        });
+        const { type, data } = files[request.url ?? "/"] ?? body(request.url ?? "/");
+        response.writeHead(200, {
+            "content-type": type,
+            "access-control-allow-origin": "*",
+            "cache-control": "no-store",
+        });
+        response.end(data);
+    });
+    server.on("connection", () => {
+        connections += 1;
+    });
+    server.on("upgrade", (request, socket) => {
+        heard.push({ method: "UPGRADE", path: request.url ?? "/", origin: request.headers.origin });
+        socket.destroy();
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    return {
+        origin: `http://127.0.0.1:${port}`,
+        requests: () => [...heard],
+        connections: () => connections,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}
+export async function udpOracle() {
+    let packets = 0;
+    const socket = createSocket("udp4");
+    socket.on("message", () => {
+        packets += 1;
+    });
+    await new Promise((resolve) => socket.bind(0, "127.0.0.1", resolve));
+    const { port } = socket.address();
+    return {
+        stun: `stun:127.0.0.1:${port}`,
+        packets: () => packets,
+        close: () => new Promise((resolve) => socket.close(() => resolve())),
+    };
+}
+/** Waits `ms`, so a request that was going to leave has time to arrive. */
+export const settle = (ms = 800) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/conformance/probes.d.ts

@@ -0,0 +1,33 @@
+import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type Page, type TestInfo, type TestType } from "@playwright/test";
+import type { ConformanceHost, LeakSuiteOptions } from "./index.ts";
+import { type Probe } from "./kit.ts";
+export type { Probe, ProbeContext } from "./kit.ts";
+export { attack } from "./kit.ts";
+export declare const PROBES: readonly Probe[];
+type AnyTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+/** The fixtures a conformance test uses. */
+export interface ConformanceFixtures {
+    readonly page: Page;
+    readonly browserName: string;
+}
+/**
+ * One conformance test, for a host's own spec file to register: its tests are then located in that
+ * file, so `playwright test my-conformance.spec.ts` (or `--grep "\[1\.connect\]"`) finds them.
+ *
+ *   for (const each of leakTests(myHost)) {
+ *     test(each.title, ({ page, browserName }, info) => each.run({ page, browserName }, info));
+ *   }
+ */
+export interface ConformanceTest {
+    readonly id: string;
+    /** `[<id>] <what it proves>`: the probe id is greppable. */
+    readonly title: string;
+    run(fixtures: ConformanceFixtures, info: TestInfo): Promise<void>;
+}
+/** Every probe as a test entry (see `ConformanceTest`). */
+export declare function leakTests(host: ConformanceHost, options?: LeakSuiteOptions): ConformanceTest[];
+/**
+ * Registers every probe as a test. Its tests are located in Porthole's own files; a host that
+ * wants to select them by its spec file registers `leakTests` itself instead.
+ */
+export declare function defineLeakSuite(test: AnyTest, host: ConformanceHost, options?: LeakSuiteOptions): void;