miravo 0.1.4 → 0.2.1

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

@@ -0,0 +1,276 @@
+import { afterEach, describe, expect, test } from "bun:test";
+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) {
+  const runtime = {
+    state: initialState as EngineCoreMetrics["state"],
+    tickCount: 0,
+    lastTickProgressAt: performance.now(),
+    executedCommands: [] as EngineCommand[],
+  };
+
+  const snapshot: EngineStateSnapshot = {
+    simulationName: "test-sim",
+    models: [],
+    instances: [],
+    config: {
+      seed: 1,
+      tickIntervalMs,
+      timeMultiplier: 1,
+      adapters: [],
+    },
+  };
+
+  return {
+    engine: {
+      getMetrics: () => ({
+        simulationName: snapshot.simulationName,
+        core: {
+          state: runtime.state,
+          tickCount: runtime.tickCount,
+          simulationTimeSeconds: 0,
+          instanceCount: 1,
+          memberValueCount: 1,
+          quarantinedInstanceCount: 0,
+          engineErrorsCount: 0,
+          tickOverrunsCount: 0,
+          circuitBreakerTripsCount: 0,
+          uptimeMs: 0,
+          actualTicksPerSecond: 1,
+        },
+        fleet: {
+          modelBreakdown: [{ model: "test-sensor", count: 1 }],
+          lifecycleBreakdown: { running: 1 },
+          activeFaultCount: 0,
+          faultBreakdown: [],
+        },
+        adapters: [],
+      }),
+      getState: () => snapshot,
+      execute: (command: EngineCommand): CommandResult => {
+        runtime.executedCommands.push(command);
+        return {
+          success: true,
+          command: command.type,
+          correlationId: command.correlationId,
+          message: `Executed ${command.type}`,
+        };
+      },
+    },
+    setState(state: EngineCoreMetrics["state"]) {
+      runtime.state = state;
+    },
+    setTickCount(tickCount: number) {
+      runtime.tickCount = tickCount;
+    },
+    setLastTickProgressAt(timestamp: number) {
+      runtime.lastTickProgressAt = timestamp;
+    },
+    getLastTickProgressAt() {
+      return runtime.lastTickProgressAt;
+    },
+    getExecutedCommands() {
+      return [...runtime.executedCommands];
+    },
+  };
+}
+
+function serverBaseUrl(endpoint: string): string {
+  const url = new URL(endpoint);
+  return `http://127.0.0.1:${url.port}`;
+}
+
+interface StartServerOptions {
+  readonly state: EngineCoreMetrics["state"];
+  readonly tickIntervalMs?: number;
+  readonly mqttEnabled: boolean;
+  readonly isMqttConnected: () => boolean;
+  readonly opcuaEnabled?: boolean;
+  readonly isOpcuaConnected?: () => boolean;
+}
+
+function startTestServer(options: StartServerOptions, handles: Array<{ stop: () => void }>) {
+  const mock = createMockAdminEngine(options.state, options.tickIntervalMs ?? 1000);
+  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(),
+  });
+  handles.push(handle);
+  const baseUrl = serverBaseUrl(handle.endpoint);
+  return { mock, baseUrl };
+}
+
+describe("admin server", () => {
+  const handles: Array<{ stop: () => void }> = [];
+
+  afterEach(() => {
+    for (const handle of handles) {
+      handle.stop();
+    }
+    handles.length = 0;
+  });
+
+  test.each([
+    {
+      label: "200 when running and mqtt connected",
+      state: "running" as const,
+      healthStatus: 200,
+      readyStatus: 200,
+    },
+    { 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 },
+      handles,
+    );
+
+    const health = await fetch(`${baseUrl}/healthz`);
+    const ready = await fetch(`${baseUrl}/readyz`);
+
+    expect(health.status).toBe(healthStatus);
+    expect(ready.status).toBe(readyStatus);
+  });
+
+  test("/readyz returns 503 when mqtt is enabled but disconnected", async () => {
+    const { baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: true, isMqttConnected: () => false },
+      handles,
+    );
+
+    const ready = await fetch(`${baseUrl}/readyz`);
+    expect(ready.status).toBe(503);
+  });
+
+  test("/readyz returns 503 when opcua is enabled but disconnected", async () => {
+    const { baseUrl } = startTestServer(
+      {
+        state: "running",
+        mqttEnabled: false,
+        isMqttConnected: () => false,
+        opcuaEnabled: true,
+        isOpcuaConnected: () => false,
+      },
+      handles,
+    );
+
+    const ready = await fetch(`${baseUrl}/readyz`);
+    expect(ready.status).toBe(503);
+    const body = (await ready.json()) as { reason?: string };
+    expect(body.reason).toBe("opcua disconnected");
+  });
+
+  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,
+    );
+    mock.setLastTickProgressAt(performance.now() - 3_500);
+
+    const stalled = await fetch(`${baseUrl}/healthz`);
+    expect(stalled.status).toBe(503);
+
+    mock.setLastTickProgressAt(performance.now());
+    mock.setTickCount(1);
+    const recovered = await fetch(`${baseUrl}/healthz`);
+    expect(recovered.status).toBe(200);
+  });
+
+  test("GET /metrics returns the engine metrics snapshot", async () => {
+    const { mock, baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
+      handles,
+    );
+    mock.setTickCount(12);
+
+    const response = await fetch(`${baseUrl}/metrics`);
+    const body = (await response.json()) as {
+      core: { tickCount: number; state: EngineCoreMetrics["state"] };
+      simulationName: string;
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.simulationName).toBe("test-sim");
+    expect(body.core.tickCount).toBe(12);
+    expect(body.core.state).toBe("running");
+  });
+
+  test("GET /state returns the engine state snapshot", async () => {
+    const { baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
+      handles,
+    );
+
+    const response = await fetch(`${baseUrl}/state`);
+    const body = (await response.json()) as EngineStateSnapshot;
+
+    expect(response.status).toBe(200);
+    expect(body.simulationName).toBe("test-sim");
+    expect(body.config.tickIntervalMs).toBe(1000);
+  });
+
+  test("POST /commands validates and dispatches engine commands", async () => {
+    const { mock, baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
+      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 CommandResult;
+
+    expect(response.status).toBe(200);
+    expect(body.success).toBe(true);
+    expect(body.command).toBe("pause");
+    expect(mock.getExecutedCommands()).toEqual([{ type: "pause", correlationId: "req-1" }]);
+  });
+
+  test("POST /commands returns 400 for invalid JSON", async () => {
+    const { baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
+      handles,
+    );
+
+    const response = await fetch(`${baseUrl}/commands`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{bad json",
+    });
+    const body = (await response.json()) as { message: string };
+
+    expect(response.status).toBe(400);
+    expect(body.message).toBe("Invalid JSON in command request body.");
+  });
+
+  test("POST /commands returns 400 for invalid command shape", async () => {
+    const { baseUrl } = startTestServer(
+      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
+      handles,
+    );
+
+    const response = await fetch(`${baseUrl}/commands`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ type: "setSpeed" }),
+    });
+    const body = (await response.json()) as CommandResult;
+
+    expect(response.status).toBe(400);
+    expect(body.success).toBe(false);
+    expect(body.command).toBe("setSpeed");
+  });
+});

