sen-ether-client 0.2.1 → 0.2.3

package/API.md

@@ -95,15 +95,15 @@ Preferred multi-session usage:
 ```js
 const sen = await Sen.connect();
 
-const hmi = await sen.interest('SELECT * FROM hmi.diagnostics');
-const world = await sen.interest('SELECT * FROM world1.environment');
+const first = await sen.interest('SELECT * FROM session.bus');
+const second = await sen.interest('SELECT * FROM otherSession.otherBus');
 ```
 
 TCP discovery hub usage:
 
 ```js
 const sen = await Sen.connect({
-  session: 'hmi',
+  session: 'session',
   tcpHub: '127.0.0.1:65222'
 });
 ```
@@ -116,7 +116,7 @@ Multicast discovery usage:
 
 ```js
 const sen = await Sen.connect({
-  session: 'hmi',
+  session: 'session',
   interfaceAddress: '127.0.0.1',
   listenHost: '127.0.0.1',
   advertisedHost: '127.0.0.1'
@@ -129,21 +129,21 @@ and received on the intended network device.
 Explicit single-session usage is still supported:
 
 ```js
-const hmi = await Sen.connect({ session: 'hmi' });
-await hmi.interest('SELECT * FROM hmi.diagnostics');
+const session = await Sen.connect({ session: 'session' });
+await session.interest('SELECT * FROM session.bus');
 ```
 
 If a SEN bus name itself contains dots and is not a session-qualified bus, pass
 it explicitly. This is useful for standalone scenarios that run in one Ether
-session but publish on a bus such as `scenario.environment`:
+session but publish on a bus such as `domain.bus`:
 
 ```js
