node-red-modbus-dynamic-server 0.1.0

package/src/modbus-server-exception.html

@@ -0,0 +1,82 @@
+<script type="text/html" data-template-name="modbus-server-exception">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-exceptionCode"><i class="fa fa-ban"></i> Default Exception</label>
+    <select id="node-input-exceptionCode" style="width: calc(100% - 110px);">
+      <option value="1">1 - Illegal Function</option>
+      <option value="2">2 - Illegal Data Address</option>
+      <option value="3">3 - Illegal Data Value</option>
+      <option value="4">4 - Server Device Failure</option>
+      <option value="5">5 - Acknowledge</option>
+      <option value="6">6 - Server Device Busy</option>
+      <option value="8">8 - Memory Parity Error</option>
+      <option value="10">10 - Gateway Path Unavailable</option>
+      <option value="11">11 - Gateway Target Device Failed to Respond</option>
+    </select>
+  </div>
+</script>
+
+<script type="text/html" data-help-name="modbus-server-exception">
+  <p>Sends a Modbus exception response for a pending intercepted server request.</p>
+
+  <p>This is a convenience node for custom flows that decide a request must be
+  rejected, such as unsupported address ranges, blocked unit/function combinations,
+  policy violations, or fallback reject paths.</p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt>_modbus.requestId <span class="property-type">string</span></dt>
+    <dd>Required internal request identifier for the pending Modbus transaction.</dd>
+
+    <dt>_modbus.configNodeId <span class="property-type">string</span></dt>
+    <dd>Required internal config-node identifier used to submit the exception response.</dd>
+
+    <dt class="optional">modbusExceptionCode <span class="property-type">number</span></dt>
+    <dd>Optional per-message exception code override. If valid, this overrides the
+    configured default exception code.</dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <p>None. This node terminates the request by responding with an exception.</p>
+
+  <h3>Details</h3>
+  <p>Exception code source precedence:</p>
+  <ol>
+    <li><code>msg.modbusExceptionCode</code> (if valid)</li>
+    <li>Configured <em>Default Exception</em></li>
+  </ol>
+  <p>Flows must preserve <code>msg._modbus</code>:</p>
+  <pre><code>// CORRECT
+msg.payload = newValue;
+return msg;
+
+// INCORRECT: request context is lost
+msg = { payload: newValue };
+return msg;</code></pre>
+  <p>Use <code>modbus-source-router</code> or <code>modbus-fc-filter</code> for common filtering
+  cases, and use this node when custom logic in a <code>switch</code> or <code>function</code>
+  node decides the request must be rejected.</p>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('modbus-server-exception', {
+    category: 'modbus',
+    color: '#E9967A',
+    defaults: {
+      name: { value: '' },
+      exceptionCode: { value: 4, required: true, validate: RED.validators.number() }
+    },
+    inputs: 1,
+    outputs: 0,
+    icon: 'arrow-out.svg',
+    label: function () {
+      return this.name || 'modbus-server-exception'
+    }
+  })
+</script>
+
+

package/src/modbus-server-exception.js

@@ -0,0 +1,44 @@
+const { respondWithPayload } = require('./modbus-response-context')
+
+module.exports = function (RED) {
+  'use strict'
+
+  function toValidExceptionCode (value) {
+    const n = Number(value)
+    if (!Number.isInteger(n) || n < 1 || n > 255) return null
+    return n
+  }
+
+  function ModbusServerExceptionNode (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+
+    node.exceptionCode = toValidExceptionCode(config.exceptionCode) || 4
+
+    node.status({ fill: 'grey', shape: 'ring', text: 'ready' })
+
+    node.on('input', function (msg, send, done) {
+      const override = toValidExceptionCode(msg ? msg.modbusExceptionCode : undefined)
+      const exceptionCode = override !== null ? override : node.exceptionCode
+
+      const responseResult = respondWithPayload(RED, node, msg, { exception: exceptionCode })
+      if (!responseResult.context) {
+        node.status({ fill: 'yellow', shape: 'ring', text: 'missing context' })
+        done()
+        return
+      }
+
+      if (!responseResult.ok) {
+        node.status({ fill: 'red', shape: 'ring', text: 'unknown requestId' })
+        done()
+        return
+      }
+
+      node.status({ fill: 'yellow', shape: 'ring', text: `exception ${exceptionCode}` })
+      done()
+    })
+  }
+
+  RED.nodes.registerType('modbus-server-exception', ModbusServerExceptionNode)
+}
+

