sen-ether-client 0.1.6 → 0.2.0

package/API.md

@@ -8,7 +8,7 @@ import { Sen, SenInterest, SenRemoteObject } from 'sen-ether-client';
 
 ## Compatibility
 
-`sen-ether-client@0.1.x` supports:
+`sen-ether-client@0.1.x` and `sen-ether-client@0.2.x` support:
 
 - kernel protocol `9`
 - ether protocol `2`
@@ -39,9 +39,25 @@ Connection options:
 - `interfaceAddress`: local interface address or interface name for multicast
   discovery.
 - `tcpHub`: optional SEN TCP discovery hub as `host:port`. If omitted,
-  multicast discovery is used.
+  multicast discovery is used. When combined with `session`, the client opens
+  a local Ether listener, sends presence beams to the hub and connects to
+  compatible peers announced by the hub.
 - `session`: optional SEN session name. If omitted, `Sen` can use queries for
-  different sessions and connects to each one on demand.
+  different sessions and connects to each one on demand. When provided, the
+  client also acts as an active Ether process and announces itself through the
+  selected discovery transport.
+- `multicastDiscovery`: enable active multicast presence beaming when no
+  `tcpHub` is configured. Defaults to `true`.
+- `group`: multicast discovery group. Defaults to `239.255.0.44`.
+- `bindAddress`: optional multicast discovery bind address.
+- `listen`: enable the local Ether TCP listener. Defaults to `true` for active
+  hub sessions.
+- `listenHost`: host/interface for the local Ether listener. Defaults to
+  `0.0.0.0`.
+- `listenPort`: local Ether listener port. Defaults to `0` so the OS picks one.
+- `advertisedHost`: host advertised in discovery beams. Defaults to the
+  selected interface address.
+- `beamPeriodMs`: active discovery beam period. Defaults to `1000`.
 - `timeout`: discovery and operation timeout in ms.
 - `discoverySettleMs`: discovery settle time after the first process is found.
   Defaults to `100`.
@@ -67,7 +83,12 @@ variable as its multicast default:
 - `SEN_ETHER_DISCOVERY_PORT`
 
 Multicast group, bind address and interface selection are explicit `sen-ether-client`
-options, not SEN environment variables.
+options, not SEN environment variables. When no `interfaceAddress` is provided,
+multicast discovery joins every local IPv4 interface visible to Node.js. If a
+SEN producer on the same host sends discovery through a physical interface that
+does not loop multicast packets back locally, discovery can still return no
+processes; in that case run the producer discovery on `lo`, pass the matching
+`interfaceAddress`, or use SEN TCP discovery.
 
 Preferred multi-session usage:
 
@@ -81,9 +102,30 @@ const world = await sen.interest('SELECT * FROM world1.environment');
 TCP discovery hub usage:
 
 ```js
-const sen = await Sen.connect({ tcpHub: '127.0.0.1:65222' });
+const sen = await Sen.connect({
+  session: 'hmi',
+  tcpHub: '127.0.0.1:65222'
+});
+```
+
+The TCP discovery hub forwards fixed-size presence beams only. Bus messages are
+sent over direct process TCP connections between peers, so Node.js producers
+and consumers must advertise reachable `listenHost`/`advertisedHost` endpoints.
+
+Multicast discovery usage:
+
+```js
+const sen = await Sen.connect({
+  session: 'hmi',
+  interfaceAddress: '127.0.0.1',
+  listenHost: '127.0.0.1',
+  advertisedHost: '127.0.0.1'
+});
 ```
 
