unetjs 5.0.1 → 6.0.0

package/dist/cjs/unet.cjs

@@ -1,8 +1,8 @@
-/* unet.js v5.0.1 2025-09-10T10:45:09.129Z */
+/* unet.js v6.0.0 2026-04-01T02:42:00.135Z */
 
 'use strict';
 
-/* fjage.js v2.2.2 */
+/* fjage.js v2.3.0 */
 
 /**
 * An action represented by a message. The performative actions are a subset of the
@@ -1846,6 +1846,60 @@ const ParameterReq = MessageClass('org.arl.fjage.param.ParameterReq');
 */
 MessageClass('org.arl.fjage.param.ParameterRsp');
 
+/**
+* Request to write contents to a file, or delete a file.
+*
+* @typedef {Message} PutFileReq
+* @property {string} filename - name of the file to be written to or deleted
+* @property {number} [content] - content to be written to the file as a byte array. If not provided, the file will be deleted.
+* @property {number} [offset=0] - offset in the file to write the content to.
+* @exports PutFileReq
+*/
+const PutFileReq = MessageClass('org.arl.fjage.shell.PutFileReq');
+
+
+/**
+* Request to read a file or a directory.
+*
+* If the filename specified represents a directory, then the contents of the
+* directory (list of files) are returned as a tab separated string with:
+*   filename, file size, last modification time.
+*
+* The time is represented as epoch time (milliseconds since 1 Jan 1970).
+*
+* @typedef {Message} GetFileReq
+* @property {string} filename - name of the file or directory to be read
+* @property {number} [offset=0] - offset in the file to read from (ignored for directories)
+* @property {number} [length=0] - number of bytes to read from the file (ignored for directories). If 0,
+* the entire file will be read.
+*  @exports GetFileReq
+*/
+const GetFileReq = MessageClass('org.arl.fjage.shell.GetFileReq');
+
+/**
+* Response to a {@link GetFileReq}, with the contents of the file or the directory.
+*
+* @typedef {Message} GetFileRsp
+* @property {string} filename - name of the file or directory that was read
+* @property {number} [content] - content of the file as a byte array. If the filename represents a directory,
+* the content consists of a list of files (one file per line). Each line starts with the filename
+* (with a trailing "/" if it is a directory), "\t", file size in bytes, "\t", and last modification date.
+* @property {number} [offset=0] - offset in the file that the content corresponds to (ignored for directories)
+* @property {boolean} [directory=false] - indicates if the filename represents a directory
+* @exports GetFileRsp
+*/
+const GetFileRsp = MessageClass('org.arl.fjage.shell.GetFileRsp');
+
+/**
+* Request to execute shell command/script.
+*
+* @typedef {Message} ShellExecReq
+* @property {string} command - shell command or script to be executed
+* @property {boolean} ans  - indicates if the response to this request should include the output of the command/script execution
+* @exports ShellExecReq
+*/
+const ShellExecReq = MessageClass('org.arl.fjage.shell.ShellExecReq');
+
 /**
 * Services supported by fjage agents.
 */
@@ -1858,9 +1912,15 @@ init();
 const DatagramReq$1 = MessageClass('org.arl.unet.DatagramReq');
 const DatagramNtf$1 = MessageClass('org.arl.unet.DatagramNtf');
 const TxFrameReq = MessageClass('org.arl.unet.phy.TxFrameReq', DatagramReq$1);
-const RxFrameNtf$1 = MessageClass('org.arl.unet.phy.RxFrameNtf', DatagramNtf$1);
+const RxFrameNtf = MessageClass('org.arl.unet.phy.RxFrameNtf', DatagramNtf$1);
 const BasebandSignal = MessageClass('org.arl.unet.bb.BasebandSignal');
 