package/src/modbus-source-router.html

@@ -0,0 +1,296 @@
+<!-- ─── Edit dialog template ──────────────────────────────────────────────── -->
+<script type="text/html" data-template-name="modbus-source-router">
+
+	<div class="form-row">
+		<label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+		<input type="text" id="node-input-name" placeholder="Name">
+	</div>
+
+	<!-- Rule list --------------------------------------------------------- -->
+	<div class="form-row">
+		<label style="vertical-align:top; padding-top:6px;"><i class="fa fa-filter"></i> Rules</label>
+		<div style="display:inline-block; width:calc(100% - 110px); vertical-align:top;">
+			<!-- Column headings -->
+			<div id="node-input-rule-header"
+			     style="display:flex; align-items:center; gap:4px;
+			            font-size:0.82em; color:#888; padding:0 2px 4px 2px;">
+				<span style="width:20px;"></span>
+				<span style="flex:1; min-width:70px;">Label (optional)</span>
+				<span style="flex:2; min-width:110px;">CIDR (e.g. 192.168.1.0/24)</span>
+				<span style="width:28px;"></span>
+			</div>
+			<ol id="node-input-rule-container"
+			    style="list-style:none; margin:0; padding:0;"></ol>
+		</div>
+	</div>
+
+	<div class="form-row">
+		<label>&nbsp;</label>
+		<button type="button" id="node-input-add-rule"
+		        style="background:#f0f0f0; border:1px solid #ccc; border-radius:3px;
+		               padding:4px 10px; cursor:pointer;">
+			<i class="fa fa-plus"></i> Add Rule
+		</button>
+	</div>
+
+	<!-- No-match exception code ------------------------------------------- -->
+	<div class="form-row">
+		<label for="node-input-noMatchException">
+			<i class="fa fa-ban"></i> No-match Exception
+		</label>
+		<select id="node-input-noMatchException" style="width:calc(100% - 110px);">
+			<option value="1">1 — Illegal Function</option>
+			<option value="2">2 — Illegal Data Address</option>
+			<option value="3">3 — Illegal Data Value</option>
+			<option value="4">4 — Server Device Failure</option>
+			<option value="10">10 — Gateway Path Unavailable</option>
+			<option value="11">11 — Gateway Target Device Failed to Respond</option>
+		</select>
+	</div>
+
+</script>
+
+
+<!-- ─── Help text ────────────────────────────────────────────────────────── -->
+<script type="text/html" data-help-name="modbus-source-router">
+	<p>Routes an incoming Modbus request emitted by a <code>modbus-dynamic-server</code> node to
+	one of several outputs based on the client's source IP address.</p>
+
+	<p>Rules are evaluated in the order they appear in the editor. The <strong>first matching
+	rule wins</strong> and the message is forwarded to the corresponding output only. A message
+	is never sent to more than one output. If no rule matches, the node sends a Modbus exception
+	response using the configured exception code and emits nothing on any output.</p>
+
+	<h3>Inputs</h3>
+	<dl class="message-properties">
+    <dt>_modbus.requestId <span class="property-type">string</span></dt>
+    <dd>Required internal request context field emitted by
+    <code>modbus-dynamic-server</code>.</dd>
+
+    <dt>_modbus.configNodeId <span class="property-type">string</span></dt>
+    <dd>Required internal context field used to send a no-match exception response.</dd>
+
+		<dt>modbus.connection.source.address <span class="property-type">string</span></dt>
+		<dd>Required. IPv4 address of the Modbus client. IPv6-mapped IPv4 addresses
+		(<code>::ffff:x.x.x.x</code>) are automatically normalised.</dd>
+	</dl>
+
+	<h3>Outputs</h3>
+	<p>One output per configured rule. Output <em>N</em> corresponds to rule <em>N</em> in
+	the ordered rule list. The total number of outputs is equal to the number of rules.</p>
+	<dl class="message-properties">
+		<dt>payload <span class="property-type">object</span></dt>
+		<dd>The original request message, forwarded unchanged to the matching output.</dd>
+	</dl>
+
+	<h3>Configuration</h3>
+	<dl class="message-properties">
+		<dt>Rules <span class="property-type">list</span></dt>
+		<dd>An ordered list of source-address match rules.  Each rule has:
+			<ul>
+				<li><b>Label</b> — optional description shown on the output port.</li>
+				<li><b>CIDR</b> — an IPv4 CIDR block such as <code>192.168.1.0/24</code>
+				or a single host as <code>192.168.1.42/32</code>.</li>
+			</ul>
+			Rules are evaluated top-to-bottom. Drag rows to reorder them.
+		</dd>
+
+		<dt>No-match Exception <span class="property-type">select</span></dt>
+		<dd>The Modbus exception code sent to the client when no rule matches the
+		source address. Common values:
+			<ul>
+				<li><b>1</b> — Illegal Function</li>
+				<li><b>2</b> — Illegal Data Address</li>
+				<li><b>3</b> — Illegal Data Value</li>
+				<li><b>4</b> — Server Device Failure</li>
+				<li><b>10</b> — Gateway Path Unavailable</li>
+				<li><b>11</b> — Gateway Target Device Failed to Respond</li>
+			</ul>
+		</dd>
+	</dl>
+
+	<h3>Details</h3>
+	<p>This node is intended to sit immediately after a <code>modbus-dynamic-server</code> node
+	and filter/route requests by client IP before they reach any processing logic.</p>
+	<p>A catch-all rule (<code>0.0.0.0/0</code>) can be added as the last rule to handle any
+	address not matched by earlier, more-specific rules. It is never added automatically.</p>
+	<p>IPv4 CIDR matching examples:</p>
+	<ul>
+		<li><code>192.168.1.42</code> matches <code>192.168.1.42/32</code></li>
+		<li><code>192.168.1.42</code> matches <code>192.168.1.0/24</code></li>
+		<li><code>192.168.1.42</code> does <em>not</em> match <code>192.168.2.0/24</code></li>
+		<li><code>10.5.6.7</code> matches <code>10.0.0.0/8</code></li>
+	</ul>
+	<p>IPv6 is not supported in this version. IPv6-mapped IPv4 addresses
+	(e.g. <code>::ffff:192.168.1.1</code>) are automatically converted to plain IPv4 before
+	evaluation.</p>
+  <p>Flows must preserve <code>msg._modbus</code> so no-match exceptions can be sent:</p>
+  <pre><code>// CORRECT
+msg.payload = newValue;
+return msg;
+
+// INCORRECT: request context is lost
+msg = { payload: newValue };
+return msg;</code></pre>
+</script>
+
+
+<!-- ─── Node registration ─────────────────────────────────────────────── -->
+<script type="text/javascript">
+;(function () {
+  /**
+   * Validate an IPv4 CIDR string.
+   * Accepts /0 through /32, rejects any other form.
+   */
+  function isValidIpv4Cidr (cidr) {
+    if (typeof cidr !== 'string') return false
+    const parts = cidr.trim().split('/')
+    if (parts.length !== 2) return false
+    const ip = parts[0]
+    const prefixStr = parts[1]
+    // Prefix must be a non-negative integer with no leading zeros (except "0" itself).
+    if (!/^\d+$/.test(prefixStr)) return false
+    const prefix = parseInt(prefixStr, 10)
+    if (prefix < 0 || prefix > 32) return false
+    const octets = ip.split('.')
+    if (octets.length !== 4) return false
+    for (let i = 0; i < 4; i++) {
+      if (!/^\d+$/.test(octets[i])) return false
+      const n = parseInt(octets[i], 10)
+      if (n < 0 || n > 255) return false
+    }
+    return true
+  }
+
+  RED.nodes.registerType('modbus-source-router', {
+    category: 'modbus',
+    color: '#E9967A',
+    defaults: {
+      name: { value: '' },
+      rules: {
+        value: [],
+        validate: function (v) {
+          if (!Array.isArray(v) || v.length === 0) return true
+          return v.every(function (rule) {
+            return rule && typeof rule.cidr === 'string' && isValidIpv4Cidr(rule.cidr)
+          })
+        }
+      },
+      noMatchException: { value: 1, required: true },
+      outputs: { value: 0 }
+    },
+    inputs: 1,
+    outputs: 0,
+    icon: 'switch.svg',
+
+    label: function () {
+      return this.name || 'Modbus Source Router'
+    },
+
+    outputLabels: function (index) {
+      const rule = (this.rules || [])[index]
+      if (!rule) return 'Rule ' + (index + 1)
+      return rule.label || rule.cidr || ('Rule ' + (index + 1))
+    },
+
+    oneditprepare: function () {
+      const node = this
+      const container = $('#node-input-rule-container')
+
+      // ── Sortable ──────────────────────────────────────────────────────
+      container.sortable({
+        handle: '.rule-drag-handle',
+        axis: 'y',
+        cursor: 'move',
+        revert: true,
+        placeholder: 'ui-sortable-placeholder',
+        start: function (event, ui) {
+          ui.placeholder.height(ui.item.outerHeight())
+        }
+      })
+
+      // ── Row factory ───────────────────────────────────────────────────
+      function addRuleRow (rule) {
+        const li = $('<li></li>').css({
+          display: 'flex',
+          alignItems: 'center',
+          gap: '4px',
+          marginBottom: '4px',
+          padding: '4px 6px',
+          background: '#f8f8f8',
+          border: '1px solid #ddd',
+          borderRadius: '3px'
+        })
+
+        // Drag handle
+        const handle = $(
+          '<i class="fa fa-bars rule-drag-handle" title="Drag to reorder"' +
+          ' style="cursor:move; color:#bbb; padding:0 2px; flex-shrink:0;"></i>'
+        )
+
+        // Label input
+        const labelInput = $('<input type="text" class="rule-label" placeholder="Label (optional)">')
+          .css({ flex: '1', minWidth: '60px' })
+          .val((rule && rule.label) || '')
+
+        // CIDR input with live validation
+        const cidrInput = $('<input type="text" class="rule-cidr" placeholder="e.g. 192.168.1.0/24">')
+          .css({ flex: '2', minWidth: '100px' })
+          .val((rule && rule.cidr) || '')
+
+        function validateCidr () {
+          const val = cidrInput.val().trim()
+          if (val && !isValidIpv4Cidr(val)) {
+            cidrInput.css({ outline: '2px solid #c00', outlineOffset: '1px' })
+          } else {
+            cidrInput.css({ outline: '' })
+          }
+        }
+
+        cidrInput.on('input change', validateCidr)
+        validateCidr()
+
+        // Delete button
+        const deleteBtn = $(
+          '<button type="button" title="Remove rule"' +
+          ' style="background:none; border:1px solid #ccc; border-radius:3px;' +
+          '        padding:2px 7px; cursor:pointer; color:#666; flex-shrink:0;">' +
+          '<i class="fa fa-remove"></i></button>'
+        )
+        deleteBtn.on('click', function () {
+          li.remove()
+        })
+
+        li.append(handle, labelInput, cidrInput, deleteBtn)
+        container.append(li)
+      }
+
+      // Populate with saved rules
+      ;(node.rules || []).forEach(function (rule) {
+        addRuleRow(rule)
+      })
+
+      // Add Rule button
+      $('#node-input-add-rule').on('click', function () {
+        addRuleRow({ cidr: '', label: '' })
+      })
+    },
+
+    oneditsave: function () {
+      const rules = []
+      $('#node-input-rule-container').children('li').each(function () {
+        const cidr = $(this).find('.rule-cidr').val().trim()
+        const label = $(this).find('.rule-label').val().trim()
+        rules.push({ cidr: cidr, label: label })
+      })
+      this.rules = rules
+      this.outputs = rules.length
+    },
+
+    oneditcancel: function () {
+      // No cleanup needed.
+    }
+  })
+})()
+</script>
+