package/src/lib/admin-server.ts

@@ -0,0 +1,307 @@
+import type { EngineCoreMetrics, EngineStateSnapshot } from "@miravo/core";
+import type { CommandResult, EngineCommand } from "@miravo/shared";
+import { EngineCommandSchema } from "@miravo/shared";
+
+interface AdminEngine {
+  getMetrics(): { readonly core: EngineCoreMetrics };
+  getState(): EngineStateSnapshot;
+  execute(command: EngineCommand): CommandResult;
+}
+
+interface AdminServerOptions {
+  readonly engine: AdminEngine;
+  readonly host: string;
+  readonly port: number;
+  readonly tickIntervalMs: number;
+  readonly mqttEnabled: boolean;
+  readonly isMqttConnected: () => boolean;
+  readonly opcuaEnabled: boolean;
+  readonly isOpcuaConnected: () => boolean;
+  readonly getLastTickProgressAt: () => number;
+}
+
+interface AdminServerStatus {
+  readonly status: "ok" | "fail";
+  readonly reason?: string;
+}
+
+interface AdminServerHandle {
+  readonly endpoint: string;
+  stop(): void;
+}
+
+interface HealthResponseBody {
+  readonly status: "ok" | "fail";
+  readonly simulationState: EngineCoreMetrics["state"];
+  readonly tickCount: number;
+  readonly mqttEnabled: boolean;
+  readonly mqttConnected: boolean | null;
+  readonly opcuaEnabled: boolean;
+  readonly opcuaConnected: boolean | null;
+  readonly stalled: boolean;
+  readonly reason?: string;
+}
+
+interface AdminErrorResponse {
+  readonly message: string;
+  readonly error: string;
+}
+
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+function plainResponse(body: string, status: number, allow?: string): Response {
+  return new Response(body, {
+    status,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+      ...(allow ? { allow } : {}),
+    },
+  });
+}
+
+function livenessStatus(input: {
+  readonly core: EngineCoreMetrics;
+  readonly stalled: boolean;
+}): AdminServerStatus {
+  if (input.core.state === "stopped") {
+    return { status: "fail", reason: 'engine state is "stopped"' };
+  }
+  if (input.stalled) {
+    return { status: "fail", reason: "tick loop stalled" };
+  }
+  return { status: "ok" };
+}
+
+function readinessStatus(input: {
+  readonly core: EngineCoreMetrics;
+  readonly stalled: boolean;
+  readonly mqttEnabled: boolean;
+  readonly mqttConnected: boolean;
+  readonly opcuaEnabled: boolean;
+  readonly opcuaConnected: boolean;
+}): AdminServerStatus {
+  if (input.core.state !== "running") {
+    return { status: "fail", reason: `engine state is "${input.core.state}"` };
+  }
+  if (input.stalled) {
+    return { status: "fail", reason: "tick loop stalled" };
+  }
+  if (input.mqttEnabled && !input.mqttConnected) {
+    return { status: "fail", reason: "mqtt disconnected" };
+  }
+  if (input.opcuaEnabled && !input.opcuaConnected) {
+    return { status: "fail", reason: "opcua disconnected" };
+  }
+  return { status: "ok" };
+}
+
+function commandValidationErrorResponse(
+  commandType: string,
+  correlationId: string | undefined,
+  issues: string,
+): Response {
+  return jsonResponse(
+    {
+      success: false,
+      command: commandType,
+      correlationId,
+      message: `Command validation failed: ${issues}`,
+      error:
+        "Check the command shape. Required: { type, ...fields }. See documentation for valid command types.",
+    },
+    400,
+  );
+}
+
+function extractCorrelationId(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+  const maybeCorrelationId = (payload as Record<string, unknown>)["correlationId"];
+  return typeof maybeCorrelationId === "string" ? maybeCorrelationId : undefined;
+}
+
+function extractCommandType(payload: unknown): string {
+  if (typeof payload !== "object" || payload === null) {
+    return "unknown";
+  }
+  const maybeType = (payload as Record<string, unknown>)["type"];
+  return typeof maybeType === "string" ? maybeType : "unknown";
+}
+
+function buildHealthBody(input: {
+  readonly metrics: { readonly core: EngineCoreMetrics };
+  readonly stalled: boolean;
+  readonly mqttEnabled: boolean;
+  readonly mqttConnected: boolean;
+  readonly opcuaEnabled: boolean;
+  readonly opcuaConnected: boolean;
+}): Omit<HealthResponseBody, "status" | "reason"> {
+  return {
+    simulationState: input.metrics.core.state,
+    tickCount: input.metrics.core.tickCount,
+    mqttEnabled: input.mqttEnabled,
+    mqttConnected: input.mqttEnabled ? input.mqttConnected : null,
+    opcuaEnabled: input.opcuaEnabled,
+    opcuaConnected: input.opcuaEnabled ? input.opcuaConnected : null,
+    stalled: input.stalled,
+  };
+}
+
+async function parseCommandRequest(request: Request): Promise<Response | EngineCommand> {
+  let payload: unknown;
+  try {
+    payload = await request.json();
+  } catch {
+    return jsonResponse(
+      {
+        message: "Invalid JSON in command request body.",
+        error: 'Send a valid JSON object. Example: {"type":"pause"}',
+      } satisfies AdminErrorResponse,
+      400,
+    );
+  }
+
+  const validation = EngineCommandSchema.safeParse(payload);
+  if (!validation.success) {
+    const issues = validation.error.issues
+      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      .join("; ");
+    return commandValidationErrorResponse(
+      extractCommandType(payload),
+      extractCorrelationId(payload),
+      issues,
+    );
+  }
+
+  return validation.data;
+}
+
+/**
+ * Start the Miravo admin HTTP server.
+ *
+ * - `/healthz`: liveness (process/tick loop health)
+ * - `/readyz`: readiness (engine running + adapters connected when enabled)
+ * - `/metrics`: engine metrics snapshot
+ * - `/state`: engine state snapshot
+ * - `/commands`: command execution endpoint using EngineCommandSchema
+ */
+function startAdminServer(options: AdminServerOptions): AdminServerHandle {
+  const {
+    engine,
+    host,
+    port,
+    mqttEnabled,
+    isMqttConnected,
+    opcuaEnabled,
+    isOpcuaConnected,
+    getLastTickProgressAt,
+  } = options;
+
+  const server = Bun.serve({
+    hostname: host,
+    port,
+    async fetch(request) {
+      const url = new URL(request.url);
+      const pathname = url.pathname;
+
+      const metrics = engine.getMetrics();
+
+      const now = performance.now();
+      const stallThresholdMs = Math.max(100, options.tickIntervalMs * 3);
+      const lastTickProgressAt = getLastTickProgressAt();
+      const stalled =
+        metrics.core.state === "running" &&
+        Number.isFinite(lastTickProgressAt) &&
+        now - lastTickProgressAt > stallThresholdMs;
+
+      const mqttConnected = mqttEnabled ? isMqttConnected() : false;
+      const opcuaConnected = opcuaEnabled ? isOpcuaConnected() : false;
+      const healthBody = buildHealthBody({
+        metrics,
+        stalled,
+        mqttEnabled,
+        mqttConnected,
+        opcuaEnabled,
+        opcuaConnected,
+      });
+
+      if (pathname === "/healthz") {
+        const status = livenessStatus({ core: metrics.core, stalled });
+        return jsonResponse(
+          {
+            status: status.status,
+            ...healthBody,
+            ...(status.reason ? { reason: status.reason } : {}),
+          } satisfies HealthResponseBody,
+          status.status === "ok" ? 200 : 503,
+        );
+      }
+
+      if (pathname === "/readyz") {
+        const status = readinessStatus({
+          core: metrics.core,
+          stalled,
+          mqttEnabled,
+          mqttConnected,
+          opcuaEnabled,
+          opcuaConnected,
+        });
+        return jsonResponse(
+          {
+            status: status.status,
+            ...healthBody,
+            ...(status.reason ? { reason: status.reason } : {}),
+          } satisfies HealthResponseBody,
+          status.status === "ok" ? 200 : 503,
+        );
+      }
+
+      if (pathname === "/metrics") {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        return jsonResponse(metrics, 200);
+      }
+
+      if (pathname === "/state") {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        return jsonResponse(engine.getState(), 200);
+      }
+
+      if (pathname === "/commands") {
+        if (request.method !== "POST") {
+          return plainResponse("Method Not Allowed", 405, "POST");
+        }
+        const commandOrError = await parseCommandRequest(request);
+        if (commandOrError instanceof Response) {
+          return commandOrError;
+        }
+        return jsonResponse(engine.execute(commandOrError), 200);
+      }
+
+      return plainResponse("Not Found", 404);
+    },
+  });
+
+  return {
+    endpoint: `http://${host}:${server.port}`,
+    stop() {
+      server.stop(true);
+    },
+  };
+}
+
+export { startAdminServer };
+export type { AdminEngine, AdminServerHandle, AdminServerOptions };