miravo 0.2.2 → 0.3.0

package/src/lib/admin-server.ts

@@ -1,25 +1,88 @@
-import type { EngineCoreMetrics, EngineStateSnapshot } from "@miravo/core";
-import type { CommandResult, EngineCommand } from "@miravo/shared";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type {
+  EngineCoreMetrics,
+  EngineStateSnapshot,
+  EventLogQuery,
+  EventLogResult,
+  InstanceDetail,
+  ModelSchema,
+  TemplateRun,
+} from "@miravo/core";
+import type { CatalogTemplate, CommandResult, EngineCommand, LoggedEvent } from "@miravo/shared";
 import { EngineCommandSchema } from "@miravo/shared";
+import type { WSClientData } from "./ws-hub.ts";
+import { ALL_CHANNELS, WSHub } from "./ws-hub.ts";
+
+/** Valid event types for the /events endpoint, derived from LoggedEvent discriminant. */
+const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<LoggedEvent["type"]>([
+  "fault:triggered",
+  "fault:cleared",
+  "lifecycle:changed",
+  "instance:created",
+  "instance:removed",
+  "engine:state-changed",
+]);
 
 interface AdminEngine {
-  getMetrics(): { readonly core: EngineCoreMetrics };
+  getMetrics(): {
+    readonly core: EngineCoreMetrics;
+    readonly adapters: ReadonlyArray<{
+      readonly name: string;
+      readonly metrics: { readonly connected: boolean };
+    }>;
+  };
+  getAvailableAdapters(): ReadonlyArray<{
+    readonly name: string;
+    readonly enabled: boolean;
+  }>;
   getState(): EngineStateSnapshot;
-  execute(command: EngineCommand): CommandResult;
+  execute(command: EngineCommand): Promise<CommandResult>;
+  getInstanceDetail(id: string): InstanceDetail | undefined;
+  getModelSchema(name: string): ModelSchema | undefined;
+  getEventLog(query?: EventLogQuery): EventLogResult;
+  getRunningTemplates(): readonly TemplateRun[];
 }
 
