@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/hue/hue.classes.integration.ts

@@ -15,32 +15,70 @@ export class HueIntegration extends BaseIntegration<IHueConfig> {
   public readonly discoveryDescriptor = createHueDiscoveryDescriptor();
   public readonly configFlow = new HueConfigFlow();
   readonly #runtimes = new Set<HueIntegrationRuntime>();
+  readonly #setups = new Set<Promise<IIntegrationRuntime>>();
   #closed = false;
+  #destroyPromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
 
   public async setup(configArg: IHueConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
     if (this.#closed) throw new Error('Hue integration is closed.');
-    const client = new HueClient(configArg, contextArg.abortSignal);
+    const context = hueRecord(contextArg);
+    const signal = context.abortSignal;
+    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('Hue abortSignal must be an AbortSignal.');
+    const client = new HueClient(configArg, signal);
     const runtime = new HueIntegrationRuntime(client, () => this.#runtimes.delete(runtime));
     this.#runtimes.add(runtime);
-    try {
-      await client.getResources();
-      if (this.#closed || contextArg.abortSignal?.aborted) throw new Error('Hue setup was cancelled.');
-      return runtime;
-    } catch (error) {
-      await runtime.destroy();
-      throw error;
+    const setup = Promise.resolve().then(async () => {
+      try {
+        await client.getResources();
+        if (this.#closed || signal?.aborted) throw new Error('Hue setup was cancelled.');
+        return runtime;
+      } catch (error) {
+        try { await runtime.destroy(); }
+        catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Hue setup and cleanup failed.'); }
+        throw error;
+      }
+    });
+    this.#setups.add(setup);
+    void setup.then(() => this.#setups.delete(setup), () => this.#setups.delete(setup));
+    return setup;
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.#destroyPromise) {
+      this.#closed = true;
+      this.#destroyPromise = Promise.resolve().then(() => this.drain(false));
+    }
+    return this.#destroyPromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroyPromise) throw new Error('Hue cleanup retry requires a terminal integration.');
+    if (!this.#retryPromise) {
+      this.#retryPromise = Promise.resolve().then(async () => {
+        await this.#destroyPromise!.catch(() => undefined);
+        await this.drain(true);
+      });
+      const settled = (): void => { this.#retryPromise = undefined; };
+      void this.#retryPromise.then(settled, settled);
     }
+    return this.#retryPromise;
   }
 
-  public async destroy(): Promise<void> {
-    this.#closed = true;
-    await Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()));
+  private async drain(retryArg: boolean): Promise<void> {
+    const cleanup = Promise.allSettled([...this.#runtimes].map((runtimeArg) => retryArg ? runtimeArg.retryCleanup() : runtimeArg.destroy()));
+    const [results] = await Promise.all([cleanup, Promise.allSettled([...this.#setups])]);
+    const errors = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected').map((resultArg) => resultArg.reason as unknown);
+    if (errors.length) throw new AggregateError(errors, 'Hue integration cleanup failed; resources remain retained for explicit retry.');
   }
+
 }
 
 class HueIntegrationRuntime implements IIntegrationRuntime {
   public readonly domain = 'hue';
 
+  #destroyPromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
   constructor(private readonly client: HueClient, private readonly released: () => void) {}
 
   public isHealthy(): boolean { return this.client.isHealthy(); }
@@ -59,24 +97,27 @@ class HueIntegrationRuntime implements IIntegrationRuntime {
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'light' || !['turn_on', 'turn_off', 'set_percentage'].includes(requestArg.service)) {
+    const request = hueRecord(requestArg);
+    if (Reflect.ownKeys(request).some((keyArg) => !['domain', 'service', 'target', 'data'].includes(String(keyArg)))) return { success: false, error: 'Hue service contains unsupported fields.' };
+    if (request.domain !== 'light' || typeof request.service !== 'string' || !['turn_on', 'turn_off', 'set_percentage'].includes(request.service)) {
       return { success: false, error: 'Hue supports only light turn_on, turn_off and set_percentage.' };
     }
-    const target = hueRecord(requestArg.target);
+    const target = hueRecord(request.target);
     if (Reflect.ownKeys(target).some((keyArg) => keyArg !== 'entityId' && keyArg !== 'deviceId')) {
       return { success: false, error: 'Hue service target contains unsupported fields.' };
     }
-    const data = requestArg.data === undefined ? {} : hueRecord(requestArg.data);
-    const allowedKey = requestArg.service === 'set_percentage' ? 'percentage' : requestArg.service === 'turn_on' ? 'brightness' : undefined;
+    if (Object.values(target).some((valueArg) => typeof valueArg !== 'string' || !valueArg)) return { success: false, error: 'Hue service targets must be identifiers.' };
+    const data = request.data === undefined ? {} : hueRecord(request.data);
+    const allowedKey = request.service === 'set_percentage' ? 'percentage' : request.service === 'turn_on' ? 'brightness' : undefined;
     if (Reflect.ownKeys(data).some((keyArg) => keyArg !== allowedKey)) return { success: false, error: 'Hue service data contains unsupported fields.' };
-    const state: IHueLightStatePatch = { on: requestArg.service !== 'turn_off' };
-    if (requestArg.service === 'set_percentage' || data.brightness !== undefined) {
-      const brightness = data[requestArg.service === 'set_percentage' ? 'percentage' : 'brightness'];
+    const state: IHueLightStatePatch = { on: request.service !== 'turn_off' };
+    if (request.service === 'set_percentage' || data.brightness !== undefined) {
+      const brightness = data[request.service === 'set_percentage' ? 'percentage' : 'brightness'];
       if (typeof brightness !== 'number' || !Number.isFinite(brightness) || brightness < 0 || brightness > 100) {
         return { success: false, error: 'Hue brightness must be between 0 and 100 percent.' };
       }
       state.brightness = brightness;
-      if (requestArg.service === 'set_percentage') state.on = brightness > 0;
+      if (request.service === 'set_percentage') state.on = brightness > 0;
     }
     const snapshot = await this.client.getResources();
     const lightId = this.resolveLight(snapshot, target.entityId, target.deviceId);
@@ -86,22 +127,47 @@ class HueIntegrationRuntime implements IIntegrationRuntime {
   }
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const request = hueRecord(requestArg);
+    if (Reflect.ownKeys(request).some((keyArg) => !['device', 'feature', 'value'].includes(String(keyArg)))) return { success: false, error: 'Hue feature request contains unsupported fields.' };
+    const selectedDevice = hueRecord(request.device);
+    const selectedFeature = hueRecord(request.feature);
+    const deviceId = selectedDevice.id;
+    const featureId = selectedFeature.id;
+    const capability = selectedFeature.capability;
+    const value = request.value;
+    if (selectedDevice.integrationDomain !== this.domain || typeof deviceId !== 'string' || typeof featureId !== 'string') {
+      return { success: false, error: 'Hue feature requires one exact Hue device and feature.' };
+    }
     const snapshot = await this.client.getResources(abortSignalArg);
-    const device = HueMapper.toDevices(snapshot).find((deviceArg) => deviceArg.id === requestArg.device.id);
-    const feature = device?.features.find((featureArg) => featureArg.id === requestArg.feature.id && featureArg.writable);
+    const device = HueMapper.toDevices(snapshot).find((deviceArg) => deviceArg.id === deviceId);
+    const feature = device?.features.find((featureArg) => featureArg.id === featureId && featureArg.capability === capability && featureArg.writable);
     const lightId = this.resolveLight(snapshot, undefined, device?.id);
     if (!device || !device.online || !feature || !lightId) return { success: false, error: 'Hue feature target is unknown, unavailable or not writable.' };
     let state: IHueLightStatePatch;
-    if (feature.id === 'on' && typeof requestArg.value === 'boolean') state = { on: requestArg.value };
-    else if (feature.id === 'brightness' && typeof requestArg.value === 'number') state = { brightness: requestArg.value };
+    if (feature.id === 'on' && typeof value === 'boolean') state = { on: value };
+    else if (feature.id === 'brightness' && typeof value === 'number') state = { brightness: value };
     else return { success: false, error: 'Hue feature value has an invalid type.' };
     await this.client.setLightState(lightId, state, abortSignalArg);
     return { success: true };
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-    this.released();
+  public destroy(): Promise<void> {
+    this.#destroyPromise ??= Promise.resolve().then(async () => { await this.client.destroy(); this.released(); });
+    return this.#destroyPromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.#destroyPromise) throw new Error('Hue cleanup retry requires a terminal runtime.');
+    if (!this.#retryPromise) {
+      this.#retryPromise = Promise.resolve().then(async () => {
+        await this.#destroyPromise!.catch(() => undefined);
+        await this.client.retryCleanup();
+        this.released();
+      });
+      const settled = (): void => { this.#retryPromise = undefined; };
+      void this.#retryPromise.then(settled, settled);
+    }
+    return this.#retryPromise;
   }
 
   private resolveLight(snapshotArg: IHueResourceResponse, entityIdArg: unknown, deviceIdArg: unknown): string | undefined {

package/ts/integrations/hue/hue.validation.ts

@@ -10,11 +10,21 @@ export const hueUuid = (valueArg: unknown): valueArg is string =>
 export const hueBridgeId = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[0-9a-f]{16}$/i.test(valueArg);
 
+/** Capture plain data fields without invoking caller accessors or retaining mutable objects. */
 export const hueRecord = (valueArg: unknown): Record<string, unknown> => {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
-    throw new Error('Hue returned an invalid object.');
+  if (!valueArg || typeof valueArg !== 'object'
+    || (Object.getPrototypeOf(valueArg) !== Object.prototype && Object.getPrototypeOf(valueArg) !== null)) {
+    throw new Error('Hue requires a plain data object.');
   }
-  return valueArg as Record<string, unknown>;
+  const record: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new Error('Hue data contains an unsupported field or accessor.');
+    }
+    record[key] = descriptor.value as unknown;
+  }
+  return record;
 };
 
 export const normalizeHueHost = (valueArg: unknown): string => {

package/ts/integrations/hue/readme.md

@@ -33,7 +33,7 @@ Setup checks both the TLS identity and the `bridge_id` returned by `/clip/v2/res
 
 Lights advertise brightness only when the bridge reports the `dimming` capability. Availability follows the owning device's Zigbee connectivity resource; missing or disconnected connectivity is unavailable. Manufacturer and model come from the owning device, including supported third-party Hue lights.
 
-Light services are `turn_on`, `turn_off` and `set_percentage`. `turn_on` accepts optional `brightness` from 0 to 100; `set_percentage` requires `percentage` in that same range. A target must match the current entity/device exactly; supplying both requires them to identify the same light. `writeFeature` supports boolean `on` and numeric `brightness` only for an available light's declared writable capabilities. Unsupported fields, unknown targets and values outside the protocol range are rejected.
+Light services are `turn_on`, `turn_off` and `set_percentage`. `turn_on` accepts optional `brightness` from 0 to 100; `set_percentage` requires `percentage` in that same range. A target must match the current entity/device exactly; supplying both requires them to identify the same light. `writeFeature` supports boolean `on` and numeric `brightness` only for an available light's declared writable capabilities. Unsupported fields, unknown targets and values outside the protocol range are rejected. Controls capture plain-data target IDs, domain, capability and value before awaiting a fresh read; later caller mutation cannot retarget a write. Accessors, symbols, hidden fields and class instances are rejected without invoking getters. Setup cancellation and config-flow discovery endpoint hints are also captured before awaiting readiness or displaying a form.
 
 Writes use `PUT /clip/v2/resource/light/<UUID>` and require the bridge's matching resource acknowledgement. Success means the bridge accepted the write; it does not guarantee physical delivery. Accepted writes never change local read state. Each `devices()` or `entities()` call reads current authoritative resources, and writes are not automatically retried.
 
@@ -41,11 +41,11 @@ Writes use `PUT /clip/v2/resource/light/<UUID>` and require the bridge's matchin
 
 `subscribe()` opens authenticated HTTPS `/eventstream/clip/v2` and returns an asynchronous, idempotent unsubscribe function. Change notifications contain only relevant resource IDs/types; consumers reread authoritative state. Unknown resource payloads are omitted because they may contain credentials. Invalid frames, stream termination and transport failures produce an error event and mark the runtime unhealthy. Reads do not silently restart a failed subscription; the host may explicitly establish a new one or replace the runtime.
 
-Requests have whole-response deadlines and a 4 MiB body limit. Discovery uses the fixed documented `https://discovery.meethue.com/` broker with a five-second deadline and 256 KiB body limit. SSE frames are limited to 1 MiB and batches to 256 events. A client permits at most 32 outstanding connections, two event subscriptions, and three simultaneous HTTPS sockets. Caller cancellation and `destroy()` close owned requests/streams; destroy waits for them to close. The integration also owns pending setups and destroys their clients on failure or shutdown.
+Requests have whole-response deadlines and a 4 MiB body limit. Discovery uses the fixed documented `https://discovery.meethue.com/` broker with a five-second deadline and 256 KiB body limit. SSE frames are limited to 1 MiB and batches to 256 events. A client permits at most 32 outstanding connections, two event subscriptions, and three simultaneous HTTPS sockets. Caller cancellation and `destroy()` close owned requests/streams; destroy waits for them and all admitted request/subscriber continuations to settle. Subscriber callbacks may return promises. Unsubscribe has stable promise identity and joins admitted callbacks; later events are fenced. Each stream permits at most 32 pending callbacks. Synchronous throws and async rejections are observed, mark the stream unhealthy, and use a redacted subscriber error rather than being relabelled as malformed stream data. Callback failures remain visible on terminal client cleanup until explicit `HueClient.retryCleanup()` or `HueIntegration.retryCleanup()` acknowledges them. Failed transport cleanup is retained for the same retry. Retry performs cleanup only; it never replays GETs, PUTs, subscriptions, or callbacks. `destroy()` publishes a stable terminal promise before aborting and continues to return that promise after a retry. Integration and runtime destroy also have stable terminal promise identity. Integration shutdown joins pending setups and all sibling runtimes before surfacing cleanup failures, retaining failed runtime handles for explicit cleanup-only retry. Shared native home/resource admission, flow ownership, and home-qualified IDs are pending a separate breaking config/identity decision. Raw `appKey` configuration remains the current contract; home-bound credential references and existing-config migration require a separate public-contract decision.
 
 ## Verification and limits
 
-Tests use disposable CA-signed local TLS bridges, including untrusted issuers, a wrong bridge certificate, resource identity mismatch, exact PUT payloads, non-optimistic reads, unsupported controls, unavailable devices, malformed/oversized bodies, cancellation and event-stream cleanup. No physical bridge or owner's home was accessed.
+Tests use disposable CA-signed local TLS bridges, including untrusted issuers, a wrong bridge certificate, resource identity mismatch, exact PUT payloads, non-optimistic reads, unsupported controls, unavailable devices, malformed/oversized bodies, cancellation, plain-data/accessor validation, blocked async subscribers, sibling drainage, reentrant close, retained cleanup failures and cleanup-only retry without HTTPS replay. No physical bridge or owner's home was accessed.
 
 The public [Hue API announcement](https://developers.meethue.com/new-hue-api/) establishes API v2 HTTPS, local proactive events and the supported discovery methods. Detailed Hue API and HTTPS pages require a developer login and returned login/403 here. Implemented wire resource models and event paths were cross-checked against [aiohue's upstream v2 implementation](https://github.com/home-assistant-libs/aiohue/tree/main/aiohue/v2). Aiohue's disabled-TLS and geofence keepalive workaround are not used. Physical bridge firmware compatibility, operator CA provisioning and physical command delivery remain acceptance checks. Color, color temperature, scenes, entertainment streaming, grouped lights and accessory sensors are not exposed by this runtime.