sen-ether-client 0.1.0

package/lib/discovery.js

@@ -0,0 +1,439 @@
+import dgram from 'node:dgram';
+import { EventEmitter } from 'node:events';
+import net from 'node:net';
+import os from 'node:os';
+import { decodeSessionPresenceBeam } from './codec.js';
+
+export const DEFAULT_DISCOVERY_GROUP = '239.255.0.44';
+export const DEFAULT_DISCOVERY_PORT = 60543;
+export const DEFAULT_SCAN_TIMEOUT_MS = 3000;
+export const TCP_DISCOVERY_BEAM_SIZE = 508;
+
+function processKey(beam) {
+  const { hostId, processId, sessionId } = beam.info;
+  return `${hostId}:${processId}:${sessionId}`;
+}
+
+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 normalizeTcpRemote(socket) {
+  return {
+    address: socket.remoteAddress,
+    family: socket.remoteFamily,
+    port: socket.remotePort,
+    transport: 'tcp'
+  };
+}
+
+function normalizeBeam(beam, remote) {
+  return {
+    key: processKey(beam),
+    protocolVersion: beam.protocolVersion,
+    session: {
+      id: beam.info.sessionId,
+      name: beam.info.sessionName
+    },
+    process: {
+      hostId: beam.info.hostId,
+      processId: beam.info.processId,
+      appName: beam.info.appName,
+      hostName: beam.info.hostName,
+      osKind: beam.info.osKind,
+      osName: beam.info.osName,
+      cpuArch: beam.info.cpuArch
+    },
+    endpoints: beam.endpoints,
+    beamPeriodMs: beam.beamPeriodMs,
+    remote,
+    firstSeen: Date.now(),
+    lastSeen: Date.now()
+  };
+}
+
+/**
+ * Passive SEN ether multicast discovery scanner.
+ *
+ * It listens for sen.components.ether.SessionPresenceBeam messages. It does
+ * not join SEN buses or create interests.
+ */
+export class EtherDiscoveryScanner extends EventEmitter {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.group]
+   * @param {number} [options.port]
+   * @param {string} [options.interfaceAddress]
+   * @param {string} [options.bindAddress]
+   */
+  constructor(options = {}) {
+    super();
+    this.group = options.group ?? DEFAULT_DISCOVERY_GROUP;
+    this.port = options.port ?? discoveryPortFromEnv() ?? DEFAULT_DISCOVERY_PORT;
+    this.interfaceAddress = resolveInterfaceAddress(options.interfaceAddress);
+    this.bindAddress = options.bindAddress ?? (process.platform === 'win32' ? undefined : this.group);
+    this.socket = null;
+    this.processes = new Map();
+  }
+
+  async start() {
+    if (this.socket) {
+      return this;
+    }
+
+    const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+    this.socket = socket;
+
+    socket.on('message', (message, remote) => {
+      try {
+        const beam = decodeSessionPresenceBeam(message);
+        const key = processKey(beam);
+        const current = this.processes.get(key);
+
+        if (current) {
+          current.lastSeen = Date.now();
+          current.remote = remote;
+          current.endpoints = beam.endpoints;
+          this.emit('beam', current);
+          return;
+        }
+
+        const discovered = normalizeBeam(beam, remote);
+        this.processes.set(key, discovered);
+        this.emit('process', discovered);
+        this.emit('beam', discovered);
+      } catch (error) {
+        this.emit('decodeError', error, 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(this.group, this.interfaceAddress);
+          socket.setMulticastLoopback(true);
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      };
+
+      socket.once('error', onError);
+      socket.once('listening', onListening);
+      socket.bind(this.port, this.bindAddress);
+    });
+
+    return this;
+  }
+
+  async stop() {
+    const socket = this.socket;
+    this.socket = null;
+
+    if (!socket) {
+      return;
+    }
+
+    await new Promise(resolve => {
+      socket.close(resolve);
+    });
+  }
+
+  listProcesses() {
+    return [...this.processes.values()].sort((a, b) => {
+      const sessionCmp = a.session.name.localeCompare(b.session.name);
+      if (sessionCmp !== 0) {
+        return sessionCmp;
+      }
+      return a.process.appName.localeCompare(b.process.appName);
+    });
+  }
+}
+
+/**
+ * Passive SEN ether TCP discovery-hub scanner.
+ *
+ * SEN's TcpDiscoveryHub forwards fixed-size beam buffers between connected
+ * clients. This scanner does not announce itself; it only listens for beams.
+ */
+export class TcpDiscoveryHubScanner extends EventEmitter {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.host]
+   * @param {number} [options.port]
+   */
+  constructor(options = {}) {
+    super();
+    this.host = options.host ?? '127.0.0.1';
+    this.port = options.port ?? 64222;
+    this.socket = null;
+    this.receiveBuffer = Buffer.alloc(0);
+    this.processes = new Map();
+  }
+
+  async start() {
+    if (this.socket) {
+      return this;
+    }
+
+    const socket = net.createConnection({ host: this.host, port: this.port });
+    this.socket = socket;
+
+    socket.on('data', chunk => this.#onData(chunk));
+    socket.on('close', hadError => {
+      this.socket = null;
+      this.emit('close', hadError);
+    });
+
+    await new Promise((resolve, reject) => {
+      const onError = error => {
+        socket.off('connect', onConnect);
+        reject(error);
+      };
+      const onConnect = () => {
+        socket.off('error', onError);
+        socket.on('error', error => this.emit('error', error));
+        resolve();
+      };
+      socket.once('error', onError);
+      socket.once('connect', onConnect);
+    });
+
+    return this;
+  }
+
+  async stop() {
+    const socket = this.socket;
+    this.socket = null;
+
+    if (!socket) {
+      return;
+    }
+
+    await new Promise(resolve => {
+      socket.once('close', resolve);
+      socket.destroy();
+    });
+  }
+
+  listProcesses() {
+    return [...this.processes.values()].sort((a, b) => {
+      const sessionCmp = a.session.name.localeCompare(b.session.name);
+      if (sessionCmp !== 0) {
+        return sessionCmp;
+      }
+      return a.process.appName.localeCompare(b.process.appName);
+    });
+  }
+
+  #onData(chunk) {
+    this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
+
+    while (this.receiveBuffer.length >= TCP_DISCOVERY_BEAM_SIZE) {
+      const message = this.receiveBuffer.subarray(0, TCP_DISCOVERY_BEAM_SIZE);
+      this.receiveBuffer = this.receiveBuffer.subarray(TCP_DISCOVERY_BEAM_SIZE);
+      this.#onBeamBuffer(message);
+    }
+  }
+
+  #onBeamBuffer(message) {
+    try {
+      const beam = decodeSessionPresenceBeam(message);
+      const key = processKey(beam);
+      const current = this.processes.get(key);
+
+      if (current) {
+        current.lastSeen = Date.now();
+        current.remote = normalizeTcpRemote(this.socket);
+        current.endpoints = beam.endpoints;
+        this.emit('beam', current);
+        return;
+      }
+
+      const discovered = normalizeBeam(beam, normalizeTcpRemote(this.socket));
+      this.processes.set(key, discovered);
+      this.emit('process', discovered);
+      this.emit('beam', discovered);
+    } catch (error) {
+      this.emit('decodeError', error, message, normalizeTcpRemote(this.socket));
+    }
+  }
+}
+
+/**
+ * Scan visible SEN ether multicast presence beams.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout]
+ * @param {number} [options.settleMs] Time to keep collecting beams after the first discovered process.
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<Array<object>>}
+ */
+export async function scan(options = {}) {
+  const timeout = options.timeout ?? DEFAULT_SCAN_TIMEOUT_MS;
+  const settleMs = options.settleMs ?? 100;
+  const scanner = new EtherDiscoveryScanner(options);
+
+  if (options.signal?.aborted) {
+    throw options.signal.reason ?? new Error('scan aborted');
+  }
+
+  let timeoutId;
+  let settleTimeoutId;
+  let onScannerError;
+  let onProcess;
+  const abortPromise = new Promise((_, reject) => {
+    if (!options.signal) {
+      return;
+    }
+    options.signal.addEventListener(
+      'abort',
+      () => reject(options.signal.reason ?? new Error('scan aborted')),
+      { once: true }
+    );
+  });
+
+  try {
+    await scanner.start();
+    const scannerErrorPromise = new Promise((_, reject) => {
+      onScannerError = error => reject(error);
+      scanner.on('error', onScannerError);
+    });
+    const discoveryPromise = new Promise(resolve => {
+      timeoutId = setTimeout(resolve, timeout);
+      onProcess = () => {
+        if (settleTimeoutId) {
+          return;
+        }
+        settleTimeoutId = setTimeout(resolve, settleMs);
+      };
+      scanner.on('process', onProcess);
+    });
+    await Promise.race([
+      discoveryPromise,
+      scannerErrorPromise,
+      abortPromise
+    ]);
+    return scanner.listProcesses();
+  } finally {
+    if (onScannerError) {
+      scanner.off('error', onScannerError);
+    }
+    if (onProcess) {
+      scanner.off('process', onProcess);
+    }
+    clearTimeout(timeoutId);
+    clearTimeout(settleTimeoutId);
+    await scanner.stop();
+  }
+}
+
+/**
+ * Scan visible SEN ether TCP discovery hub beams.
+ *
+ * @param {object} [options]
+ * @param {string} [options.host]
+ * @param {number} [options.port]
+ * @param {number} [options.timeout]
+ * @param {number} [options.settleMs] Time to keep collecting beams after the first discovered process.
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<Array<object>>}
+ */
+export async function scanTcpDiscoveryHub(options = {}) {
+  const timeout = options.timeout ?? DEFAULT_SCAN_TIMEOUT_MS;
+  const settleMs = options.settleMs ?? 100;
+  const scanner = new TcpDiscoveryHubScanner(options);
+
+  if (options.signal?.aborted) {
+    throw options.signal.reason ?? new Error('scan aborted');
+  }
+
+  let timeoutId;
+  let settleTimeoutId;
+  let onScannerError;
+  let onProcess;
+  const abortPromise = new Promise((_, reject) => {
+    if (!options.signal) {
+      return;
+    }
+    options.signal.addEventListener(
+      'abort',
+      () => reject(options.signal.reason ?? new Error('scan aborted')),
+      { once: true }
+    );
+  });
+
+  try {
+    await scanner.start();
+    const scannerErrorPromise = new Promise((_, reject) => {
+      onScannerError = error => reject(error);
+      scanner.on('error', onScannerError);
+    });
+    const discoveryPromise = new Promise(resolve => {
+      timeoutId = setTimeout(resolve, timeout);
+      onProcess = () => {
+        if (settleTimeoutId) {
+          return;
+        }
+        settleTimeoutId = setTimeout(resolve, settleMs);
+      };
+      scanner.on('process', onProcess);
+    });
+    await Promise.race([
+      discoveryPromise,
+      scannerErrorPromise,
+      abortPromise
+    ]);
+    return scanner.listProcesses();
+  } finally {
+    if (onScannerError) {
+      scanner.off('error', onScannerError);
+    }
+    if (onProcess) {
+      scanner.off('process', onProcess);
+    }
+    clearTimeout(timeoutId);
+    clearTimeout(settleTimeoutId);
+    await scanner.stop();
+  }
+}

