@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/shelly/shelly.classes.client.ts

@@ -1,323 +1,440 @@
 import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
 import { AuthenticationError, DeviceCommunicationError } from '../../core/errors.js';
-import type { ILogger } from '../../core/types.js';
 import { ShellySubscription } from './shelly.classes.subscription.js';
-import {
-  createShellyDigest,
-  isShellyRecord,
-  mergeShellyStatus,
-  parseShellyConfig,
-  parseShellyDeviceInfo,
-  parseShellyHttpChallenge,
-  parseShellyRpcResult,
-  parseShellyStatus,
-} from './shelly.rpc.js';
+import { createShellyDigest, isShellyRecord, mergeShellyStatus, parseShellyConfig, parseShellyDeviceInfo,
+  parseShellyHttpChallenge, parseShellyRpcResult, parseShellyStatus } from './shelly.rpc.js';
 import type { IShellyDigestChallenge } from './shelly.rpc.js';
-import type { IShellyConfig, IShellyDeviceConfig, IShellyDeviceInfo, IShellySnapshot, IShellyStatus, TShellyClientEvent } from './shelly.types.js';
+import { normalizeShellyConfig, normalizeShellyOptions, type TNormalizedShellyConfig } from './shelly.validation.js';
+import { ShellyOperationError, type IShellyConfig, type IShellyDeviceConfig, type IShellyDeviceInfo,
+  type IShellyEffectResult, type IShellyIntegrationOptions, type IShellySnapshot, type IShellyStatus,
+  type TShellyClientEvent } from './shelly.types.js';
 
+interface IShellyOperation {
+  readonly signal: AbortSignal;
+  readonly deadline: number;
+  password?: string;
+  dispatched: boolean;
+  acknowledged: boolean;
+  task?: Promise<unknown>;
+}
 interface IShellySubscriber {
   handler(eventArg: TShellyClientEvent): void;
-  signal?: AbortSignal;
-  abort(): void;
+  active: boolean;
+  failed: boolean;
+  detach(): void;
+  stop(): Promise<void>;
 }
