miravo 0.2.3 → 0.3.0

package/src/lib/admin-server.test.ts

@@ -1,14 +1,85 @@
 import { afterEach, describe, expect, test } from "bun:test";
+import type { EventEmitter } from "node:events";
+import { createServer } from "node:net";
 import type { EngineCoreMetrics, EngineStateSnapshot } from "@miravo/core";
 import type { CommandResult, EngineCommand } from "@miravo/shared";
 import { startAdminServer } from "./admin-server.ts";
 
-function createMockAdminEngine(initialState: EngineCoreMetrics["state"], tickIntervalMs: number) {
+async function canBindLocalTcp(): Promise<boolean> {
+  const probe = createServer();
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      try {
+        probe.close();
+      } catch {
+        // Ignore close races in test cleanup.
+      }
+    };
+
+    (probe as unknown as EventEmitter).once("error", () => {
+      cleanup();
+      resolve(false);
+    });
+    (probe as unknown as EventEmitter).once("listening", () => {
+      cleanup();
+      resolve(true);
+    });
+    probe.listen(0, "127.0.0.1");
+  });
+}
+
+async function reservePort(): Promise<number> {
+  const probe = createServer();
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      try {
+        probe.close();
+      } catch {
+        // Ignore close races in test cleanup.
+      }
+    };
+
+    (probe as unknown as EventEmitter).once("error", (error: Error) => {
+      cleanup();
+      reject(error);
+    });
+    (probe as unknown as EventEmitter).once("listening", () => {
+      const address = probe.address();
+      if (!address || typeof address === "string") {
+        cleanup();
+        reject(new Error("Failed to reserve a local TCP port for the admin server test."));
+        return;
+      }
+
+      const { port } = address;
+      probe.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(port);
+      });
+    });
+    probe.listen(0, "127.0.0.1");
+  });
+}
+
+const TCP_AVAILABLE = await canBindLocalTcp();
+const describeIfTcp = TCP_AVAILABLE ? describe : describe.skip;
+
+function createMockAdminEngine(
+  initialState: EngineCoreMetrics["state"],
+  tickIntervalMs: number,
+  connectedAdapters: string[] = [],
+  enabledAdapters: string[] = [],
+) {
   const runtime = {
     state: initialState as EngineCoreMetrics["state"],
     tickCount: 0,
     lastTickProgressAt: performance.now(),
     executedCommands: [] as EngineCommand[],
+    connectedAdapters: [...connectedAdapters],
+    enabledAdapters: [...enabledAdapters],
   };
 
   const snapshot: EngineStateSnapshot = {
@@ -46,10 +117,30 @@ function createMockAdminEngine(initialState: EngineCoreMetrics["state"], tickInt
           activeFaultCount: 0,
           faultBreakdown: [],
         },
-        adapters: [],
+        adapters: runtime.connectedAdapters.map((name) => ({
+          name,
+          metrics: { connected: true },
+        })),
       }),