+On multi-interface machines, set `interfaceAddress` so multicast beams are sent
+and received on the intended network device.
+
 Explicit single-session usage is still supported:
 
 ```js
@@ -110,6 +152,8 @@ Main methods:
 
 - `await sen.connect(options)`
 - `await sen.interest(query, options)`
+- `await sen.publishObjects(busName, objects, options)`
+- `await sen.removePublishedObjects(busName, objects, options)`
 - `await sen.session(name)`
 - `await sen.discoverBuses(options)`
 - `sen.listSessions()`
@@ -140,6 +184,30 @@ const diagnostics = await sen.session('hmi').then(hmi => hmi.bus('diagnostics'))
 does open a lightweight process connection per discovered session, because SEN
 presence beams announce sessions/processes but not the bus list.
 
+Publishing local objects:
+
+```js
+const sen = await Sen.connect({
+  session: 'session',
+  tcpHub: '127.0.0.1:65222'
+});
+
+await sen.publishObjects('session.bus', [{
+  name: 'demo-counter',
+  className: 'demo.Counter',
+  properties: {
+    label: 'Demo Counter',
+    count: 1,
+    running: true
+  }
+}]);
+```
+
+When no `spec` is provided, `sen-ether-client` infers a simple ClassTypeSpec
+from scalar `properties`. For objects with nested structs, sequences, enums or
+aliases, pass the exact SEN `spec` and dependent `types` so consumers can decode
+the state with the same model as native SEN producers.
+
 Main events:
 
 - `connect`
@@ -183,8 +251,8 @@ 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 hmi.tactical.BaseTrack FROM hmi.loadtest', {
-  properties: ['latitude', 'longitude', 'altitude', 'trackHeading'],
+const tracks = await sen.interest('SELECT bus.Track FROM hmi.loadtest', {
+  properties: ['latitude', 'longitude', 'altitude', 'heading'],
   changeMode: 'batch',
   batchIntervalMs: 16,
   batchMaxSize: 1000,

package/README.md

@@ -39,6 +39,7 @@ versions, not to a specific SEN release name.
 | sen-ether-client | Kernel protocol | Ether protocol |
 | --- | ---: | ---: |
 | 0.1.x | 9 | 2 |
+| 0.2.x | 9 | 2 |
 
 If a remote kernel reports another kernel or ether protocol version during the
 SEN handshake, `sen-ether-client` treats it as incompatible until that protocol version
@@ -61,6 +62,10 @@ visible SEN processes:
 const sen = await Sen.connect();
 ```
 
+When a `session` is provided, the client also behaves as an active Ether
+process: it opens a TCP listener, announces its presence through multicast
+discovery, and connects to compatible peers announced on the same session.
+
 If your SEN ether discovery port is configured through SEN's environment,
 `sen-ether-client` reads the same variable:
 
@@ -80,10 +85,28 @@ explicitly:
 
 ```js
 const sen = await Sen.connect({
+  session: 'hmi',
   tcpHub: '127.0.0.1:65222'
 });
 ```
 
+With a `session` and `tcpHub`, `sen-ether-client` acts as an active Ether
+process: it opens a TCP listener, announces a SEN presence beam to the hub, and
+connects to compatible peers announced by the hub. This allows Node.js
+producers and consumers to discover each other without a native SEN process
+brokering their bus messages.
+
+For local multicast tests, select loopback explicitly:
+
+```js
+const sen = await Sen.connect({
+  session: 'hmi',
+  interfaceAddress: '127.0.0.1',
+  listenHost: '127.0.0.1',
+  advertisedHost: '127.0.0.1'
+});
+```
+
 Connected sessions are monitored through SEN ether presence beams. If the
 remote process stops announcing itself for `presenceTimeoutMs` milliseconds
 (default `5000`), the client closes the stale connection and restarts the
@@ -152,8 +175,8 @@ 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 hmi.tactical.BaseTrack FROM hmi.loadtest', {
-  properties: ['latitude', 'longitude', 'altitude', 'trackHeading'],
+const tracks = await sen.interest('SELECT bus.Track FROM hmi.loadtest', {
+  properties: ['latitude', 'longitude', 'altitude', 'heading'],
   changeMode: 'batch',
   coalesce: true
 });