package/lib/hash32.js

@@ -0,0 +1,40 @@
+export const HASH_SEED = 23835769;
+export const PROPERTY_HASH_SEED = 19830715;
+export const METHOD_HASH_SEED = 93580253;
+export const EVENT_HASH_SEED = 12125807;
+
+const FNV1A_OFFSET_BASIS = 0x811c9dc5;
+const FNV1A_PRIME = 0x01000193;
+const HASH_COMBINE_MAGIC = 0x9e3779b9;
+
+export function fnv1aString(value) {
+  let hash = FNV1A_OFFSET_BASIS;
+  for (const byte of Buffer.from(String(value))) {
+    hash ^= byte;
+    hash = Math.imul(hash, FNV1A_PRIME) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+export function hashCombine(seed, ...values) {
+  let result = seed >>> 0;
+  for (const value of values) {
+    const hashed = typeof value === 'number' ? value >>> 0 : fnv1aString(value);
+    result = (result ^ (
+      (hashed + HASH_COMBINE_MAGIC + ((result << 6) >>> 0) + (result >>> 2)) >>> 0
+    )) >>> 0;
+  }
+  return result >>> 0;
+}
+
+export function propertyHash(name) {
+  return hashCombine(PROPERTY_HASH_SEED, name);
+}
+
+export function methodHash(name) {
+  return hashCombine(METHOD_HASH_SEED, name);
+}
+
+export function eventHash(name) {
+  return hashCombine(EVENT_HASH_SEED, name);
+}

package/lib/protocol/generated.js

@@ -0,0 +1,157 @@
+// Generated by scripts/generate-protocol.mjs from resources/protocol.
+// Do not edit by hand.
+
+export const KERNEL_PROTOCOL_VERSION = 9;
+export const ETHER_PROTOCOL_VERSION = 2;
+
+export const ETHER_CONTROL_MESSAGE = Object.freeze([
+  "Hello",
+  "Ready",
+  "BusJoined",
+  "BusLeft"
+]);
+export const ETHER_CONTROL_MESSAGE_KEY = Object.freeze({
+  "Hello": 0,
+  "Ready": 1,
+  "BusJoined": 2,
+  "BusLeft": 3
+});
+
+export const KERNEL_CONTROL_MESSAGE = Object.freeze([
+  "RemoteParticipantReady",
+  "InterestStarted",
+  "InterestStopped",
+  "ObjectsPublished",
+  "ObjectsRemoved",
+  "PublicationRejection",
+  "ObjectsStateRequest",
+  "ObjectsStateResponse",
+  "TypesInfoRequest",
+  "TypesInfoResponse",
+  "TypesInfoRejection"
+]);
+export const KERNEL_CONTROL_MESSAGE_KEY = Object.freeze({
+  "RemoteParticipantReady": 0,
+  "InterestStarted": 1,
+  "InterestStopped": 2,
+  "ObjectsPublished": 3,
+  "ObjectsRemoved": 4,
+  "PublicationRejection": 5,
+  "ObjectsStateRequest": 6,
+  "ObjectsStateResponse": 7,
+  "TypesInfoRequest": 8,
+  "TypesInfoResponse": 9,
+  "TypesInfoRejection": 10
+});
+
+export const TYPE_SPEC_RESPONSE = Object.freeze([
+  "ClassSpecResponse",
+  "NonClassSpecResponse"
+]);
+
+export const OS_KIND = Object.freeze([
+  "windowsOs",
+  "linuxOs",
+  "androidOs",
+  "appleOs",
+  "unixOs",
+  "posixOs",
+  "otherOs"
+]);
+export const CPU_ARCH = Object.freeze([
+  "x86",
+  "x64",
+  "arm2",
+  "arm3",
+  "arm4T",
+  "arm5",
+  "arm6T2",
+  "arm6",
+  "arm7",
+  "arm7a",
+  "arm7r",
+  "arm7s",
+  "arm64",
+  "mips",
+  "superH",
+  "ppc",
+  "ppc64",
+  "sparc",
+  "m68k",
+  "otherArch"
+]);
+export const UNIT_CATEGORY = Object.freeze([
+  "length",
+  "mass",
+  "time",
+  "angle",
+  "temperature",
+  "frequency",
+  "velocity",
+  "angularVelocity",
+  "acceleration",
+  "angularAcceleration",
+  "density",
+  "pressure",
+  "area",
+  "force",
+  "torque"
+]);
+
+export const INTEGRAL_TYPE = Object.freeze([
+  "uint8Type",
+  "int16Type",
+  "uint16Type",
+  "int32Type",
+  "uint32Type",
+  "int64Type",
+  "uint64Type"
+]);
+export const REAL_TYPE = Object.freeze([
+  "float32Type",
+  "float64Type"
+]);
+export const NUMERIC_TYPE = Object.freeze([
+  "IntegralType",
+  "RealType"
+]);
+export const BASIC_TYPE = Object.freeze([
+  "booleanType",
+  "stringType",
+  "durationType",
+  "timestampType"
+]);
+export const BUILT_IN_TYPE = Object.freeze([
+  "NumericType",
+  "BasicType"
+]);
+export const TRANSPORT_MODE = Object.freeze([
+  "unicast",
+  "multicast",
+  "confirmed"
+]);
+export const METHOD_CONSTNESS = Object.freeze([
+  "constant",
+  "nonConstant"
+]);
+export const PROPERTY_RELATION = Object.freeze([
+  "nonPropertyRelated",
+  "propertyGetter",
+  "propertySetter"
+]);
+export const PROPERTY_CATEGORY = Object.freeze([
+  "staticRW",
+  "staticRO",
+  "dynamicRW",
+  "dynamicRO"
+]);
+export const CUSTOM_TYPE_DATA = Object.freeze([
+  "EnumTypeSpec",
+  "QuantityTypeSpec",
+  "SequenceTypeSpec",
+  "StructTypeSpec",
+  "VariantTypeSpec",
+  "AliasTypeSpec",
+  "OptionalTypeSpec",
+  "ClassTypeSpec"
+]);