Add QoS overriding options for publishers and subscriptions

index.js

@@ -39,6 +39,10 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
+const {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+} = require('./lib/qos_overriding_options.js');
 const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
@@ -258,6 +262,12 @@ let rcl = {
   /** {@link QoS} class */
   QoS: QoS,
 
+  /** {@link QoSPolicyKind} enum */
+  QoSPolicyKind: QoSPolicyKind,
+
+  /** {@link QoSOverridingOptions} class */
+  QoSOverridingOptions: QoSOverridingOptions,
+
   /** {@link RMWUtils} */
   RMWUtils: RMWUtils,
 

lib/node.js

@@ -48,6 +48,10 @@ const Service = require('./service.js');
 const Subscription = require('./subscription.js');
 const ObservableSubscription = require('./observable_subscription.js');
 const MessageInfo = require('./message_info.js');
+const {
+  declareQosParameters,
+  _resolveQoS,
+} = require('./qos_overriding_options.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
@@ -752,6 +756,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'publisher',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let publisher = publisherClass.createPublisher(
       this,
       typeClass,
@@ -848,6 +867,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'subscription',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let subscription = Subscription.createSubscription(
       this,
       typeClass,

lib/qos_overriding_options.js

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 The Robot Web Tools Contributors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const QoS = require('./qos.js');
+const {
+  Parameter,
+  ParameterType,
+  ParameterDescriptor,
+} = require('./parameter.js');
+
+/**
+ * Enum of overridable QoS policy kinds.
+ * Each value corresponds to a QoS property on the {@link QoS} class.
+ * @enum {number}
+ */
+const QoSPolicyKind = Object.freeze({
+  HISTORY: 1,
+  DEPTH: 2,
+  RELIABILITY: 3,
+  DURABILITY: 4,
+  LIVELINESS: 5,
+  AVOID_ROS_NAMESPACE_CONVENTIONS: 6,
+});
+
+// Maps QoSPolicyKind -> { qosProp, paramType, toParam, fromParam }
+const POLICY_MAP = {
+  [QoSPolicyKind.HISTORY]: {
+    qosProp: 'history',
+    enumObj: QoS.HistoryPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DEPTH]: {
+    qosProp: 'depth',
+    paramType: ParameterType.PARAMETER_INTEGER,
+    toParam: (val) => val,
+    fromParam: (val) => Number(val),
+  },
+  [QoSPolicyKind.RELIABILITY]: {
+    qosProp: 'reliability',
+    enumObj: QoS.ReliabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DURABILITY]: {
+    qosProp: 'durability',
+    enumObj: QoS.DurabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.LIVELINESS]: {
+    qosProp: 'liveliness',
+    enumObj: QoS.LivelinessPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.AVOID_ROS_NAMESPACE_CONVENTIONS]: {
+    qosProp: 'avoidRosNameSpaceConventions',
+    paramType: ParameterType.PARAMETER_BOOL,
+    toParam: (val) => val,
+    fromParam: (val) => Boolean(val),
+  },
+};
+
+/**
+ * Convert a numeric enum value to a lowercase string name.
+ * @param {number} val - enum numeric value
+ * @param {Object} enumObj - the enum object (e.g. QoS.HistoryPolicy)
+ * @returns {string}
+ */
+function _enumToString(val, enumObj) {
+  for (const [key, v] of Object.entries(enumObj)) {
+    if (v === val) {
+      // Strip the RMW prefix: "RMW_QOS_POLICY_HISTORY_KEEP_LAST" -> "keep_last"
+      const parts = key.split('_');
+      // Find the index after the policy name (HISTORY, RELIABILITY, etc.)
+      // Pattern: RMW_QOS_POLICY_<POLICY>_<VALUE>
+      const policyNames = [
+        'HISTORY',
+        'RELIABILITY',
+        'DURABILITY',
+        'LIVELINESS',
+      ];
+      let valueStart = 4; // default: skip RMW_QOS_POLICY_<X>_
+      for (let i = 3; i < parts.length; i++) {
+        if (policyNames.includes(parts[i])) {
+          valueStart = i + 1;
+          break;
+        }
+      }
+      return parts.slice(valueStart).join('_').toLowerCase();
+    }
+  }
+  return String(val);
+}
+
+/**
+ * Convert a lowercase string back to a numeric enum value.
+ * @param {string} str - the string value (e.g. "keep_last")
+ * @param {Object} enumObj - the enum object
+ * @returns {number}
+ */
+function _stringToEnum(str, enumObj) {
+  const upper = str.toUpperCase();
+  for (const [key, val] of Object.entries(enumObj)) {
+    if (key.endsWith('_' + upper)) {
+      return val;
+    }
+  }
+  throw new Error(`Unknown QoS policy value: "${str}"`);
+}
+
+/**
+ * Options for overriding QoS policies via ROS parameters.
+ *
+ * When passed to `createPublisher()` or `createSubscription()`, the node
+ * will declare read-only parameters for each specified policy kind. These
+ * parameters can be set via command-line arguments, launch files, or
+ * parameter files to override the QoS profile at startup.
+ *
+ * Parameter naming convention:
+ *   `qos_overrides.<topic>.<publisher|subscription>[_<entityId>].<policy>`
+ *
+ * @example
+ * // Override history, depth, and reliability via parameters
+ * const sub = node.createSubscription(
+ *   'std_msgs/msg/String', '/chatter',
+ *   { qos: rclnodejs.QoS.profileDefault,
+ *     qosOverridingOptions: QoSOverridingOptions.withDefaultPolicies() },
+ *   (msg) => console.log(msg.data)
+ * );
+ * // Now you can override via CLI:
+ * //   --ros-args -p "qos_overrides./chatter.subscription.depth:=20"
+ */
+class QoSOverridingOptions {
+  /**
+   * @param {Array<QoSPolicyKind>} policyKinds - Which QoS policies to expose as parameters.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Optional validation callback. Receives the
+   *   final QoS profile after overrides are applied. Should return
+   *   `{successful: true}` or `{successful: false, reason: '...'}`.
+   * @param {string} [opts.entityId] - Optional suffix to disambiguate multiple
+   *   publishers/subscriptions on the same topic.
+   */
+  constructor(policyKinds, opts = {}) {
+    this._policyKinds = Array.from(policyKinds);
+    this._callback = opts.callback || null;
+    this._entityId = opts.entityId || null;
+  }
+
+  get policyKinds() {
+    return this._policyKinds;
+  }
+
+  get callback() {
+    return this._callback;
+  }
+
+  get entityId() {
+    return this._entityId;
+  }
+
+  /**
+   * Create options that override history, depth, and reliability —
+   * the most commonly tuned policies.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Validation callback.
+   * @param {string} [opts.entityId] - Entity disambiguation suffix.
+   * @returns {QoSOverridingOptions}
+   */
+  static withDefaultPolicies(opts = {}) {
+    return new QoSOverridingOptions(
+      [QoSPolicyKind.HISTORY, QoSPolicyKind.DEPTH, QoSPolicyKind.RELIABILITY],
+      opts
+    );
+  }
+}
+
+/**
+ * Resolve QoS profile string to a mutable QoS object.
+ * If already a QoS instance, return as-is.
+ * @param {QoS|string} qos
+ * @returns {QoS}
+ */
+function _resolveQoS(qos) {
+  if (qos instanceof QoS) {
+    return qos;
+  }
+  // Profile string: create a QoS with the corresponding defaults
+  switch (qos) {
+    case QoS.profileSensorData:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        5,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileServicesDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileDefault:
+    case QoS.profileSystemDefault:
+    default:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+  }
+}
+
+/**
+ * Declare QoS override parameters on the node and apply any overrides
+ * to the QoS profile in-place.
+ *
+ * @param {'publisher'|'subscription'} entityType
+ * @param {Node} node
+ * @param {string} topic - Fully resolved topic name.
+ * @param {QoS} qos - Mutable QoS object (will be modified in-place).
+ * @param {QoSOverridingOptions} options
+ */
+function declareQosParameters(entityType, node, topic, qos, options) {
+  if (!options || options.policyKinds.length === 0) {
+    return;
+  }
+
+  const idSuffix = options.entityId ? `_${options.entityId}` : '';
+  const namePrefix = `qos_overrides.${topic}.${entityType}${idSuffix}`;
+
+  for (const policyKind of options.policyKinds) {
+    const mapping = POLICY_MAP[policyKind];
+    if (!mapping) {
+      continue;
+    }
+
+    const paramName = `${namePrefix}.${mapping.qosProp}`;
+    const currentValue = qos[mapping.qosProp];
+    const paramValue = mapping.toParam(currentValue, mapping.enumObj);
+
+    const descriptor = new ParameterDescriptor(
+      paramName,
+      mapping.paramType,
+      `QoS override for ${mapping.qosProp}`,
+      true // readOnly
+    );
+
+    let param;
+    try {
+      param = node.declareParameter(
+        new Parameter(paramName, mapping.paramType, paramValue),
+        descriptor
+      );
+    } catch (e) {
+      // Already declared (e.g. multiple entities on same topic) — reuse
+      if (node.hasParameter(paramName)) {
+        param = node.getParameter(paramName);
+      } else {
+        throw e;
+      }
+    }
+
+    // Apply the (possibly overridden) parameter value back to QoS
+    if (param && param.value !== paramValue) {
+      qos[mapping.qosProp] = mapping.fromParam(param.value, mapping.enumObj);
+    }
+  }
+
+  // Run validation callback if provided
+  if (options.callback) {
+    const result = options.callback(qos);
+    if (result && !result.successful) {
+      throw new Error(
+        `QoS override validation failed: ${result.reason || 'unknown reason'}`
+      );
+    }
+  }
+}
+
+module.exports = {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+  declareQosParameters,
+  _resolveQoS,
+};