@@ -178,6 +201,35 @@ const firstAircraft = await tracks.waitFor(
 );
 ```
 
+## Publish objects
+
+`sen-ether-client` can also act as a lightweight producer. The producer joins
+the bus, publishes local objects to remote interests, and answers type/state
+requests for those objects.
+
+```js
+import { Sen } from 'sen-ether-client';
+
+const sen = await Sen.connect({
+  session: 'session',
+  tcpHub: '127.0.0.1:65222'
+});
+
+await sen.publishObjects('session.bus', {
+  name: 'demo-counter',
+  className: 'demo.Counter',
+  properties: {
+    label: 'Demo Counter',
+    count: 1,
+    running: true
+  }
+});
+```
+
+For exact SEN typing, pass a `spec` on each object and any dependent custom
+types through `types`. This is required for structured values such as structs,
+sequences, enums and variants.
+
 ## Objects
 
 Read and write properties:

package/index.js

@@ -31,6 +31,9 @@
  * @property {string} [tcpHub] Optional SEN TCP discovery hub as `host:port`. If omitted, multicast discovery is used.
  * @property {string} [session] Optional SEN session name. Omit it to let
  * `interest(query)` connect to the session named in the query.
+ * @property {boolean} [multicastDiscovery=true] Enable active multicast presence beaming when no TCP hub is configured.
+ * @property {string} [group='239.255.0.44'] Multicast discovery group.
+ * @property {string} [bindAddress] Optional multicast discovery bind address.
  * @property {string} [app] Remote process appName substring filter.
  * @property {number} [timeout=3000] Discovery and operation timeout in ms.
  * @property {number} [discoverySettleMs=100] Discovery settle time after the first process is found.
@@ -45,6 +48,11 @@
  * @property {number} [presenceTimeoutMs=5000] Close and reconnect when the connected SEN process stops announcing presence beams. `0` disables it.
  * @property {number} [presenceCheckIntervalMs=1000] Presence watchdog check interval in ms.
  * @property {string} [interfaceAddress] Local interface address or interface name for multicast discovery.
+ * @property {boolean} [listen=true] Enable the local Ether TCP listener for active discovery.
+ * @property {string} [listenHost='0.0.0.0'] Local host/interface for the Ether listener.
+ * @property {number} [listenPort=0] Local Ether listener port. `0` lets the OS choose.
+ * @property {string} [advertisedHost] Host advertised in TCP discovery beams.
+ * @property {number} [beamPeriodMs=1000] Active discovery beam period in ms.
  * @property {object} [target] Already discovered/direct SEN target.
  */
 
@@ -62,6 +70,24 @@
  * @property {boolean} [coalesce=false] Keep only latest queued change per object/property.
  */
 
+/**
+ * @typedef {object} SenPublishedObject
+ * @property {string} name SEN object name.
+ * @property {string} className SEN class name.
+ * @property {number} [id] Optional stable object id. Defaults to CRC32(name).
+ * @property {number} [typeHash] Optional class hash. Defaults to CRC32(className).
+ * @property {object} [properties] Current object property values.
+ * @property {object} [snapshot] Alias for properties.
+ * @property {object} [spec] Optional SEN ClassTypeSpec. If omitted, a simple class spec is inferred from properties.
+ * @property {bigint|number|string} [timestamp] Optional SEN timestamp in ns.
+ */
+
+/**
+ * @typedef {object} SenPublishOptions
+ * @property {Map<string, object>|Record<string, object>|object[]} [types] Extra SEN type specs required by object properties.
+ * @property {number} [participantId] Optional local participant id for a newly joined bus.
+ */
+
 /**
  * @typedef {object} SenListBusesOptions
  * @property {boolean} [qualified=false] Return session-qualified bus names.

package/lib/bus.js

@@ -67,9 +67,36 @@ function readU32List(reader) {
 }
 
 function writeU32List(writer, values = []) {
+    writer.writeUInt32(values.length);
+    for (const value of values) {
+        writer.writeUInt32(value);
+    }
+}
+
+function enumKey(values, value, label) {
+  const index = values.indexOf(value);
+  if (index < 0) {
+    throw new RangeError(`unknown SEN ${label} value: ${value}`);
+  }
+  return index;
+}
+
+function writeSequence(writer, values = [], writeItem) {
   writer.writeUInt32(values.length);
   for (const value of values) {
-    writer.writeUInt32(value);
+    writeItem(writer, value);
+  }
+}
+
+function writeStringList(writer, values = []) {
+  writeSequence(writer, values, (itemWriter, value) => itemWriter.writeString(value));
+}
+
+function writeOptional(writer, value, writeValue) {
+  const present = value !== null && value !== undefined;
+  writer.writeBool(present);
+  if (present) {
+    writeValue(writer, value);
   }
 }
 
@@ -333,6 +360,224 @@ function readTypeSpecResponse(reader) {
   }
 }
 
+function writeEnumeratorSpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeUInt32(item.key ?? 0);
+  writer.writeString(item.description ?? '');
+}
+
+function writeEnumTypeSpec(writer, value = {}) {
+  writeSequence(writer, value.enums ?? [], writeEnumeratorSpec);
+  writer.writeUInt8(enumKey(INTEGRAL_TYPE, value.storageType ?? 'uint32Type', 'IntegralType'));
+}
+
+function writeNumericType(writer, value = {}) {
+  const type = value.type ?? 'RealType';
+  writer.writeUInt32(enumKey(NUMERIC_TYPE, type, 'NumericType'));
+  if (type === 'IntegralType') {
+    writer.writeUInt8(enumKey(INTEGRAL_TYPE, value.value ?? 'int32Type', 'IntegralType'));
+    return;
+  }
+  if (type === 'RealType') {
+    writer.writeUInt8(enumKey(REAL_TYPE, value.value ?? 'float64Type', 'RealType'));
+    return;
+  }
+  throw new TypeError(`unhandled SEN NumericType alternative: ${type}`);
+}
+
+function writeUnitInfo(writer, value = {}) {
+  writer.writeString(value.name ?? '');
+  writer.writeString(value.abbreviation ?? '');
+  writer.writeUInt8(enumKey(UNIT_CATEGORY, value.category ?? 'length', 'UnitCat'));
+}
+
+function writeQuantityTypeSpec(writer, value = {}) {
+  writeNumericType(writer, value.elementType ?? { type: 'RealType', value: 'float64Type' });
+  writeUnitInfo(writer, value.unit ?? {});
+  writeOptional(writer, value.minValue, (itemWriter, item) => itemWriter.writeFloat64(Number(item)));
+  writeOptional(writer, value.maxValue, (itemWriter, item) => itemWriter.writeFloat64(Number(item)));
+}
+
+function writeSequenceTypeSpec(writer, value = {}) {
+  writer.writeString(value.elementType ?? '');
+  writeOptional(writer, value.maxSize, (itemWriter, item) => itemWriter.writeUInt64(item));
+  writer.writeBool(Boolean(value.fixedSize));
+}
+
+function writeStructTypeFieldSpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeString(item.description ?? '');
+  writer.writeString(item.type ?? '');
+}
+
+function writeStructTypeSpec(writer, value = {}) {
+  writeSequence(writer, value.fields ?? [], writeStructTypeFieldSpec);
+  writer.writeString(value.parent ?? '');
+}
+
+function writeVariantTypeFieldSpec(writer, item = {}) {
+  writer.writeUInt32(item.key ?? 0);
+  writer.writeString(item.description ?? '');
+  writer.writeString(item.type ?? '');
+}
+
+function writeVariantTypeSpec(writer, value = {}) {
+  writeSequence(writer, value.fields ?? [], writeVariantTypeFieldSpec);
+}
+
+function writeAliasTypeSpec(writer, value = {}) {
+  writer.writeString(value.aliasedType ?? '');
+}
+
+function writeOptionalTypeSpec(writer, value = {}) {
+  writer.writeString(value.type ?? '');
+}
+
+function writeArgSpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeString(item.description ?? '');
+  writer.writeString(item.type ?? '');
+}
+
+function writeEventSpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeString(item.description ?? '');
+  writeSequence(writer, item.args ?? [], writeArgSpec);
+  writer.writeUInt8(enumKey(TRANSPORT_MODE, item.transportMode ?? 'confirmed', 'TransportModeSpec'));
+}
+
+function writeMethodSpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeString(item.description ?? '');
+  writeSequence(writer, item.args ?? [], writeArgSpec);
+  writer.writeUInt8(enumKey(TRANSPORT_MODE, item.transportMode ?? 'confirmed', 'TransportModeSpec'));
+  writer.writeUInt8(enumKey(METHOD_CONSTNESS, item.constness ?? 'nonConstant', 'MethodConstnessSpec'));
+  writer.writeBool(Boolean(item.deferred));
+  writer.writeString(item.returnType ?? '');
+  writer.writeUInt8(enumKey(PROPERTY_RELATION, item.propertyRelation ?? 'nonPropertyRelated', 'PropertyRelationSpec'));
+  writer.writeBool(Boolean(item.localOnly));
+}
+
+function writePropertySpec(writer, item = {}) {
+  writer.writeString(item.name ?? '');
+  writer.writeString(item.description ?? '');
+  writer.writeUInt8(enumKey(PROPERTY_CATEGORY, item.category ?? 'dynamicRO', 'PropertyCategorySpec'));
+  writer.writeString(item.type ?? '');
+  writer.writeUInt8(enumKey(TRANSPORT_MODE, item.transportMode ?? 'confirmed', 'TransportModeSpec'));
+  writeStringList(writer, item.tags ?? []);
+  writer.writeBool(Boolean(item.checkedSet));
+}
+
+function writeClassTypeSpec(writer, value = {}) {
+  writeSequence(writer, value.properties ?? [], writePropertySpec);
+  writeSequence(writer, value.methods ?? [], writeMethodSpec);
+  writeSequence(writer, value.events ?? [], writeEventSpec);
+  writeMethodSpec(writer, value.constructor ?? { name: '', returnType: '' });
+  writeStringList(writer, value.parents ?? []);
+  writer.writeBool(Boolean(value.isInterface));
+}
+
+function writeCustomTypeData(writer, data = {}) {
+  const type = data.type ?? 'StructTypeSpec';
+  const value = data.value ?? {};
+  writer.writeUInt32(enumKey(CUSTOM_TYPE_DATA, type, 'CustomTypeData'));
+
+  switch (type) {
+    case 'EnumTypeSpec':
+      writeEnumTypeSpec(writer, value);
+      break;
+    case 'QuantityTypeSpec':
+      writeQuantityTypeSpec(writer, value);
+      break;
+    case 'SequenceTypeSpec':
+      writeSequenceTypeSpec(writer, value);
+      break;
+    case 'StructTypeSpec':
+      writeStructTypeSpec(writer, value);
+      break;
+    case 'VariantTypeSpec':
+      writeVariantTypeSpec(writer, value);
+      break;
+    case 'AliasTypeSpec':
+      writeAliasTypeSpec(writer, value);
+      break;
+    case 'OptionalTypeSpec':
+      writeOptionalTypeSpec(writer, value);
+      break;
+    case 'ClassTypeSpec':
+      writeClassTypeSpec(writer, value);
+      break;
+    default:
+      throw new TypeError(`unhandled SEN CustomTypeData alternative: ${type}`);
+  }
+}
+
+function writeCustomTypeSpec(writer, spec = {}) {
+  writer.writeString(spec.name ?? '');
+  writer.writeString(spec.qualifiedName ?? spec.name ?? '');
+  writer.writeString(spec.description ?? '');
+  writeCustomTypeData(writer, spec.data);
+}
+
+function writeTypeSpecResponse(writer, item = {}) {
+  writer.writeUInt32(enumKey(TYPE_SPEC_RESPONSE, item.type ?? 'NonClassSpecResponse', 'TypeSpecResponse'));
+  if ((item.type ?? 'NonClassSpecResponse') === 'ClassSpecResponse') {
+    writer.writeUInt32(item.classHash ?? crc32(item.spec?.qualifiedName ?? item.spec?.name ?? ''));
+    writeCustomTypeSpec(writer, item.spec);
+    writeU32List(writer, item.dependentTypes ?? []);
+    return;
+  }
+  writeCustomTypeSpec(writer, item.spec);
+}
+
+function writeObjectAdded(writer, item = {}) {
+  writer.writeString(item.className ?? '');
+  writer.writeUInt32(item.typeHash ?? crc32(item.className ?? ''));
+  writer.writeString(item.name ?? '');
+  writer.writeUInt32(item.id ?? crc32(item.name ?? ''));
+  writer.writeBuffer(item.state ?? Buffer.alloc(0));
+  writer.writeInt64(item.time ?? 0n);
+}
+
+function writeInterestDiscovery(writer, item = {}) {
+  writer.writeUInt32(item.interestId ?? 0);
+  writeSequence(writer, item.objects ?? [], writeObjectAdded);
+}
+
+function writeObjectsPublished(writer, value = {}) {
+  writer.writeUInt32(value.ownerId ?? 0);
+  writeSequence(writer, value.discoveries ?? [], writeInterestDiscovery);
+}
+
+function writeObjectsRemoved(writer, value = {}) {
+  writeSequence(writer, value.removals ?? [], (itemWriter, item) => {
+    itemWriter.writeUInt32(item.interestId ?? 0);
+    writeU32List(itemWriter, item.ids ?? []);
+  });
+}
+
+function writeObjectsStateResponse(writer, value = {}) {
+  writer.writeUInt32(value.ownerId ?? 0);
+  writeSequence(writer, value.responses ?? [], (itemWriter, response) => {
+    itemWriter.writeUInt32(response.interestId ?? 0);
+    writeSequence(itemWriter, response.objectStates ?? [], (stateWriter, state) => {
+      stateWriter.writeUInt32(state.id ?? 0);
+      stateWriter.writeInt64(state.timestamp ?? 0n);
+      stateWriter.writeBuffer(state.state ?? Buffer.alloc(0));
+    });
+  });
+}
+
+function writeTypesInfoResponse(writer, value = {}) {
+  writer.writeUInt32(value.ownerId ?? 0);
+  writeSequence(writer, value.types ?? [], writeTypeSpecResponse);
+}
+
+function writeTypesInfoRejection(writer, value = {}) {
+  writer.writeUInt32(value.ownerId ?? 0);
+  writeStringList(writer, value.rejections ?? []);
+}
+
 function readTypesInfoResponse(reader) {
   return {
     ownerId: reader.readUInt32(),
@@ -637,6 +882,21 @@ export function encodeKernelControlMessage(message) {
       writer.writeUInt32(value.ownerId);
       writeU32List(writer, value.requests);
       break;
+    case 'ObjectsPublished':
+      writeObjectsPublished(writer, value);
+      break;
+    case 'ObjectsRemoved':
+      writeObjectsRemoved(writer, value);
+      break;
+    case 'ObjectsStateResponse':
+      writeObjectsStateResponse(writer, value);
+      break;
+    case 'TypesInfoResponse':
+      writeTypesInfoResponse(writer, value);
+      break;
+    case 'TypesInfoRejection':
+      writeTypesInfoRejection(writer, value);
+      break;
     default:
       throw new TypeError(`encoding SEN kernel ControlMessage ${type} is not implemented`);
   }