+const UnetTopics = {
+    'PARAMCHANGE' : 'org.arl.unet.Topics.PARAMCHANGE',  // Topic for parameter change notification.
+    'LIFECYCLE' : 'org.arl.unet.Topics.LIFECYCLE',      // Topic for agent lifecycle notification.
+    'DATAGRAM' : 'org.arl.unet.Topics.DATAGRAM',        // Topic for incoming datagram notification.
+};
+
 let UnetServices = {
   'NODE_INFO': 'org.arl.unet.Services.NODE_INFO',
   'ADDRESS_RESOLUTION': 'org.arl.unet.Services.ADDRESS_RESOLUTION',
@@ -1905,6 +1965,13 @@ let Protocol = {
  * @typedef {Object.<string, MessageClass>} UnetMessages
  */
 let UnetMessages = {
+
+  // fjage
+  'PutFileReq'             : PutFileReq,
+  'GetFileReq'             : GetFileReq,
+  'GetFileRsp'             : GetFileRsp,
+  'ShellExecReq'           : ShellExecReq,
+
   // unet
   'TestReportNtf'          : MessageClass('org.arl.unet.TestReportNtf'),
   'AbnormalTerminationNtf' : MessageClass('org.arl.unet.AbnormalTerminationNtf'),
@@ -1917,6 +1984,7 @@ let UnetMessages = {
   'DatagramNtf'            : MessageClass('org.arl.unet.DatagramNtf'),
   'DatagramProgressNtf'    : MessageClass('org.arl.unet.DatagramProgressNtf'),
   'DatagramReq'            : MessageClass('org.arl.unet.DatagramReq'),
+  'DatagramTransmissionNtf': MessageClass('org.arl.unet.DatagramTransmissionNtf'),
   'ParamChangeNtf'         : MessageClass('org.arl.unet.ParamChangeNtf'),
   'RefuseRsp'              : MessageClass('org.arl.unet.RefuseRsp'),
   'FailureNtf'             : MessageClass('org.arl.unet.FailureNtf'),
@@ -1930,9 +1998,9 @@ let UnetMessages = {
 
   // phy
   'FecDecodeReq'           : MessageClass('org.arl.unet.phy.FecDecodeReq'),
-  'RxSWiG1FrameNtf'        : MessageClass('org.arl.unet.phy.RxSWiG1FrameNtf', RxFrameNtf$1),
+  'RxSWiG1FrameNtf'        : MessageClass('org.arl.unet.phy.RxSWiG1FrameNtf', RxFrameNtf),
   'TxSWiG1FrameReq'        : MessageClass('org.arl.unet.phy.TxSWiG1FrameReq', TxFrameReq),
-  'RxJanusFrameNtf'        : MessageClass('org.arl.unet.phy.RxJanusFrameNtf', RxFrameNtf$1),
+  'RxJanusFrameNtf'        : MessageClass('org.arl.unet.phy.RxJanusFrameNtf', RxFrameNtf),
   'TxJanusFrameReq'        : MessageClass('org.arl.unet.phy.TxJanusFrameReq', TxFrameReq),
   'BadFrameNtf'            : MessageClass('org.arl.unet.phy.BadFrameNtf'),
   'BadRangeNtf'            : MessageClass('org.arl.unet.phy.BadRangeNtf'),
@@ -1986,6 +2054,7 @@ let UnetMessages = {
   'RemoteFileGetReq'       : MessageClass('org.arl.unet.remote.RemoteFileGetReq'),
   'RemoteFileNtf'          : MessageClass('org.arl.unet.remote.RemoteFileNtf'),
   'RemoteFilePutReq'       : MessageClass('org.arl.unet.remote.RemoteFilePutReq'),
+  'RemoteDeliveryNtf'      : MessageClass('org.arl.unet.remote.RemoteDeliveryNtf'),
   'RemoteSuccessNtf'       : MessageClass('org.arl.unet.remote.RemoteSuccessNtf'),
   'RemoteTextNtf'          : MessageClass('org.arl.unet.remote.RemoteTextNtf'),
   'RemoteTextReq'          : MessageClass('org.arl.unet.remote.RemoteTextReq'),
@@ -2040,243 +2109,33 @@ function _initConv(lat){
   return [xScale, yScale];
 }
 
-/**
- * A message which requests the transmission of the datagram from the Unet
- *
- * @typedef {Message} DatagramReq
- * @property {number[]} data - data as an Array of bytes
- * @property {number} from - from/source node address
- * @property {number} to - to/destination node address
- * @property {number} protocol - protocol number to be used to send this Datagram
- * @property {boolean} reliability - true if Datagram should be reliable, false if unreliable
- * @property {number} ttl - time-to-live for the datagram. Time-to-live is advisory, and an agent may choose it ignore it
- */
-
-/**
- * Notification of received datagram message received by the Unet node.
- *
- * @typedef {Message} DatagramNtf
- * @property {number[]} data - data as an Array of bytes
- * @property {number} from - from/source node address
- * @property {number} to - to/destination node address
- * @property {number} protocol - protocol number to be used to send this Datagram
- * @property {number} ttl - time-to-live for the datagram. Time-to-live is advisory, and an agent may choose it ignore it
- */
-
-/**
- * An identifier for an agent or a topic.
- * @external AgentID
- * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
- */
-
-/**
- * Services supported by fjage agents.
- * @external Services
- * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
- */
-
-/**
- *  An action represented by a message.
- * @external Performative
- * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
- */
-
-/**
- * Function to creates a unqualified message class based on a fully qualified name.
- * @external MessageClass
- * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
- */
-
-/**
- * A caching CachingAgentID which caches Agent parameters locally.
- *
- * @class
- * @extends AgentID
- * @param {string | AgentID} name - name of the agent or an AgentID to copy
- * @param {boolean} topic - name of topic
- * @param {Gateway} owner - Gateway owner for this AgentID
- * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
- *
-*/
-class CachingAgentID extends AgentID {
-
-  constructor(name, topic, owner, greedy=true) {
-    if (name instanceof AgentID) {
-      super(name.getName(), name.topic, name.owner);
-    } else {
-      super(name, topic, owner);
-    }
-    this.greedy = greedy;
-    this.cache = {};
-    this.specialParams = ['name', 'version'];
-  }
-
-  /**
-   * Sets parameter(s) on the Agent referred to by this AgentID, and caches the parameter(s).
-   *
-   * @param {(string|string[])} params - parameters name(s) to be set
-   * @param {(Object|Object[])} values - parameters value(s) to be set
-   * @param {number} [index=-1] - index of parameter(s) to be set
-   * @param {number} [timeout=5000] - timeout for the response
-   * @returns {Promise<(Object|Object[])>} - a promise which returns the new value(s) of the parameters
-   */
-  async set(params, values, index=-1, timeout=5000) {
-    let s = await super.set(params, values, index, timeout);
-    this._updateCache(params, s, index);
-    return s;
-  }
-
-  /**
-   * Gets parameter(s) on the Agent referred to by this AgentID, getting them from the cache if possible.
-   *
-   * @param {(string|string[])} params - parameters name(s) to be fetched
-   * @param {number} [index=-1] - index of parameter(s) to be fetched
-   * @param {number} [timeout=5000] - timeout for the response
-   * @param {number} [maxage=5000] - maximum age of the cached result to retreive
-   * @returns {Promise<(Object|Object[])>} - a promise which returns the value(s) of the parameters
-   */
-  async get(params, index=-1, timeout=5000, maxage=5000) {
-    if (this._isCached(params, index, maxage)) return this._getCache(params, index);
-    if (this.greedy &&
-      !(Array.isArray(params) && [...new Set([...params, ...this.specialParams])].length!=0) &&
-      !this.specialParams.includes(params)) {
-      let rsp = await super.get(null, index, timeout);
-      this._updateCache(null, rsp, index);
-      if (!rsp) return Array.isArray(params) ? new Array(params.length).fill(null) : null;
-      if (!params) return rsp;
-      else if (Array.isArray(params)) {
-        return params.map(p => {
-          let f = Object.keys(rsp).find(rv => this._toNamed(rv) === p);
-          return f ? rsp[f] : null;
-        });
-      } else {
-        let f = Object.keys(rsp).find(rv => this._toNamed(rv) === params);
-        return f ? rsp[f] : null;
-      }
-    } else {
-      let r = await super.get(params, index, timeout);
-      this._updateCache(params, r, index);
-      return r;
-    }
-  }
-
-  _updateCache(params, vals, index) {
-    if (vals == null || Array.isArray(vals) && vals.every(v => v == null)) return;
-    if (params == null) {
-      params = Object.keys(vals);
-      vals = Object.values(vals);
-    } else if (!Array.isArray(params)) params = [params];
-    if (!Array.isArray(vals)) vals = [vals];
-    params = params.map(this._toNamed);
-    if (this.cache[index.toString()] === undefined) this.cache[index.toString()] = {};
-    let c = this.cache[index.toString()];
-    for (let i = 0; i < params.length; i++) {
-      if (c[params[i]] === undefined) c[params[i]] = {};
-      c[params[i]].value = vals[i];
-      c[params[i]].ctime = Date.now();
-    }
-  }
-
-  _isCached(params, index, maxage) {
-    if (maxage <= 0) return false;
-    if (params == null) return false;
-    let c = this.cache[index.toString()];
-    if (!c) {
-      return false;
-    }
-    if (!Array.isArray(params)) params = [params];
-    const rv = params.every(p => {
-      p = this._toNamed(p);
-      return (p in c) && (Date.now() - c[p].ctime <= maxage);
-    });
-    return rv;
-  }
-
-  _getCache(params, index) {
-    let c = this.cache[index.toString()];
-    if (!c) return null;
-    if (!Array.isArray(params)){
-      if (params in c) return c[params].value;
-      return null;
-    }else {
-      return params.map(p => p in c ? c[p].value : null);
-    }
-  }
-
-  _toNamed(param) {
-    const idx = param.lastIndexOf('.');
-    if (idx < 0) return param;
-    else return param.slice(idx+1);
-  }
-
-}
-
-
-class CachingGateway extends Gateway{
-
-  /**
-   * Get an AgentID for a given agent name.
-   *
-   * @param {string} name - name of agent
-   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
-   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
-   * @returns {AgentID|CachingAgentID} - AgentID for the given name
-   */
-  agent(name, caching=true, greedy=true) {
-    const aid = super.agent(name);
-    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
-  }
-
-  /**
-   * Returns an object representing the named topic.
-   *
-   * @param {string|AgentID} topic - name of the topic or AgentID
-   * @param {string} topic2 - name of the topic if the topic param is an AgentID
-   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
-   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
-   * @returns {AgentID|CachingAgentID} - object representing the topic
-   */
-  topic(topic, topic2, caching=true, greedy=true) {
-    const aid = super.topic(topic, topic2);
-    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
-  }
-
-  /**
-   * Finds an agent that provides a named service. If multiple agents are registered
-   * to provide a given service, any of the agents' id may be returned.
-   *
-   * @param {string} service - the named service of interest
-   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
-   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
-   * @returns {Promise<?AgentID|CachingAgentID>} - a promise which returns an agent id for an agent that provides the service when resolved
-   */
-  async agentForService(service, caching=true, greedy=true) {
-    const aid = await super.agentForService(service);
-    if (!aid) return aid;
-    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
-  }
-
-  /**
-   * Finds all agents that provides a named service.
-   *
-   * @param {string} service - the named service of interest
-   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
-   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
-   * @returns {Promise<?AgentID|CachingAgentID[]>} - a promise which returns an array of all agent ids that provides the service when resolved
-   */
-  async agentsForService(service, caching=true, greedy=true) {
-    const aids = await super.agentsForService(service);
-    return caching ? aids.map(a => new CachingAgentID(a, null, null, greedy)) : aids;
-  }
-}
-
+const BROADCAST_ADDR = 0;
 const REQUEST_TIMEOUT = 1000;
+const NON_BLOCKING = 0;
+const SEMI_BLOCKING = 1;
+const BLOCKING = 2;
 
 const AddressResolutionReq = UnetMessages.AddressResolutionReq;
+const DatagramDeliveryNtf = UnetMessages.DatagramDeliveryNtf;
+const DatagramFailureNtf = UnetMessages.DatagramFailureNtf;
 const DatagramReq = UnetMessages.DatagramReq;
 const DatagramNtf = UnetMessages.DatagramNtf;
-const RxFrameNtf = UnetMessages.RxFrameNtf;
+const DatagramTransmissionNtf = UnetMessages.DatagramTransmissionNtf;
+const RemoteDeliveryNtf = UnetMessages.RemoteDeliveryNtf;
+const RemoteFailureNtf = UnetMessages.RemoteFailureNtf;
+const RemoteSuccessNtf = UnetMessages.RemoteSuccessNtf;
+
+function isReservedProtocol(protocol) {
+  return protocol != Protocol.DATA && (protocol < Protocol.USER || protocol > Protocol.MAX);
+}
+
+function hasValue(value) {
+  return value !== undefined && value !== null;
+}
 
+function hasFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
 /**
  * Creates a new UnetSocket to connect to a running Unet instance. This constructor returns a
  * {@link Promise} instead of the constructed UnetSocket object. Use `await` or `.then()` to get
@@ -2297,18 +2156,63 @@ class UnetSocket {
 
   constructor(hostname, port, path='') {
     return (async () => {
-      this.gw = new Gateway({
+      this._gw = new Gateway({
         hostname : hostname,
         port : port,
         path : path
       });
-      this.localProtocol = -1;
-      this.remoteAddress = -1;
-      this.remoteProtocol = Protocol.DATA;
-      this.timeout = 0;
-      this.provider = null;
-      const alist = await this.gw.agentsForService(Services.DATAGRAM);
-      alist.forEach(a => {this.gw.subscribe(this.gw.topic(a));});
+      this._localProtocol = -1;
+      this._remoteAddress = -1;
+      this._localAddress = -1;
+      this._remoteProtocol = Protocol.DATA;
+      this._timeout = 0;
+      this._serviceProvider = null;
+      this._ttl = NaN;
+      this._priority = null;
+      this._reliability = null;
+      this._route = null;
+      this._mimeType = null;
+      this._remoteRecipient = null;
+      this._mailbox = null;
+      this._messageClass = null;
+      this._sendMode = SEMI_BLOCKING;
+      this._warnedDeprecatedSend = false;
+      this._paramChangeCallbacks = {};
+
+      //for new UnetStack versions (5.2.0 and later)
+      this._gw.subscribe(this._gw.topic(UnetTopics.DATAGRAM));
+
+      //for compatibility with older UnetStack versions (before 5.2.0)
+      const alist = await this._gw.agentsForService(Services.DATAGRAM);
+      alist.forEach(a => {this._gw.subscribe(this._gw.topic(a));});
+
+      // get local nodeinfo agent
+      const nodeinfo = await this._gw.agentForService(Services.NODE_INFO);
+
+      // subscribe to paramchange notifications for onParamChange callbacks
+      this._gw.subscribe(this._gw.topic(UnetTopics.PARAMCHANGE));
+      if (nodeinfo != null) this._gw.subscribe(this._gw.topic(nodeinfo)); // nodeinfo publishes param changes for local node parameters
+      this._gw.addMessageListener(msg => {
+        if (msg instanceof UnetMessages.ParamChangeNtf) {
+          const sender = (msg.sender instanceof AgentID) ? msg.sender.name : msg.sender;
+          if (msg.paramValues != null){
+            for (const p in msg.paramValues) {
+              // if p has dots inside then take the substring after the last dot as the parameter name,
+              // since many times fully qualified parameter names are used in the notifications
+              const paramName = p.includes('.') ? p.substring(p.lastIndexOf('.') + 1) : p;
+              const callback = this._paramChangeCallbacks[sender + '.' + paramName];
+              if (callback != null) callback(msg.paramValues[p]);
+            }
+          }
+        }
+      });
+
+      // get local node address and subscribe to changes in the local node address
+      if (nodeinfo != null) {
+        this.onParamChange(nodeinfo.name, 'address', (addr) => { this._localAddress = addr; });
+        this._localAddress = await nodeinfo.get('address');
+      }
+
       return this;
     })();
   }
@@ -2318,8 +2222,8 @@ class UnetSocket {
    * @returns {void}
    */
   close() {
-    this.gw.close();
-    this.gw = null;
+    this._gw.close();
+    this._gw = null;
   }
 
   /**
@@ -2327,7 +2231,7 @@ class UnetSocket {
    * @returns {boolean} - true if closed, false if open
    */
   isClosed() {
-    return this.gw == null;
+    return this._gw == null;
   }
 
   /**
@@ -2339,7 +2243,7 @@ class UnetSocket {
    */
   bind(protocol) {
     if (protocol == Protocol.DATA || (protocol >= Protocol.USER && protocol <= Protocol.MAX)) {
-      this.localProtocol = protocol;
+      this._localProtocol = protocol;
       return true;
     }
     return false;
@@ -2350,13 +2254,13 @@ class UnetSocket {
    * Protocol numbers between Protocol.DATA+1 to Protocol.USER-1 are considered reserved.
    * @returns {void}
    */
-  unbind() { this.localProtocol = -1;}
+  unbind() { this._localProtocol = -1;}
 
   /**
    * Checks if a socket is bound.
    * @returns {boolean} - true if bound to a protocol, false if unbound
    */
-  isBound() { return this.localProtocol >= 0;}
+  isBound() { return this._localProtocol >= 0;}
 
   /**
    * Sets the default destination address and destination protocol number for datagrams sent
@@ -2372,8 +2276,8 @@ class UnetSocket {
    */
   connect(to, protocol) {
     if (to >= 0 && (protocol == Protocol.DATA || (protocol >= Protocol.USER && protocol <= Protocol.MAX))) {
-      this.remoteAddress = to;
-      this.remoteProtocol = protocol;
+      this._remoteAddress = to;
+      this._remoteProtocol = protocol;
       return true;
     }
     return false;
@@ -2385,23 +2289,23 @@ class UnetSocket {
    * @returns {void}
    */
   disconnect() {
-    this.remoteAddress = -1;
-    this.remoteProtocol = 0;
+    this._remoteAddress = -1;
+    this._remoteProtocol = 0;
   }
 
   /**
    * Checks if a socket is connected, i.e., has a default destination address and protocol number.
    * @returns {boolean} - true if connected, false otherwise
    */
-  isConnected() { return this.remoteAddress >= 0; }
+  isConnected() { return this._remoteAddress >= 0; }
 
   /**
    * Gets the local node address of the Unet node connected to.
    * @returns {Promise<int>} - local node address, or -1 on error
    */
   async getLocalAddress() {
-    if (this.gw == null) return -1;
-    const nodeinfo = await this.gw.agentForService(Services.NODE_INFO);
+    if (this._gw == null) return -1;
+    const nodeinfo = await this._gw.agentForService(Services.NODE_INFO);
     if (nodeinfo == null) return -1;
     const addr = await nodeinfo.get('address');
     return addr != null ? addr : -1;
@@ -2409,21 +2313,21 @@ class UnetSocket {
 
   /**
    * Gets the protocol number that the socket is bound to.
-   * @returns {number}} - protocol number if socket is bound, -1 otherwise
+   * @returns {number} - protocol number if socket is bound, -1 otherwise
    */
-  getLocalProtocol() { return this.localProtocol; }
+  getLocalProtocol() { return this._localProtocol; }
 
   /**
    * Gets the default destination node address for a connected socket.
-   * @returns {number}} - default destination node address if connected, -1 otherwise
+   * @returns {number} - default destination node address if connected, -1 otherwise
    */
-  getRemoteAddress() { return this.remoteAddress; }
+  getRemoteAddress() { return this._remoteAddress; }
 
   /**
    * Gets the default transmission protocol number.
-   * @returns {number}} - default protocol number used to transmit a datagram
+   * @returns {number} - default protocol number used to transmit a datagram
    */
-  getRemoteProtocol() { return this.remoteProtocol; }
+  getRemoteProtocol() { return this._remoteProtocol; }
 
   /**
    * Sets the timeout for datagram reception. A timeout of 0 means the
@@ -2435,14 +2339,275 @@ class UnetSocket {
    */
   setTimeout(ms) {
     if (ms < 0) ms = 0;
-    this.timeout = ms;
+    this._timeout = ms;
   }
 
   /**
    * Gets the timeout for datagram reception.
    * @returns {number} - timeout in milliseconds
    */
-  getTimeout() { return this.timeout; }
+  getTimeout() { return this._timeout; }
+
+  /**
+   * Sets the default time-to-live for datagrams sent using this socket.
+   * TTL is advisory; an agent may choose to ignore it.
+   * @param {number} ttl - time-to-live in seconds
+   * @returns {void}
+   */
+  setTTL(ttl) {
+    this._ttl = ttl;
+  }
+
+  /**
+   * Gets the default time-to-live for datagrams sent using this socket.
+   * @returns {number} - time-to-live in seconds, or NaN if not set
+   */
+  getTTL() {
+    return this._ttl;
+  }
+
+  /**
+   * Sets the default priority for datagrams sent using this socket.
+   * @param {*} priority - priority value; interpretation is provider-dependent
+   * @returns {void}
+   */
+  setPriority(priority) {
+    this._priority = priority;
+  }
+
+  /**
+   * Gets the default priority for datagrams sent using this socket.
+   * @returns {*} - priority value, or null if not set
+   */
+  getPriority() {
+    return this._priority;
+  }
+
+  /**
+   * Sets the default reliability for datagrams sent using this socket.
+   * When set to true, the socket will request reliable delivery and, in
+   * SEMI_BLOCKING mode, will wait for a delivery confirmation before returning.
+   * @param {boolean} reliability - true for reliable delivery, false for unreliable
+   * @returns {void}
+   */
+  setReliability(reliability) {
+    this._reliability = reliability;
+  }
+
+  /**
+   * Gets the default reliability setting for datagrams sent using this socket.
+   * @returns {boolean|null} - true if reliable, false if unreliable, null if not set
+   */
+  getReliability() {
+    return this._reliability;
+  }
+
+  /**
+   * Sets the default route identifier for datagrams sent using this socket.
+   * Route selection is provider-dependent; not all providers support explicit routing.
+   * @param {*} route - route identifier
+   * @returns {void}
+   */
+  setRoute(route) {
+    this._route = route;
+  }
+
+  /**
+   * Gets the default route identifier for datagrams sent using this socket.
+   * @returns {*} - route identifier, or null if not set
+   */
+  getRoute() {
+    return this._route;
+  }
+
+  /**
+   * Sets the default MIME type describing the datagram payload.
+   * This can be used by REMOTE service providers to apply content-aware compression.
+   * @param {string} mimeType - MIME type string (e.g. 'application/json')
+   * @returns {void}
+   */
+  setMimeType(mimeType) {
+    this._mimeType = mimeType;
+  }
+
+  /**
+   * Gets the default MIME type for datagrams sent using this socket.
+   * @returns {string|null} - MIME type string, or null if not set
+   */
+  getMimeType() {
+    return this._mimeType;
+  }
+
+  /**
+   * Sets the default remote recipient for datagrams sent using this socket.
+   * Used by REMOTE service providers to address a specific entity on the remote node.
+   * @param {*} remoteRecipient - remote recipient identifier (e.g. an AgentID or name string)
+   * @returns {void}
+   */
+  setRemoteRecipient(remoteRecipient) {
+    this._remoteRecipient = remoteRecipient;
+  }
+
+  /**
+   * Gets the default remote recipient for datagrams sent using this socket.
+   * @returns {*} - remote recipient identifier, or null if not set
+   */
+  getRemoteRecipient() {
+    return this._remoteRecipient;
+  }
+
+  /**
+   * Sets the default mailbox name for datagrams sent using this socket.
+   * Mailboxes are used by REMOTE service providers to deliver messages
+   * to a named queue on the remote node.
+   * @param {string} mailbox - mailbox name
+   * @returns {void}
+   */
+  setMailbox(mailbox) {
+    this._mailbox = mailbox;
+  }
+
+  /**
+   * Gets the default mailbox name for datagrams sent using this socket.
+   * @returns {string|null} - mailbox name, or null if not set
+   */
+  getMailbox() {
+    return this._mailbox;
+  }
+
+  /**
+   * Sets the default application message class for datagrams sent using this socket.
+   * Used by REMOTE service providers to associate a fully-qualified class name with the payload.
+   * @param {string} messageClass - fully-qualified message class name (e.g. 'org.example.Status')
+   * @returns {void}
+   */
+  setMessageClass(messageClass) {
+    this._messageClass = messageClass;
+  }
+
+  /**
+   * Gets the default application message class for datagrams sent using this socket.
+   * @returns {string|null} - message class name, or null if not set
+   */
+  getMessageClass() {
+    return this._messageClass;
+  }
+
+  /**
+   * Overrides the service provider used to transmit datagrams. When set, provider
+   * auto-selection is bypassed and all sends go through the specified agent.
+   * Pass null to re-enable auto-selection.
+   * @param {AgentID|string|null} provider - agent id, agent name string, or null to clear the override
+   * @returns {void}
+   */
+  setServiceProvider(provider) {
+    if (typeof provider === 'string') provider = this.agent(provider);
+    this._serviceProvider = provider instanceof AgentID || provider == null ? provider : null;
+  }
+
+  /**
+   * Gets the currently configured service provider override.
+   * @returns {AgentID|null} - the override agent id, or null if auto-selection is active
+   */
+  getServiceProvider() {
+    return this._serviceProvider;
+  }
+
+  /**
+   * Sets the send mode that controls how send() behaves after the provider accepts a request:
+   * - `UnetSocket.NON_BLOCKING` (0): returns immediately after the provider agrees.
+   * - `UnetSocket.SEMI_BLOCKING` (1): if reliability is not true, returns after AGREE; otherwise
+   *   waits for a delivery confirmation (RemoteDeliveryNtf / DatagramDeliveryNtf) or failure.
+   * - `UnetSocket.BLOCKING` (2): waits for a transmission or delivery notification
+   *   (DatagramTransmissionNtf, DatagramDeliveryNtf) before returning.
+   * The default is SEMI_BLOCKING.
+   * @param {number} sendMode - one of UnetSocket.NON_BLOCKING, SEMI_BLOCKING, or BLOCKING
+   * @returns {void}
+   */
+  setSendMode(sendMode) {
+    if ([NON_BLOCKING, SEMI_BLOCKING, BLOCKING].includes(sendMode)) this._sendMode = sendMode;
+  }
+
+  /**
+   * Gets the current send mode.
+   * @returns {number} - current send mode (NON_BLOCKING=0, SEMI_BLOCKING=1, BLOCKING=2)
+   */
+  getSendMode() {
+    return this._sendMode;
+  }
+
+  async _chooseAgentForService(service) {
+    const agents = await this._gw.agentsForService(service);
+    if (agents == null || agents.length === 0) return null;
+    return agents[Math.floor(Math.random() * agents.length)];
+  }
+
+  async _resolveProvider() {
+    if (this._serviceProvider != null) return this._serviceProvider;
+    const serviceOrder = [
+      Services.REMOTE,
+      Services.TRANSPORT,
+      Services.ROUTING,
+      Services.LINK,
+      Services.PHYSICAL,
+      Services.DATAGRAM,
+    ];
+    for (const service of serviceOrder) {
+      const provider = await this._chooseAgentForService(service);
+      if (provider != null) return provider;
+    }
+    return null;
+  }
+
+  _applySocketSettings(req) {
+    if (!hasValue(req.priority) && hasValue(this._priority)) req.priority = this._priority;
+    if (!hasValue(req.reliability) && hasValue(this._reliability)) req.reliability = this._reliability;
+    if ((!hasValue(req.ttl) || Number.isNaN(req.ttl)) && hasFiniteNumber(this._ttl)) req.ttl = this._ttl;
+    if (!hasValue(req.route) && hasValue(this._route)) req.route = this._route;
+    if (!hasValue(req.mimeType) && hasValue(this._mimeType)) req.mimeType = this._mimeType;
+    if (!hasValue(req.remoteRecipient) && hasValue(this._remoteRecipient)) req.remoteRecipient = this._remoteRecipient;
+    if (!hasValue(req.mailbox) && hasValue(this._mailbox)) req.mailbox = this._mailbox;
+    if (!hasValue(req.messageClass) && hasValue(this._messageClass)) req.messageClass = this._messageClass;
+  }
+
+  _effectiveReliability(req) {
+    return hasValue(req.reliability) ? req.reliability : this._reliability;
+  }
+
+  async _waitForNotification(req, types, timeout = REQUEST_TIMEOUT) {
+    return await this._gw.receive(msg => {
+      if (!types.some(type => msg instanceof type)) return false;
+      if (hasValue(msg.inReplyTo) && msg.inReplyTo === req.msgID) return true;
+      return false;
+    }, timeout);
+  }
+
+  async _waitForSemiBlockingOutcome(req) {
+    const notification = await this._waitForNotification(req, [
+      DatagramDeliveryNtf,
+      DatagramFailureNtf,
+      RemoteDeliveryNtf,
+      RemoteSuccessNtf,
+      RemoteFailureNtf,
+    ]);
+    if (notification == null) return false;
+    if (notification instanceof DatagramFailureNtf || notification instanceof RemoteFailureNtf) return false;
+    return true;
+  }
+
+  async _waitForBlockingOutcome(req) {
+    const notification = await this._waitForNotification(req, [
+      DatagramTransmissionNtf,
+      DatagramDeliveryNtf,
+      DatagramFailureNtf,
+      RemoteDeliveryNtf,
+      RemoteSuccessNtf,
+      RemoteFailureNtf,
+    ]);
+    if (notification == null) return false;
+    if (notification instanceof DatagramFailureNtf || notification instanceof RemoteFailureNtf) return false;
+    return true;
+  }
 
   /**
    * Transmits a datagram to the specified node address using the specified protocol.
@@ -2453,32 +2618,43 @@ class UnetSocket {
    * @param {number} protocol - protocol number
    * @returns {Promise<boolean>} - true if the Unet node agreed to send out the Datagram, false otherwise
    */
-  async send(data, to=this.remoteAddress, protocol=this.remoteProtocol) {
-    if (to < 0 || this.gw == null) return false;
-    var req;
-    if (Array.isArray(data)){
+  async send(data, to=this._remoteAddress, protocol=this._remoteProtocol) {
+    if (this._gw == null) return false;
+    let req;
+    if (Array.isArray(data)) {
       req = new DatagramReq();
       req.data = data;
       req.to = to;
       req.protocol = protocol;
-    } else if (data instanceof DatagramReq){
+    } else if (data instanceof DatagramReq) {
       req = data;
+      if (!this._warnedDeprecatedSend && typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn('UnetSocket.send(DatagramReq) is deprecated; prefer socket metadata setters with send(data, to, protocol).');
+        this._warnedDeprecatedSend = true;
+      }
     } else {
       return false;
     }
-    let p = req.protocol;
-    if (p != Protocol.DATA && (p < Protocol.USER || p > Protocol.MAX)) return false;
+    if ((!hasValue(req.to) || req.to < 0) && to >= 0) req.to = to;
+    if (!hasValue(req.protocol)) req.protocol = protocol;
+    this._applySocketSettings(req);
+
+    if (!Array.isArray(req.data) || req.to < 0 || isReservedProtocol(req.protocol)) return false;
     if (req.recipient == null) {
-      if (this.provider == null) this.provider = await this.gw.agentForService(Services.TRANSPORT);
-      if (this.provider == null) this.provider = await this.gw.agentForService(Services.ROUTING);
-      if (this.provider == null) this.provider = await this.gw.agentForService(Services.LINK);
-      if (this.provider == null) this.provider = await this.gw.agentForService(Services.PHYSICAL);
-      if (this.provider == null) this.provider = await this.gw.agentForService(Services.DATAGRAM);
-      if (this.provider == null) return false;
-      req.recipient = this.provider;
+      req.recipient = await this._resolveProvider();
+      if (req.recipient == null) return false;
     }
-    const rsp = await this.gw.request(req, REQUEST_TIMEOUT);
-    return (rsp != null && rsp.perf == Performative.AGREE);
+    const rsp = await this._gw.request(req, REQUEST_TIMEOUT);
+    if (rsp == null || rsp.perf != Performative.AGREE) return false;
+
+    if (this._sendMode === NON_BLOCKING) return true;
+
+    if (this._sendMode === SEMI_BLOCKING) {
+      if (this._effectiveReliability(req) !== true) return true;
+      return await this._waitForSemiBlockingOutcome(req);
+    }
+
+    return await this._waitForBlockingOutcome(req);
   }
 
   /**
@@ -2488,22 +2664,23 @@ class UnetSocket {
    * @returns {Promise<?DatagramNtf>} - datagram received by the socket
    */
   async receive() {
-    if (this.gw == null) return null;
-    return await this.gw.receive(msg => {
-      if (msg.__clazz__ != DatagramNtf.__clazz__ && msg.__clazz__ != RxFrameNtf.__clazz__ ) return false;
+    if (this._gw == null) return null;
+    return await this._gw.receive(msg => {
+      if (!(msg instanceof DatagramNtf)) return false;
       let p = msg.protocol;
+      if (msg.to != BROADCAST_ADDR && msg.to != this._localAddress) return false;  // Datagram not addressed to this node
       if (p == Protocol.DATA || p >= Protocol.USER) {
-        return this.localProtocol < 0 || this.localProtocol == p;
+        return this._localProtocol < 0 || this._localProtocol == p;
       }
       return false;
-    }, this.timeout);
+    }, this._timeout);
   }
 
   /**
    * Gets a Gateway to provide low-level access to UnetStack.
    * @returns {Gateway} - underlying fjage Gateway supporting this socket
    */
-  getGateway() { return this.gw; }
+  getGateway() { return this._gw; }
 
   /**
    * Gets an AgentID providing a specified service for low-level access to UnetStack
@@ -2511,8 +2688,8 @@ class UnetSocket {
    * @returns {Promise<?AgentID>} - a promise which returns an {@link AgentID} that provides the service when resolved
    */
   async agentForService(svc) {
-    if (this.gw == null) return null;
-    return await this.gw.agentForService(svc);
+    if (this._gw == null) return null;
+    return await this._gw.agentForService(svc);
   }
 
   /**
@@ -2521,8 +2698,8 @@ class UnetSocket {
    * @returns {Promise<AgentID[]>} - a promise which returns an array of {@link AgentID|AgentIDs} that provides the service when resolved
    */
   async agentsForService(svc) {
-    if (this.gw == null) return null;
-    return await this.gw.agentsForService(svc);
+    if (this._gw == null) return null;
+    return await this._gw.agentsForService(svc);
   }
 
   /**
@@ -2531,8 +2708,8 @@ class UnetSocket {
    * @returns {AgentID} - AgentID for the given name
    */
   agent(name) {
-    if (this.gw == null) return null;
-    return this.gw.agent(name);
+    if (this._gw == null) return null;
+    return this._gw.agent(name);
   }
 
   /**
@@ -2546,15 +2723,42 @@ class UnetSocket {
     const req = new AddressResolutionReq(nodeName);
     req.name = nodeName;
     req.recipient = arp;
-    const rsp = await this.gw.request(req, REQUEST_TIMEOUT);
+    const rsp = await this._gw.request(req, REQUEST_TIMEOUT);
     if (rsp == null || ! Object.prototype.hasOwnProperty.call(rsp, 'address')) return null;
     return rsp.address;
   }
+
+  /**
+   * Registers a callback function to be called when a parameter value changes for the local node. This
+   * uses the ParamChangeNtf messages published by the Unet node to notify of parameter changes. The callback
+   * function will be called with the new value of the parameter.
+   *
+   * @param {AgentID|string} agentId
+   * @param {string} paramName
+   * @param {function(object): void} callback
+   */
+  onParamChange(agentId, paramName, callback) {
+    if (agentId instanceof AgentID) agentId = agentId.name;
+    this._paramChangeCallbacks[agentId + '.' + paramName] = callback;
+  }
+
+  /**
+   * Removes a callback function registered to be called when a parameter value changes for the local node.
+   *
+   * @param {AgentID|string} agentId
+   * @param {string} paramName
+   */
+  removeParamChange(agentId, paramName) {
+    if (agentId instanceof AgentID) agentId = agentId.name;
+    delete this._paramChangeCallbacks[agentId + '.' + paramName];
+  }
 }
 
+UnetSocket.NON_BLOCKING = NON_BLOCKING;
+UnetSocket.SEMI_BLOCKING = SEMI_BLOCKING;
+UnetSocket.BLOCKING = BLOCKING;
+
 exports.AgentID = AgentID;
-exports.CachingAgentID = CachingAgentID;
-exports.CachingGateway = CachingGateway;
 exports.Gateway = Gateway;
 exports.Message = Message;
 exports.MessageClass = MessageClass;
@@ -2563,5 +2767,6 @@ exports.Protocol = Protocol;
 exports.Services = Services;
 exports.UnetMessages = UnetMessages;
 exports.UnetSocket = UnetSocket;
+exports.UnetTopics = UnetTopics;
 exports.toGps = toGps;
 exports.toLocal = toLocal;