package/src/modbus-source-router.js

@@ -0,0 +1,120 @@
+const { respondWithPayload } = require('./modbus-response-context')
+
+module.exports = function (RED) {
+  'use strict'
+
+  /**
+   * Convert a dotted-decimal IPv4 string to a 32-bit unsigned integer.
+   * Returns NaN if the string is not a valid IPv4 address.
+   */
+  function ipToUint32 (ip) {
+    const parts = ip.split('.')
+    if (parts.length !== 4) return NaN
+    let num = 0
+    for (let i = 0; i < 4; i++) {
+      const octet = parseInt(parts[i], 10)
+      if (!Number.isFinite(octet) || octet < 0 || octet > 255 || String(octet) !== parts[i]) return NaN
+      num = ((num << 8) | octet) >>> 0
+    }
+    return num
+  }
+
+  /**
+   * Return true if the given IPv4 address string falls within the given CIDR block.
+   * Both ip and cidr must be valid IPv4 / IPv4-CIDR strings.
+   */
+  function matchesCidr (ip, cidr) {
+    if (typeof ip !== 'string' || typeof cidr !== 'string') return false
+    const slashIdx = cidr.indexOf('/')
+    if (slashIdx === -1) return false
+    const networkStr = cidr.slice(0, slashIdx)
+    const prefixStr = cidr.slice(slashIdx + 1)
+    const prefix = parseInt(prefixStr, 10)
+    if (!Number.isFinite(prefix) || prefix < 0 || prefix > 32 || String(prefix) !== prefixStr) return false
+    // A /0 mask covers every address.
+    const mask = prefix === 0 ? 0 : (0xFFFFFFFF << (32 - prefix)) >>> 0
+    const networkInt = ipToUint32(networkStr)
+    const ipInt = ipToUint32(ip)
+    if (isNaN(networkInt) || isNaN(ipInt)) return false
+    return (ipInt & mask) === (networkInt & mask)
+  }
+
+  /**
+   * Normalise an IP address string.
+   * Node.js TCP sockets can return IPv6-mapped IPv4 addresses such as
+   * "::ffff:192.168.1.1". Strip the prefix so CIDR matching works correctly.
+   */
+  function normalizeIp (ip) {
+    if (typeof ip !== 'string') return ip
+    if (ip.startsWith('::ffff:')) return ip.slice(7)
+    // Handle full-form IPv6-mapped notation, e.g. ::ffff:c0a8:0101
+    return ip
+  }
+
+  function ModbusSourceRouterNode (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+
+    node.rules = Array.isArray(config.rules) ? config.rules : []
+    node.noMatchException = Number(config.noMatchException) || 1
+
+    if (node.rules.length === 0) {
+      node.status({ fill: 'yellow', shape: 'ring', text: 'no rules configured' })
+    } else {
+      node.status({ fill: 'grey', shape: 'ring', text: 'ready' })
+    }
+
+    node.on('input', function (msg, send, done) {
+      // Extract the source IP address from the message.
+      const rawAddress =
+        msg.modbus &&
+        msg.modbus.connection &&
+        msg.modbus.connection.source
+          ? msg.modbus.connection.source.address
+          : null
+
+      if (!rawAddress) {
+        node.status({ fill: 'yellow', shape: 'ring', text: 'no source address' })
+        done(new Error('modbus-source-router: msg.modbus.connection.source.address is missing'))
+        return
+      }
+
+      const sourceAddress = normalizeIp(rawAddress)
+
+      // Evaluate rules from top to bottom; the first matching rule wins.
+      for (let i = 0; i < node.rules.length; i++) {
+        const rule = node.rules[i]
+        if (!rule || !rule.cidr) continue
+
+        if (matchesCidr(sourceAddress, rule.cidr)) {
+          const label = rule.label || rule.cidr
+          node.status({ fill: 'green', shape: 'dot', text: `rule ${i + 1}: ${label}` })
+
+          // Build an output array with the matching slot filled and all others null.
+          const outputs = new Array(node.rules.length).fill(null)
+          outputs[i] = msg
+          send(outputs)
+          done()
+          return
+        }
+      }
+
+      // No rule matched — send a Modbus exception response and emit nothing.
+      node.status({ fill: 'yellow', shape: 'ring', text: `no match → exception ${node.noMatchException}` })
+
+      const responseResult = respondWithPayload(RED, node, msg, { exception: node.noMatchException })
+      if (!responseResult.context) {
+        node.status({ fill: 'red', shape: 'ring', text: 'missing context' })
+      }
+
+      done()
+    })
+
+    node.on('close', function () {
+      // Pending requests are owned and cleaned up by the config node.
+    })
+  }
+
+  RED.nodes.registerType('modbus-source-router', ModbusSourceRouterNode)
+}
+