miravo 0.4.0 → 0.6.0

package/src/lib/le/le-template-exporter.ts

@@ -0,0 +1,459 @@
+/**
+ * Litmus Edge template export (JSON + tags CSV) from desired state.
+ *
+ * The JSON template includes hardcoded `driverId` per protocol to support direct upload to LE.
+ * The CSV template uses `driverName` since that is expected by the LE CSV import format.
+ */
+
+import type { ProtocolName } from "@miravo/shared";
+import type { ApplyDesiredState, DesiredDevice, DesiredTag } from "./le-apply.ts";
+import { buildLeDeviceHubDeviceProperties } from "./le-devicehub-properties.ts";
+import { LE_DRIVER_IDS, LE_DRIVER_NAMES } from "./le-drivers.ts";
+import { encodeDeviceMarkers } from "./le-markers.ts";
+
+const ZERO = "00000000-0000-0000-0000-000000000000";
+
+interface LeExportResult {
+  readonly templateJson: string;
+  readonly tagsCSV: string;
+}
+
+/**
+ * Convert offline desired state into a full LE template JSON + tags CSV.
+ *
+ * The JSON includes devicehub devices with registers, DT models and instances,
+ * and stats config. The CSV covers all tags across all devices in one file,
+ * with deviceId/registerId cross-referenced from the generated template.
+ */
+export function buildLeExport(desired: ApplyDesiredState, templateId: string): LeExportResult {
+  const generatedDevices = desired.devices.map((d) => generateDevice(d, templateId));
+  const modelObjects = extractModelObjects(desired, templateId);
+  const modelByName = new Map(
+    modelObjects.map((m) => [(m as Record<string, unknown>)["name"] as string, m]),
+  );
+  const instanceObjects = desired.instances.map((inst) => {
+    const model = modelByName.get(inst.dtModelName);
+    if (!model) throw new Error(`Model "${inst.dtModelName}" not found in desired state`);
+    return buildInstance(
+      crypto.randomUUID(), // LE requires a UUID, not the human-readable instanceId
+      inst.dtInstanceName,
+      inst.modelName,
+      inst.boundDeviceName,
+      templateId,
+      model as Record<string, unknown>,
+      inst.browsePath,
+    );
+  });
+
+  const template = {
+    devicehub: { Devs: generatedDevices.map((g) => g.devObj) },
+    dtwin: { models: modelObjects, instances: instanceObjects },
+    stats: buildStats(generatedDevices),
+  };
+
+  return {
+    templateJson: JSON.stringify(template, null, 2),
+    tagsCSV: buildTagsCSV(generatedDevices),
+  };
+}
+
+interface GeneratedDevice {
+  readonly id: string;
+  readonly name: string;
+  readonly instanceId: string;
+  readonly modelName: string;
+  readonly protocol: ProtocolName;
+  readonly registers: GeneratedRegister[];
+  readonly devObj: unknown;
+}
+
+interface GeneratedRegister {
+  readonly id: string;
+  readonly tag: DesiredTag;
+  readonly protocol: ProtocolName;
+}
+
+function generateDevice(device: DesiredDevice, templateId: string): GeneratedDevice {
+  const deviceId = crypto.randomUUID();
+  const registers: GeneratedRegister[] = device.tags.map((tag) => ({
+    id: crypto.randomUUID(),
+    tag,
+    protocol: device.protocol,
+  }));
+
+  const markers = encodeDeviceMarkers({
+    templateId,
+    instanceId: device.instanceId,
+    modelName: device.modelName,
+    protocol: device.protocol,
+    unsPath: device.browsePath,
+  });
+
+  const devObj = {
+    Dev: {
+      id: deviceId,
+      name: device.deviceName,
+      driverId: LE_DRIVER_IDS[device.protocol],
+      settings: buildDeviceSettings(device),
+      aliasTopics: true,
+      meta_tags: Object.fromEntries(markers.map(({ Key, Value }) => [Key, Value])),
+      debug: false,
+      stopped: true,
+      version: "0.0.1",
+    },
+    Registers: registers.map((r) => buildRegisterObj(r, deviceId)),
+  };
+
+  return {
+    id: deviceId,
+    name: device.deviceName,
+    instanceId: device.instanceId,
+    modelName: device.modelName,
+    protocol: device.protocol,
+    registers,
+    devObj,
+  };
+}
+
+function buildDeviceSettings(device: DesiredDevice): Record<string, string> {
+  const { host, port } = device.endpoint;
+  return Object.fromEntries(
+    buildLeDeviceHubDeviceProperties(device.protocol, host, port).map((item) => [
+      item.Key,
+      item.Value,
+    ]),
+  );
+}
+
+function buildRegisterObj(reg: GeneratedRegister, deviceId: string): Record<string, unknown> {
+  return {
+    id: reg.id,
+    deviceId,
+    value_type: reg.tag.valueType,
+    name: reg.tag.name,
+    tag_name: reg.tag.tagName,
+    settings: buildRegisterSettings(reg.tag, reg.protocol),
+  };
+}
+
+function buildRegisterSettings(tag: DesiredTag, protocol: ProtocolName): Record<string, string> {
+  if (protocol === "modbus") {
+    const propMap = new Map(tag.properties.map((p) => [p.Key, p.Value]));
+    return {
+      address: propMap.get("address") ?? "0",
+      count: propMap.get("count") ?? "1",
+      pollingInterval: "1000",
+    };
+  }
+  return {};
+}
+
+/**
+ * Adapt leDtJson models for /dm/template/v2 import. The ImportModel mutation
+ * and the template import use different subsets of the model schema:
+ *
+ * - version: must be absent (0 causes "restore failed")
+ * - dynamicAttributes.topicExpression: must be absent (template rejects it; instances carry it)
+ * - parameters: must include id/ownerId/ownerType (template rejects simple {name,value} form)
+ * - staticAttributes: $param.* references and __miravo_placeholder__ are resolved/sanitized
+ */
+function extractModelObjects(desired: ApplyDesiredState, templateId: string): unknown[] {
+  return desired.models.flatMap((m) => {
+    const arr = m.leDtJson as unknown[];
+    const models = Array.isArray(arr) ? arr : [arr];
+    return models.map((model) => {
+      if (!model || typeof model !== "object") return model;
+      const { version: _v, ...rest } = model as Record<string, unknown>;
+      const modelId = rest["id"] as string;
+      const modelNameLower = String(rest["name"] ?? "").toLowerCase();
+
+      const dynAttrs = rest["dynamicAttributes"] as Array<Record<string, unknown>> | undefined;
+      if (dynAttrs) {
+        rest["dynamicAttributes"] = dynAttrs.map(
+          ({ topicExpression: _te, topic: _t, ...attr }) => ({
+            ...attr,
+            topic: "",
+            unit: sanitizeUnit(String(attr["unit"] ?? "")),
+          }),
+        );
+      }
+
+      const params = rest["parameters"] as Array<Record<string, unknown>> | undefined;
+      if (params?.[0] && !params[0]["id"]) {
+        rest["parameters"] = params.map((p) => ({
+          id: crypto.randomUUID(),
+          ownerId: modelId,
+          ownerType: 2,
+          name: p["name"],
+          value: p["value"],
+        }));
+      }
+
+      const staticAttrs = rest["staticAttributes"] as Array<Record<string, unknown>> | undefined;
+      if (staticAttrs) {
+        rest["staticAttributes"] = staticAttrs.map((a) => {
+          const key = String(a["key"] ?? "");
+          let value = String(a["value"] ?? "");
+          // Resolve miravo marker placeholders at model level where possible
+          if (value === "__miravo_placeholder__") {
+            if (key === "miravo_template") value = templateId;
+            else if (key === "miravo_model") value = modelNameLower;
+            // miravo_instance cannot be resolved at model level — keep placeholder
+          }
+          // Template-exported models are Miravo-owned — mark as managed so cleanup can target them
+          if (key === "miravo_managed") value = "true";
+          // LE rejects $param.* template references and empty values
+          if (value.startsWith("$")) value = "N/A";
+          return { ...a, value };
+        });
+      }
+
+      return rest;
+    });
+  });
+}
+
+function buildInstance(
+  instanceId: string,
+  instanceName: string,
+  modelName: string,
+  deviceName: string,
+  templateId: string,
+  model: Record<string, unknown>,
+  browsePath: string,
+): Record<string, unknown> {
+  const modelId = model["id"] as string;
+  const modelNameLower = (model["name"] as string).toLowerCase();
+
+  const modelDynAttrs = (model["dynamicAttributes"] as Array<Record<string, unknown>>) ?? [];
+  const modelStaticAttrs = (model["staticAttributes"] as Array<Record<string, unknown>>) ?? [];
+  const modelParams = (model["parameters"] as Array<Record<string, unknown>>) ?? [];
+
+  const dynamicAttributes = modelDynAttrs.map((a) => {
+    const name = String(a["name"] ?? "");
+    // The LE template import format rejects `topicExpression` on model objects
+    // (extractModelObjects strips it), but instance objects require it.
+    // Reconstruct it here using the standard devicehub alias formula; the {device}
+    // parameter is resolved at runtime by LE using the instance's bound device name.
+    const topicExpression =
+      (a["topicExpression"] as string | undefined) || `devicehub.alias.{device}.${name}`;
+    return {
+      id: crypto.randomUUID(),
+      modelId: ZERO,
+      parentId: a["id"] as string,
+      instanceId,
+      topic: "",
+      name,
+      unit: sanitizeUnit(String(a["unit"] ?? "")),
+      dataType: a["dataType"] ?? "",
+      schemaId: ZERO,
+      skipParentKey: a["skipParentKey"] ?? false,
+      topicExpression,
+    };
+  });
+
+  const staticAttributes = modelStaticAttrs.map((a) => {
+    const key = String(a["key"] ?? "");
+    let value: string;
+    switch (key) {
+      case "miravo_managed":
+        value = "true";
+        break;
+      case "miravo_template":
+        value = templateId;
+        break;
+      case "miravo_model":
+        value = modelName;
+        break;
+      case "miravo_instance":
+        value = instanceName;
+        break;
+      case "uns_path":
+        value = browsePath;
+        break;
+      default:
+        value = sanitizeStaticValue(String(a["value"] ?? ""));
+    }
+    return {
+      id: crypto.randomUUID(),
+      parentId: a["id"] as string,
+      modelId: ZERO,
+      instanceId,
+      key,
+      value,
+      type: a["type"] ?? 0,
+    };
+  });
+
+  // Override model's {device} parameter with the bound device name.
+  const parameters = modelParams.map((p) => ({
+    id: crypto.randomUUID(),
+    ownerId: instanceId,
+    ownerType: 1,
+    name: p["name"] as string,
+    value: p["name"] === "device" ? deviceName : (p["value"] as string),
+  }));
+
+  return {
+    id: instanceId,
+    modelId,
+    name: instanceName,
+    topic: `digitaltwins.${modelNameLower}.${instanceName}`,
+    interval: 1,
+    image: "",
+    dynamicAttributes,
+    staticAttributes,
+    transformationBackup: null,
+    parameters,
+    flatten: false,
+    isEnabled: true,
+    publishAttributes: false,
+  };
+}
+
+function buildStats(devices: GeneratedDevice[]): Record<string, unknown> {
+  const statsDevices = devices.map((d) => ({
+    name: d.name,
+    id: d.id,
+    retention_hours: 720,
+    save_all: true,
+    topic: `devicehub.alias.${d.name}.>`,
+  }));
+
+  const timeseries = devices.map((d) => ({
+    id: d.id,
+    name: d.name,
+    topics: [`devicehub.alias.${d.name}.>`],
+  }));
+
+  return {
+    devices: statsDevices,
+    timeseries,
+    timeseries_db: { source: "internal", enabled: true },
+  };
+}
+
+/** LE DeviceHub CSV header — matches the real LE export format. */
+const CSV_HEADER =
+  "deviceId,deviceName,driverName,name,tagName,description,valueType,registerId,publishCoV,tagFormula,metaData,Retain,Qos,address,count,pollingInterval,endianness";
+
+function buildTagsCSV(devices: GeneratedDevice[]): string {
+  const rows = [CSV_HEADER];
+  for (const device of devices) {
+    for (const reg of device.registers) {
+      rows.push(buildCSVRow(device, reg));
+    }
+  }
+  return `${rows.join("\n")}\n`;
+}
+
+function buildCSVRow(device: GeneratedDevice, reg: GeneratedRegister): string {
+  const { id: deviceId, name: deviceName, instanceId, modelName, protocol } = device;
+  const { tag, id: registerId } = reg;
+  const driverName = LE_DRIVER_NAMES[protocol];
+  const propMap = new Map(tag.properties.map((p) => [p.Key, p.Value]));
+  const metaData = buildTagMetaDataJson(tag, instanceId, modelName);
+
+  switch (protocol) {
+    case "opcua":
+      return [
+        deviceId,
+        esc(deviceName),
+        esc(driverName),
+        esc(tag.name), // OPC-UA NodeId
+        esc(tag.tagName),
+        "",
+        tag.valueType,
+        registerId,
+        "false",
+        "",
+        metaData,
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+      ].join(",");
+
+    case "modbus":
+      return [
+        deviceId,
+        esc(deviceName),
+        esc(driverName),
+        "H", // Holding register
+        esc(tag.tagName),
+        "",
+        tag.valueType,
+        registerId,
+        "false",
+        "",
+        metaData,
+        "",
+        "",
+        propMap.get("address") ?? "0",
+        propMap.get("count") ?? "1",
+        "1.0000000000",
+        "AB CD",
+      ].join(",");
+
+    case "mqtt":
+      return [
+        deviceId,
+        esc(deviceName),
+        esc(driverName),
+        esc(tag.name), // MQTT topic
+        esc(tag.tagName),
+        "",
+        tag.valueType,
+        registerId,
+        "false",
+        "",
+        metaData,
+        "Disable",
+        "0",
+        "",
+        "",
+        "",
+        "",
+      ].join(",");
+
+    default: {
+      const _never: never = protocol;
+      throw new Error(`Unknown protocol: ${_never}`);
+    }
+  }
+}
+
+function buildTagMetaDataJson(tag: DesiredTag, instanceId: string, modelName: string): string {
+  const meta: Record<string, string> = {
+    uns_path: tag.unsPath,
+    model: modelName,
+    instance: instanceId,
+    access: tag.access,
+  };
+  if (tag.unit) meta["unit"] = tag.unit;
+  if (tag.euRange) {
+    meta["eu_range_min"] = String(tag.euRange[0]);
+    meta["eu_range_max"] = String(tag.euRange[1]);
+  }
+  return esc(JSON.stringify(meta));
+}
+
+function esc(value: string): string {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/** LE rejects staticAttribute values that are empty or have leading/trailing spaces. */
+function sanitizeStaticValue(value: string): string {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : "N/A";
+}
+
+/** LE rejects dynamicAttribute units containing /, ^, or %. */
+function sanitizeUnit(unit: string): string {
+  return unit.replace(/[/^%]/g, "");
+}

package/src/lib/le/le-value-types.ts

@@ -0,0 +1,23 @@
+/**
+ * Miravo → LE value type mappings (shared between export and apply).
+ */
+
+/** OPC UA: map Miravo data types to LE OPC UA Client Advanced value types. */
+export const OPCUA_VALUE_TYPE: Readonly<Record<string, string>> = {
+  Boolean: "bool",
+  Int32: "int32",
+  UInt16: "uint16",
+  UInt32: "uint32",
+  Float: "float32",
+  Double: "float64",
+  String: "string",
+};
+
+/** Modbus: map Miravo register encodings to LE Modbus TCP value types. */
+export const MODBUS_VALUE_TYPE: Readonly<Record<string, string>> = {
+  float32: "float32",
+  int32: "int32",
+  uint32: "uint32",
+  uint16: "word",
+  boolean: "word",
+};

package/src/lib/mqtt-client.ts

@@ -112,5 +112,4 @@ function disconnectClient(client: MqttClient): void {
   }
 }
 
