sen-ether-client 0.1.1 → 0.1.3

package/bin/node-sen-probe.js

@@ -254,7 +254,9 @@ try {
 
   const client = new EtherClient({
     sessionName: target.session.name,
-    appName: 'sen-ether-probe'
+    appName: 'sen-ether-probe',
+    interfaceAddress: options.interfaceAddress,
+    discoveryPort: options.port
   });
   const remoteBuses = new Set();
   const requestedTypeHashes = new Set();
@@ -405,7 +407,7 @@ try {
     });
   }
 
-  client.joinBus(bus);
+  await client.joinBus(bus);
   await waitForEvent(client, 'busParticipantReady', 5000).catch(error => {
     console.warn(`[warn] ${error.message}; starting interest anyway`);
   });

package/lib/client.js

@@ -24,6 +24,18 @@ import { crc32 } from './crc32.js';
 
 const LINUX_OS_KIND = 1;
 const X64_CPU_ARCH = 1;
+const DEFAULT_DISCOVERY_PORT = 60543;
+const DEFAULT_BUS_MULTICAST_PORT = 50985;
+const BUS_HASH_SEED = 15071983;
+const FNV1A_OFFSET_BASIS = 0x811c9dc5;
+const FNV1A_PRIME = 0x01000193;
+const HASH_COMBINE_MAGIC = 0x9e3779b9;
+const DEFAULT_MULTICAST_RANGE = Object.freeze([
+  { min: 224, max: 239 },
+  { min: 0, max: 255 },
+  { min: 0, max: 255 },
+  { min: 0, max: 255 }
+]);
 
 function randomUInt32() {
   return randomBytes(4).readUInt32LE(0);
@@ -57,6 +69,87 @@ function detectCpuArch() {
   }
 }
 