-const scenario = await Sen.connect({
-  session: 'scenario'
+const session = await Sen.connect({
+  session: 'session'
 });
 
-const objects = await scenario.interest('SELECT * FROM scenario.environment', {
-  bus: 'scenario.environment',
+const objects = await session.interest('SELECT * FROM domain.bus', {
+  bus: 'domain.bus',
   forceBus: true
 });
 ```
@@ -164,20 +164,24 @@ Main methods:
 - `await sen.waitForObject(selector, options)`
 - `await sen.close()`
 
+By default, interest creation uses the SEN-native `CRC32(query)` value as the
+interest id. Pass `options.id` only when a caller must force a specific native
+interest id.
+
 Session and bus navigation:
 
 ```js
 const sen = await Sen.connect();
 
 console.log(await sen.discoverBuses());
-// [{ session: 'hmi', bus: 'diagnostics', qualified: 'hmi.diagnostics' }]
+// [{ session: 'session', bus: 'bus', qualified: 'session.bus' }]
 
 for (const sessionName of sen.listSessions()) {
   const session = await sen.session(sessionName);
   console.log(sessionName, session.listBuses());
 }
 
-const diagnostics = await sen.session('hmi').then(hmi => hmi.bus('diagnostics'));
+const bus = await sen.session('session').then(session => session.bus('bus'));
 ```
 
 `discoverBuses()` does not create interests and does not join any SEN bus. It
@@ -226,8 +230,8 @@ Main events:
 Returned by `await sen.interest(query)`.
 
 ```js
-const interest = await sen.interest('SELECT * FROM hmi.diagnostics');
-const object = await interest.waitFor('EtherProbe');
+const interest = await sen.interest('SELECT * FROM session.bus');
+const object = await interest.waitFor('object-1');
 ```
 
 Main methods:
@@ -251,7 +255,7 @@ For browser gateways or high-frequency telemetry, request only the properties
 you need and emit batches instead of one JS event per property update:
 
 ```js
-const tracks = await sen.interest('SELECT bus.Track FROM hmi.loadtest', {
+const objects = await sen.interest('SELECT demo.Object FROM session.bus', {
   properties: ['latitude', 'longitude', 'altitude', 'heading'],
   changeMode: 'batch',
   batchIntervalMs: 16,
@@ -261,7 +265,7 @@ const tracks = await sen.interest('SELECT bus.Track FROM hmi.loadtest', {
   coalesce: true
 });
 
-tracks.on('changes', ({ changes, dropped }) => {
+objects.on('changes', ({ changes, dropped }) => {
   // Send one compact WebSocket frame to the browser.
 });
 ```
@@ -309,7 +313,7 @@ Main events:
 64-bit timestamp precision. Convert it explicitly at JSON boundaries:
 
 ```js
-tracks.on('change', ({ object, name, value, timestampNs }) => {
+objects.on('change', ({ object, name, value, timestampNs }) => {
   websocket.send(JSON.stringify({
     object: object.name,
     name,

package/README.md

@@ -11,16 +11,16 @@ import { Sen } from 'sen-ether-client';
 
 const sen = await Sen.connect();
 
-const diagnostics = await sen.interest('SELECT * FROM hmi.diagnostics');
-const probe = await diagnostics.waitFor('EtherProbe');
+const objects = await sen.interest('SELECT * FROM session.bus');
+const object = await objects.waitFor('object-1');
 
-probe.on('change:label', ({ value }) => {
+object.on('change:label', ({ value }) => {
   console.log('label changed:', value);
 });
 
-console.log(await probe.get('label'));
-await probe.set('label', 'from-js');
-console.log(await probe.call('ping', ['hello']));
+console.log(await object.get('label'));
+await object.set('label', 'from-js');
+console.log(await object.call('ping', ['hello']));
 
 await sen.close();
 ```
@@ -85,7 +85,7 @@ explicitly:
 
 ```js
 const sen = await Sen.connect({
-  session: 'hmi',
+  session: 'session',
   tcpHub: '127.0.0.1:65222'
 });
 ```
@@ -100,7 +100,7 @@ For local multicast tests, select loopback explicitly:
 
 ```js
 const sen = await Sen.connect({
-  session: 'hmi',
+  session: 'session',
   interfaceAddress: '127.0.0.1',
   listenHost: '127.0.0.1',
   advertisedHost: '127.0.0.1'
@@ -116,8 +116,8 @@ configured interests.
 is inferred from the query:
 
 ```js
-const hmi = await sen.interest('SELECT * FROM hmi.diagnostics');
-const world = await sen.interest('SELECT * FROM world1.environment');
+const first = await sen.interest('SELECT * FROM session.bus');
+const second = await sen.interest('SELECT * FROM otherSession.otherBus');
 ```
 
 You can also navigate explicitly through sessions and buses:
@@ -127,13 +127,13 @@ const sen = await Sen.connect();
 
 console.log(sen.listSessions());
 console.log(await sen.discoverBuses());
-// [{ session: 'hmi', bus: 'diagnostics', qualified: 'hmi.diagnostics' }]
+// [{ session: 'session', bus: 'bus', qualified: 'session.bus' }]
 
-const hmi = await sen.session('hmi');
-console.log(hmi.listBuses());
+const session = await sen.session('session');
+console.log(session.listBuses());
 
-const diagnostics = await hmi.bus('diagnostics');
-const probe = await diagnostics.waitFor('EtherProbe');
+const bus = await session.bus('bus');
+const object = await bus.waitFor('object-1');
 ```
 
 `discoverBuses()` does not create interests and does not join any SEN bus. It
@@ -144,11 +144,11 @@ process connection, it waits up to `busDiscoverySettleMs` milliseconds.
 You can also connect to one explicit session:
 
 ```js
-const hmi = await Sen.connect({
-  session: 'hmi'
+const session = await Sen.connect({
+  session: 'session'
 });
 
-const diagnostics = await hmi.interest('SELECT * FROM hmi.diagnostics');
+const objects = await session.interest('SELECT * FROM session.bus');
 ```
 
 ## Interests
@@ -156,17 +156,17 @@ const diagnostics = await hmi.interest('SELECT * FROM hmi.diagnostics');
 Create an interest with a normal SEN query:
 
 ```js
-const tracks = await sen.interest('SELECT * FROM world1.environment');
+const objects = await sen.interest('SELECT * FROM session.bus');
 ```
 
 Listen for objects and changes:
 
 ```js
-tracks.on('object', object => {
+objects.on('object', object => {
   console.log(object.name, object.className);
 });
 
-tracks.on('change', ({ object, name, value }) => {
+objects.on('change', ({ object, name, value }) => {
   console.log(object.name, name, value);
 });
 ```
@@ -175,13 +175,13 @@ For browser gateways or high-frequency telemetry, batch changes and decode only
 the properties needed by the UI:
 
 ```js
-const tracks = await sen.interest('SELECT bus.Track FROM hmi.loadtest', {
+const objects = await sen.interest('SELECT demo.Object FROM session.bus', {
   properties: ['latitude', 'longitude', 'altitude', 'heading'],
   changeMode: 'batch',
   coalesce: true
 });
 
-tracks.on('changes', ({ changes }) => {
+objects.on('changes', ({ changes }) => {
   websocket.send(JSON.stringify(changes.map(({ object, name, value, timestampNs }) => ({
     object: object.name,
     name,
@@ -194,10 +194,10 @@ tracks.on('changes', ({ changes }) => {
 Get an object by name, id, class name, or predicate:
 
 ```js
-const aircraft = await tracks.waitFor('blue-air-1');
+const object = await objects.waitFor('object-1');
 
-const firstAircraft = await tracks.waitFor(
-  object => object.className === 'rpr.Aircraft'
+const firstDemoObject = await objects.waitFor(
+  object => object.className === 'demo.Object'
 );
 ```
 
@@ -277,7 +277,7 @@ Probe a bus:
 ```bash
 npx sen-ether-probe \
   --tcp-hub 127.0.0.1:65222 \
-  --bus hmi.diagnostics
+  --bus session.bus
 ```
 
 ## API

package/bin/node-sen-probe.js

@@ -66,7 +66,7 @@ Options:
 Examples:
   sen-ether-probe --bus scenario.control
   sen-ether-probe --tcp-hub 127.0.0.1:64222 --bus scenario.control
-  sen-ether-probe --bus world1.environment --query "SELECT * FROM world1.environment"
+  sen-ether-probe --bus session.bus --query "SELECT * FROM session.bus"
 
 Environment:
   SEN_ETHER_DISCOVERY_PORT       Default multicast discovery port

package/index.js

@@ -11,17 +11,16 @@
  * const sen = await Sen.connect();
  *
  * console.log(sen.listSessions());
- * const hmi = await sen.session('hmi');
- * console.log(hmi.listBuses());
+ * const session = await sen.session('session');
+ * console.log(session.listBuses());
  *
- * const diagnostics = await sen.interest('SELECT * FROM hmi.diagnostics');
- * const world = await sen.interest('SELECT * FROM world1.environment');
- * const probe = await diagnostics.waitFor('EtherProbe');
+ * const objects = await sen.interest('SELECT * FROM session.bus');
+ * const object = await objects.waitFor('object-1');
  *
- * probe.on('change:label', ({ value }) => console.log(value));
- * console.log(await probe.get('label'));
- * await probe.set('label', 'from-js');
- * console.log(await probe.call('ping', ['hello']));
+ * object.on('change:label', ({ value }) => console.log(value));
+ * console.log(await object.get('label'));
+ * await object.set('label', 'from-js');
+ * console.log(await object.call('ping', ['hello']));
  *
  * await sen.close();
  */
@@ -61,6 +60,7 @@
  * @property {string} [bus] Explicit bus name when it cannot be inferred from the query.
  * @property {boolean} [forceBus=false] Join without waiting for the remote process to announce the bus.
  * @property {number} [timeout] Operation timeout in ms.
+ * @property {number} [id] Optional native interest id. Defaults to CRC32(query).
  * @property {string[]|string} [properties] Optional property names to decode and emit.
  * @property {'individual'|'batch'|'both'} [changeMode='individual'] Change emission mode.
  * @property {number} [batchIntervalMs=16] Batched change flush interval in ms.

package/lib/client.js

@@ -788,6 +788,12 @@ export class EtherClient extends EventEmitter {
       this.socket = socket;
     }
     socket.on('data', chunk => this.#onTcpData(connection, chunk));
+    socket.on('error', error => {
+      this.#removeConnection(connection);
+      if (!['EPIPE', 'ECONNRESET'].includes(error?.code)) {
+        this.emit('error', error);
+      }
+    });
     socket.on('close', hadError => {
       this.#removeConnection(connection);
       this.emit('connectionClose', { connection, hadError });
@@ -804,10 +810,18 @@ export class EtherClient extends EventEmitter {
     if (connection.processKey) {
       this.connectionsByProcessKey.delete(connection.processKey);
     }
+    const leftParticipants = [];
     for (const [busId, participants] of this.remoteParticipantsByBusId) {
       for (const [participantId, participant] of participants) {
         if (participant.connection === connection) {
           participants.delete(participantId);
+          leftParticipants.push({
+            participantId,
+            busId,
+            busName: participant.busName,
+            connection,
+            reason: 'connectionClose'
+          });
         }
       }
       if (!participants.size) {
@@ -824,6 +838,9 @@ export class EtherClient extends EventEmitter {
     if (this.socket === connection.socket) {
       this.socket = [...this.connections.values()][0]?.socket;
     }
+    for (const participant of leftParticipants) {
+      this.emit('busLeft', participant);
+    }
   }
 
   #configureTcpSocket(socket) {
@@ -998,7 +1015,7 @@ export class EtherClient extends EventEmitter {
    */
   startInterest(bus, query, options = {}) {
     const busState = this.#getBus(bus);
-    const id = options.id ?? this.#nextInterestId(busState);
+    const id = options.id ?? this.#nextInterestId(busState, crc32(query));
     this.#sendBusControlToRemoteParticipants(busState, {
       type: 'InterestStarted',
       value: { query, id }
@@ -1008,7 +1025,13 @@ export class EtherClient extends EventEmitter {
     return { busName: busState.busName, busId: busState.busId, id, query };
   }
 
-  #nextInterestId(busState) {
+  #nextInterestId(busState, preferredId) {
+    const preferred = preferredId >>> 0;
+    if (preferred && !busState.interests.has(preferred)) {
+      this.nextInterestId = preferred;
+      return preferred;
+    }
+
     for (let attempts = 0; attempts < 0xffff_ffff; attempts += 1) {
       this.nextInterestId = (this.nextInterestId + 1) >>> 0;
       const id = this.nextInterestId || 1;
@@ -1478,7 +1501,27 @@ export class EtherClient extends EventEmitter {
       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 });
+        const control = busMessage.control;
+        this.emit('busControlMessage', { ...frame, control, remote, multicast: true });
+        switch (control.type) {
+          case 'ObjectsPublished':
+            this.emit('objectsPublished', { bus: busState, remote, multicast: true, ...control.value });
+            break;
+          case 'ObjectsRemoved':
+            this.emit('objectsRemoved', { bus: busState, remote, multicast: true, ...control.value });
+            break;
+          case 'ObjectsStateResponse':
+            this.emit('objectsStateResponse', { bus: busState, remote, multicast: true, ...control.value });
+            break;
+          case 'TypesInfoResponse':
+            this.emit('typesInfoResponse', { bus: busState, remote, multicast: true, ...control.value });
+            break;
+          case 'TypesInfoRejection':
+            this.emit('typesInfoRejection', { bus: busState, remote, multicast: true, ...control.value });
+            break;
+          default:
+            break;
+        }
         return;
       }
       this.emit(busMessage.categoryName, { ...frame, ...busMessage, remote, multicast: true });
@@ -1746,25 +1789,26 @@ export class EtherClient extends EventEmitter {
       return;
     }
     const socket = this.#writableConnectionSocket(connection);
+    if (!socket) {
+      return;
+    }
     const processBusPayload = encodeConfirmedBusFrame({
       to: busState.participantId,
       busId: busState.busId,
       message: busPayload
     });
-    socket.write(encodeProcessTcpFrame(PROCESS_MESSAGE_CATEGORY.busMessage, processBusPayload), error => {
-      if (error) {
-        this.emit('error', error);
-      }
-    });
+    try {
+      socket.write(encodeProcessTcpFrame(PROCESS_MESSAGE_CATEGORY.busMessage, processBusPayload));
+    } catch {
+      this.#removeConnection(connection);
+    }
   }
 
   #writableConnectionSocket(connection) {
     const socket = connection?.socket;
     if (!socket || socket.destroyed || !socket.writable) {
-      const error = new Error('SEN ether TCP socket is not writable');
-      error.code = 'SEN_TCP_NOT_WRITABLE';
-      this.emit('error', error);
-      throw error;
+      this.#removeConnection(connection);
+      return undefined;
     }
     return socket;
   }

package/lib/sen.js

@@ -4,6 +4,7 @@ import { decodePropertyValues, decodeValue, encodeArguments, decodeArguments } f
 import { EtherClient } from './client.js';
 import { EtherDiscoveryScanner, TcpDiscoveryHubScanner, scan, scanTcpDiscoveryHub } from './discovery.js';
 import { methodHash } from './hash32.js';
+import { crc32 } from './crc32.js';
 
 function wait(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -467,6 +468,7 @@ export class Sen extends EventEmitter {
    * @param {string} [options.query]
    * @param {boolean} [options.forceBus]
    * @param {number} [options.timeout]
+   * @param {number} [options.id] Optional native interest id. Defaults to CRC32(query).
    */
   async subscribe(busName, options = {}) {
     if (!this.client) {
@@ -507,7 +509,7 @@ export class Sen extends EventEmitter {
   /**
    * Start a native SEN interest and return a live object collection.
    *
-   * @param {string} query Native SEN interest query, for example `SELECT * FROM hmi.hud`.
+   * @param {string} query Native SEN interest query, for example `SELECT * FROM session.bus`.
    * @param {object} [options]
    * @param {string} [options.bus] Explicit bus when it cannot be inferred from the query.
    * @param {boolean} [options.forceBus]
@@ -944,7 +946,7 @@ export class Sen extends EventEmitter {
       return this.targetsBySession.keys().next().value;
     }
 
-    throw new Error(`cannot infer SEN session from bus "${busName}"; use a session-qualified query such as SELECT * FROM hmi.${busName}`);
+    throw new Error(`cannot infer SEN session from bus "${busName}"; use a session-qualified query such as SELECT * FROM session.${busName}`);
   }
 
   #assertBusBelongsToSession(busName, sessionName) {
@@ -987,6 +989,7 @@ export class Sen extends EventEmitter {
     });
     client.on('busLeft', value => {
       this.remoteBuses.delete(value.busName);
+      this.#busForEvent(value)?.handleParticipantLeft(value);
       this.emit('busUnavailable', value);
     });
     client.on('objectsPublished', event => this.#busForEvent(event)?.handleObjectsPublished(event));
@@ -998,6 +1001,10 @@ export class Sen extends EventEmitter {
     client.on('runtimeEvents', event => this.#busForEvent(event)?.handleRuntimeEvents(event));
     client.on('runtimeMethodResponse', event => this.#busForEvent(event)?.handleRuntimeMethodResponse(event));
     client.on('error', error => {
+      if (['EPIPE', 'ECONNRESET', 'SEN_TCP_NOT_WRITABLE'].includes(error?.code)) {
+        this.emit('warning', error);
+        return;
+      }
       if (this.manualClose || this.reconnecting || this.options.reconnect !== false) {
         this.emit('warning', error);
         return;
@@ -1222,6 +1229,7 @@ export class SenBus extends EventEmitter {
     this.id = id;
     this.objectsById = new Map();
     this.typeRegistry = new Map();
+    this.typeRegistryByHash = new Map();
     this.requestedTypeHashes = new Set();
     this.stateRequestedObjectIds = new Set();
     this.stateResyncTimers = new Set();
@@ -1232,7 +1240,7 @@ export class SenBus extends EventEmitter {
   }
 
   startInterest(query, options = {}) {
-    const started = this.sen.client.startInterest(this.name, query);
+    const started = this.sen.client.startInterest(this.name, query, { id: options.id });
     const interest = new SenInterest(this, started.id, query, options);
     this.interests.set(interest.id, interest);
     return interest;
@@ -1240,7 +1248,7 @@ export class SenBus extends EventEmitter {
 
   stopInterest(id) {
     const interestId = typeof id === 'object' ? id.id : id;
-    this.sen.client?.stopInterest(this.name, interestId);
+    this.sen.client?.stopInterest(this.id ?? this.name, interestId);
     const interest = this.interests.get(interestId);
     this.#detachInterestObjects(interestId, interest);
     this.interests.delete(interestId);
@@ -1264,7 +1272,7 @@ export class SenBus extends EventEmitter {
       }
     }
     try {
-      this.sen.client?.leaveBus(this.name);
+      this.sen.client?.leaveBus(this.id ?? this.name);
     } catch (error) {
       this.sen.emit('warning', error);
     }
@@ -1282,6 +1290,7 @@ export class SenBus extends EventEmitter {
     }
     this.objectsById.clear();
     this.typeRegistry.clear();
+    this.typeRegistryByHash.clear();
     this.requestedTypeHashes.clear();
     this.stateRequestedObjectIds.clear();
     this.#clearStateResyncTimers();
@@ -1307,7 +1316,7 @@ export class SenBus extends EventEmitter {
     const interests = [...this.interests.values()];
     this.interests.clear();
     for (const interest of interests) {
-      const started = this.sen.client.startInterest(this.name, interest.query);
+      const started = this.sen.client.startInterest(this.name, interest.query, { id: interest.options.id ?? interest.id });
       interest.id = started.id;
       interest.resetLocal();
       this.interests.set(interest.id, interest);
@@ -1353,10 +1362,9 @@ export class SenBus extends EventEmitter {
             ownerId
           });
         }
+        this.#attachKnownType(object);
         interest?.objectsById.set(object.key, object);
-        if (info.state?.length) {
-          object.applyState(info.state, 'published', info.time, { interestId: discovery.interestId });
-        }
+        object.applyState(info.state?.length ? info.state : Buffer.alloc(0), 'state', info.time, { interestId: discovery.interestId });
         if (!this.requestedTypeHashes.has(info.typeHash)) {
           this.requestedTypeHashes.add(info.typeHash);
           newTypeHashes.add(info.typeHash);
@@ -1387,6 +1395,19 @@ export class SenBus extends EventEmitter {
     }
   }
 
+  handleParticipantLeft(event) {
+    const ownerId = event?.participantId;
+    if (ownerId === undefined || ownerId === null) {
+      return;
+    }
+    const detail = { reason: event?.reason ?? 'busLeft', ownerId: ownerId >>> 0 };
+    for (const object of [...this.objectsById.values()]) {
+      if (object.ownerId === (ownerId >>> 0)) {
+        this.#removeObjectFromAllInterests(object, detail);
+      }
+    }
+  }
+
   #detachInterestObjects(interestId, interest) {
     const normalizedInterestId = interestId >>> 0;
     const keyPrefix = `${normalizedInterestId}:`;
@@ -1478,6 +1499,7 @@ export class SenBus extends EventEmitter {
     for (const type of event.types ?? []) {
       this.typeRegistry.set(type.spec.qualifiedName, type.spec);
       if (type.classHash !== undefined) {
+        this.typeRegistryByHash.set(type.classHash >>> 0, type.spec);
         for (const object of this.objectsById.values()) {
           if (object.typeHash === type.classHash) {
             object.spec = type.spec;
@@ -1674,6 +1696,26 @@ export class SenBus extends EventEmitter {
     }
   }
 
+  #attachKnownType(object) {
+    if (object.spec) {
+      return;
+    }
+    const specByHash = this.typeRegistryByHash.get(object.typeHash >>> 0);
+    if (specByHash) {
+      object.spec = specByHash;
+      object.emit('type', specByHash);
+      return;
+    }
+    for (const spec of this.typeRegistry.values()) {
+      const hash = crc32(spec?.qualifiedName ?? spec?.name ?? '');
+      if (hash === object.typeHash) {
+        object.spec = spec;
+        object.emit('type', spec);
+        return;
+      }
+    }
+  }
+
   #objectByOwnerAndId(ownerId, objectId) {
     if (ownerId !== undefined && ownerId !== null) {
       return this.objectsById.get(remoteObjectKey(ownerId, objectId));

package/package.json

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