-export type { BrokerConnectionInfo };
-export { connectToBroker, connectWithTimeout, disconnectClient, resolveBrokerInfo };
+export { connectToBroker, disconnectClient };

package/src/lib/resolve-simulation.ts

@@ -177,10 +177,5 @@ async function resolveTargetSimulation(
   };
 }
 
-export type {
-  ResolvedTargetSimulation,
-  ResolveTargetSimulationOptions,
-  SimulationResolverClient,
-  SimulationTopics,
-};
+export type { SimulationResolverClient };
 export { discoverRunningSimulations, resolveTargetSimulation };

package/src/lib/session-store.ts

@@ -0,0 +1,110 @@
+/**
+ * Server-side session store — in-memory sessions with 24h TTL.
+ *
+ * Sessions are created on successful login and validated on every request.
+ * Cookie helpers handle Set-Cookie header construction and parsing.
+ */
+
+// ---------------------------------------------------------------------------
+// Session types
+// ---------------------------------------------------------------------------
+
+export interface Session {
+  readonly id: string;
+  readonly username: string;
+  readonly createdAt: number;
+}
+
+export interface SessionStore {
+  /** Create a new session for the given username. */
+  create(username: string): Session;
+  /** Validate a session ID. Returns the session or null if expired/missing. */
+  validate(sessionId: string): Session | null;
+  /** Destroy a specific session. */
+  destroy(sessionId: string): void;
+  /** Clear all sessions (used on server stop). */
+  clear(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const SESSION_TTL_SECONDS = 24 * 60 * 60;
+const COOKIE_NAME = "miravo_session";
+const SWEEP_THRESHOLD = 50;
+
+// ---------------------------------------------------------------------------
+// Session store
+// ---------------------------------------------------------------------------
+
+export function createSessionStore(): SessionStore {
+  const sessions = new Map<string, Session>();
+
+  function sweepExpired(): void {
+    const now = Date.now();
+    for (const [id, s] of sessions) {
+      if (now - s.createdAt > SESSION_TTL_MS) sessions.delete(id);
+    }
+  }
+
+  return {
+    create(username: string): Session {
+      if (sessions.size >= SWEEP_THRESHOLD) sweepExpired();
+      const session: Session = {
+        id: crypto.randomUUID(),
+        username,
+        createdAt: Date.now(),
+      };
+      sessions.set(session.id, session);
+      return session;
+    },
+
+    validate(sessionId: string): Session | null {
+      const session = sessions.get(sessionId);
+      if (!session) return null;
+      if (Date.now() - session.createdAt > SESSION_TTL_MS) {
+        sessions.delete(sessionId);
+        return null;
+      }
+      return session;
+    },
+
+    destroy(sessionId: string): void {
+      sessions.delete(sessionId);
+    },
+
+    clear(): void {
+      sessions.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+
+/** Build a Set-Cookie header value for a new session. */
+export function buildSessionCookie(sessionId: string): string {
+  return `${COOKIE_NAME}=${sessionId}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_TTL_SECONDS}`;
+}
+
+/** Build a Set-Cookie header value that clears the session cookie. */
+export function buildClearCookie(): string {
+  return `${COOKIE_NAME}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`;
+}
+
+/** Extract the session ID from the Cookie header of a request. Returns null if absent. */
+export function extractSessionId(request: Request): string | null {
+  const header = request.headers.get("cookie");
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const [key, ...rest] = part.split("=");
+    if (key?.trim() === COOKIE_NAME) {
+      const value = rest.join("=").trim();
+      if (value.length > 0) return value;
+    }
+  }
+  return null;
+}