+function discoveryPortFromEnv() {
+  const value = process.env.SEN_ETHER_DISCOVERY_PORT;
+  if (!value) {
+    return undefined;
+  }
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`invalid SEN discovery port in environment: ${value}`);
+  }
+  return port;
+}
+
+function resolveInterfaceAddress(value) {
+  const text = String(value || '').trim();
+  if (!text) {
+    return undefined;
+  }
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(text)) {
+    return text;
+  }
+
+  const interfaces = os.networkInterfaces();
+  const candidates = interfaces[text];
+  if (!candidates) {
+    return text;
+  }
+
+  const ipv4 = candidates.find(item => (item.family === 'IPv4' || item.family === 4) && !item.internal);
+  if (!ipv4) {
+    throw new Error(`network interface "${text}" has no non-internal IPv4 address`);
+  }
+  return ipv4.address;
+}
+
+function normalizeMulticastRange(value) {
+  const ranges = Array.isArray(value) && value.length === 4 ? value : DEFAULT_MULTICAST_RANGE;
+  return ranges.map((range, index) => {
+    const fallback = DEFAULT_MULTICAST_RANGE[index];
+    const min = Number(range?.min ?? fallback.min);
+    const max = Number(range?.max ?? fallback.max);
+    if (!Number.isInteger(min) || !Number.isInteger(max) || min < 0 || max > 255 || min > max) {
+      throw new Error(`invalid SEN bus multicast range at byte ${index}`);
+    }
+    return { min, max };
+  });
+}
+
+function computeByte(range, hashByte) {
+  const length = range.max - range.min;
+  return length !== 0 ? range.min + (hashByte % length) : range.min;
+}
+
+function hashIntegral(value, byteSize) {
+  let hash = FNV1A_OFFSET_BASIS;
+  for (let shift = (byteSize - 1) * 8; shift >= 0; shift -= 8) {
+    hash ^= (value >>> shift) & 0xff;
+    hash = Math.imul(hash, FNV1A_PRIME) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function combineHashed(seed, hashed) {
+  return (seed ^ (
+    (hashed + HASH_COMBINE_MAGIC + ((seed << 6) >>> 0) + (seed >>> 2)) >>> 0
+  )) >>> 0;
+}
+
+function computeBusMulticastGroup(sessionId, busId, discoveryPort, ranges) {
+  let hash = BUS_HASH_SEED;
+  hash = combineHashed(hash, hashIntegral(sessionId >>> 0, 4));
+  hash = combineHashed(hash, hashIntegral(busId >>> 0, 4));
+  hash = combineHashed(hash, hashIntegral(discoveryPort >>> 0, 2));
+  const bytes = [
+    computeByte(ranges[0], hash & 0xff),
+    computeByte(ranges[1], (hash >>> 8) & 0xff),
+    computeByte(ranges[2], (hash >>> 16) & 0xff),
+    computeByte(ranges[3], (hash >>> 24) & 0xff)
+  ];
+  return bytes.map((byte, index) => Math.min(Math.max(byte, ranges[index].min), ranges[index].max)).join('.');
+}
+
 /**
  * Create a ProcessInfo compatible with sen::kernel::getOwnProcessInfo.
  *
@@ -139,9 +232,17 @@ export class EtherClient extends EventEmitter {
       socketKeepAlive: true,
       socketKeepAliveInitialDelayMs: 1000,
       socketIdleTimeoutMs: 0,
+      discoveryPort: discoveryPortFromEnv() ?? DEFAULT_DISCOVERY_PORT,
+      busMulticastPort: DEFAULT_BUS_MULTICAST_PORT,
+      busMulticastRange: DEFAULT_MULTICAST_RANGE,
       ...options
     };
+    this.options.discoveryPort ??= discoveryPortFromEnv() ?? DEFAULT_DISCOVERY_PORT;
+    this.options.busMulticastPort ??= DEFAULT_BUS_MULTICAST_PORT;
+    this.options.busMulticastRange ??= DEFAULT_MULTICAST_RANGE;
     this.processInfo = createProcessInfo(this.options);
+    this.interfaceAddress = resolveInterfaceAddress(this.options.interfaceAddress);
+    this.busMulticastRange = normalizeMulticastRange(this.options.busMulticastRange);
     this.socket = undefined;
     this.udpSocket = undefined;
     this.receiveBuffer = Buffer.alloc(0);
@@ -242,6 +343,14 @@ export class EtherClient extends EventEmitter {
         udpSocket.close(resolve);
       }));
     }
+    for (const busState of this.buses.values()) {
+      if (busState.multicastSocket) {
+        closing.push(new Promise(resolve => {
+          busState.multicastSocket.close(resolve);
+        }));
+      }
+    }
+    this.buses.clear();
 
     await Promise.allSettled(closing);
   }
@@ -252,7 +361,7 @@ export class EtherClient extends EventEmitter {
    * @param {string} busName
    * @param {{ participantId?: number }} [options]
    */
-  joinBus(busName, options = {}) {
+  async joinBus(busName, options = {}) {
     if (!this.socket) {
       throw new Error('EtherClient is not connected');
     }
@@ -264,10 +373,21 @@ export class EtherClient extends EventEmitter {
       busId,
       participantId,
       readyRemoteParticipants: new Set(),
-      interests: new Map()
+      interests: new Map(),
+      multicastSocket: undefined,
+      multicastGroup: undefined
     };
 
     this.buses.set(busId, bus);
+    try {
+      if (this.options.busMulticast !== false) {
+        await this.#openBusMulticastSocket(bus);
+      }
+    } catch (error) {
+      this.buses.delete(busId);
+      throw error;
+    }
+
     this.#sendControlPayload(encodeEtherControlMessage({
       type: 'BusJoined',
       value: {
@@ -277,8 +397,20 @@ export class EtherClient extends EventEmitter {
       }
     }));
 
-    this.emit('busJoinedLocal', { busName, busId, participantId });
-    return { busName, busId, participantId };
+    this.emit('busJoinedLocal', {
+      busName,
+      busId,
+      participantId,
+      multicastGroup: bus.multicastGroup,
+      multicastPort: this.options.busMulticastPort
+    });
+    return {
+      busName,
+      busId,
+      participantId,
+      multicastGroup: bus.multicastGroup,
+      multicastPort: this.options.busMulticastPort
+    };
   }
 
   /**
@@ -426,6 +558,10 @@ export class EtherClient extends EventEmitter {
       }
     }));
     this.buses.delete(busState.busId);
+    if (busState.multicastSocket) {
+      busState.multicastSocket.close();
+      busState.multicastSocket = undefined;
+    }
     this.emit('busLeftLocal', {
       busName: busState.busName,
       busId: busState.busId,
@@ -573,6 +709,81 @@ export class EtherClient extends EventEmitter {
     }
   }
 
+  #onMulticastBusDatagram(busState, message, remote) {
+    try {
+      if (message.length < 8) {
+        throw new RangeError(`SEN multicast bus datagram too small: ${message.length}`);
+      }
+      const processId = message.readUInt32LE(0);
+      const payloadSize = message.readUInt32LE(4);
+      if (processId === this.processInfo.processId) {
+        return;
+      }
+      if (payloadSize !== message.length - 8) {
+        throw new RangeError(
+          `SEN multicast bus payload size mismatch: expected ${payloadSize}, got ${message.length - 8}`
+        );
+      }
+
+      const frame = {
+        to: busState.participantId,
+        busId: busState.busId,
+        message: message.subarray(8)
+      };
+      const busMessage = decodeBusMessage(frame.message);
+      this.emit('busFrame', { ...frame, busMessage, remote, multicast: true });
+      if (busMessage.categoryName === 'controlMessage') {
+        this.emit('busControlMessage', { ...frame, control: busMessage.control, remote, multicast: true });
+        return;
+      }
+      this.emit(busMessage.categoryName, { ...frame, ...busMessage, remote, multicast: true });
+    } catch (error) {
+      this.emit('error', error);
+    }
+  }
+
+  async #openBusMulticastSocket(busState) {
+    const group = computeBusMulticastGroup(
+      this.processInfo.sessionId,
+      busState.busId,
+      this.options.discoveryPort,
+      this.busMulticastRange
+    );
+    const port = this.options.busMulticastPort;
+    const bindAddress = process.platform === 'win32' ? undefined : group;
+    const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+    busState.multicastSocket = socket;
+    busState.multicastGroup = group;
+
+    socket.on('message', (message, remote) => this.#onMulticastBusDatagram(busState, message, remote));
+    socket.on('error', error => this.emit('error', error));
+
+    await new Promise((resolve, reject) => {
+      const onError = error => {
+        socket.off('listening', onListening);
+        reject(error);
+      };
+      const onListening = () => {
+        socket.off('error', onError);
+        try {
+          socket.addMembership(group, this.interfaceAddress);
+          socket.setMulticastLoopback(true);
+          if (this.interfaceAddress) {
+            socket.setMulticastInterface(this.interfaceAddress);
+          }
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      };
+
+      socket.once('error', onError);
+      socket.once('listening', onListening);
+      socket.bind(port, bindAddress);
+    });
+  }
+
   #onRemoteParticipantReady(busState, frame, value) {
     if (value.id !== busState.participantId) {
       return;

package/lib/sen.js

@@ -402,7 +402,12 @@ export class Sen extends EventEmitter {
       appName: config.appName,
       socketKeepAlive: config.socketKeepAlive,
       socketKeepAliveInitialDelayMs: config.socketKeepAliveInitialDelayMs,
-      socketIdleTimeoutMs: config.socketIdleTimeoutMs
+      socketIdleTimeoutMs: config.socketIdleTimeoutMs,
+      interfaceAddress: config.interfaceAddress,
+      discoveryPort: config.port,
+      busMulticast: config.busMulticast,
+      busMulticastPort: config.busMulticastPort,
+      busMulticastRange: config.busMulticastRange
     });
     this.client = client;
     this.target = target;
@@ -457,7 +462,7 @@ export class Sen extends EventEmitter {
 
     let senBus = this.buses.get(bus);
     if (!senBus) {
-      const joined = this.client.joinBus(bus);
+      const joined = await this.client.joinBus(bus);
       const participantReadyTimeoutMs = this.#participantReadyTimeout(options, timeout);
       await waitForEvent(this.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {
         this.emit('warning', error);
@@ -511,7 +516,7 @@ export class Sen extends EventEmitter {
 
     let senBus = this.buses.get(bus);
     if (!senBus) {
-      const joined = this.client.joinBus(bus);
+      const joined = await this.client.joinBus(bus);
       const participantReadyTimeoutMs = this.#participantReadyTimeout(options, timeout);
       await waitForEvent(this.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {
         this.emit('warning', error);
@@ -1124,7 +1129,7 @@ export class SenBus extends EventEmitter {
     await this.sen.waitForRemoteBus(this.name, busReadyTimeoutMs).catch(error => {
       this.sen.emit('warning', error);
     });
-    const joined = this.sen.client.joinBus(this.name);
+    const joined = await this.sen.client.joinBus(this.name);
     this.id = joined.busId;
     const participantReadyTimeoutMs = Math.min(timeoutMs, this.sen.options.participantReadyTimeoutMs ?? 1000);
     await waitForEvent(this.sen.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {

package/lib/values.js

@@ -70,9 +70,7 @@ function collectClassProperties(spec, typeRegistry, seen = new Set()) {
 
 function decodeEnum(reader, spec) {
   const storage = spec.data.value.storageType;
-  const key = decodeValueFromReader(reader, storage);
-  const item = spec.data.value.enums.find(candidate => candidate.key === key);
-  return item?.name ?? key;
+  return decodeValueFromReader(reader, storage);
 }
 
 function decodeStruct(reader, spec, typeRegistry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sen-ether-client",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Pure JavaScript SEN client for existing kernels over ether",
   "senCompatibility": {
     "kernelProtocolVersion": 9,