-interface AdminServerOptions {
-  readonly engine: AdminEngine;
+/** Network binding configuration. */
+interface AdminServerNetworkOptions {
   readonly host: string;
   readonly port: number;
   readonly tickIntervalMs: number;
-  readonly mqttEnabled: boolean;
-  readonly isMqttConnected: () => boolean;
-  readonly opcuaEnabled: boolean;
-  readonly isOpcuaConnected: () => boolean;
+}
+
+/** Protocol adapter status configuration. */
+interface AdminServerProtocolOptions {
   readonly getLastTickProgressAt: () => number;
 }
 
+/** WebSocket streaming configuration. When provided, enables the /ws endpoint. */
+interface AdminServerWSOptions {
+  readonly bus: import("@miravo/core").EventBus;
+  readonly getEngineState: () => import("@miravo/shared").EngineRunState;
+  readonly getTickInfo: () => { tick: number; simulationTime: number; instanceCount: number };
+}
+
+interface AdminServerOptions {
+  readonly engine: AdminEngine;
+  readonly network: AdminServerNetworkOptions;
+  readonly protocols: AdminServerProtocolOptions;
+  /** WebSocket streaming. When provided, enables /ws endpoint. */
+  readonly ws?: AdminServerWSOptions | undefined;
+  /** Bearer token for mutation endpoints. When set, POST /commands requires Authorization header. */
+  readonly adminToken?: string | undefined;
+  /** Path to console static assets directory. When set, serves the SPA at non-API routes. */
+  readonly consoleDir?: string | undefined;
+  /** Template catalog provider for GET /catalog/templates. */
+  readonly getCatalog?: (() => readonly CatalogTemplate[]) | undefined;
+  /** Simulation name for daemon identity verification via /readyz. */
+  readonly simulationName?: string | undefined;
+  /** Run ID for daemon identity verification via /readyz. */
+  readonly runId?: string | undefined;
+  /** Callback to request graceful shutdown. Used by POST /shutdown. */
+  readonly requestShutdown?: ((reason: string) => void) | undefined;
+}
+
 interface AdminServerStatus {
   readonly status: "ok" | "fail";
   readonly reason?: string;
@@ -27,6 +90,7 @@ interface AdminServerStatus {
 
 interface AdminServerHandle {
   readonly endpoint: string;
+  readonly wsHub: WSHub | null;
   stop(): void;
 }
 
@@ -40,6 +104,8 @@ interface HealthResponseBody {
   readonly opcuaConnected: boolean | null;
   readonly stalled: boolean;
   readonly reason?: string;
+  readonly simulationName?: string;
+  readonly runId?: string;
 }
 
 interface AdminErrorResponse {
@@ -196,58 +262,168 @@ async function parseCommandRequest(request: Request): Promise<Response | EngineC
  * - `/commands`: command execution endpoint using EngineCommandSchema
  */
 function startAdminServer(options: AdminServerOptions): AdminServerHandle {
-  const {
-    engine,
-    host,
-    port,
-    mqttEnabled,
-    isMqttConnected,
-    opcuaEnabled,
-    isOpcuaConnected,
-    getLastTickProgressAt,
-  } = options;
+  const { engine } = options;
+  const { host, port } = options.network;
+  const { getLastTickProgressAt } = options.protocols;
+
+  const adminToken = options.adminToken;
+  const isLoopback = host === "127.0.0.1" || host === "localhost" || host === "::1";
+  const isWildcard = host === "0.0.0.0" || host === "::";
+
+  /** Check bearer token on mutation endpoints. Returns error Response or null if OK. */
+  function checkAuth(request: Request): Response | null {
+    if (!adminToken) return null;
+    const authHeader = request.headers.get("authorization");
+    if (authHeader === `Bearer ${adminToken}`) return null;
+    return jsonResponse(
+      { message: "Unauthorized.", error: "Provide a valid Authorization: Bearer <token> header." },
+      401,
+    );
+  }
+
+  /** Require an admin token for remote mutation endpoints. */
+  function checkRemoteMutationAuthConfigured(): Response | null {
+    if (isLoopback || adminToken) return null;
+    return jsonResponse(
+      {
+        message: "Mutation endpoints require authentication.",
+        error: "Set MIRAVO_ADMIN_TOKEN when binding to a non-loopback address.",
+      },
+      403,
+    );
+  }
+
+  /**
+   * Require Content-Type: application/json on mutation endpoints.
+   * This forces cross-origin requests through a CORS preflight (since application/json
+   * is not a CORS-safe content type), which blocks form CSRF and no-cors fetch attacks.
+   */
+  function checkContentType(request: Request): Response | null {
+    const ct = request.headers.get("content-type");
+    if (ct && ct.split(";")[0]?.trim() === "application/json") return null;
+    return jsonResponse(
+      {
+        message: "Unsupported Media Type.",
+        error: "Content-Type must be application/json.",
+      },
+      415,
+    );
+  }
+
+  /** Check Origin header on mutation endpoints for non-loopback binds. Returns error Response or null if OK. */
+  function checkOrigin(request: Request): Response | null {
+    // Loopback and wildcard binds skip Origin checking — wildcard (0.0.0.0)
+    // accepts connections from any interface, so we can't match a specific host.
+    if (isLoopback || isWildcard) return null;
+    const origin = request.headers.get("origin");
+    if (!origin) return null; // No origin = non-browser client, allow
+    try {
+      const originHost = new URL(origin).hostname;
+      if (originHost === host || originHost === "localhost" || originHost === "127.0.0.1")
+        return null;
+    } catch {
+      // Malformed origin
+    }
+    return jsonResponse({ message: "Forbidden.", error: "Origin not allowed." }, 403);
+  }
+
+  // Create WebSocket hub if ws config is provided
+  const wsHub = options.ws
+    ? new WSHub({
+        bus: options.ws.bus,
+        getEngineState: options.ws.getEngineState,
+        getTickInfo: options.ws.getTickInfo,
+      })
+    : null;
+
+  // Pre-resolve console dir and index.html once at startup (avoids per-request exists() check).
+  // Verify the file exists so we don't silently serve a missing build as a 200.
+  const consoleDir = options.consoleDir ? resolve(options.consoleDir) : null;
+  const consoleIndexPath = consoleDir ? `${consoleDir}/index.html` : null;
+  const consoleIndexFile =
+    consoleIndexPath && existsSync(consoleIndexPath) ? Bun.file(consoleIndexPath) : null;
 
   const server = Bun.serve({
     hostname: host,
     port,
-    async fetch(request) {
+    async fetch(request, server) {
       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,
-        );
+      // WebSocket upgrade for /ws
+      if (pathname === "/ws") {
+        if (!wsHub) {
+          return plainResponse("WebSocket not available", 503);
+        }
+        const originBlock = checkOrigin(request);
+        if (originBlock) return originBlock;
+        const upgraded = server.upgrade(request, {
+          // WSClientData — Bun's untyped websocket generic requires the cast
+          data: { channels: new Set(ALL_CHANNELS) } as unknown as undefined,
+        });
+        if (!upgraded) {
+          return plainResponse("WebSocket upgrade failed", 400);
+        }
+        // Bun requires a Response return, but upgrade() consumes the request
+        return undefined as unknown as Response;
       }
 
-      if (pathname === "/readyz") {
+      // Health/metrics routes — compute expensive metrics only when needed
+      if (pathname === "/healthz" || pathname === "/readyz" || pathname === "/metrics") {
+        if (pathname === "/metrics" && request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+
+        const metrics = engine.getMetrics();
+
+        if (pathname === "/metrics") {
+          return jsonResponse(metrics, 200);
+        }
+
+        const now = performance.now();
+        const stallThresholdMs = Math.max(100, options.network.tickIntervalMs * 3);
+        const lastTickProgressAt = getLastTickProgressAt();
+        const stalled =
+          metrics.core.state === "running" &&
+          Number.isFinite(lastTickProgressAt) &&
+          now - lastTickProgressAt > stallThresholdMs;
+
+        const availableAdapters = engine.getAvailableAdapters();
+        const mqttEnabled = availableAdapters.some(
+          (adapter) => adapter.name === "mqtt" && adapter.enabled,
+        );
+        const opcuaEnabled = availableAdapters.some(
+          (adapter) => adapter.name === "opcua" && adapter.enabled,
+        );
+
+        const mqttConnected = mqttEnabled
+          ? (metrics.adapters.find((a) => a.name === "mqtt")?.metrics.connected ?? false)
+          : false;
+        const opcuaConnected = opcuaEnabled
+          ? (metrics.adapters.find((a) => a.name === "opcua")?.metrics.connected ?? false)
+          : 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,
+          );
+        }
+
+        // /readyz
         const status = readinessStatus({
           core: metrics.core,
           stalled,
@@ -261,18 +437,13 @@ function startAdminServer(options: AdminServerOptions): AdminServerHandle {
             status: status.status,
             ...healthBody,
             ...(status.reason ? { reason: status.reason } : {}),
+            ...(options.simulationName ? { simulationName: options.simulationName } : {}),
+            ...(options.runId ? { runId: options.runId } : {}),
           } 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");
@@ -284,24 +455,204 @@ function startAdminServer(options: AdminServerOptions): AdminServerHandle {
         if (request.method !== "POST") {
           return plainResponse("Method Not Allowed", 405, "POST");
         }
+        const authConfigBlock = checkRemoteMutationAuthConfigured();
+        if (authConfigBlock) return authConfigBlock;
+        const ctBlock = checkContentType(request);
+        if (ctBlock) return ctBlock;
+        const originBlock = checkOrigin(request);
+        if (originBlock) return originBlock;
+        const authBlock = checkAuth(request);
+        if (authBlock) return authBlock;
         const commandOrError = await parseCommandRequest(request);
         if (commandOrError instanceof Response) {
           return commandOrError;
         }
-        return jsonResponse(engine.execute(commandOrError), 200);
+        return jsonResponse(await engine.execute(commandOrError), 200);
+      }
+
+      // POST /shutdown — graceful shutdown for daemon mode
+      if (pathname === "/shutdown") {
+        if (request.method !== "POST") {
+          return plainResponse("Method Not Allowed", 405, "POST");
+        }
+        if (!options.requestShutdown) {
+          return jsonResponse(
+            {
+              message: "Shutdown not available.",
+              error: "This server does not support remote shutdown.",
+            },
+            501,
+          );
+        }
+        const authConfigBlock = checkRemoteMutationAuthConfigured();
+        if (authConfigBlock) return authConfigBlock;
+        const shutdownCtBlock = checkContentType(request);
+        if (shutdownCtBlock) return shutdownCtBlock;
+        const originBlock = checkOrigin(request);
+        if (originBlock) return originBlock;
+        const authBlock = checkAuth(request);
+        if (authBlock) return authBlock;
+
+        let reason = "remote shutdown request";
+        try {
+          const body = (await request.json()) as unknown;
+          if (typeof body === "object" && body !== null && "reason" in body) {
+            const maybeReason = (body as Record<string, unknown>)["reason"];
+            if (typeof maybeReason === "string" && maybeReason.length > 0) {
+              reason = maybeReason;
+            }
+          }
+        } catch {
+          // No body or invalid JSON — use default reason
+        }
+
+        options.requestShutdown(reason);
+        return jsonResponse({ status: "shutting_down" }, 200);
+      }
+
+      // --- New REST endpoints (Phase 1c) ---
+
+      // GET /instances/:id
+      if (pathname.startsWith("/instances/")) {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        const instanceId = pathname.slice("/instances/".length);
+        if (!instanceId) {
+          return jsonResponse(
+            { message: "Missing instance ID.", error: "Use /instances/{id}" },
+            400,
+          );
+        }
+        const detail = engine.getInstanceDetail(instanceId);
+        if (!detail) {
+          return jsonResponse(
+            { message: `Instance "${instanceId}" not found.`, error: "Check the instance ID." },
+            404,
+          );
+        }
+        return jsonResponse(detail, 200);
+      }
+
+      // GET /models/:name
+      if (pathname.startsWith("/models/")) {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        const modelName = pathname.slice("/models/".length);
+        if (!modelName) {
+          return jsonResponse({ message: "Missing model name.", error: "Use /models/{name}" }, 400);
+        }
+        const schema = engine.getModelSchema(modelName);
+        if (!schema) {
+          return jsonResponse(
+            { message: `Model "${modelName}" not found.`, error: "Check the model name." },
+            404,
+          );
+        }
+        return jsonResponse(schema, 200);
+      }
+
+      // GET /events
+      if (pathname === "/events") {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        const typeParam = url.searchParams.get("type");
+        if (typeParam && !VALID_EVENT_TYPES.has(typeParam)) {
+          return jsonResponse(
+            {
+              message: `Invalid event type "${typeParam}".`,
+              error: `Valid types: ${[...VALID_EVENT_TYPES].join(", ")}`,
+            },
+            400,
+          );
+        }
+        const instanceIdParam = url.searchParams.get("instanceId");
+        const limitRaw = url.searchParams.get("limit");
+        const cursorRaw = url.searchParams.get("cursor");
+        const query: EventLogQuery = {};
+        if (typeParam)
+          (query as { type: EventLogQuery["type"] }).type = typeParam as EventLogQuery["type"];
+        if (instanceIdParam) (query as { instanceId: string }).instanceId = instanceIdParam;
+        const parsedLimit = limitRaw ? Number.parseInt(limitRaw, 10) : 0;
+        if (parsedLimit > 0 && Number.isFinite(parsedLimit))
+          (query as { limit: number }).limit = parsedLimit;
+        const parsedCursor = cursorRaw ? Number.parseInt(cursorRaw, 10) : Number.NaN;
+        if (Number.isFinite(parsedCursor)) (query as { cursor: number }).cursor = parsedCursor;
+        return jsonResponse(engine.getEventLog(query), 200);
+      }
+
+      // GET /catalog/templates
+      if (pathname === "/catalog/templates") {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        const catalog = options.getCatalog ? options.getCatalog() : [];
+        return jsonResponse(catalog, 200);
+      }
+
+      // GET /running-templates
+      if (pathname === "/running-templates") {
+        if (request.method !== "GET") {
+          return plainResponse("Method Not Allowed", 405, "GET");
+        }
+        return jsonResponse(engine.getRunningTemplates(), 200);
+      }
+
+      // --- Console static file serving ---
+      if (consoleIndexFile && consoleDir) {
+        if (pathname !== "/") {
+          // Resolve and verify the path stays within consoleDir to prevent traversal.
+          const resolvedFile = resolve(consoleDir, `.${pathname}`);
+          if (resolvedFile.startsWith(`${consoleDir}/`)) {
+            const file = Bun.file(resolvedFile);
+            if (await file.exists()) {
+              return new Response(file);
+            }
+          }
+        }
+        // SPA fallback: serve pre-verified index.html
+        return new Response(consoleIndexFile);
       }
 
       return plainResponse("Not Found", 404);
     },
+    websocket: wsHub
+      ? {
+          open(ws: import("bun").ServerWebSocket<unknown>) {
+            wsHub.onOpen(ws as import("bun").ServerWebSocket<WSClientData>);
+          },
+          message(ws: import("bun").ServerWebSocket<unknown>, message: string | Buffer) {
+            wsHub.onMessage(ws as import("bun").ServerWebSocket<WSClientData>, message);
+          },
+          close(ws: import("bun").ServerWebSocket<unknown>) {
+            wsHub.onClose(ws as import("bun").ServerWebSocket<WSClientData>);
+          },
+        }
+      : {
+          open() {},
+          message() {},
+          close() {},
+        },
   });
 
   return {
     endpoint: `http://${host}:${server.port}`,
+    wsHub,
     stop() {
+      wsHub?.close();
       server.stop(true);
     },
   };
 }
 
+export type {
+  AdminEngine,
+  AdminServerHandle,
+  AdminServerNetworkOptions,
+  AdminServerOptions,
+  AdminServerProtocolOptions,
+  AdminServerWSOptions,
+};
 export { startAdminServer };
-export type { AdminEngine, AdminServerHandle, AdminServerOptions };