@tsplc/opcua 0.0.0-stage → 0.2.0

package/src/variables.ts

@@ -0,0 +1,309 @@
+/**
+ * Reads and writes PLC symbols over an OPC UA session.
+ *
+ * Every symbol's IEC type comes from the generated contract. Reads turn OPC UA
+ * values into `Reading`s and mark anything unexpected as bad quality; writes
+ * validate the whole patch before sending, so a bad value never reaches the PLC.
+ */
+import type { Reading, Variable } from "./types";
+import {
+  AttributeIds,
+  DataType,
+  type DataValue,
+  type ReadValueIdOptions,
+  type StatusCode,
+  VariantArrayType,
+  type WriteValueOptions,
+} from "./native";
+
+interface ReadSession {
+  read: (nodes: Array<ReadValueIdOptions>, maxAge: number) => Promise<Array<DataValue>>;
+}
+
+export interface VariableSession extends ReadSession {
+  write: (nodes: Array<WriteValueOptions>) => Promise<Array<StatusCode>>;
+}
+
+/** Nodes per OPC UA read or write request. */
+const BATCH_SIZE = 50;
+
+// --- IEC type mapping -------------------------------------------------------
+
+const isInteger =
+  (min: number, max: number) =>
+  (value: unknown): value is number =>
+    typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+
+/** The OPC UA type each published scalar arrives as, and the values it accepts. */
+const scalarTypes: Record<string, { dataType: DataType; accepts: (value: unknown) => boolean }> = {
+  BOOL: {
+    accepts: (value) => typeof value === "boolean",
+    dataType: DataType.Boolean,
+  },
+  BYTE: { accepts: isInteger(0, 255), dataType: DataType.Byte },
+  DINT: {
+    accepts: isInteger(-2_147_483_648, 2_147_483_647),
+    dataType: DataType.Int32,
+  },
+  DWORD: { accepts: isInteger(0, 4_294_967_295), dataType: DataType.UInt32 },
+  INT: { accepts: isInteger(-32_768, 32_767), dataType: DataType.Int16 },
+  LREAL: {
+    accepts: (value) => typeof value === "number" && Number.isFinite(value),
+    dataType: DataType.Double,
+  },
+  REAL: {
+    accepts: (value) => typeof value === "number" && Number.isFinite(value),
+    dataType: DataType.Float,
+  },
+  SINT: { accepts: isInteger(-128, 127), dataType: DataType.SByte },
+  UDINT: { accepts: isInteger(0, 4_294_967_295), dataType: DataType.UInt32 },
+  UINT: { accepts: isInteger(0, 65_535), dataType: DataType.UInt16 },
+  USINT: { accepts: isInteger(0, 255), dataType: DataType.Byte },
+  WORD: { accepts: isInteger(0, 65_535), dataType: DataType.UInt16 },
+};
+
+const scalarTypeFor = (type: string) => {
+  const capacity = /^STRING\((\d+)\)$/.exec(type)?.[1];
+  if (capacity === undefined) {
+    return scalarTypes[type];
+  }
+
+  return {
+    accepts: (value: unknown) =>
+      typeof value === "string" &&
+      !value.includes("\0") &&
+      Buffer.byteLength(value, "utf8") <= Number(capacity),
+    dataType: DataType.String,
+  };
+};
+
+/** Length of an `ARRAY[0..n] OF BYTE` scanner buffer, or null for any other type. */
+const byteBufferLength = (type: string) => {
+  const match = /^ARRAY\[0\.\.(\d+)\] OF BYTE$/.exec(type);
+  return match ? Number(match[1]) + 1 : null;
+};
+
+const byteArrayValue = (value: unknown, length: number): Array<number> | null => {
+  const bytes: unknown = value instanceof Uint8Array ? Array.from(value) : value;
+  if (!Array.isArray(bytes) || bytes.length !== length) {
+    return null;
+  }
+  return bytes.every(isInteger(0, 255)) ? bytes : null;
+};
+
+// --- Reads ------------------------------------------------------------------
+
+const badReading = (status: string): Reading => ({
+  quality: "bad",
+  status,
+  value: null,
+});
+
+const toReading = (variable: Variable, data: DataValue): Reading => {
+  if (!data.statusCode.isGood()) {
+    return badReading(data.statusCode.toString());
+  }
+
+  const value: unknown = data.value.value;
+  const bufferLength = byteBufferLength(variable.type);
+  if (bufferLength !== null) {
+    const bytes = byteArrayValue(value, bufferLength);
+    // CODESYS may publish a byte buffer as Byte[] or as a scalar ByteString.
+    const typeMatches =
+      (data.value.dataType === DataType.Byte && data.value.arrayType === VariantArrayType.Array) ||
+      (data.value.dataType === DataType.ByteString &&
+        data.value.arrayType === VariantArrayType.Scalar);
+    if (!typeMatches || !bytes) {
+      return badReading("Unexpected OPC UA byte buffer type or length");
+    }
+    return {
+      quality: "good",
+      status: data.statusCode.toString(),
+      value: bytes,
+    };
+  }
+
+  const scalar =
+    typeof value === "boolean" ||
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isFinite(value));
+  if (
+    !scalar ||
+    data.value.dataType !== scalarTypeFor(variable.type)?.dataType ||
+    data.value.arrayType !== VariantArrayType.Scalar
+  ) {
+    return badReading("Unexpected OPC UA data type");
+  }
+  return { quality: "good", status: data.statusCode.toString(), value };
+};
+
+/** Reads `selected` in batches; symbols without a published node are reported unavailable. */
+export const readVariables = async (
+  session: ReadSession,
+  nodes: ReadonlyMap<string, string>,
+  selected: ReadonlyArray<Variable>,
+): Promise<Record<string, Reading>> => {
+  const readings: Record<string, Reading> = Object.fromEntries(
+    selected.map(({ path }) => [
+      path,
+      { quality: "unavailable", status: "Symbol not published", value: null },
+    ]),
+  );
+  const bound = selected.flatMap((variable) => {
+    const nodeId = nodes.get(variable.path);
+    return nodeId ? [{ nodeId, variable }] : [];
+  });
+
+  const batches = Array.from({ length: Math.ceil(bound.length / BATCH_SIZE) }, (_, index) =>
+    bound.slice(index * BATCH_SIZE, (index + 1) * BATCH_SIZE),
+  );
+  // Batches go out together so a large read costs about one round trip.
+  await Promise.all(
+    batches.map(async (batch) => {
+      const values = await session.read(
+        batch.map(({ nodeId }) => ({ attributeId: AttributeIds.Value, nodeId })),
+        0,
+      );
+      if (values.length !== batch.length) {
+        throw new Error("Incomplete OPC UA read response");
+      }
+      for (const [index, { variable }] of batch.entries()) {
+        const data = values[index];
+        if (!data) {
+          throw new Error("Missing OPC UA value in read response");
+        }
+        readings[variable.path] = toReading(variable, data);
+      }
+    }),
+  );
+  return readings;
+};
+
+// --- Writes -----------------------------------------------------------------
+
+export interface WriteResult {
+  path: string;
+  status: string;
+  /** null means the request outcome is unknown after a transport failure. */
+  written: boolean | null;
+}
+
+/** Carries every field's outcome so the caller can see what reached the PLC before retrying. */
+export class VariableWriteError extends Error {
+  readonly results: ReadonlyArray<WriteResult>;
+  constructor(results: ReadonlyArray<WriteResult>, cause?: unknown) {
+    super("PLC write did not succeed for every field; inspect results before retrying", { cause });
+    this.name = "VariableWriteError";
+    this.results = results;
+  }
+}
+
+const notAttempted = (updates: ReadonlyArray<{ variable: Variable }>) =>
+  updates.map(({ variable }) => ({
+    path: variable.path,
+    status: "Not attempted",
+    written: false,
+  }));
+
+/** Validates the value and builds its write request; byte buffers need the node's current representation. */
+const prepareWrite = (
+  session: ReadSession,
+  nodes: ReadonlyMap<string, string>,
+  { variable, value }: { variable: Variable; value: unknown },
+) => {
+  const nodeId = nodes.get(variable.path);
+  if (!nodeId) {
+    throw new Error(`Symbol not published: ${variable.path}`);
+  }
+  const invalid = new Error(`Invalid ${variable.type} value for ${variable.path}`);
+
+  const bufferLength = byteBufferLength(variable.type);
+  if (bufferLength === null) {
+    const scalarType = scalarTypeFor(variable.type);
+    if (!scalarType?.accepts(value)) {
+      throw invalid;
+    }
+    const request: WriteValueOptions = {
+      attributeId: AttributeIds.Value,
+      nodeId,
+      value: {
+        value: {
+          arrayType: VariantArrayType.Scalar,
+          dataType: scalarType.dataType,
+          value,
+        },
+      },
+    };
+    return () => Promise.resolve(request);
+  }
+
+  const bytes = byteArrayValue(value, bufferLength);
+  if (!bytes) {
+    throw invalid;
+  }
+  return async (): Promise<WriteValueOptions> => {
+    // Write back in whichever representation (Byte[] or ByteString) the node publishes.
+    const [current] = await session.read([{ attributeId: AttributeIds.Value, nodeId }], 0);
+    if (!current || toReading(variable, current).quality !== "good") {
+      throw new Error(`Cannot determine byte-buffer representation: ${variable.path}`);
+    }
+    return {
+      attributeId: AttributeIds.Value,
+      nodeId,
+      value: {
+        value: {
+          arrayType: current.value.arrayType,
+          dataType: current.value.dataType,
+          value: Buffer.from(bytes),
+        },
+      },
+    };
+  };
+};
+
+/**
+ * Writes `updates` in order, stopping at the first batch that does not fully
+ * succeed. Throws `VariableWriteError` with each field's outcome.
+ */
+export const writeVariables = async (
+  session: VariableSession,
+  nodes: ReadonlyMap<string, string>,
+  updates: ReadonlyArray<{ variable: Variable; value: unknown }>,
+): Promise<ReadonlyArray<WriteResult>> => {
+  // Validate the whole patch and all bindings before sending any writes.
+  const prepared = updates.map((update) => prepareWrite(session, nodes, update));
+  const requests = await Promise.all(prepared.map((build) => build()));
+
+  const results: Array<WriteResult> = [];
+  for (let offset = 0; offset < requests.length; offset += BATCH_SIZE) {
+    const batch = requests.slice(offset, offset + BATCH_SIZE);
+    const batchUpdates = updates.slice(offset, offset + batch.length);
+    const remaining = updates.slice(offset + batch.length);
+    const statuses = await session.write(batch).catch((cause: unknown) => {
+      throw new VariableWriteError(
+        [
+          ...results,
+          ...batchUpdates.map(({ variable }) => ({
+            path: variable.path,
+            status: "Unknown write outcome",
+            written: null,
+          })),
+          ...notAttempted(remaining),
+        ],
+        cause,
+      );
+    });
+    for (const [index, { variable }] of batchUpdates.entries()) {
+      const status = statuses[index];
+      results.push({
+        path: variable.path,
+        status: status?.toString() ?? "Missing write result",
+        written: status ? status.isGood() : null,
+      });
+    }
+    if (statuses.length !== batch.length || results.some(({ written }) => written !== true)) {
+      throw new VariableWriteError([...results, ...notAttempted(remaining)]);
+    }
+  }
+  return results;
+};