@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/mqtt/mqtt.classes.client.ts

@@ -1,437 +1,465 @@
 import * as plugins from '../../plugins.js';
-import type { IMqttConfig, IMqttMessage, IMqttPayload, IMqttPublishOptions, IMqttSnapshot } from './mqtt.types.js';
 import { MqttMapper } from './mqtt.mapper.js';
-
-const packetConnect = 1;
-const packetConnack = 2;
-const packetPublish = 3;
-const packetPuback = 4;
-const packetSubscribe = 8;
-const packetSuback = 9;
-const packetPingreq = 12;
-const packetPingresp = 13;
-const packetDisconnect = 14;
-const defaultDiscoveryPrefix = 'homeassistant';
+import type { IMqttConfig, IMqttConnectionState, IMqttMessage, IMqttPublishOptions, IMqttSnapshot } from './mqtt.types.js';
 
 type TMqttMessageHandler = (messageArg: IMqttMessage) => void;
+type TMqttStateHandler = (stateArg: IMqttConnectionState) => void;
 
-interface IPendingPacket {
-  resolve(valueArg?: unknown): void;
-  reject(errorArg: Error): void;
-  timer: ReturnType<typeof setTimeout>;
+interface IMqttSubscription {
+  topic: string;
+  handler?: TMqttMessageHandler;
 }
 
-export class MqttClient {
-  private connection?: MqttTcpConnection;
-  private readonly receivedMessages: IMqttMessage[] = [];
-  private readonly messageHandlers = new Set<TMqttMessageHandler>();
-  private started = false;
-
-  constructor(private readonly config: IMqttConfig) {}
-
-  public async getSnapshot(): Promise<IMqttSnapshot> {
-    if (this.config.host && !this.started) {
-      await this.start();
-    }
-    return MqttMapper.toSnapshot(this.config, Boolean(this.connection?.connected), this.receivedMessages);
+export const mqttTopicMatches = (filterArg: string, topicArg: string): boolean => {
+  if (topicArg.startsWith('$') && !filterArg.startsWith('$')) return false;
+  const filter = filterArg.split('/');
+  const topic = topicArg.split('/');
+  for (let index = 0; index < filter.length; index++) {
+    if (filter[index] === '#') return index === filter.length - 1;
+    if (index >= topic.length || (filter[index] !== '+' && filter[index] !== topic[index])) return false;
   }
+  return filter.length === topic.length;
+};
 
-  public async start(): Promise<void> {
-    if (this.started || !this.config.host) {
-      this.started = true;
-      return;
-    }
-    const connection = new MqttTcpConnection(this.config, (messageArg) => this.handleMessage(messageArg));
-    await connection.connect();
-    this.connection = connection;
-    this.started = true;
-
-    if (this.config.birthMessage !== false) {
-      const birth = this.config.birthMessage || { topic: `${this.config.discoveryPrefix || defaultDiscoveryPrefix}/status`, payload: 'online', qos: 0, retain: false };
-      await this.publish(birth);
-    }
+export const validateMqttTopic = (topicArg: string, filterArg = false): void => {
+  if (typeof topicArg !== 'string' || !topicArg || Buffer.byteLength(topicArg) > 65535 || topicArg.includes('\u0000')) {
+    throw new Error('MQTT topic must be a non-empty UTF-8 string of at most 65535 bytes.');
+  }
+  const levels = topicArg.split('/');
+  if (levels.some((levelArg, indexArg) =>
+    levelArg.includes('+') && (!filterArg || levelArg !== '+') ||
+    levelArg.includes('#') && (!filterArg || levelArg !== '#' || indexArg !== levels.length - 1)
+  )) throw new Error('MQTT topic has an invalid wildcard.');
+};
 
-    const subscriptions = new Set(this.config.subscriptions || []);
-    if (this.config.discovery !== false) {
-      subscriptions.add(`${this.config.discoveryPrefix || defaultDiscoveryPrefix}/#`);
-    }
-    for (const topic of subscriptions) {
-      await this.subscribe(topic);
-    }
+export class MqttClient {
+  private client?: plugins.mqtt.MqttClient;
+  private startPromise?: Promise<void>;
+  private destroyPromise?: Promise<void>;
+  private cleanupPromise = Promise.resolve();
+  private destroyed = false;
+  private ready = false;
+  private hasStarted = false;
+  private generation = 0;
+  private readonly subscriptions = new Set<IMqttSubscription>();
+  private readonly messageHandlers = new Set<TMqttMessageHandler>();
+  private readonly stateHandlers = new Set<TMqttStateHandler>();
+  private readonly messages = new Map<string, IMqttMessage>();
+  private readonly persistentTopics = new Set<string>();
+  private readonly brokerTopics = new Set<string>();
+  private readonly pendingOperations = new Set<(errorArg: Error) => void>();
+  private topicSync?: Promise<void>;
+  private topicSyncRequested = false;
+  private bufferedBytes = 0;
+  private readonly connectTimeoutMs: number;
+  private readonly operationTimeoutMs: number;
+  private readonly maxMessageTopics: number;
+  private readonly maxPayloadBytes: number;
+  private readonly maxBufferedBytes: number;
+
+  constructor(private readonly config: IMqttConfig) {
+    this.config = structuredClone(config);
+    this.connectTimeoutMs = this.integerOption(config.connectTimeoutMs, 7000, 1, 2147483647);
+    this.operationTimeoutMs = this.integerOption(config.operationTimeoutMs, 7000, 1, 2147483647);
+    this.maxMessageTopics = this.integerOption(config.maxMessageTopics, 4096, 1, 100000);
+    this.maxPayloadBytes = this.integerOption(config.maxPayloadBytes, 262144, 1, 16777216);
+    this.maxBufferedBytes = this.integerOption(config.maxBufferedBytes, 8388608, 1, 1073741824);
+    this.integerOption(config.port, config.protocol === 'mqtts' ? 8883 : 1883, 1, 65535);
+    this.integerOption(config.keepalive, 60, 0, 65535);
+    this.integerOption(config.reconnectPeriodMs, 1000, 0, 2147483647);
+    if (config.protocol !== undefined && config.protocol !== 'mqtt' && config.protocol !== 'mqtts') throw new Error('Unsupported MQTT transport protocol.');
+    if (config.clean === false && !config.clientId) throw new Error('MQTT persistent sessions require an explicit clientId.');
+    for (const topic of config.subscriptions || []) {
+      validateMqttTopic(topic, true);
+      this.persistentTopics.add(topic);
+    }
+    if (config.discovery !== false) {
+      const prefix = config.discoveryPrefix || 'homeassistant';
+      validateMqttTopic(prefix);
+      this.persistentTopics.add(prefix + '/#');
+    }
+    for (const message of [...(config.retainedMessages || []), ...(config.discoveryMessages || [])]) this.storeMessage(message);
   }
 
-  public async publish(optionsArg: IMqttPublishOptions): Promise<void> {
-    await this.ensureConnection();
-    await this.connection?.publish(optionsArg);
+  public get connected(): boolean {
+    return this.ready && this.client?.connected === true && !this.destroyed;
   }
 
-  public async subscribe(topicArg: string, handlerArg?: TMqttMessageHandler): Promise<() => Promise<void>> {
-    if (handlerArg) {
-      this.messageHandlers.add(handlerArg);
-    }
-    await this.ensureConnection();
-    await this.connection?.subscribe(topicArg);
-    return async () => {
-      if (handlerArg) {
-        this.messageHandlers.delete(handlerArg);
-      }
-    };
+  public isHealthy(): boolean {
+    return this.connected;
   }
 
-  public async destroy(): Promise<void> {
-    if (this.config.birthMessage !== false && this.connection?.connected) {
-      await this.publish({ topic: `${this.config.discoveryPrefix || defaultDiscoveryPrefix}/status`, payload: 'offline', qos: 0, retain: false });
-    }
-    this.connection?.destroy();
-    this.connection = undefined;
-    this.started = false;
-    this.messageHandlers.clear();
+  public onConnectionState(handlerArg: TMqttStateHandler): () => void {
+    this.stateHandlers.add(handlerArg);
+    return () => { this.stateHandlers.delete(handlerArg); };
   }
 
-  private async ensureConnection(): Promise<void> {
-    if (!this.connection?.connected) {
-      await this.start();
-    }
-    if (!this.connection?.connected) {
-      throw new Error('MQTT broker connection is not available.');
-    }
+  public onMessage(handlerArg: TMqttMessageHandler): () => void {
+    this.messageHandlers.add(handlerArg);
+    return () => { this.messageHandlers.delete(handlerArg); };
   }
 
-  private handleMessage(messageArg: IMqttMessage): void {
-    this.receivedMessages.push(messageArg);
-    for (const handler of this.messageHandlers) {
-      handler(messageArg);
-    }
+  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<IMqttSnapshot> {
+    if (this.destroyed) throw new Error('MQTT client has been destroyed.');
+    if (this.config.host && !this.client && !this.hasStarted) await this.start(abortSignalArg);
+    this.throwIfAborted(abortSignalArg);
+    return MqttMapper.toSnapshot({ ...this.config, retainedMessages: [], discoveryMessages: [] }, this.connected, [...this.messages.values()]);
   }
-}
 
-class MqttTcpConnection {
-  private socket?: plugins.net.Socket;
-  private buffer = Buffer.alloc(0);
-  private nextPacketId = 1;
-  private pingTimer?: ReturnType<typeof setInterval>;
-  private connectPending?: IPendingPacket;
-  private readonly pendingPackets = new Map<number, IPendingPacket>();
-  private readonly subscriptions = new Set<string>();
-  public connected = false;
-
-  constructor(private readonly config: IMqttConfig, private readonly messageHandler: TMqttMessageHandler) {}
-
-  public async connect(): Promise<void> {
-    if (this.connected) {
-      return;
-    }
+  public async start(abortSignalArg?: AbortSignal): Promise<void> {
+    this.throwIfAborted(abortSignalArg);
+    if (this.destroyed) throw new Error('MQTT client has been destroyed.');
+    this.hasStarted = true;
+    if (this.connected) return;
     if (!this.config.host) {
-      throw new Error('MQTT host is required when fixture data is not provided.');
+      if (this.messages.size || this.config.entities?.length) return;
+      throw new Error('MQTT broker host is required.');
+    }
+    await this.cleanupPromise;
+    this.throwIfAborted(abortSignalArg);
+    if (this.destroyed) throw new Error('MQTT client has been destroyed.');
+    if (!this.startPromise) {
+      const promise = this.startConnection();
+      this.startPromise = promise;
+      void promise.finally(() => {
+        if (this.startPromise === promise) this.startPromise = undefined;
+      }).catch(() => {});
+    }
+    try {
+      await this.bounded(this.startPromise, this.connectTimeoutMs, abortSignalArg);
+    } catch (error) {
+      if (this.client) await this.failConnection(this.asError(error), this.client);
+      await this.cleanupPromise;
+      throw error;
     }
-    this.socket = await this.createSocket();
-    this.socket.on('data', (chunkArg) => this.handleData(chunkArg));
-    this.socket.on('error', (errorArg) => this.rejectAll(errorArg));
-    this.socket.on('close', () => {
-      this.connected = false;
-      this.rejectAll(new Error('MQTT socket closed.'));
-    });
-    await this.sendConnect();
-    const keepalive = this.config.keepalive || 60;
-    this.pingTimer = setInterval(() => {
-      if (this.connected) {
-        void this.writePacket(packetPingreq, Buffer.alloc(0));
-      }
-    }, Math.max(15, keepalive) * 1000);
   }
 
-  public async publish(optionsArg: IMqttPublishOptions): Promise<void> {
-    const topic = this.encodeString(optionsArg.topic);
+  public async publish(optionsArg: IMqttPublishOptions, abortSignalArg?: AbortSignal): Promise<void> {
+    this.validatePublish(optionsArg);
+    await this.start(abortSignalArg);
+    const client = this.requireClient();
     const payload = this.payloadBuffer(optionsArg.payload);
-    const qos = optionsArg.qos || 0;
-    if (qos !== 0) {
-      throw new Error('MQTT publish currently supports QoS 0.');
-    }
-    await this.writePacket(packetPublish, Buffer.concat([topic, payload]), optionsArg.retain ? 0x01 : 0);
+    let packetId: number | undefined;
+    const observePacket = (packetArg: plugins.mqtt.Packet): void => {
+      if (packetArg.cmd === 'publish' && packetArg.payload === payload) packetId = packetArg.messageId;
+    };
+    client.on('packetsend', observePacket);
+    try {
+      await this.bounded(client.publishAsync(optionsArg.topic, payload, {
+        qos: optionsArg.qos ?? 0, retain: optionsArg.retain ?? false,
+      }), this.operationTimeoutMs, abortSignalArg, () => {
+        if (packetId !== undefined && optionsArg.qos) client.removeOutgoingMessage(packetId);
+      });
+    } finally { client.removeListener('packetsend', observePacket); }
   }
 
-  public async subscribe(topicArg: string): Promise<void> {
-    if (this.subscriptions.has(topicArg)) {
-      return;
-    }
-    const packetId = this.nextId();
-    const variableHeader = Buffer.alloc(2);
-    variableHeader.writeUInt16BE(packetId, 0);
-    const payload = Buffer.concat([this.encodeString(topicArg), Buffer.from([0])]);
-    const promise = this.waitForPacket(packetId, `MQTT subscribe ${topicArg}`);
-    await this.writePacket(packetSubscribe, Buffer.concat([variableHeader, payload]), 0x02);
-    await promise;
-    this.subscriptions.add(topicArg);
-  }
-
-  public destroy(): void {
-    if (this.connected) {
-      void this.writePacket(packetDisconnect, Buffer.alloc(0));
-    }
-    if (this.pingTimer) {
-      clearInterval(this.pingTimer);
-      this.pingTimer = undefined;
-    }
-    this.rejectAll(new Error('MQTT connection destroyed.'));
-    this.socket?.destroy();
-    this.socket = undefined;
-    this.connected = false;
-  }
-
-  private async createSocket(): Promise<plugins.net.Socket> {
-    const port = this.config.port || (this.config.protocol === 'mqtts' ? 8883 : 1883);
-    if (this.config.protocol === 'mqtts') {
-      return new Promise<plugins.net.Socket>((resolve, reject) => {
-        const socket = plugins.tls.connect({
-          host: this.config.host,
-          port,
-          rejectUnauthorized: this.config.rejectUnauthorized !== false,
-          servername: this.config.host,
+  public async subscribe(topicArg: string, handlerArg?: TMqttMessageHandler, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    validateMqttTopic(topicArg, true);
+    this.throwIfAborted(abortSignalArg);
+    const subscription: IMqttSubscription = { topic: topicArg, handler: handlerArg };
+    this.subscriptions.add(subscription);
+    try {
+      await this.start(abortSignalArg);
+      await this.bounded(this.synchronizeTopics(), this.operationTimeoutMs, abortSignalArg);
+    } catch (error) {
+      this.subscriptions.delete(subscription);
+      throw error;
+    }
+    let released = false;
+    return async () => {
+      if (released) return;
+      released = true;
+      this.subscriptions.delete(subscription);
+      if (this.connected) await this.bounded(this.synchronizeTopics(), this.operationTimeoutMs);
+    };
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.destroyPromise) this.destroyPromise = this.destroyConnection();
+    return this.destroyPromise;
+  }
+
+  private async startConnection(): Promise<void> {
+    let client = this.client;
+    if (!client) {
+      const will = this.config.willMessage === false ? undefined : this.config.willMessage || this.defaultStatusMessage('offline');
+      if (will) this.validatePublish(will);
+      client = plugins.mqtt.connect({
+        host: this.config.host,
+        port: this.config.port ?? (this.config.protocol === 'mqtts' ? 8883 : 1883),
+        protocol: this.config.protocol || 'mqtt',
+        protocolVersion: 4,
+        clientId: this.config.clientId || 'shx-' + plugins.crypto.randomBytes(8).toString('hex'),
+        username: this.config.username, password: this.config.password,
+        clean: this.config.clean ?? true,
+        keepalive: this.config.keepalive ?? 60,
+        rejectUnauthorized: this.config.rejectUnauthorized !== false,
+        connectTimeout: this.connectTimeoutMs,
+        reconnectPeriod: this.config.reconnectPeriodMs ?? 1000,
+        queueQoSZero: false,
+        resubscribe: false,
+        will: will ? { topic: will.topic, payload: this.payloadBuffer(will.payload), qos: will.qos ?? 0, retain: will.retain ?? false } : undefined,
+      });
+      this.client = client;
+      const ownedClient = client;
+      client.on('connect', () => {
+        this.brokerTopics.clear();
+        const generation = ++this.generation;
+        void this.bounded(this.initializeConnection(ownedClient), this.operationTimeoutMs).then(() => {
+          if (this.client !== ownedClient || generation !== this.generation || !ownedClient.connected) return;
+          this.ready = true;
+          this.emitState({ connected: true });
+        }).catch((error: unknown) => {
+          if (generation === this.generation) void this.failConnection(this.asError(error), ownedClient);
         });
-        socket.once('secureConnect', () => resolve(socket));
-        socket.once('error', reject);
+      });
+      client.on('message', (topicArg, payloadArg, packetArg) => {
+        if (this.client !== ownedClient) return;
+        try {
+          this.handleMessage({ topic: topicArg, payload: payloadArg.toString('utf8'), qos: packetArg.qos, retain: packetArg.retain, timestamp: Date.now() });
+        } catch (error) { void this.failConnection(this.asError(error), ownedClient); }
+      });
+      client.on('error', (errorArg) => {
+        if (this.client === ownedClient) {
+          this.ready = false;
+          this.emitState({ connected: false, error: errorArg });
+        }
+      });
+      client.on('close', () => {
+        if (this.client !== ownedClient) return;
+        this.ready = false;
+        this.generation++;
+        this.brokerTopics.clear();
+        this.emitState({ connected: false });
       });
     }
-    return new Promise<plugins.net.Socket>((resolve, reject) => {
-      const socket = plugins.net.connect({ host: this.config.host, port });
-      socket.once('connect', () => resolve(socket));
-      socket.once('error', reject);
+    if (this.connected) return;
+    if (!client.connected && !client.reconnecting && client.stream.destroyed) client.reconnect();
+    await new Promise<void>((resolve, reject) => {
+      const rejectOperation = (errorArg: Error): void => {
+        remove();
+        this.pendingOperations.delete(rejectOperation);
+        reject(errorArg);
+      };
+      const remove = this.onConnectionState((stateArg) => {
+        if (stateArg.connected) {
+          remove();
+          this.pendingOperations.delete(rejectOperation);
+          resolve();
+        } else if (stateArg.error) rejectOperation(stateArg.error);
+      });
+      this.pendingOperations.add(rejectOperation);
+      if (this.connected) {
+        remove();
+        this.pendingOperations.delete(rejectOperation);
+        resolve();
+      }
     });
   }
 
-  private async sendConnect(): Promise<void> {
-    const keepalive = this.config.keepalive || 60;
-    const clientId = this.config.clientId || `smarthome-exchange-${plugins.crypto.randomBytes(4).toString('hex')}`;
-    const will = this.config.willMessage === false ? undefined : this.config.willMessage || { topic: `${this.config.discoveryPrefix || defaultDiscoveryPrefix}/status`, payload: 'offline', qos: 0, retain: false };
-    let flags = this.config.clean === false ? 0 : 0x02;
-    if (will) {
-      flags |= 0x04 | ((will.qos || 0) << 3);
-      if (will.retain) {
-        flags |= 0x20;
-      }
-    }
-    if (this.config.password) {
-      flags |= 0x40;
-    }
-    if (this.config.username) {
-      flags |= 0x80;
-    }
-    const variableHeader = Buffer.concat([
-      this.encodeString('MQTT'),
-      Buffer.from([4, flags]),
-      this.uint16(keepalive),
-    ]);
-    const payloadParts = [this.encodeString(clientId)];
-    if (will) {
-      payloadParts.push(this.encodeString(will.topic), this.payloadWithLength(will.payload));
-    }
-    if (this.config.username) {
-      payloadParts.push(this.encodeString(this.config.username));
-    }
-    if (this.config.password) {
-      payloadParts.push(this.encodeString(this.config.password));
+  private async initializeConnection(clientArg: plugins.mqtt.MqttClient): Promise<void> {
+    await this.synchronizeTopics();
+    if (this.config.birthMessage !== false) {
+      const birth = this.config.birthMessage || this.defaultStatusMessage('online');
+      this.validatePublish(birth);
+      await clientArg.publishAsync(birth.topic, this.payloadBuffer(birth.payload), { qos: birth.qos ?? 0, retain: birth.retain ?? false });
     }
-    const promise = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.connectPending = undefined;
-        reject(new Error('MQTT connect timed out.'));
-      }, 7000);
-      this.connectPending = { resolve: () => resolve(), reject, timer };
-    });
-    await this.writePacket(packetConnect, Buffer.concat([variableHeader, ...payloadParts]));
-    await promise;
   }
 
-  private handleData(chunkArg: Buffer | string): void {
-    const chunk = Buffer.isBuffer(chunkArg) ? chunkArg : Buffer.from(chunkArg);
-    this.buffer = Buffer.concat([this.buffer, chunk]);
-    while (this.buffer.length >= 2) {
-      const remainingLength = this.decodeRemainingLength(this.buffer, 1);
-      if (!remainingLength || this.buffer.length < 1 + remainingLength.bytes + remainingLength.value) {
-        return;
-      }
-      const header = this.buffer[0];
-      const payloadStart = 1 + remainingLength.bytes;
-      const payloadEnd = payloadStart + remainingLength.value;
-      const payload = this.buffer.subarray(payloadStart, payloadEnd);
-      this.buffer = this.buffer.subarray(payloadEnd);
-      this.handlePacket(header, payload);
+  private synchronizeTopics(): Promise<void> {
+    this.topicSyncRequested = true;
+    if (!this.topicSync) {
+      const client = this.client;
+      const generation = this.generation;
+      const next = this.bounded(this.performTopicSynchronization(), this.operationTimeoutMs);
+      this.topicSync = next;
+      void next.finally(() => {
+        if (this.topicSync === next) this.topicSync = undefined;
+      }).catch((error: unknown) => {
+        if (client && generation === this.generation) void this.failConnection(this.asError(error), client);
+      });
     }
+    return this.topicSync;
   }
 
-  private handlePacket(headerArg: number, payloadArg: Buffer): void {
-    const packetType = headerArg >> 4;
-    if (packetType === packetConnack) {
-      const returnCode = payloadArg[1];
-      const pending = this.connectPending;
-      this.connectPending = undefined;
-      if (!pending) {
-        return;
+  private async performTopicSynchronization(): Promise<void> {
+    do {
+      this.topicSyncRequested = false;
+      const client = this.client;
+      if (!client?.connected || this.destroyed) return;
+      const desired = new Set([...this.persistentTopics, ...[...this.subscriptions].map((subscriptionArg) => subscriptionArg.topic)]);
+      const snapshot = MqttMapper.toSnapshot({ ...this.config, retainedMessages: [], discoveryMessages: [] }, true, [...this.messages.values()]);
+      if (snapshot.entities.length > this.maxMessageTopics) throw new Error('MQTT entity limit exceeded.');
+      for (const entity of snapshot.entities) {
+        for (const topic of [entity.stateTopic, entity.availabilityTopic, entity.jsonAttributesTopic, ...(entity.availability || []).map((itemArg) => itemArg.topic)]) {
+          if (topic) { validateMqttTopic(topic); desired.add(topic); }
+        }
       }
-      clearTimeout(pending.timer);
-      if (returnCode === 0) {
-        this.connected = true;
-        pending.resolve();
-      } else {
-        pending.reject(new Error(`MQTT broker rejected connection with code ${returnCode}.`));
+      if (desired.size > this.maxMessageTopics) throw new Error('MQTT subscription limit exceeded.');
+      for (const topic of desired) {
+        if (this.brokerTopics.has(topic)) continue;
+        const grants = await client.subscribeAsync(topic, { qos: 2 });
+        if (grants.some((grantArg) => grantArg.qos === 128)) throw new Error('MQTT broker rejected subscription.');
+        if (this.client !== client || !client.connected) throw new Error('MQTT connection changed during subscription.');
+        this.brokerTopics.add(topic);
       }
-      return;
-    }
-    if (packetType === packetSuback) {
-      const packetId = payloadArg.readUInt16BE(0);
-      const pending = this.pendingPackets.get(packetId);
-      if (pending) {
-        clearTimeout(pending.timer);
-        this.pendingPackets.delete(packetId);
-        const failure = payloadArg.subarray(2).includes(0x80);
-        failure ? pending.reject(new Error(`MQTT subscribe ${packetId} was rejected.`)) : pending.resolve();
+      for (const topic of [...this.brokerTopics]) {
+        if (desired.has(topic)) continue;
+        await client.unsubscribeAsync(topic);
+        this.brokerTopics.delete(topic);
+        if (![...desired].some((filterArg) => mqttTopicMatches(filterArg, topic))) this.removeMessage(topic);
       }
-      return;
-    }
-    if (packetType === packetPublish) {
-      this.handlePublish(headerArg, payloadArg);
-      return;
+    } while (this.topicSyncRequested);
+  }
+
+  private handleMessage(messageArg: IMqttMessage): void {
+    this.storeMessage(messageArg);
+    if (this.config.discovery !== false && messageArg.topic.endsWith('/config') && mqttTopicMatches((this.config.discoveryPrefix || 'homeassistant') + '/#', messageArg.topic)) {
+      void this.synchronizeTopics();
     }
-    if (packetType === packetPingresp) {
-      return;
+    for (const subscription of this.subscriptions) {
+      if (subscription.handler && mqttTopicMatches(subscription.topic, messageArg.topic)) subscription.handler(messageArg);
     }
+    for (const handler of this.messageHandlers) handler(messageArg);
   }
 
-  private handlePublish(headerArg: number, payloadArg: Buffer): void {
-    const retain = Boolean(headerArg & 0x01);
-    const qos = ((headerArg >> 1) & 0x03) as 0 | 1 | 2;
-    const topicLength = payloadArg.readUInt16BE(0);
-    const topic = payloadArg.subarray(2, 2 + topicLength).toString('utf8');
-    let offset = 2 + topicLength;
-    if (qos > 0) {
-      const packetId = payloadArg.readUInt16BE(offset);
-      offset += 2;
-      if (qos === 1) {
-        void this.writePacket(packetPuback, this.uint16(packetId));
-      }
+  private storeMessage(messageArg: IMqttMessage): void {
+    validateMqttTopic(messageArg.topic);
+    const bytes = this.payloadBuffer(messageArg.payload).length + Buffer.byteLength(messageArg.topic);
+    const previous = this.messages.get(messageArg.topic);
+    const previousBytes = previous ? this.payloadBuffer(previous.payload).length + Buffer.byteLength(previous.topic) : 0;
+    if (this.payloadBuffer(messageArg.payload).length > this.maxPayloadBytes ||
+      !previous && this.messages.size >= this.maxMessageTopics ||
+      this.bufferedBytes - previousBytes + bytes > this.maxBufferedBytes) throw new Error('MQTT message snapshot limit exceeded.');
+    this.bufferedBytes += bytes - previousBytes;
+    this.messages.delete(messageArg.topic);
+    this.messages.set(messageArg.topic, structuredClone(messageArg));
+  }
+
+  private removeMessage(topicArg: string): void {
+    const message = this.messages.get(topicArg);
+    if (message) {
+      this.bufferedBytes -= this.payloadBuffer(message.payload).length + Buffer.byteLength(topicArg);
+      this.messages.delete(topicArg);
     }
-    const payload = payloadArg.subarray(offset).toString('utf8');
-    const subscribedTopic = [...this.subscriptions].find((topicArg) => this.topicMatches(topicArg, topic)) || topic;
-    this.messageHandler({ topic, payload, qos, retain, subscribedTopic, timestamp: Date.now() } as IMqttMessage & { subscribedTopic: string });
-  }
-
-  private waitForPacket(packetIdArg: number, descriptionArg: string): Promise<void> {
-    return new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingPackets.delete(packetIdArg);
-        reject(new Error(`${descriptionArg} timed out.`));
-      }, 7000);
-      this.pendingPackets.set(packetIdArg, { resolve: () => resolve(), reject, timer });
+  }
+
+  private async destroyConnection(): Promise<void> {
+    this.destroyed = true;
+    this.ready = false;
+    const client = this.client;
+    this.client = undefined;
+    this.rejectOperations(new Error('MQTT client has been destroyed.'));
+    this.emitState({ connected: false });
+    this.subscriptions.clear();
+    this.messageHandlers.clear();
+    this.stateHandlers.clear();
+    this.messages.clear();
+    this.bufferedBytes = 0;
+    this.brokerTopics.clear();
+    if (client) await this.closeClient(client);
+    await this.cleanupPromise;
+  }
+
+  private failConnection(errorArg: Error, clientArg: plugins.mqtt.MqttClient): Promise<void> {
+    if (this.client !== clientArg) return this.cleanupPromise;
+    this.ready = false;
+    this.generation++;
+    this.client = undefined;
+    this.brokerTopics.clear();
+    this.emitState({ connected: false, error: errorArg });
+    const cleanup = this.closeClient(clientArg);
+    this.cleanupPromise = cleanup;
+    void cleanup.then(() => this.rejectOperations(errorArg), (error: unknown) => {
+      this.rejectOperations(new AggregateError([errorArg, error], 'MQTT cancellation cleanup failed.'));
     });
+    return cleanup;
   }
 
-  private async writePacket(packetTypeArg: number, payloadArg: Buffer, flagsArg = 0): Promise<void> {
-    if (!this.socket || this.socket.destroyed) {
-      throw new Error('MQTT socket is not connected.');
-    }
-    const fixedHeader = Buffer.concat([Buffer.from([(packetTypeArg << 4) | flagsArg]), this.encodeRemainingLength(payloadArg.length)]);
-    const packet = Buffer.concat([fixedHeader, payloadArg]);
-    await new Promise<void>((resolve, reject) => {
-      this.socket?.write(packet, (errorArg) => errorArg ? reject(errorArg) : resolve());
+  private async closeClient(clientArg: plugins.mqtt.MqttClient): Promise<void> {
+    const closed = clientArg.stream.closed ? Promise.resolve() : new Promise<void>((resolve) => clientArg.once('close', resolve));
+    await clientArg.endAsync(true);
+    await closed;
+  }
+
+  private bounded<TValue>(promiseArg: Promise<TValue>, timeoutMsArg: number, abortSignalArg?: AbortSignal, cancelArg?: () => void): Promise<TValue> {
+    const ownedClient = this.client;
+    const generation = this.generation;
+    return new Promise<TValue>((resolve, reject) => {
+      let settled = false;
+      let cancelling = false;
+      const finish = (errorArg?: Error, valueArg?: TValue): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        abortSignalArg?.removeEventListener('abort', abort);
+        this.pendingOperations.delete(cancel);
+        if (errorArg) reject(errorArg); else resolve(valueArg as TValue);
+      };
+      const cancel = (errorArg: Error): void => { finish(errorArg); };
+      const stop = (errorArg: Error): void => {
+        if (settled || cancelling) return;
+        cancelling = true;
+        const client = this.client;
+        if (!client || client !== ownedClient || generation !== this.generation) cancelArg?.();
+        const cleanup = client && client === ownedClient && generation === this.generation ? this.failConnection(errorArg, client) : this.cleanupPromise;
+        void cleanup.then(() => finish(errorArg), (error: unknown) => finish(this.asError(error)));
+      };
+      const abort = (): void => { stop(this.abortError()); };
+      const timer = setTimeout(() => stop(new Error('MQTT operation timed out.')), timeoutMsArg);
+      this.pendingOperations.add(cancel);
+      abortSignalArg?.addEventListener('abort', abort, { once: true });
+      if (abortSignalArg?.aborted) abort();
+      void promiseArg.then((valueArg) => { if (!cancelling) finish(undefined, valueArg); }, (error: unknown) => { if (!cancelling) finish(this.asError(error)); });
     });
   }
 
-  private encodeRemainingLength(valueArg: number): Buffer {
-    const bytes: number[] = [];
-    let value = valueArg;
-    do {
-      let encodedByte = value % 128;
-      value = Math.floor(value / 128);
-      if (value > 0) {
-        encodedByte |= 128;
-      }
-      bytes.push(encodedByte);
-    } while (value > 0);
-    return Buffer.from(bytes);
-  }
-
-  private decodeRemainingLength(bufferArg: Buffer, offsetArg: number): { value: number; bytes: number } | undefined {
-    let multiplier = 1;
-    let value = 0;
-    let bytes = 0;
-    let offset = offsetArg;
-    while (offset < bufferArg.length) {
-      const encodedByte = bufferArg[offset++];
-      bytes++;
-      value += (encodedByte & 127) * multiplier;
-      if ((encodedByte & 128) === 0) {
-        return { value, bytes };
-      }
-      multiplier *= 128;
-      if (bytes > 4) {
-        throw new Error('Invalid MQTT remaining length.');
-      }
-    }
-    return undefined;
+  private rejectOperations(errorArg: Error): void {
+    for (const reject of [...this.pendingOperations]) reject(errorArg);
+    this.pendingOperations.clear();
   }
 
-  private payloadBuffer(payloadArg: IMqttPayload | undefined): Buffer {
-    if (payloadArg === undefined || payloadArg === null) {
-      return Buffer.alloc(0);
-    }
-    if (typeof payloadArg === 'object') {
-      return Buffer.from(JSON.stringify(payloadArg), 'utf8');
-    }
-    return Buffer.from(String(payloadArg), 'utf8');
+  private emitState(stateArg: IMqttConnectionState): void {
+    for (const handler of this.stateHandlers) handler(stateArg);
   }
 
-  private payloadWithLength(payloadArg: IMqttPayload | undefined): Buffer {
-    const payload = this.payloadBuffer(payloadArg);
-    return Buffer.concat([this.uint16(payload.length), payload]);
+  private requireClient(): plugins.mqtt.MqttClient {
+    if (!this.connected || !this.client) throw new Error('MQTT broker connection is not ready.');
+    return this.client;
   }
 
-  private encodeString(valueArg: string): Buffer {
-    const value = Buffer.from(valueArg, 'utf8');
-    return Buffer.concat([this.uint16(value.length), value]);
+  private defaultStatusMessage(payloadArg: string): IMqttPublishOptions {
+    return { topic: (this.config.discoveryPrefix || 'homeassistant') + '/status', payload: payloadArg, qos: 0, retain: false };
   }
 
-  private uint16(valueArg: number): Buffer {
-    const buffer = Buffer.alloc(2);
-    buffer.writeUInt16BE(valueArg, 0);
-    return buffer;
+  private validatePublish(optionsArg: IMqttPublishOptions): void {
+    validateMqttTopic(optionsArg.topic);
+    if (optionsArg.qos !== undefined && optionsArg.qos !== 0 && optionsArg.qos !== 1 && optionsArg.qos !== 2) throw new Error('MQTT QoS must be 0, 1, or 2.');
+    if (this.payloadBuffer(optionsArg.payload).length > this.maxPayloadBytes) throw new Error('MQTT payload limit exceeded.');
   }
 
-  private nextId(): number {
-    const id = this.nextPacketId++;
-    if (this.nextPacketId > 0xffff) {
-      this.nextPacketId = 1;
-    }
-    return id;
+  private payloadBuffer(payloadArg: IMqttPublishOptions['payload']): Buffer {
+    if (payloadArg === undefined || payloadArg === null) return Buffer.alloc(0);
+    return Buffer.from(typeof payloadArg === 'object' ? JSON.stringify(payloadArg) : String(payloadArg), 'utf8');
   }
 
-  private topicMatches(filterArg: string, topicArg: string): boolean {
-    const filterParts = filterArg.split('/');
-    const topicParts = topicArg.split('/');
-    for (let index = 0; index < filterParts.length; index++) {
-      const filterPart = filterParts[index];
-      if (filterPart === '#') {
-        return index === filterParts.length - 1;
-      }
-      if (filterPart === '+') {
-        continue;
-      }
-      if (filterPart !== topicParts[index]) {
-        return false;
-      }
-    }
-    return filterParts.length === topicParts.length;
+  private integerOption(valueArg: number | undefined, defaultArg: number, minArg: number, maxArg: number): number {
+    const value = valueArg ?? defaultArg;
+    if (!Number.isSafeInteger(value) || value < minArg || value > maxArg) throw new Error('MQTT numeric configuration is out of range.');
+    return value;
   }
 
-  private rejectAll(errorArg: Error): void {
-    if (this.connectPending) {
-      clearTimeout(this.connectPending.timer);
-      this.connectPending.reject(errorArg);
-      this.connectPending = undefined;
-    }
-    for (const [packetId, pending] of this.pendingPackets) {
-      clearTimeout(pending.timer);
-      pending.reject(errorArg);
-      this.pendingPackets.delete(packetId);
-    }
+  private throwIfAborted(abortSignalArg?: AbortSignal): void {
+    if (abortSignalArg?.aborted) throw this.abortError();
+  }
+
+  private abortError(): Error {
+    const error = new Error('MQTT operation aborted.');
+    error.name = 'AbortError';
+    return error;
+  }
+
+  private asError(valueArg: unknown): Error {
+    return valueArg instanceof Error ? valueArg : new Error(String(valueArg));
   }
 }