+interface IShellyHttpResponse { status: number; challenge?: string; body: string; }
 
 export class ShellyClient {
-  private requestId = 1;
-  private nonceCount = 0;
-  private digestChallenge?: IShellyDigestChallenge;
-  private deviceId?: string;
-  private snapshot?: IShellySnapshot;
-  private subscription?: ShellySubscription;
-  private readonly subscribers = new Set<IShellySubscriber>();
-  private readonly lifetime = new AbortController();
-  private readonly lifetimeSignal: AbortSignal;
-  // Firmware tracks increasing digest nonce counts, so HTTP calls must arrive in order.
-  private requestQueue: Promise<void> = Promise.resolve();
-  private readonly timeoutMs: number;
-  private readonly endpoint: URL;
-  private readonly config: IShellyConfig;
-  private healthy = false;
-  private destroyed = false;
+  readonly #config: TNormalizedShellyConfig;
+  readonly #context: INativeAdmissionContext;
+  readonly #endpoint: URL;
+  readonly #lifetime = new AbortController();
+  readonly #tasks = new Set<Promise<unknown>>();
+  readonly #credentials = new Set<Promise<unknown>>();
+  readonly #credentialOperations = new Map<Promise<unknown>, Promise<unknown>>();
+  readonly #credentialFailures = new Set<Error>();
+  readonly #requests = new Set<plugins.http.ClientRequest>();
+  readonly #sockets = new Set<plugins.net.Socket>();
+  readonly #drains = new Set<Promise<void>>();
+  readonly #subscribers = new Set<IShellySubscriber>();
+  readonly #subscriptions = new Set<ShellySubscription>();
+  readonly #parentAbort: () => void;
+  #resolvePassword?: IShellyIntegrationOptions['resolvePassword'];
+  #tail: Promise<void> = Promise.resolve();
+  #requestId = 1;
+  #nonceCount = 0;
+  #challenge?: IShellyDigestChallenge;
+  #snapshot?: IShellySnapshot;
+  #subscription?: ShellySubscription;
+  #healthy = false;
+  #closed = false;
+  #closePromise?: Promise<void>;
+  #cleanupPromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+  #cleanupFailed = false;
 
-  constructor(configArg: IShellyConfig, abortSignalArg?: AbortSignal, private readonly logger?: ILogger) {
-    const config: IShellyConfig = {
-      host: configArg.host,
-      port: configArg.port,
-      protocol: configArg.protocol,
-      username: configArg.username,
-      password: configArg.password,
-      requestTimeoutMs: configArg.requestTimeoutMs,
-    };
-    this.config = config;
-    this.timeoutMs = config.requestTimeoutMs ?? 10000;
-    if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs < 10 || this.timeoutMs > 60000) {
-      throw new Error('Shelly requestTimeoutMs must be an integer between 10 and 60000.');
-    }
-    if (config.username !== undefined && config.username !== 'admin') throw new AuthenticationError('Shelly authentication username must be admin.');
-    if (config.password !== undefined && typeof config.password !== 'string') throw new AuthenticationError('Shelly password must be a string.');
-    if (config.protocol !== undefined && config.protocol !== 'http' && config.protocol !== 'https') throw new Error('Shelly protocol must be http or https.');
-    if (config.port !== undefined && (!Number.isSafeInteger(config.port) || config.port < 1 || config.port > 65535)) throw new Error('Shelly port must be between 1 and 65535.');
-    if (config.host === undefined) throw new Error('Shelly host is required for live requests.');
-    if (typeof config.host !== 'string' || !config.host || /[\s\/?#@]/.test(config.host)) throw new Error('Shelly host must be a hostname or IP address.');
-    const host = config.host.includes(':') && !config.host.startsWith('[') ? `[${config.host}]` : config.host;
-    try { this.endpoint = new URL(`${config.protocol ?? 'http'}://${host}${config.port === undefined ? '' : `:${config.port}`}`); }
-    catch { throw new Error('Shelly host must be a hostname or IP address.'); }
-    this.lifetimeSignal = AbortSignal.any([this.lifetime.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+  constructor(configArg: IShellyConfig, contextArg: INativeIntegrationSetupContext,
+    optionsArg: IShellyIntegrationOptions = {}) {
+    this.#config = normalizeShellyConfig(configArg);
+    const options = normalizeShellyOptions(optionsArg);
+    this.#context = new NativeHomeAdmission('shelly', { homeId: options.homeId }).admit(contextArg, this.#config.homeId);
+    this.#resolvePassword = options.resolvePassword;
+    if (this.#config.credentialRef !== undefined && !this.#resolvePassword) throw new TypeError('Shelly credential reference requires a caller-owned password resolver.');
+    const host = this.#config.host.includes(':') && !this.#config.host.startsWith('[') ? `[${this.#config.host}]` : this.#config.host;
+    this.#endpoint = new URL(`${this.#config.protocol}://${host}:${this.#config.port}`);
+    this.#parentAbort = () => { void this.destroy().catch(() => undefined); };
+    this.#context.abortSignal?.addEventListener('abort', this.#parentAbort, { once: true });
+    if (this.#context.abortSignal?.aborted) this.#parentAbort();
   }
 
   public isHealthy(): boolean {
-    return !this.destroyed && !this.lifetimeSignal.aborted && this.healthy && (!this.subscription || this.subscription.isHealthy);
+    return !this.#closed && this.#healthy && (!this.#subscription || this.#subscription.isHealthy);
   }
-
-  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<IShellySnapshot> {
-    this.assertActive(abortSignalArg);
-    if (this.snapshot && this.subscription?.isHealthy) return structuredClone(this.snapshot);
-    const deviceInfo = await this.getDeviceInfo(abortSignalArg);
-    const status = await this.getStatus(abortSignalArg);
-    const deviceConfig = await this.getDeviceConfig(abortSignalArg);
-    this.snapshot = { deviceInfo, status, deviceConfig };
-    return structuredClone(this.snapshot);
+  /** Validated push observations may satisfy reads; controls always call read() afresh. */
+  public getSnapshot(signalArg?: AbortSignal): Promise<IShellySnapshot> {
+    try {
+      this.assertOpen();
+      if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Shelly cancellation requires an AbortSignal.');
+      if (signalArg?.aborted) throw new DOMException('Shelly operation cancelled.', 'AbortError');
+      if (this.#snapshot && this.#healthy && this.#subscription?.isHealthy) return Promise.resolve(structuredClone(this.#snapshot));
+    } catch (errorArg) { return Promise.reject(errorArg); }
+    return this.run((operationArg) => this.read(operationArg), signalArg);
   }
-
-  public async getDeviceInfo(abortSignalArg?: AbortSignal): Promise<IShellyDeviceInfo> {
-    this.assertActive(abortSignalArg);
-    const response = await this.requestJson('/shelly', undefined, abortSignalArg);
-    const deviceInfo = this.parseResponse(() => {
-      const info = parseShellyDeviceInfo(response);
-      if (this.deviceId !== undefined && this.deviceId !== info.id) throw new DeviceCommunicationError('Shelly endpoint device identity changed.');
-      return info;
-    });
-    this.deviceId = deviceInfo.id;
-    return deviceInfo;
+  public getDeviceInfo(signalArg?: AbortSignal): Promise<IShellyDeviceInfo> {
+    return this.run(async (operationArg) => { await this.bootstrap(operationArg); return this.identity(await this.rpc(operationArg, 'Shelly.GetDeviceInfo')); }, signalArg);
   }
-
-  public async getStatus(abortSignalArg?: AbortSignal): Promise<IShellyStatus> {
-    this.assertActive(abortSignalArg);
-    const response = await this.callRpc('Shelly.GetStatus', undefined, abortSignalArg);
-    const status = this.parseResponse(() => parseShellyStatus(response));
-    this.healthy = true;
-    if (this.snapshot) this.updateStatus(status, true, Date.now());
-    return status;
+  public getStatus(signalArg?: AbortSignal): Promise<IShellyStatus> {
+    return this.run(async (operationArg) => (await this.read(operationArg)).status, signalArg);
   }
-
-  public async getDeviceConfig(abortSignalArg?: AbortSignal): Promise<IShellyDeviceConfig> {
-    this.assertActive(abortSignalArg);
-    const response = await this.callRpc('Shelly.GetConfig', undefined, abortSignalArg);
-    return this.parseResponse(() => parseShellyConfig(response));
+  public getDeviceConfig(signalArg?: AbortSignal): Promise<IShellyDeviceConfig> {
+    return this.run(async (operationArg) => (await this.read(operationArg)).deviceConfig ?? {}, signalArg);
   }
-
-  public async setSwitchOutput(switchIdArg: number, onArg: boolean, abortSignalArg?: AbortSignal): Promise<void> {
-    if (!Number.isSafeInteger(switchIdArg) || switchIdArg < 0 || typeof onArg !== 'boolean') throw new Error('Shelly switch writes require a non-negative integer id and boolean output.');
-    const snapshot = await this.getSnapshot(abortSignalArg);
-    if (!isShellyRecord(snapshot.status[`switch:${switchIdArg}`])) throw new Error('Shelly switch is not present on the connected device.');
-    const result = await this.callRpc('Switch.Set', { id: switchIdArg, on: onArg }, abortSignalArg);
-    this.parseResponse(() => {
+  public setSwitchOutput(idArg: number, onArg: boolean, signalArg?: AbortSignal): Promise<IShellyEffectResult> {
+    if (!Number.isSafeInteger(idArg) || idArg < 0 || typeof onArg !== 'boolean') return Promise.reject(new ShellyOperationError('Shelly switch writes require a non-negative integer id and boolean output.'));
+    if (!this.#config.allowControl) return Promise.reject(new ShellyOperationError('Shelly output controls are disabled.'));
+    return this.run(async (operationArg) => {
+      const before = await this.read(operationArg);
+      if (!before.methods.includes('Switch.Set') || !before.methods.includes('Switch.GetStatus')) throw new ShellyOperationError('Shelly does not currently allow the required switch methods.');
+      if (!isShellyRecord(before.status[`switch:${idArg}`])) throw new ShellyOperationError('Shelly switch is not present on the connected device.');
+      parseShellyStatus({ [`switch:${idArg}`]: await this.rpc(operationArg, 'Switch.GetStatus', { id: idArg }) });
+      const result = await this.rpc(operationArg, 'Switch.Set', { id: idArg, on: onArg }, true);
       if (typeof result.was_on !== 'boolean') throw new DeviceCommunicationError('Shelly returned an invalid switch response.');
-    });
-    await this.getStatus(abortSignalArg);
+      operationArg.acknowledged = true;
+      this.identity(await this.rpc(operationArg, 'Shelly.GetDeviceInfo'));
+      const status = parseShellyStatus({ [`switch:${idArg}`]: await this.rpc(operationArg, 'Switch.GetStatus', { id: idArg }) });
+      const component = status[`switch:${idArg}`];
+      if (!isShellyRecord(component)) throw new DeviceCommunicationError('Shelly returned an invalid switch readback.');
+      const snapshot = { ...before, status: { ...before.status, ...status } };
+      this.observe(snapshot);
+      return { componentId: idArg, requested: onArg, wasOn: result.was_on, commandAcknowledged: true,
+        causalityConfirmed: false, outcome: component.output === onArg ? 'observed-target' : 'indeterminate',
+        snapshot: structuredClone(snapshot) };
+    }, signalArg);
   }
-
-  public async subscribe(handlerArg: (eventArg: TShellyClientEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
-    this.assertActive(abortSignalArg);
-    if (!this.snapshot) await this.getSnapshot(abortSignalArg);
-    let rejectCancelled: ((errorArg: Error) => void) | undefined;
-    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancelled = rejectArg; });
-    const subscriber: IShellySubscriber = {
-      handler: handlerArg,
-      signal: abortSignalArg,
-      abort: () => {
-        rejectCancelled?.(new DOMException('Shelly subscription cancelled.', 'AbortError'));
-        void unsubscribe().catch(() => {
-          this.logger?.log('error', 'Shelly subscription cleanup failed.');
-          this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly subscription cleanup failed.'), timestamp: Date.now() });
-        });
-      },
-    };
-    let removed = false;
-    const unsubscribe = async (): Promise<void> => {
-      if (!removed) {
-        removed = true;
-        subscriber.signal?.removeEventListener('abort', subscriber.abort);
-        this.subscribers.delete(subscriber);
-      }
-      if (this.subscribers.size === 0 && this.subscription) {
-        const subscription = this.subscription;
-        await subscription.stop();
-        if (this.subscription === subscription) this.subscription = undefined;
-      }
-    };
-    this.subscribers.add(subscriber);
-    abortSignalArg?.addEventListener('abort', subscriber.abort, { once: true });
-    if (abortSignalArg?.aborted) subscriber.abort();
+  public subscribe(handlerArg: (eventArg: TShellyClientEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
     try {
-      await Promise.race([this.connectSubscription(), cancellation]);
-      this.assertActive(abortSignalArg);
-      rejectCancelled = undefined;
-      return unsubscribe;
-    } catch (errorArg) {
-      await unsubscribe();
+      this.assertOpen();
+      if (typeof handlerArg !== 'function' || signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Shelly subscription requires a callback and optional AbortSignal.');
+      if (signalArg?.aborted) throw new DOMException('Shelly subscription cancelled.', 'AbortError');
+      if (this.#subscribers.size >= 32) throw new Error('Shelly subscriber capacity reached.');
+    } catch (errorArg) { return Promise.reject(errorArg); }
+    const aborted = (): void => { void subscriber.stop().catch(() => undefined); };
+    const subscriber: IShellySubscriber = { handler: handlerArg, active: true, failed: false,
+      detach: () => { subscriber.active = false; signalArg?.removeEventListener('abort', aborted); },
+      stop: async () => {
+        subscriber.detach();
+        if (!subscriber.failed) this.#subscribers.delete(subscriber);
+        if (![...this.#subscribers].some((entryArg) => entryArg.active) && this.#subscription) {
+          const subscription = this.#subscription;
+          await subscription.stop();
+          if (this.#subscription === subscription) this.#subscription = undefined;
+          this.#subscriptions.delete(subscription);
+        }
+        if (subscriber.failed) throw new Error('Shelly subscriber callback failed.');
+      } };
+    this.#subscribers.add(subscriber);
+    signalArg?.addEventListener('abort', aborted, { once: true });
+    if (signalArg?.aborted) aborted();
+    return this.run(async (operationArg) => {
+      if (!this.#snapshot) await this.read(operationArg); else await this.resolveCredential(operationArg);
+      this.active(operationArg);
+      await this.connectSubscription(operationArg);
+      this.active(operationArg);
+      return subscriber.stop;
+    }, signalArg).catch(async (errorArg: unknown) => {
+      try { await subscriber.stop(); } catch (cleanupArg) { throw new AggregateError([errorArg, cleanupArg], 'Shelly subscription and cleanup failed.'); }
       throw errorArg;
+    });
+  }
+  /** Memo precedes abort and all foreign callbacks. */
+  public destroy(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closed = true;
+      this.#healthy = false;
+      this.#closePromise = Promise.resolve().then(() => this.drainCleanup(false));
+      this.#cleanupPromise = this.#closePromise;
+      this.#context.abortSignal?.removeEventListener('abort', this.#parentAbort);
+      for (const subscriber of this.#subscribers) subscriber.detach();
+      this.#lifetime.abort(new DOMException('Shelly operation cancelled.', 'AbortError'));
+      for (const request of this.#requests) request.destroy();
+      for (const socket of this.#sockets) socket.destroy();
     }
+    return this.#closePromise;
   }
-
-  public async destroy(): Promise<void> {
-    this.destroyed = true;
-    this.healthy = false;
-    for (const subscriber of this.subscribers) subscriber.signal?.removeEventListener('abort', subscriber.abort);
-    this.subscribers.clear();
-    this.lifetime.abort();
-    await this.requestQueue;
-    if (this.subscription) {
-      await this.subscription.stop();
-      this.subscription = undefined;
+  /** Terminal cleanup retry never resolves credentials or replays transport. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) return this.destroy();
+    if (!this.#cleanupFailed) return this.#cleanupPromise ?? this.#closePromise;
+    if (!this.#retryPromise) {
+      this.#retryPromise = Promise.resolve().then(() => this.drainCleanup(true));
+      this.#cleanupPromise = this.#retryPromise;
+      const settled = (): void => { this.#retryPromise = undefined; };
+      void this.#retryPromise.then(settled, settled);
     }
+    return this.#retryPromise;
   }
-
-  private async connectSubscription(): Promise<void> {
-    if (this.subscription?.isStopping) {
-      const previous = this.subscription;
-      await previous.stop();
-      if (this.subscription === previous) this.subscription = undefined;
+  private async drainCleanup(retryArg: boolean): Promise<void> {
+    const cleanup = [...this.#subscriptions].map((entryArg) => Promise.resolve().then(() => retryArg ? entryArg.retryCleanup() : entryArg.stop()));
+    const results = await Promise.allSettled(cleanup);
+    while (this.#tasks.size || this.#credentials.size || this.#drains.size) await Promise.allSettled([...this.#tasks, ...this.#credentials, ...this.#drains]);
+    const late = await Promise.allSettled([...this.#subscriptions].map((entryArg) => retryArg ? entryArg.retryCleanup() : entryArg.stop()));
+    const failures = [...results, ...late].filter((entryArg): entryArg is PromiseRejectedResult => entryArg.status === 'rejected').map((entryArg) => entryArg.reason as unknown);
+    if (!retryArg) {
+      failures.push(...this.#credentialFailures);
+      for (const subscriber of this.#subscribers) if (subscriber.failed) failures.push(new Error('Shelly subscriber callback failed.'));
+    } else this.#credentialFailures.clear();
+    for (const subscription of this.#subscriptions) if (subscription.isClosed) this.#subscriptions.delete(subscription);
+    if (retryArg || !failures.length) this.#subscribers.clear();
+    this.#resolvePassword = undefined;
+    this.#snapshot = undefined;
+    this.#cleanupFailed = failures.length > 0;
+    if (failures.length) throw new AggregateError([...new Set(failures)], 'Shelly owned cleanup failed.');
+  }
+  private async read(operationArg: IShellyOperation): Promise<IShellySnapshot> {
+    await this.bootstrap(operationArg);
+    const deviceInfo = this.identity(await this.rpc(operationArg, 'Shelly.GetDeviceInfo'));
+    const allowed = await this.rpc(operationArg, 'Shelly.ListMethods');
+    if (!Array.isArray(allowed.methods) || allowed.methods.length > 512 ||
+      !allowed.methods.every((methodArg: unknown) => typeof methodArg === 'string' && /^[A-Za-z][A-Za-z0-9]*\.[A-Za-z][A-Za-z0-9]*$/.test(methodArg))) throw new DeviceCommunicationError('Shelly returned invalid allowed methods.');
+    const methods = [...new Set(allowed.methods as string[])];
+    if (!methods.includes('Shelly.GetStatus') || !methods.includes('Shelly.GetConfig') || !methods.includes('Shelly.GetDeviceInfo')) throw new DeviceCommunicationError('Shelly does not currently allow the required observation methods.');
+    const status = parseShellyStatus(await this.rpc(operationArg, 'Shelly.GetStatus'));
+    if (status.sys?.mac !== undefined && status.sys.mac.toUpperCase() !== this.#config.expectedMacAddress) throw new DeviceCommunicationError('Shelly endpoint device identity changed.');
+    const deviceConfig = parseShellyConfig(await this.rpc(operationArg, 'Shelly.GetConfig'));
+    const snapshot: IShellySnapshot = { homeId: this.#context.homeId, deviceInfo, status, deviceConfig, methods, controlEnabled: this.#config.allowControl };
+    this.observe(snapshot);
+    return structuredClone(snapshot);
+  }
+  private async bootstrap(operationArg: IShellyOperation): Promise<void> {
+    this.identity(await this.requestJson(operationArg, '/shelly'));
+    await this.resolveCredential(operationArg);
+  }
+  private identity(valueArg: unknown): IShellyDeviceInfo {
+    const info = parseShellyDeviceInfo(valueArg);
+    if (info.id !== this.#config.expectedDeviceId || info.mac?.toUpperCase() !== this.#config.expectedMacAddress || info.model !== this.#config.expectedModel || info.gen !== this.#config.expectedGeneration) throw new DeviceCommunicationError('Shelly endpoint device identity changed.');
+    return info;
+  }
+  private observe(snapshotArg: IShellySnapshot): void {
+    this.assertOpen();
+    this.#snapshot = structuredClone(snapshotArg);
+    this.#healthy = true;
+    this.emit({ type: 'status', snapshot: structuredClone(snapshotArg), timestamp: Date.now() });
+  }
+  private async connectSubscription(operationArg: IShellyOperation): Promise<void> {
+    if (this.#subscription?.isStopping) {
+      await this.#subscription.stop();
+      this.#subscriptions.delete(this.#subscription);
+      this.#subscription = undefined;
     }
-    this.assertActive();
-    if (!this.subscription || this.subscription.isClosed) {
-      if (!this.deviceId) throw new Error('Shelly subscription requires a validated device.');
-      const url = new URL('/rpc', this.endpoint);
-      url.protocol = this.endpoint.protocol === 'https:' ? 'wss:' : 'ws:';
-      this.subscription = new ShellySubscription({
-        url: url.toString(),
-        deviceId: this.deviceId,
-        source: `shx-${plugins.crypto.randomUUID()}`,
-        password: this.config.password,
-        timeoutMs: this.timeoutMs,
-        abortSignal: this.lifetimeSignal,
+    this.active(operationArg);
+    if (!this.#subscription || this.#subscription.isClosed) {
+      const url = new URL('/rpc', this.#endpoint);
+      url.protocol = this.#config.protocol === 'https' ? 'wss:' : 'ws:';
+      const subscription = new ShellySubscription({ url: url.toString(), deviceId: this.#config.expectedDeviceId,
+        source: `shx-${plugins.crypto.randomUUID()}`, password: operationArg.password,
+        timeoutMs: this.#config.requestTimeoutMs, abortSignal: this.#lifetime.signal,
         onStatus: (statusArg, fullArg, timestampArg) => this.updateStatus(statusArg, fullArg, timestampArg),
         onEvent: (eventArg, timestampArg) => {
           this.emit({ type: 'event', event: eventArg, timestamp: timestampArg });
-          if (eventArg.event === 'config_changed') void this.refreshConfig(timestampArg);
+          if (eventArg.event === 'config_changed') void this.run((operationArg) => this.read(operationArg)).catch(() => {
+            if (!this.#closed) this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly configuration refresh failed.'), timestamp: Date.now() });
+          });
         },
         onAvailability: (availableArg) => this.emit({ type: 'availability', available: availableArg, timestamp: Date.now() }),
-        onError: (errorArg) => this.emit({ type: 'error', error: errorArg, timestamp: Date.now() }),
-      });
+        onError: (errorArg) => this.emit({ type: 'error', error: errorArg, timestamp: Date.now() }) });
+      this.#subscriptions.add(subscription);
+      this.#subscription = subscription;
     }
-    await this.subscription.start();
+    const subscription = this.#subscription;
+    let cancelled: () => void = () => {};
+    const cancellation = new Promise<never>((_resolveArg, rejectArg) => {
+      cancelled = () => { try { this.active(operationArg); } catch (errorArg) { rejectArg(errorArg); } };
+      operationArg.signal.addEventListener('abort', cancelled, { once: true });
+    });
+    try { await Promise.race([subscription.start(), cancellation]); }
+    finally { operationArg.signal.removeEventListener('abort', cancelled); }
   }
-
   private updateStatus(statusArg: IShellyStatus, fullArg: boolean, timestampArg: number): void {
-    if (!this.snapshot || this.destroyed) return;
-    this.snapshot = { ...this.snapshot, status: fullArg ? statusArg : mergeShellyStatus(this.snapshot.status, statusArg) };
-    this.emit({ type: 'status', snapshot: structuredClone(this.snapshot), timestamp: timestampArg });
+    if (!this.#snapshot || this.#closed) return;
+    const status = fullArg ? statusArg : mergeShellyStatus(this.#snapshot.status, statusArg);
+    if (status.sys?.mac !== undefined && status.sys.mac.toUpperCase() !== this.#config.expectedMacAddress) throw new DeviceCommunicationError('Shelly notification identity changed.');
+    this.#snapshot = { ...this.#snapshot, status };
+    this.emit({ type: 'status', snapshot: structuredClone(this.#snapshot), timestamp: timestampArg });
   }
-
   private emit(eventArg: TShellyClientEvent): void {
-    for (const subscriber of [...this.subscribers]) {
-      if (!this.subscribers.has(subscriber)) continue;
+    if (this.#closed) return;
+    for (const subscriber of [...this.#subscribers]) {
+      if (this.#closed) break;
+      if (!subscriber.active) continue;
       try { subscriber.handler(structuredClone(eventArg)); }
       catch {
-        this.logger?.log('error', 'Shelly subscriber callback failed.');
-        subscriber.abort();
+        subscriber.failed = true;
+        subscriber.detach();
+        try { this.#context.logger?.log('error', 'Shelly subscriber callback failed.'); } catch { /* Failure remains retained. */ }
         this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly subscriber callback failed.'), timestamp: Date.now() });
       }
     }
   }
-
-  private async refreshConfig(timestampArg: number): Promise<void> {
+  private async resolveCredential(operationArg: IShellyOperation): Promise<void> {
+    if (this.#config.credentialRef === undefined) return;
+    this.active(operationArg);
+    const resolver = this.#resolvePassword;
+    if (!resolver) throw new AuthenticationError('Shelly credential resolver is unavailable.');
+    const credential = Promise.resolve().then(() => {
+      this.active(operationArg);
+      return resolver(Object.freeze({ homeId: this.#context.homeId, credentialRef: this.#config.credentialRef!, signal: operationArg.signal, deadline: operationArg.deadline }));
+    });
+    this.#credentials.add(credential);
+    this.#credentialOperations.set(credential, operationArg.task!);
+    void credential.then(() => { this.#credentials.delete(credential); this.#credentialOperations.delete(credential); }, (errorArg: unknown) => {
+      this.#credentials.delete(credential);
+      this.#credentialOperations.delete(credential);
+      if (operationArg.signal.aborted && errorArg !== operationArg.signal.reason) this.#credentialFailures.add(new Error('Shelly caller credential resolution failed.'));
+    });
+    let cancel: () => void = () => {};
+    const cancelled = new Promise<never>((_resolveArg, rejectArg) => {
+      cancel = () => { try { this.active(operationArg); } catch (errorArg) { rejectArg(errorArg); } };
+      operationArg.signal.addEventListener('abort', cancel, { once: true });
+    });
     try {
-      const deviceConfig = await this.getDeviceConfig();
-      if (this.snapshot && !this.destroyed) {
-        this.snapshot = { ...this.snapshot, deviceConfig };
-        this.emit({ type: 'status', snapshot: structuredClone(this.snapshot), timestamp: timestampArg });
-      }
-    } catch {
-      if (!this.destroyed && !this.lifetimeSignal.aborted) this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly configuration refresh failed.'), timestamp: Date.now() });
-    }
-  }
-
-  private parseResponse<TResult>(parserArg: () => TResult): TResult {
-    try { return parserArg(); }
-    catch (errorArg) { this.healthy = false; throw errorArg; }
+      const password = await Promise.race([credential, cancelled]);
+      this.active(operationArg);
+      if (typeof password !== 'string' || !password || password.length > 1024) throw new AuthenticationError('Shelly caller credential resolution failed.');
+      operationArg.password = password;
+    } catch { this.active(operationArg); throw new AuthenticationError('Shelly caller credential resolution failed.'); }
+    finally { operationArg.signal.removeEventListener('abort', cancel); }
   }
-
-  private async callRpc(methodArg: string, paramsArg?: Record<string, unknown>, abortSignalArg?: AbortSignal): Promise<Record<string, unknown>> {
-    if (!this.deviceId) await this.getDeviceInfo(abortSignalArg);
-    const id = this.requestId++;
+  private rpc(operationArg: IShellyOperation, methodArg: string, paramsArg?: Record<string, unknown>, effectArg = false): Promise<Record<string, unknown>> {
+    const id = this.#requestId++;
     const source = 'smarthome.exchange';
-    const frame = await this.requestJson('/rpc', { id, src: source, method: methodArg, params: paramsArg }, abortSignalArg);
-    return this.parseResponse(() => parseShellyRpcResult(frame, id, this.deviceId, source));
+    return this.requestJson(operationArg, '/rpc', { id, src: source, method: methodArg, ...(paramsArg ? { params: paramsArg } : {}) }, effectArg).then((frameArg) => parseShellyRpcResult(frameArg, id, this.#config.expectedDeviceId, source));
   }
-
-  private async requestJson(pathArg: string, bodyArg?: Record<string, unknown>, abortSignalArg?: AbortSignal): Promise<unknown> {
-    this.assertActive(abortSignalArg);
-    const deadline = new AbortController();
-    let timedOut = false;
-    const timer = setTimeout(() => { timedOut = true; deadline.abort(); }, this.timeoutMs);
-    const signal = AbortSignal.any([deadline.signal, this.lifetimeSignal, ...(abortSignalArg ? [abortSignalArg] : [])]);
-    const cancelled = (): Error => timedOut ? new DeviceCommunicationError('Shelly request timed out.') : new DOMException('Shelly request cancelled.', 'AbortError');
-    let rejectCancelled: ((errorArg: Error) => void) | undefined;
-    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancelled = rejectArg; });
-    const handleAbort = (): void => rejectCancelled?.(cancelled());
-    signal.addEventListener('abort', handleAbort, { once: true });
-    if (signal.aborted) handleAbort();
-    const operation = this.requestQueue.then(async () => {
-      if (signal.aborted) throw cancelled();
-      const method = bodyArg ? 'POST' : 'GET';
-      let response = await this.fetchPath(pathArg, method, bodyArg, signal);
-      if (response.status === 401) {
-        await response.body?.cancel();
-        if (!this.config.password) throw new AuthenticationError('Shelly authentication requires a password.');
-        this.digestChallenge = parseShellyHttpChallenge(response.headers.get('www-authenticate'), this.deviceId);
-        this.nonceCount = 0;
-        response = await this.fetchPath(pathArg, method, bodyArg, signal);
-      }
-      if (!response.ok) {
-        await response.body?.cancel();
-        if (response.status === 401) throw new AuthenticationError('Shelly authentication failed.');
-        throw new DeviceCommunicationError(`Shelly request failed with HTTP ${response.status}.`);
-      }
-      if (!response.body) throw new DeviceCommunicationError('Shelly returned an empty response.');
-      const reader = response.body.getReader();
-      const chunks: Uint8Array[] = [];
-      let size = 0;
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          size += value.byteLength;
-          if (size > 1024 * 1024) {
-            await reader.cancel();
-            throw new DeviceCommunicationError('Shelly response exceeds the size limit.');
-          }
-          chunks.push(value);
-        }
-      } finally { reader.releaseLock(); }
-      return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;
-    });
-    this.requestQueue = operation.then(() => undefined, () => undefined);
-    try { return await Promise.race([operation, cancellation]); }
-    catch (errorArg) {
-      this.healthy = false;
-      if (signal.aborted) throw cancelled();
-      if (errorArg instanceof AuthenticationError || errorArg instanceof DeviceCommunicationError) throw errorArg;
-      throw new DeviceCommunicationError('Shelly request failed or returned invalid JSON.');
-    } finally {
-      clearTimeout(timer);
-      signal.removeEventListener('abort', handleAbort);
-      rejectCancelled = undefined;
+  private async requestJson(operationArg: IShellyOperation, pathArg: string, bodyArg?: Record<string, unknown>, effectArg = false): Promise<unknown> {
+    this.active(operationArg);
+    let response = await this.request(operationArg, pathArg, bodyArg, effectArg);
+    if (response.status === 401 && !effectArg) {
+      if (!operationArg.password) throw new AuthenticationError('Shelly authentication requires a password.');
+      this.#challenge = parseShellyHttpChallenge(response.challenge ?? null, this.#config.expectedDeviceId);
+      this.#nonceCount = 0;
+      response = await this.request(operationArg, pathArg, bodyArg);
     }
+    if (response.status !== 200) {
+      if (response.status === 401) throw new AuthenticationError('Shelly authentication failed.');
+      throw new DeviceCommunicationError('Shelly HTTP request was rejected.');
+    }
+    try { return JSON.parse(response.body) as unknown; } catch { throw new DeviceCommunicationError('Shelly returned invalid JSON.'); }
   }
-
-  private async fetchPath(pathArg: string, methodArg: string, bodyArg: Record<string, unknown> | undefined, signalArg: AbortSignal): Promise<Response> {
-    const headers: Record<string, string> = {};
-    if (bodyArg) headers['content-type'] = 'application/json';
-    if (this.digestChallenge && this.config.password) {
-      const digest = createShellyDigest(this.digestChallenge, this.config.password, ++this.nonceCount, methodArg, pathArg);
-      headers.authorization = `Digest username="admin", realm="${this.digestChallenge.realm}", nonce="${this.digestChallenge.nonce}", uri="${pathArg}", algorithm=SHA-256, response="${digest.response}", qop=auth, nc=${digest.nc}, cnonce="${digest.cnonce}"${this.digestChallenge.opaque ? `, opaque="${this.digestChallenge.opaque}"` : ''}`;
+  private async request(operationArg: IShellyOperation, pathArg: string, bodyArg?: Record<string, unknown>, effectArg = false): Promise<IShellyHttpResponse> {
+    this.active(operationArg);
+    const method = bodyArg ? 'POST' : 'GET';
+    const payload = bodyArg ? JSON.stringify(bodyArg) : undefined;
+    const headers: Record<string, string | number> = { connection: 'close', 'accept-encoding': 'identity' };
+    if (payload) { headers['content-type'] = 'application/json'; headers['content-length'] = Buffer.byteLength(payload); }
+    if (this.#challenge && operationArg.password) {
+      const digest = createShellyDigest(this.#challenge, operationArg.password, ++this.#nonceCount, method, pathArg);
+      headers.authorization = `Digest username="admin", realm="${this.#challenge.realm}", nonce="${this.#challenge.nonce}", uri="${pathArg}", algorithm=SHA-256, response="${digest.response}", qop=auth, nc=${digest.nc}, cnonce="${digest.cnonce}"${this.#challenge.opaque ? `, opaque="${this.#challenge.opaque}"` : ''}`;
+    }
+    let request: plugins.http.ClientRequest | undefined;
+    let socketDrain: Promise<void> = Promise.resolve();
+    let resolveRequestClose: () => void = () => {};
+    const requestDrain = new Promise<void>((resolveArg) => { resolveRequestClose = resolveArg; });
+    const abort = (): void => { request?.destroy(); };
+    operationArg.signal.addEventListener('abort', abort, { once: true });
+    let failure: unknown;
+    let result: IShellyHttpResponse | undefined;
+    try {
+      result = await new Promise<IShellyHttpResponse>((resolveArg, rejectArg) => {
+        const transport = this.#config.protocol === 'https' ? plugins.https : plugins.http;
+        request = transport.request(new URL(pathArg, this.#endpoint), { method, headers, agent: false, maxHeaderSize: 8192 }, (responseArg) => {
+          const fail = (messageArg: string): void => { rejectArg(new DeviceCommunicationError(messageArg)); responseArg.destroy(); };
+          if (responseArg.rawHeaders.length > 128 || responseArg.headers['content-encoding'] && responseArg.headers['content-encoding'] !== 'identity') { fail('Shelly returned unsupported response headers.'); return; }
+          const status = responseArg.statusCode ?? 0;
+          if (status === 200 && !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(responseArg.headers['content-type'] ?? '')) { fail('Shelly returned unsupported response content.'); return; }
+          const chunks: Buffer[] = [];
+          let size = 0;
+          responseArg.on('data', (chunkArg: unknown) => {
+            if (!Buffer.isBuffer(chunkArg)) { fail('Shelly returned invalid response bytes.'); return; }
+            size += chunkArg.length;
+            if (size > this.#config.maxResponseBytes) { fail('Shelly response exceeds the size limit.'); return; }
+            chunks.push(chunkArg);
+          });
+          responseArg.once('error', () => rejectArg(new DeviceCommunicationError('Shelly response transport failed.')));
+          responseArg.once('end', () => {
+            if (!responseArg.complete) { fail('Shelly response was truncated.'); return; }
+            try { resolveArg({ status, challenge: responseArg.headers['www-authenticate'], body: new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)) }); }
+            catch { fail('Shelly returned invalid UTF-8.'); }
+          });
+        });
+        this.#requests.add(request);
+        this.#drains.add(requestDrain);
+        request.once('close', () => { this.#requests.delete(request!); this.#drains.delete(requestDrain); resolveRequestClose(); });
+        request.once('error', () => rejectArg(new DeviceCommunicationError('Shelly request transport failed.')));
+        request.once('socket', (socketArg) => {
+          this.#sockets.add(socketArg);
+          socketDrain = new Promise<void>((resolveArg) => socketArg.once('close', () => { this.#sockets.delete(socketArg); this.#drains.delete(socketDrain); resolveArg(); }));
+          this.#drains.add(socketDrain);
+          if (this.#closed || operationArg.signal.aborted) socketArg.destroy();
+        });
+        try { this.active(operationArg); if (effectArg) operationArg.dispatched = true; request.end(payload); }
+        catch (errorArg) { request.destroy(); rejectArg(errorArg); }
+      });
+    } catch (errorArg) { failure = errorArg; request?.destroy(); }
+    finally {
+      if (request) await Promise.allSettled([requestDrain, socketDrain]);
+      operationArg.signal.removeEventListener('abort', abort);
     }
-    return globalThis.fetch(new URL(pathArg, this.endpoint), { method: methodArg, headers, body: bodyArg ? JSON.stringify(bodyArg) : undefined, signal: signalArg, redirect: 'error' });
+    this.active(operationArg);
+    if (failure !== undefined) throw failure;
+    if (!result) throw new DeviceCommunicationError('Shelly request failed.');
+    return result;
   }
-
-  private assertActive(abortSignalArg?: AbortSignal): void {
-    if (this.destroyed) throw new Error('Shelly client has been destroyed.');
-    if (this.lifetimeSignal.aborted || abortSignalArg?.aborted) throw new DOMException('Shelly operation cancelled.', 'AbortError');
+  private run<TResult>(workArg: (operationArg: IShellyOperation) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    try {
+      this.assertOpen();
+      if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Shelly cancellation requires an AbortSignal.');
+      if (signalArg?.aborted) throw new DOMException('Shelly operation cancelled.', 'AbortError');
+      const retainedCredentials = [...this.#credentialOperations.values()].filter((entryArg) => !this.#tasks.has(entryArg)).length;
+      if (this.#tasks.size + retainedCredentials + this.#credentialFailures.size >= this.#config.maxPendingOperations) throw new ShellyOperationError('Shelly operation capacity reached.');
+    } catch (errorArg) { return Promise.reject(errorArg); }
+    const controller = new AbortController();
+    const operation: IShellyOperation = { signal: AbortSignal.any([controller.signal, this.#lifetime.signal]), deadline: performance.now() + this.#config.requestTimeoutMs, dispatched: false, acknowledged: false };
+    const cancel = (): void => controller.abort(new DOMException('Shelly operation cancelled.', 'AbortError'));
+    signalArg?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(() => controller.abort(new DeviceCommunicationError('Shelly request timed out.')), this.#config.requestTimeoutMs);
+    let rejectCancelled: () => void = () => {};
+    const cancellation = new Promise<never>((_resolveArg, rejectArg) => {
+      rejectCancelled = () => { try { this.active(operation); } catch (errorArg) { rejectArg(this.operationError(errorArg, operation)); } };
+      operation.signal.addEventListener('abort', rejectCancelled, { once: true });
+    });
+    const task = this.#tail.then(async () => {
+      this.active(operation);
+      try { return await workArg(operation); }
+      catch (errorArg) { this.#healthy = false; throw this.operationError(errorArg, operation); }
+      finally { operation.password = undefined; }
+    });
+    this.#tasks.add(task);
+    operation.task = task;
+    this.#tail = task.then(() => undefined, () => undefined);
+    const settled = (): void => { this.#tasks.delete(task); clearTimeout(timer); signalArg?.removeEventListener('abort', cancel); operation.signal.removeEventListener('abort', rejectCancelled); };
+    void task.then(settled, settled);
+    if (signalArg?.aborted) cancel();
+    return Promise.race([task, cancellation]);
+  }
+  private operationError(errorArg: unknown, operationArg: IShellyOperation): Error {
+    if (operationArg.dispatched) return new ShellyOperationError('Shelly control outcome is indeterminate.', 'indeterminate', operationArg.acknowledged);
+    return errorArg instanceof AuthenticationError || errorArg instanceof DeviceCommunicationError || errorArg instanceof ShellyOperationError || errorArg instanceof DOMException && errorArg.name === 'AbortError' ? errorArg : new ShellyOperationError('Shelly operation failed.');
+  }
+  private active(operationArg: IShellyOperation): void {
+    if (operationArg.signal.aborted) throw operationArg.signal.reason;
+    this.assertOpen();
+    if (performance.now() >= operationArg.deadline) throw new DeviceCommunicationError('Shelly request timed out.');
+  }
+  private assertOpen(): void {
+    if (this.#context.abortSignal?.aborted) throw new DOMException('Shelly operation cancelled.', 'AbortError');
+    if (this.#closed) throw new Error('Shelly client has been destroyed.');
   }
 }