@synefex/node-red-sila2 0.1.0

package/src/call-command/sila-call-command.html

@@ -0,0 +1,137 @@
+<script type="text/javascript">
+  RED.nodes.registerType("sila-call-command", {
+    // Space (not '-') in the category: Node-RED 4 splits ASCII-dashed
+    // categories at the first '-' to form a collapsible parent group,
+    // so "Synefex-SiLA-2" would share a section with "Synefex-LADS".
+    // The space survives Node-RED's escape-then-display round-trip
+    // (space → '_' in IDs, '_' → space in the displayed label) and
+    // doesn't trigger the split, giving us a standalone section.
+    category: "Synefex SiLA 2",
+    color: "#A6BBCF",
+    defaults: {
+      name: { value: "" },
+      connection: { value: "", type: "sila-connection", required: true },
+      feature: { value: "" },
+      featureType: { value: "str" },
+      command: { value: "" },
+      commandType: { value: "str" },
+      params: { value: "{}" },
+      paramsType: { value: "json" },
+      outputProperty: { value: "payload" },
+      outputPropertyType: { value: "msg" }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-bolt",
+    paletteLabel: "SiLA 2 call",
+    label: function () {
+      if (this.name) return this.name;
+      if (this.commandType === "str" && this.command) return "call " + this.command;
+      return "SiLA 2 call";
+    },
+    oneditprepare: function () {
+      $("#node-input-feature").typedInput({
+        default: this.featureType || "str",
+        typeField: $("#node-input-featureType"),
+        types: ["str", "msg", "flow", "global", "env"]
+      });
+      $("#node-input-command").typedInput({
+        default: this.commandType || "str",
+        typeField: $("#node-input-commandType"),
+        types: ["str", "msg", "flow", "global", "env"]
+      });
+      $("#node-input-params").typedInput({
+        default: this.paramsType || "json",
+        typeField: $("#node-input-paramsType"),
+        types: ["json", "msg", "flow", "global"]
+      });
+      $("#node-input-outputProperty").typedInput({
+        default: this.outputPropertyType || "msg",
+        typeField: $("#node-input-outputPropertyType"),
+        types: ["msg", "flow", "global"]
+      });
+
+      // Picker: cascading Feature → Command dropdowns. Writes the chosen
+      // values into the manual fields; users can also still type.
+      if (window.SilaPicker) {
+        window.SilaPicker.attach({
+          kind: "command",
+          connectionFieldId: "node-input-connection",
+          featureFieldId: "node-input-feature",
+          methodFieldId: "node-input-command",
+        });
+      }
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="sila-call-command">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name">
+  </div>
+  <div class="form-row">
+    <label for="node-input-connection"><i class="fa fa-server"></i> Connection</label>
+    <input type="text" id="node-input-connection">
+  </div>
+  <div class="form-row">
+    <label for="node-input-feature"><i class="fa fa-cube"></i> Feature</label>
+    <input type="text" id="node-input-feature" placeholder="MettlerToledoAX205Controller">
+    <input type="hidden" id="node-input-featureType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-command"><i class="fa fa-bolt"></i> Command</label>
+    <input type="text" id="node-input-command" placeholder="GetStableWeight">
+    <input type="hidden" id="node-input-commandType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-params"><i class="fa fa-list"></i> Parameters</label>
+    <input type="text" id="node-input-params">
+    <input type="hidden" id="node-input-paramsType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-outputProperty"><i class="fa fa-arrow-right"></i> Output to</label>
+    <input type="text" id="node-input-outputProperty">
+    <input type="hidden" id="node-input-outputPropertyType">
+  </div>
+</script>
+
+<script type="text/html" data-help-name="sila-call-command">
+  <p>Call an unobservable SiLA 2 command on a feature.</p>
+
+  <h3>Configuration</h3>
+  <dl class="message-properties">
+    <dt>Feature <span class="property-type">string</span></dt>
+    <dd>The feature identifier &mdash; short name (e.g.
+    <code>MettlerToledoAX205Controller</code>) or full proto-qualified
+    name. The connection node resolves short names via gRPC reflection
+    (case-insensitive match against the tail segment of the proto service
+    name).</dd>
+    <dt>Command <span class="property-type">string</span></dt>
+    <dd>The command name as declared in the feature (e.g.
+    <code>GetStableWeight</code>, <code>Tare</code>, <code>CloseDoor</code>).</dd>
+    <dt>Parameters <span class="property-type">object</span></dt>
+    <dd>Plain object encoded into the command's <code>_Parameters</code>
+    message. Use <code>{}</code> for parameter-less commands. Field
+    values can be raw natives &mdash; SiLA 2 basic-type wrapping is
+    applied at encode time via the protobufjs schema fetched by
+    reflection.</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <p>The decoded <code>_Responses</code> message with SiLA 2 basic-type
+  wrappers (<code>{ value: ... }</code>) automatically unwrapped. Example
+  for <code>GetStableWeight</code>:</p>
+  <pre>{ Status: "S S", WeightValue: 82.6824, Unit: "g" }</pre>
+
+  <h3>Errors</h3>
+  <p>gRPC errors propagate via <code>done(err)</code>. SiLA 2 framework
+  errors (validation, undefined execution, defined errors) currently
+  surface as generic gRPC errors &mdash; full <code>sila-error-bin</code>
+  trailer decoding is on the roadmap.</p>
+
+  <h3>Observable commands</h3>
+  <p>Not yet supported &mdash; only unobservable (single round-trip)
+  commands work today. Observable commands need execution-UUID tracking
+  and server-streaming subscriptions.</p>
+</script>

package/src/call-command/sila-call-command.js

@@ -0,0 +1,110 @@
+"use strict";
+
+module.exports = function (RED) {
+  function SilaCallCommandNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.connection = RED.nodes.getNode(config.connection);
+    node.feature = config.feature || "";
+    node.featureType = config.featureType || "str";
+    node.command = config.command || "";
+    node.commandType = config.commandType || "str";
+    node.params = config.params || "{}";
+    node.paramsType = config.paramsType || "json";
+    node.outputProperty = config.outputProperty || "payload";
+    node.outputPropertyType = config.outputPropertyType || "msg";
+
+    if (!node.connection) {
+      node.status({ fill: "red", shape: "ring", text: "no connection" });
+      return;
+    }
+
+    function applyConnStatus(status) {
+      switch (status.state) {
+        case "ok":
+          node.status({ fill: "green", shape: "dot", text: status.detail || "ok" });
+          break;
+        case "ready":
+          node.status({ fill: "grey", shape: "ring", text: "ready" });
+          break;
+        case "error":
+          node.status({ fill: "red", shape: "ring", text: status.detail || "error" });
+          break;
+        default:
+          node.status({ fill: "grey", shape: "ring", text: status.state || "" });
+      }
+    }
+    const unsub = node.connection.onStatus(applyConnStatus);
+
+    node.on("input", async (msg, send, done) => {
+      let feature, command, params;
+      try {
+        feature = RED.util.evaluateNodeProperty(node.feature, node.featureType, node, msg);
+        command = RED.util.evaluateNodeProperty(node.command, node.commandType, node, msg);
+        params = RED.util.evaluateNodeProperty(node.params, node.paramsType, node, msg);
+      } catch (err) {
+        if (done) done(err); else node.error(err, msg);
+        return;
+      }
+
+      if (typeof feature !== "string" || !feature) {
+        const err = new Error("SiLA call: feature name is missing");
+        if (done) done(err); else node.error(err, msg);
+        return;
+      }
+      if (typeof command !== "string" || !command) {
+        const err = new Error("SiLA call: command name is missing");
+        if (done) done(err); else node.error(err, msg);
+        return;
+      }
+
+      // typed-input "json" already parses; msg/flow/global may pass through a
+      // string by accident — be tolerant. null → empty params.
+      if (params == null) params = {};
+      if (typeof params === "string") {
+        try {
+          params = JSON.parse(params);
+        } catch (e) {
+          const err = new Error(`SiLA call: params is not valid JSON: ${e.message}`);
+          if (done) done(err); else node.error(err, msg);
+          return;
+        }
+      }
+
+      let resp;
+      try {
+        resp = await node.connection.callUnary(feature, command, params);
+      } catch (err) {
+        node.status({ fill: "red", shape: "ring", text: "call failed" });
+        if (done) done(err); else node.error(err, msg);
+        return;
+      }
+
+      try {
+        if (node.outputPropertyType === "msg") {
+          RED.util.setMessageProperty(msg, node.outputProperty, resp, true);
+        } else if (
+          node.outputPropertyType === "flow" ||
+          node.outputPropertyType === "global"
+        ) {
+          node.context()[node.outputPropertyType].set(node.outputProperty, resp);
+        } else {
+          RED.util.setMessageProperty(msg, node.outputProperty, resp, true);
+        }
+      } catch (err) {
+        if (done) done(err); else node.error(err, msg);
+        return;
+      }
+
+      send(msg);
+      if (done) done();
+    });
+
+    node.on("close", () => {
+      try { unsub(); } catch (_) { /* ignore */ }
+    });
+  }
+
+  RED.nodes.registerType("sila-call-command", SilaCallCommandNode);
+};

package/src/connection/sila-connection.html

@@ -0,0 +1,101 @@
+<!-- Browser-side SiLA 2 picker widget. Served as a static asset by the
+     connection node's admin route; loaded here once so it's available on
+     window.SilaPicker for every action node's editor dialog. -->
+<script type="text/javascript" src="sila/picker.js"></script>
+
+<script type="text/javascript">
+  RED.nodes.registerType("sila-connection", {
+    category: "config",
+    defaults: {
+      name: { value: "" },
+      host: { value: "127.0.0.1", required: true },
+      port: { value: 50052, required: true, validate: RED.validators.number() },
+      insecure: { value: true },
+      extraProtoDirs: { value: "" },
+      extraProtoFiles: { value: "" }
+    },
+    label: function () {
+      const target = (this.host && this.port) ? `${this.host}:${this.port}` : "";
+      return this.name || target || "SiLA 2 connection";
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="sila-connection">
+  <div class="form-row">
+    <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-config-input-name" placeholder="e.g. AX205 balance">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-host"><i class="fa fa-globe"></i> Host</label>
+    <input type="text" id="node-config-input-host" placeholder="192.168.8.225">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-port"><i class="fa fa-plug"></i> Port</label>
+    <input type="number" id="node-config-input-port" placeholder="50052">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-insecure" style="width:auto">
+      <input type="checkbox" id="node-config-input-insecure" style="display:inline-block; width:auto; vertical-align:middle">
+      Insecure (no TLS &mdash; lab/dev mode)
+    </label>
+  </div>
+  <hr>
+  <div class="form-row">
+    <label for="node-config-input-extraProtoDirs"><i class="fa fa-folder-open"></i> Extra proto dirs</label>
+    <input type="text" id="node-config-input-extraProtoDirs"
+           placeholder="/home/user/sila-protos, /opt/protos">
+  </div>
+  <div class="form-row">
+    <label for="node-config-input-extraProtoFiles"><i class="fa fa-file-code-o"></i> Extra proto files</label>
+    <input type="text" id="node-config-input-extraProtoFiles"
+           placeholder="/path/to/MyFeature.proto">
+  </div>
+</script>
+
+<script type="text/html" data-help-name="sila-connection">
+  <p>gRPC connection to a SiLA 2 server. One config node per server
+  endpoint. Owns a long-lived gRPC channel and a feature registry loaded
+  from <code>.proto</code> files, shared by every <code>sila-*</code>
+  action node that references it.</p>
+
+  <h3>Bundled features</h3>
+  <p>The package always loads:</p>
+  <ul>
+    <li><code>SiLAFramework.proto</code> &mdash; basic-type wrappers
+    (String, Real, Boolean, ...)</li>
+    <li><code>SiLAService.proto</code> &mdash; the mandatory core feature
+    every SiLA 2 server implements (ServerName, ImplementedFeatures, ...)</li>
+  </ul>
+  <p>That's enough to query any SiLA 2 server's identity surface
+  (`SiLAService` properties + commands) out of the box.</p>
+
+  <h3>Adding more features</h3>
+  <p>For domain features (balances, liquid handlers, etc.), you supply
+  their feature-specific <code>.proto</code> files. SiLA 2 servers
+  generate <code>.proto</code> from FDL XML; if your server runs the
+  <code>sila2</code> Python reference implementation, the generated
+  files live inside the running container and can be copied out with a
+  single shell command.</p>
+  <p>Once you have the <code>.proto</code> files, drop them in a
+  directory and point <b>Extra proto dirs</b> (or <b>Extra proto files</b>)
+  at the location. The lists are comma-separated; <code>.proto</code>
+  files in any listed directory are picked up automatically.</p>
+
+  <h3>Reflection</h3>
+  <p>Earlier versions of this package used gRPC reflection to discover
+  features at runtime. The Python <code>sila2</code> reference server
+  enables reflection by default, but our lab server has it disabled, and
+  Java/C# servers may not support it. Static proto loading is universal.</p>
+
+  <h3>TLS</h3>
+  <p>For development against an insecure server, leave <b>Insecure</b>
+  enabled. Production SiLA 2 servers run TLS with a self-signed cert
+  whose CN encodes the server UUID &mdash; pinned-cert TLS is not in
+  this phase of the package.</p>
+
+  <h3>Lifecycle</h3>
+  <p>Protos load on first call (no I/O at deploy). Per-service grpc
+  client instances are created lazily and reused across calls. Redeploy
+  to flush the cache.</p>
+</script>

package/src/connection/sila-connection.js

@@ -0,0 +1,148 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const grpc = require("@grpc/grpc-js");
+const { createSilaClient } = require("../lib/client");
+
+// Read once at module load — served by the picker.js admin route below.
+const PICKER_JS = fs.readFileSync(
+  path.join(__dirname, "..", "lib", "picker", "picker.js"),
+  "utf8",
+);
+
+module.exports = function (RED) {
+  function SilaConnectionNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    node.host = (config.host || "").trim();
+    node.port = parseInt(config.port, 10) || 50052;
+    node.insecure = config.insecure !== false; // default true (lab/dev)
+
+    // Comma-separated list of extra proto dirs and/or .proto files. The
+    // bundled protos (SiLAFramework, SiLAService, sample AX205Controller)
+    // are always loaded; this lets the user point at additional features
+    // extracted from their server (e.g. via sila-handoff/examples/extract_protos.sh).
+    node.extraProtoDirs = parseList(config.extraProtoDirs);
+    node.extraProtoFiles = parseList(config.extraProtoFiles);
+
+    /** @type {ReturnType<typeof createSilaClient>|null} */
+    let client = null;
+
+    const statusListeners = new Set();
+    let lastStatus = { state: "idle", detail: "", ts: Date.now() };
+
+    function publishStatus(state, detail) {
+      lastStatus = { state, detail: detail || "", ts: Date.now() };
+      for (const fn of statusListeners) {
+        try { fn(lastStatus); } catch (_) { /* ignore */ }
+      }
+    }
+
+    /** Action nodes subscribe with this; returns an unsubscribe fn. */
+    node.onStatus = function (fn) {
+      statusListeners.add(fn);
+      try { fn(lastStatus); } catch (_) { /* ignore */ }
+      return () => statusListeners.delete(fn);
+    };
+
+    function buildClient() {
+      if (!node.host) throw new Error("SiLA connection: host not configured");
+      const target = `${node.host}:${node.port}`;
+      const creds = node.insecure
+        ? grpc.credentials.createInsecure()
+        : grpc.credentials.createSsl(); // TLS w/o pinned roots
+      const c = createSilaClient({
+        target,
+        credentials: creds,
+        extraProtoDirs: node.extraProtoDirs,
+        extraProtoFiles: node.extraProtoFiles,
+      });
+      publishStatus("ready", `${target} (${c.listServices().length} svc loaded)`);
+      return c;
+    }
+
+    /**
+     * Lazy: build the client on first call. Loading protos is synchronous
+     * and fast (KB-sized files), but no socket opens until the first call.
+     */
+    node.getClient = function () {
+      if (!client) client = buildClient();
+      return client;
+    };
+
+    /**
+     * Convenience wrapper for action nodes: lazy init + status broadcast.
+     */
+    node.callUnary = async function (featureName, methodName, params, metadata) {
+      const c = node.getClient();
+      try {
+        const resp = await c.callUnary(featureName, methodName, params, metadata);
+        publishStatus("ok", `${featureName}.${methodName}`);
+        return resp;
+      } catch (err) {
+        publishStatus("error", err.message || String(err));
+        throw err;
+      }
+    };
+
+    /** For diagnostics / future picker UI. */
+    node.listServices = function () {
+      return node.getClient().listServices();
+    };
+
+    /** Editor picker: list loaded features with classified methods. */
+    node.listFeaturesForPicker = function () {
+      return node.getClient().listFeaturesForPicker();
+    };
+
+    node.on("close", function (done) {
+      try { if (client) client.close(); } catch (_) { /* ignore */ }
+      client = null;
+      if (typeof done === "function") done();
+    });
+  }
+
+  function parseList(s) {
+    if (!s) return [];
+    return String(s)
+      .split(",")
+      .map((x) => x.trim())
+      .filter(Boolean);
+  }
+
+  RED.nodes.registerType("sila-connection", SilaConnectionNode);
+
+  // ---------------------------------------------------------------------------
+  // Editor-side picker support: admin HTTP endpoints. Routes are scoped
+  // under /sila/conn/:id/... to mirror the LADS pattern and avoid clashes.
+  // ---------------------------------------------------------------------------
+
+  function picker(handler) {
+    return async (req, res) => {
+      const node = RED.nodes.getNode(req.params.id);
+      if (!node || typeof node.listFeaturesForPicker !== "function") {
+        return res.status(404).json({ error: "sila-connection not found: " + req.params.id });
+      }
+      try {
+        const data = await handler(node, req);
+        res.json(data);
+      } catch (err) {
+        res.status(500).json({ error: err.message });
+      }
+    };
+  }
+
+  RED.httpAdmin.get(
+    "/sila/conn/:id/features",
+    RED.auth.needsPermission("flows.read"),
+    picker((node) => node.listFeaturesForPicker()),
+  );
+
+  // Serve the picker.js asset for the editor. Static JS — sensitive data
+  // lives behind the /features endpoint which already requires flows.read.
+  RED.httpAdmin.get("/sila/picker.js", (req, res) => {
+    res.type("application/javascript").send(PICKER_JS);
+  });
+};

package/src/get-property/sila-get-property.html

@@ -0,0 +1,125 @@
+<script type="text/javascript">
+  RED.nodes.registerType("sila-get-property", {
+    // See sila-call-command.html for why this is a space, not '-'.
+    category: "Synefex SiLA 2",
+    color: "#A6BBCF",
+    defaults: {
+      name: { value: "" },
+      connection: { value: "", type: "sila-connection", required: true },
+      feature: { value: "" },
+      featureType: { value: "str" },
+      property: { value: "" },
+      propertyType: { value: "str" },
+      outputProperty: { value: "payload" },
+      outputPropertyType: { value: "msg" },
+      unwrapSingle: { value: true }
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-eye",
+    paletteLabel: "SiLA 2 get",
+    label: function () {
+      if (this.name) return this.name;
+      if (this.propertyType === "str" && this.property) return "get " + this.property;
+      return "SiLA 2 get";
+    },
+    oneditprepare: function () {
+      $("#node-input-feature").typedInput({
+        default: this.featureType || "str",
+        typeField: $("#node-input-featureType"),
+        types: ["str", "msg", "flow", "global", "env"]
+      });
+      $("#node-input-property").typedInput({
+        default: this.propertyType || "str",
+        typeField: $("#node-input-propertyType"),
+        types: ["str", "msg", "flow", "global", "env"]
+      });
+      $("#node-input-outputProperty").typedInput({
+        default: this.outputPropertyType || "msg",
+        typeField: $("#node-input-outputPropertyType"),
+        types: ["msg", "flow", "global"]
+      });
+
+      // Picker: cascading Feature → Property dropdowns. Properties are
+      // surfaced by their bare name (e.g. "ServerName"), not by the wire
+      // method name "Get_ServerName" — the node prepends Get_ at runtime.
+      if (window.SilaPicker) {
+        window.SilaPicker.attach({
+          kind: "property",
+          connectionFieldId: "node-input-connection",
+          featureFieldId: "node-input-feature",
+          methodFieldId: "node-input-property",
+        });
+      }
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="sila-get-property">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name">
+  </div>
+  <div class="form-row">
+    <label for="node-input-connection"><i class="fa fa-server"></i> Connection</label>
+    <input type="text" id="node-input-connection">
+  </div>
+  <div class="form-row">
+    <label for="node-input-feature"><i class="fa fa-cube"></i> Feature</label>
+    <input type="text" id="node-input-feature" placeholder="SiLAService">
+    <input type="hidden" id="node-input-featureType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-property"><i class="fa fa-eye"></i> Property</label>
+    <input type="text" id="node-input-property" placeholder="ServerName">
+    <input type="hidden" id="node-input-propertyType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-outputProperty"><i class="fa fa-arrow-right"></i> Output to</label>
+    <input type="text" id="node-input-outputProperty">
+    <input type="hidden" id="node-input-outputPropertyType">
+  </div>
+  <div class="form-row">
+    <label for="node-input-unwrapSingle" style="width:auto">
+      <input type="checkbox" id="node-input-unwrapSingle" style="display:inline-block; width:auto; vertical-align:middle">
+      Unwrap single-field response (drop the property-named wrapper)
+    </label>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="sila-get-property">
+  <p>Get the current value of an unobservable SiLA 2 property.</p>
+
+  <h3>Configuration</h3>
+  <dl class="message-properties">
+    <dt>Feature <span class="property-type">string</span></dt>
+    <dd>The feature identifier (short name or full proto-qualified
+    name).</dd>
+    <dt>Property <span class="property-type">string</span></dt>
+    <dd>The property name as declared on the feature (e.g.
+    <code>ServerName</code>, <code>ImplementedFeatures</code>). The node
+    prepends <code>Get_</code> automatically &mdash; if you provide
+    <code>Get_ServerName</code> it's used verbatim.</dd>
+    <dt>Unwrap single-field response <span class="property-type">boolean</span></dt>
+    <dd>When the <code>Get_&lt;Property&gt;_Responses</code> message has
+    one field (the typical case), unwrap it so <code>payload</code> is
+    the value directly. Disable to receive the wrapper object.</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <p>The unwrapped property value. Examples:</p>
+  <pre>SiLAService.ServerName
+  → "MettlerToledoAX205SiLAServer"
+
+SiLAService.ImplementedFeatures
+  → [
+      "org.silastandard/core/SiLAService/v1",
+      "master.thesis/weighing/MettlerToledoAX205Controller/v1",
+      "master.thesis/weighing/MettlerToledoAX205Metadata/v1"
+    ]</pre>
+
+  <h3>Observable properties</h3>
+  <p>Not yet supported &mdash; only unobservable (single read) properties
+  work today. Observable properties would need server-streaming
+  subscription handling.</p>
+</script>