@roster-lock/match-agent 0.1.0

package/tests/integration/piece-sort-list.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { startTestServer, TestServer, errorBody } from "./helpers/server";
+import { makeTempFolder, cleanupFolder } from "./helpers/piece";
+import { createFixturePluginDir } from "./helpers/plugin-dir";
+import { makeValidLockConfig } from "./helpers/validLockConfig";
+
+describe("GET /v1/piece/sort-list/available", () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length) await cleanups.pop()!();
+  });
+
+  function get(server: TestServer) {
+    return fetch(`${server.httpUrl}/v1/piece/sort-list/available`, {
+      headers: { Authorization: `Bearer ${server.authCode}` },
+    });
+  }
+
+  it("returns [] when no piece-selection-sort plugins are installed", async () => {
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder);
+    cleanups.push(() => server.close());
+
+    const res = await get(server);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([]);
+  });
+
+  it("lists installed piece-selection-sort plugins with their publicInfo, ignoring other plugin types", async () => {
+    const fixture = await createFixturePluginDir([
+      "@roster-lock/piece-selection-sort-most-used-locally",
+      "@roster-lock/piece-selection-sort-highest-winrate-locally",
+      "@roster-lock/dl-protocol-http",
+    ]);
+    cleanups.push(fixture.cleanup);
+
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder, undefined, fixture.pluginDir);
+    cleanups.push(() => server.close());
+
+    const res = await get(server);
+    expect(res.status).toBe(200);
+    const body = await res.json() as Array<{ pluginName: string, publicInfo: unknown }>;
+    expect(body.map((p) => p.pluginName).sort()).toEqual([
+      "@roster-lock/piece-selection-sort-highest-winrate-locally",
+      "@roster-lock/piece-selection-sort-most-used-locally",
+    ]);
+    for (const entry of body) {
+      expect(entry.publicInfo).toMatchObject({ title: expect.any(String), description: expect.any(String) });
+    }
+  });
+});
+
+describe("POST /v1/piece/sort-list/plugin/:pluginName", () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length) await cleanups.pop()!();
+  });
+
+  function post(server: TestServer, pluginName: string, body: unknown) {
+    return fetch(`${server.httpUrl}/v1/piece/sort-list/plugin/${encodeURIComponent(pluginName)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${server.authCode}` },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async function makeServer() {
+    const fixture = await createFixturePluginDir(["@roster-lock/piece-selection-sort-most-used-locally"]);
+    cleanups.push(fixture.cleanup);
+    const folder = await makeTempFolder();
+    cleanups.push(() => cleanupFolder(folder));
+    const server = await startTestServer(folder, undefined, fixture.pluginDir);
+    cleanups.push(() => server.close());
+    return server;
+  }
+
+  it("400s on a malformed body", async () => {
+    const server = await makeServer();
+    const res = await post(server, "@roster-lock/piece-selection-sort-most-used-locally", {});
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad Form");
+  });
+
+  it("400s when lockConfig fails schema validation", async () => {
+    const server = await makeServer();
+    const res = await post(server, "@roster-lock/piece-selection-sort-most-used-locally", {
+      lockConfig: { not: "a valid config" }, pieceType: "character", logicIds: ["1.0.0"],
+    });
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Invalid lockConfig");
+  });
+
+  it("500s for a plugin that isn't installed", async () => {
+    const server = await makeServer();
+    const res = await post(server, "@roster-lock/not-installed", {
+      lockConfig: makeValidLockConfig(), pieceType: "character", logicIds: ["1.0.0"],
+    });
+    expect(res.status).toBe(500);
+    expect((await errorBody(res)).error).toMatch(/Plugin not installed/);
+  });
+
+  it("passes the caller's logicIds through unchanged when the plugin has no ranking for them yet", async () => {
+    const server = await makeServer();
+    const res = await post(server, "@roster-lock/piece-selection-sort-most-used-locally", {
+      lockConfig: makeValidLockConfig(), pieceType: "character", logicIds: ["1.0.0", "2.0.0"],
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual(["1.0.0", "2.0.0"]);
+  });
+});

package/tests/integration/protocol.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { bindStepsToBridge } from "../../src/handle-room/version-1/room-handler-bridge/steps";
+import { wireBridgePair } from "./helpers/bridge";
+import { driveRoomProtocol } from "./helpers/room";
+import { FakeFolderDB } from "./helpers/fakeFolderDB";
+import { FakePluginManager } from "./helpers/fakePluginRuntime";
+import { makeLockConfig, makeHeroSelection } from "./helpers/lockConfig";
+
+// These exercise the two "scary" parts of the sync-dl protocol - real
+// runSelection (roster/requirement validation + personal merge) and real
+// handleDownloads (recursive required-piece resolution + dedup) - without
+// a relay server, WebSocket, or network download. bindStepsToBridge only
+// needs a MessageBridge; wireBridgePair connects two of them directly, and
+// driveRoomProtocol plays the relay's side of the protocol in-process
+// (mirroring room-handler-bridge/server.pseudo.ts).
+describe("bindStepsToBridge: runSelection + handleDownloads", () => {
+  it("runs the full protocol for two users picking the same piece, dedupes the shared nested requirement, and both agents converge on the same result", async () => {
+    const lockConfig = makeLockConfig();
+    const machines = [{ publicKey: "pk-a", playerCount: 1 }, { publicKey: "pk-b", playerCount: 1 }];
+
+    const pairA = wireBridgePair();
+    const pairB = wireBridgePair();
+
+    const dbA = new FakeFolderDB();
+    const dbB = new FakeFolderDB();
+    const pm = new FakePluginManager();
+
+    const resultAPromise = bindStepsToBridge({
+      bridge: pairA.agentSide,
+      fileDB: dbA,
+      pluginRuntime: pm,
+      machines,
+      ownMachinePublicKey: "pk-a",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+    const resultBPromise = bindStepsToBridge({
+      bridge: pairB.agentSide,
+      fileDB: dbB,
+      pluginRuntime: pm,
+      machines,
+      ownMachinePublicKey: "pk-b",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+
+    await driveRoomProtocol([
+      { bridge: pairA.roomSide, publicKey: "pk-a" },
+      { bridge: pairB.roomSide, publicKey: "pk-b" },
+    ]);
+
+    const [resultA, resultB] = await Promise.all([resultAPromise, resultBPromise]);
+
+    // runSelection: both agents decrypted the same inputs independently and
+    // must agree on the merged personal selection.
+    expect(resultA.finalSelection).toEqual(resultB.finalSelection);
+    expect(resultA.finalSelection.character).toEqual({
+      type: "personal",
+      value: {
+        "pk-a:0": makeHeroSelection().character,
+        "pk-b:0": makeHeroSelection().character,
+      },
+    });
+
+    // handleDownloads: both users chose the same piece (which itself
+    // requires the same nested weapon) - each agent must dedupe that down
+    // to a single download call per piece, not one per reference.
+    for (const db of [dbA, dbB]) {
+      expect(db.calls).toEqual([
+        { pieceType: "character", pieceId: "hero-1" },
+        { pieceType: "weapon", pieceId: "sword-1" },
+      ]);
+    }
+
+    expect(resultA.downloadResults).toEqual({
+      character: { "hero-1": { pieceType: "character", pieceId: "hero-1", pieceVersions: { logic: "1.0.0", media: "1.0.0" }, folder: "/fake/character/hero-1" } },
+      weapon: { "sword-1": { pieceType: "weapon", pieceId: "sword-1", pieceVersions: { logic: "1.0.0", media: "1.0.0" }, folder: "/fake/weapon/sword-1" } },
+    });
+  });
+
+  it("rejects when a user selects a piece missing from the roster (runSelection validation)", async () => {
+    const lockConfig = makeLockConfig();
+    const machines = [{ publicKey: "pk-a", playerCount: 1 }, { publicKey: "pk-b", playerCount: 1 }];
+
+    const pairA = wireBridgePair();
+    const pairB = wireBridgePair();
+    const pm = new FakePluginManager();
+
+    const badSelection = { character: [{ id: "not-a-real-piece", required: { weapon: { mandatory: [], selectable: [] } } }] };
+
+    const resultAPromise = bindStepsToBridge({
+      bridge: pairA.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime: pm,
+      machines,
+      ownMachinePublicKey: "pk-a",
+      ownSelections: { 0: badSelection },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+    const resultBPromise = bindStepsToBridge({
+      bridge: pairB.agentSide,
+      fileDB: new FakeFolderDB(),
+      pluginRuntime: pm,
+      machines,
+      ownMachinePublicKey: "pk-b",
+      ownSelections: { 0: makeHeroSelection() },
+      lockConfig,
+      gameControlledSelections: {},
+    });
+    // both agents run runSelection independently over the same decrypted
+    // inputs, so the bad selection fails validation on both sides.
+    resultAPromise.catch(() => {});
+    resultBPromise.catch(() => {});
+
+    await driveRoomProtocol([
+      { bridge: pairA.roomSide, publicKey: "pk-a" },
+      { bridge: pairB.roomSide, publicKey: "pk-b" },
+    ]).catch(() => {});
+
+    // bindStepsToBridge rejects with whatever value the room's "error" event
+    // carried (steps.ts: bridge.onEvent("error", (error) => reject(error))) -
+    // a plain string here, not an Error instance.
+    await expect(resultAPromise).rejects.toBe("Piece not-a-real-piece is not in the roster");
+    await expect(resultBPromise).rejects.toBe("Piece not-a-real-piece is not in the roster");
+  });
+});

package/tests/integration/root-and-auth.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { startTestServer, TestServer, errorBody } from "./helpers/server";
+import { makeTempFolder, cleanupFolder } from "./helpers/piece";
+
+describe("GET /", () => {
+  let server: TestServer;
+  let folder: string;
+  beforeAll(async () => { folder = await makeTempFolder(); server = await startTestServer(folder); });
+  afterAll(async () => { await server.close(); await cleanupFolder(folder); });
+
+  it("responds with hello world and requires no auth", async () => {
+    const res = await fetch(`${server.httpUrl}/`);
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toEqual({ hello: "world" });
+  });
+});
+
+describe("POST /validate-authcode", () => {
+  let server: TestServer;
+  let folder: string;
+  beforeAll(async () => { folder = await makeTempFolder(); server = await startTestServer(folder); });
+  afterAll(async () => { await server.close(); await cleanupFolder(folder); });
+
+  it("returns true for the real auth code, no auth header required", async () => {
+    const res = await fetch(`${server.httpUrl}/validate-authcode`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ authCode: server.authCode }),
+    });
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toBe(true);
+  });
+
+  it("returns false for a wrong auth code", async () => {
+    const res = await fetch(`${server.httpUrl}/validate-authcode`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ authCode: "not-the-real-code" }),
+    });
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toBe(false);
+  });
+
+  it("400s on a malformed body", async () => {
+    const res = await fetch(`${server.httpUrl}/validate-authcode`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ notAuthCode: 123 }),
+    });
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad body");
+  });
+});
+
+describe("/v1 auth gate", () => {
+  let server: TestServer;
+  let folder: string;
+  beforeAll(async () => { folder = await makeTempFolder(); server = await startTestServer(folder); });
+  afterAll(async () => { await server.close(); await cleanupFolder(folder); });
+
+  const v1Url = () => `${server.httpUrl}/v1/piece/asset-files`;
+
+  it("401s with no auth provided", async () => {
+    const res = await fetch(v1Url(), { method: "POST", body: "{}" });
+    expect(res.status).toBe(401);
+    expect((await errorBody(res)).error).toBe("User Required");
+  });
+
+  it("401s with a wrong Authorization header", async () => {
+    const res = await fetch(v1Url(), {
+      method: "POST",
+      headers: { Authorization: "Bearer wrong-code" },
+      body: "{}",
+    });
+    expect(res.status).toBe(401);
+    expect((await errorBody(res)).error).toBe("Invalid User");
+  });
+
+  it("401s with a wrong ?authorization= query param", async () => {
+    const res = await fetch(`${v1Url()}?authorization=wrong-code`, { method: "POST", body: "{}" });
+    expect(res.status).toBe(401);
+    expect((await errorBody(res)).error).toBe("Invalid User");
+  });
+
+  it("passes through with a correct Authorization header (reaches the route, fails its own validation instead)", async () => {
+    const res = await fetch(v1Url(), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${server.authCode}` },
+      body: "{}",
+    });
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad Form");
+  });
+
+  it("passes through with a correct ?authorization= query param", async () => {
+    const res = await fetch(`${v1Url()}?authorization=${server.authCode}`, { method: "POST", body: "{}" });
+    expect(res.status).toBe(400);
+    expect((await errorBody(res)).error).toBe("Bad Form");
+  });
+});

package/tests/integration/sync-dl.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { once } from "node:events";
+import { WebSocket } from "ws";
+import { MessageBridge } from "@roster-lock/utils";
+import { startTestServer, TestServer, errorBody } from "./helpers/server";
+import { makeTempFolder, cleanupFolder } from "./helpers/piece";
+
+describe("POST /v1/sync-dl", () => {
+  let server: TestServer;
+  let folder: string;
+  beforeAll(async () => { folder = await makeTempFolder(); server = await startTestServer(folder); });
+  afterAll(async () => { await server.close(); await cleanupFolder(folder); });
+
+  it("500s on a malformed body (castRoomRequest throws a plain Error)", async () => {
+    const res = await fetch(`${server.httpUrl}/v1/sync-dl`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${server.authCode}`,
+      },
+      body: JSON.stringify({ not: "a valid room request" }),
+    });
+    expect(res.status).toBe(500);
+    expect((await errorBody(res)).error).toBe("Invalid request");
+  });
+});
+
+describe("WS /v1/sync-dl", () => {
+  let server: TestServer;
+  let folder: string;
+  beforeAll(async () => { folder = await makeTempFolder(); server = await startTestServer(folder); });
+  afterAll(async () => { await server.close(); await cleanupFolder(folder); });
+
+  it("terminates the connection with no auth, without ever sending a ready event", async () => {
+    const ws = new WebSocket(`${server.wsUrl}/v1/sync-dl`);
+    let receivedMessage = false;
+    ws.on("message", () => { receivedMessage = true; });
+    ws.on("error", () => {}); // abrupt terminate() can surface as ECONNRESET - not the point of this test
+
+    await once(ws, "close");
+    expect(receivedMessage).toBe(false);
+  });
+
+  it("sends a ready event once authenticated, and rejects an invalid connect-to-relay request", async () => {
+    const ws = new WebSocket(`${server.wsUrl}/v1/sync-dl`, {
+      headers: { Authorization: `Bearer ${server.authCode}` },
+    });
+    try {
+      const bridge = new MessageBridge((message) => ws.send(JSON.stringify(message)));
+      const readyPromise = new Promise<void>((resolve) => bridge.onEvent("ready", () => resolve()));
+      ws.on("message", (data) => bridge.handleMessage(JSON.parse(data.toString())));
+
+      await once(ws, "open");
+      await readyPromise;
+
+      await expect(bridge.sendRequest("connect-to-relay", { not: "a valid room request" }))
+        .rejects.toBe("Invalid request");
+    } finally {
+      ws.close();
+    }
+  });
+});

package/tests/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node", "vitest/globals"],
+    "lib": ["es2024"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+    "lib": ["es2024"],
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "removeComments": true,
+    "noImplicitAny": true
+  },
+  "files": [
+    "src/index.ts"
+  ],
+  "include": ["./typings", "./types", "./@types", "**/*.test.ts"],
+  "exclude": ["node_modules", "**/*.spec.ts", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    testTimeout: 10000,
+    hookTimeout: 10000,
+  }
+});