-      getState: () => snapshot,
-      execute: (command: EngineCommand): CommandResult => {
+      getState: () => ({
+        ...snapshot,
+        availableAdapters: runtime.enabledAdapters.map((name) => ({
+          name,
+          enabled: true,
+          pending: false,
+          config: {},
+        })),
+      }),
+      getAvailableAdapters: () =>
+        runtime.enabledAdapters.map((name) => ({
+          name,
+          enabled: true,
+        })),
+      getInstanceDetail: (_id: string) => undefined,
+      getModelSchema: (_name: string) => undefined,
+      getEventLog: () => ({ events: [], nextCursor: null, hasMore: false }),
+      getRunningTemplates: () => [],
+      execute: async (command: EngineCommand): Promise<CommandResult> => {
         runtime.executedCommands.push(command);
         return {
           success: true,
@@ -74,6 +165,12 @@ function createMockAdminEngine(initialState: EngineCoreMetrics["state"], tickInt
     getExecutedCommands() {
       return [...runtime.executedCommands];
     },
+    setConnectedAdapters(adapterNames: string[]) {
+      runtime.connectedAdapters = [...adapterNames];
+    },
+    setEnabledAdapters(adapterNames: string[]) {
+      runtime.enabledAdapters = [...adapterNames];
+    },
   };
 }
 
@@ -85,31 +182,57 @@ function serverBaseUrl(endpoint: string): string {
 interface StartServerOptions {
   readonly state: EngineCoreMetrics["state"];
   readonly tickIntervalMs?: number;
-  readonly mqttEnabled: boolean;
-  readonly isMqttConnected: () => boolean;
-  readonly opcuaEnabled?: boolean;
-  readonly isOpcuaConnected?: () => boolean;
+  readonly host?: string;
+  /** Adapter names that should report as connected in mock metrics. */
+  readonly connectedAdapters?: string[];
+  /** Adapter names that should report as enabled in the runtime state. */
+  readonly enabledAdapters?: string[];
 }
 
-function startTestServer(options: StartServerOptions, handles: Array<{ stop: () => void }>) {
-  const mock = createMockAdminEngine(options.state, options.tickIntervalMs ?? 1000);
+async function startTestServer(options: StartServerOptions, handles: Array<{ stop: () => void }>) {
+  const port = await reservePort();
+  const mock = createMockAdminEngine(
+    options.state,
+    options.tickIntervalMs ?? 1000,
+    options.connectedAdapters,
+    options.enabledAdapters,
+  );
   const handle = startAdminServer({
     engine: mock.engine,
-    host: "127.0.0.1",
-    port: 0,
-    tickIntervalMs: options.tickIntervalMs ?? 1000,
-    mqttEnabled: options.mqttEnabled,
-    isMqttConnected: options.isMqttConnected,
-    opcuaEnabled: options.opcuaEnabled ?? false,
-    isOpcuaConnected: options.isOpcuaConnected ?? (() => false),
-    getLastTickProgressAt: () => mock.getLastTickProgressAt(),
+    network: {
+      host: options.host ?? "127.0.0.1",
+      port,
+      tickIntervalMs: options.tickIntervalMs ?? 1000,
+    },
+    protocols: {
+      getLastTickProgressAt: () => mock.getLastTickProgressAt(),
+    },
   });
   handles.push(handle);
   const baseUrl = serverBaseUrl(handle.endpoint);
   return { mock, baseUrl };
 }
 
-describe("admin server", () => {
+async function startShutdownTestServer(handles: Array<{ stop: () => void }>): Promise<{
+  baseUrl: string;
+  getShutdownReason: () => string;
+}> {
+  const port = await reservePort();
+  const mock = createMockAdminEngine("running", 1000);
+  let shutdownReason = "";
+  const handle = startAdminServer({
+    engine: mock.engine,
+    network: { host: "127.0.0.1", port, tickIntervalMs: 1000 },
+    protocols: { getLastTickProgressAt: () => mock.getLastTickProgressAt() },
+    requestShutdown: (reason) => {
+      shutdownReason = reason;
+    },
+  });
+  handles.push(handle);
+  return { baseUrl: serverBaseUrl(handle.endpoint), getShutdownReason: () => shutdownReason };
+}
+
+describeIfTcp("admin server", () => {
   const handles: Array<{ stop: () => void }> = [];
 
   afterEach(() => {
@@ -125,11 +248,16 @@ describe("admin server", () => {
       state: "running" as const,
       healthStatus: 200,
       readyStatus: 200,
+      connectedAdapters: ["mqtt"] as string[],
     },
     { label: "503 when paused", state: "paused" as const, healthStatus: 200, readyStatus: 503 },
-  ])("/readyz returns $label", async ({ state, healthStatus, readyStatus }) => {
-    const { baseUrl } = startTestServer(
-      { state, mqttEnabled: true, isMqttConnected: () => true },
+  ])("/readyz returns $label", async ({ state, healthStatus, readyStatus, connectedAdapters }) => {
+    const { baseUrl } = await startTestServer(
+      {
+        state,
+        enabledAdapters: ["mqtt"],
+        connectedAdapters: connectedAdapters ?? [],
+      },
       handles,
     );
 
@@ -141,8 +269,8 @@ describe("admin server", () => {
   });
 
   test("/readyz returns 503 when mqtt is enabled but disconnected", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: true, isMqttConnected: () => false },
+    const { baseUrl } = await startTestServer(
+      { state: "running", enabledAdapters: ["mqtt"] },
       handles,
     );
 
@@ -151,13 +279,10 @@ describe("admin server", () => {
   });
 
   test("/readyz returns 503 when opcua is enabled but disconnected", async () => {
-    const { baseUrl } = startTestServer(
+    const { baseUrl } = await startTestServer(
       {
         state: "running",
-        mqttEnabled: false,
-        isMqttConnected: () => false,
-        opcuaEnabled: true,
-        isOpcuaConnected: () => false,
+        enabledAdapters: ["opcua"],
       },
       handles,
     );
@@ -168,11 +293,28 @@ describe("admin server", () => {
     expect(body.reason).toBe("opcua disconnected");
   });
 
+  test("/readyz follows live adapter enablement instead of boot-time flags", async () => {
+    const { mock, baseUrl } = await startTestServer({ state: "running" }, handles);
+
+    const initiallyReady = await fetch(`${baseUrl}/readyz`);
+    expect(initiallyReady.status).toBe(200);
+
+    mock.setEnabledAdapters(["mqtt"]);
+    const disconnected = await fetch(`${baseUrl}/readyz`);
+    expect(disconnected.status).toBe(503);
+
+    mock.setConnectedAdapters(["mqtt"]);
+    const connected = await fetch(`${baseUrl}/readyz`);
+    expect(connected.status).toBe(200);
+
+    mock.setEnabledAdapters([]);
+    mock.setConnectedAdapters([]);
+    const disabledAgain = await fetch(`${baseUrl}/readyz`);
+    expect(disabledAgain.status).toBe(200);
+  });
+
   test("/healthz returns 503 on the first probe after running tick loop stalls", async () => {
-    const { mock, baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { mock, baseUrl } = await startTestServer({ state: "running" }, handles);
     mock.setLastTickProgressAt(performance.now() - 3_500);
 
     const stalled = await fetch(`${baseUrl}/healthz`);
@@ -185,10 +327,7 @@ describe("admin server", () => {
   });
 
   test("GET /metrics returns the engine metrics snapshot", async () => {
-    const { mock, baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { mock, baseUrl } = await startTestServer({ state: "running" }, handles);
     mock.setTickCount(12);
 
     const response = await fetch(`${baseUrl}/metrics`);
@@ -204,10 +343,7 @@ describe("admin server", () => {
   });
 
   test("GET /state returns the engine state snapshot", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { baseUrl } = await startTestServer({ state: "running" }, handles);
 
     const response = await fetch(`${baseUrl}/state`);
     const body = (await response.json()) as EngineStateSnapshot;
@@ -218,10 +354,7 @@ describe("admin server", () => {
   });
 
   test("POST /commands validates and dispatches engine commands", async () => {
-    const { mock, baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { mock, baseUrl } = await startTestServer({ state: "running" }, handles);
 
     const response = await fetch(`${baseUrl}/commands`, {
       method: "POST",
@@ -239,11 +372,26 @@ describe("admin server", () => {
     expect(mock.getExecutedCommands()).toEqual([{ type: "pause", correlationId: "req-1" }]);
   });
 
+  test("POST /commands requires auth on non-loopback binds", async () => {
+    const { baseUrl } = await startTestServer({ state: "running", host: "0.0.0.0" }, handles);
+
+    const response = await fetch(`${baseUrl}/commands`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        type: "pause",
+        correlationId: "req-1",
+      }),
+    });
+    const body = (await response.json()) as { message: string; error: string };
+
+    expect(response.status).toBe(403);
+    expect(body.message).toBe("Mutation endpoints require authentication.");
+    expect(body.error).toBe("Set MIRAVO_ADMIN_TOKEN when binding to a non-loopback address.");
+  });
+
   test("POST /commands returns 400 for invalid JSON", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { baseUrl } = await startTestServer({ state: "running" }, handles);
 
     const response = await fetch(`${baseUrl}/commands`, {
       method: "POST",
@@ -257,10 +405,7 @@ describe("admin server", () => {
   });
 
   test("POST /commands returns 400 for invalid command shape", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
+    const { baseUrl } = await startTestServer({ state: "running" }, handles);
 
     const response = await fetch(`${baseUrl}/commands`, {
       method: "POST",
@@ -273,4 +418,145 @@ describe("admin server", () => {
     expect(body.success).toBe(false);
     expect(body.command).toBe("setSpeed");
   });
+
+  // --- Daemon mode endpoints ---
+
+  test("/readyz includes simulationName and runId when provided", async () => {
+    const port = await reservePort();
+    const mock = createMockAdminEngine("running", 1000);
+    const handle = startAdminServer({
+      engine: mock.engine,
+      network: { host: "127.0.0.1", port, tickIntervalMs: 1000 },
+      protocols: { getLastTickProgressAt: () => mock.getLastTickProgressAt() },
+      simulationName: "test-daemon",
+      runId: "run-abc-123",
+    });
+    handles.push(handle);
+    const baseUrl = serverBaseUrl(handle.endpoint);
+
+    const response = await fetch(`${baseUrl}/readyz`);
+    const body = (await response.json()) as Record<string, unknown>;
+
+    expect(response.status).toBe(200);
+    expect(body["simulationName"]).toBe("test-daemon");
+    expect(body["runId"]).toBe("run-abc-123");
+  });
+
+  test("/readyz omits simulationName and runId when not provided", async () => {
+    const { baseUrl } = await startTestServer({ state: "running" }, handles);
+
+    const response = await fetch(`${baseUrl}/readyz`);
+    const body = (await response.json()) as Record<string, unknown>;
+
+    expect(response.status).toBe(200);
+    expect(body["simulationName"]).toBeUndefined();
+    expect(body["runId"]).toBeUndefined();
+  });
+
+  test("POST /shutdown calls requestShutdown callback and returns 200", async () => {
+    const { baseUrl, getShutdownReason } = await startShutdownTestServer(handles);
+
+    const response = await fetch(`${baseUrl}/shutdown`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ reason: "miravo stop" }),
+    });
+    const body = (await response.json()) as Record<string, unknown>;
+
+    expect(response.status).toBe(200);
+    expect(body["status"]).toBe("shutting_down");
+    expect(getShutdownReason()).toBe("miravo stop");
+  });
+
+  test("POST /shutdown uses default reason when body is empty", async () => {
+    const { baseUrl, getShutdownReason } = await startShutdownTestServer(handles);
+
+    const response = await fetch(`${baseUrl}/shutdown`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+    });
+    expect(response.status).toBe(200);
+    expect(getShutdownReason()).toBe("remote shutdown request");
+  });
+
+  test("GET /shutdown returns 405", async () => {
+    const port = await reservePort();
+    const mock = createMockAdminEngine("running", 1000);
+    const handle = startAdminServer({
+      engine: mock.engine,
+      network: { host: "127.0.0.1", port, tickIntervalMs: 1000 },
+      protocols: { getLastTickProgressAt: () => mock.getLastTickProgressAt() },
+      requestShutdown: () => {},
+    });
+    handles.push(handle);
+    const baseUrl = serverBaseUrl(handle.endpoint);
+
+    const response = await fetch(`${baseUrl}/shutdown`);
+    expect(response.status).toBe(405);
+  });
+
+  test("POST /shutdown returns 501 when requestShutdown not provided", async () => {
+    const { baseUrl } = await startTestServer({ state: "running" }, handles);
+
+    const response = await fetch(`${baseUrl}/shutdown`, { method: "POST" });
+    expect(response.status).toBe(501);
+  });
+
+  test("POST /shutdown requires auth when adminToken is set", async () => {
+    const port = await reservePort();
+    const mock = createMockAdminEngine("running", 1000);
+    const handle = startAdminServer({
+      engine: mock.engine,
+      network: { host: "127.0.0.1", port, tickIntervalMs: 1000 },
+      protocols: { getLastTickProgressAt: () => mock.getLastTickProgressAt() },
+      requestShutdown: () => {},
+      adminToken: "secret-token",
+    });
+    handles.push(handle);
+    const baseUrl = serverBaseUrl(handle.endpoint);
+
+    // Without token
+    const noAuth = await fetch(`${baseUrl}/shutdown`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+    });
+    expect(noAuth.status).toBe(401);
+
+    // With token
+    const withAuth = await fetch(`${baseUrl}/shutdown`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: "Bearer secret-token" },
+    });
+    expect(withAuth.status).toBe(200);
+  });
+
+  test("POST /commands accepts bearer auth on non-loopback binds", async () => {
+    const port = await reservePort();
+    const mock = createMockAdminEngine("running", 1000);
+    const handle = startAdminServer({
+      engine: mock.engine,
+      network: { host: "0.0.0.0", port, tickIntervalMs: 1000 },
+      protocols: { getLastTickProgressAt: () => mock.getLastTickProgressAt() },
+      adminToken: "secret-token",
+    });
+    handles.push(handle);
+    const baseUrl = serverBaseUrl(handle.endpoint);
+
+    const response = await fetch(`${baseUrl}/commands`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer secret-token",
+      },
+      body: JSON.stringify({
+        type: "pause",
+        correlationId: "req-2",
+      }),
+    });
+    const body = (await response.json()) as CommandResult;
+
+    expect(response.status).toBe(200);
+    expect(body.success).toBe(true);
+    expect(mock.getExecutedCommands()).toEqual([{ type: "pause", correlationId: "req-2" }]);
+  });
 });