@tier0/sdk-v2 0.9.10 → 0.10.1

package/dist/cjs/mq/client.js

@@ -5,8 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tier0MQClient = void 0;
 const mqtt_1 = __importDefault(require("mqtt"));
+const platform_proxy_js_1 = require("../platform-proxy.js");
 const runtime_env_js_1 = require("../runtime-env.js");
 const broker_js_1 = require("./broker.js");
+const topic_js_1 = require("./topic.js");
+/** Design 21.6: backoff ceiling of a client that never gives up. */
+const RECONNECT_MAX_MS = 5 * 60_000;
+/** The first reconnect after a drop is spread over this window. */
+const FIRST_RECONNECT_MS = 500;
 function parseWorkspaceIDFromApiKey(apiKey) {
     // Match the backend's sk-<type>-ws<base36>_<secret> contract, not only
     // service keys. Other workspace-encoded keys use the same MQTT identity.
@@ -30,6 +36,16 @@ function generateRandomString(length = 8) {
     }
     return result;
 }
+function snapshotConfig(config) {
+    if (!config)
+        return undefined;
+    const snapshot = { ...config };
+    // Preserve an explicitly supplied non-enumerable password as well.
+    if (Object.hasOwn(config, 'password') && !Object.hasOwn(snapshot, 'password'))
+        snapshot.password = config.password;
+    return snapshot;
+}
+const CANCELLED_BY_DISCONNECT = 'MQTT connection cancelled by disconnect';
 class Tier0MQClient {
     client = null;
     config;
@@ -37,22 +53,44 @@ class Tier0MQClient {
     explicitUsername;
     listeners = {};
     subscriptions = [];
+    // One broker subscription (including its pending SUBACK) per topic.
+    topicSubscriptions = new Map();
+    pendingTopicPackets = new Map();
+    sentTopicPackets = new Map();
     connectingPromise = null;
+    rejectPendingConnect = null;
     _connected = false;
+    /** Bumped by disconnect(); callbacks of an older generation are ignored. */
+    generation = 0;
+    /** Random clientId segment; a persistent session is found again through it. */
+    clientSuffix = generateRandomString(16);
+    reconnectTimer = null;
+    reconnectAttempts = 0;
+    connectWaiters = [];
     constructor(config) {
+        config = snapshotConfig(config);
         this.explicitClientId = config?.clientId !== undefined;
         this.explicitUsername = config?.username !== undefined;
-        const envHost = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_HOST');
+        const envHost = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_URL') || (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_HOST');
         const envPort = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_PORT');
         const host = config?.host || envHost || '';
         const port = config?.port || parseInt(envPort || '8084') || 8084;
-        const password = config?.password || (0, runtime_env_js_1.getEnvVar)('TIER0_API_KEY') || '';
+        // An explicitly given password, even undefined, is never replaced by the environment key.
+        const explicitPassword = !!config && Object.hasOwn(config, 'password');
+        const password = explicitPassword
+            ? config.password
+            : (this.tokenSource() ? '' : (0, runtime_env_js_1.getEnvVar)('TIER0_API_KEY')) || '';
         // 从 apiKey 解析 workspaceID，自动生成 clientId 和 username
         const workspaceID = config?.clientId && config?.username
             ? undefined
-            : parseWorkspaceIDFromApiKey(password);
+            : parseWorkspaceIDFromApiKey(password ?? '');
+        // In an App's runtime the platform injects the App's key as TIER0_API_KEY: Backend accepts that hosted key
+        // only with clientId `<ws>&h.<app>.<random>` (app = TIER0_APP_ID). Any other key keeps `<ws>&<random>`.
+        const appId = (0, runtime_env_js_1.getEnvVar)('TIER0_APP_ID')?.trim();
+        const hosted = !explicitPassword && !!password && config?.clientId === undefined && config?.username === undefined &&
+            !!appId && topic_js_1.APP_SEGMENT.test(appId);
         const autoClientId = workspaceID
-            ? `${workspaceID}&${generateRandomString(8)}`
+            ? hosted ? `${workspaceID}&h.${appId}.${this.clientSuffix}` : `${workspaceID}&${generateRandomString(8)}`
             : undefined;
         const autoUsername = workspaceID
             ? `${workspaceID}&open`
@@ -66,12 +104,12 @@ class Tier0MQClient {
             keepAlive: config?.keepAlive ?? 60,
             reconnectPeriod: config?.reconnectPeriod ?? 5000,
             connectTimeout: config?.connectTimeout ?? 30000,
-            clean: config?.clean ?? true,
             ...config,
+            clean: config?.clean ?? false,
         };
     }
-    get mqttUrl() {
-        const { host, port, secure } = this.config;
+    mqttUrlFor(config) {
+        const { host, port, secure } = config;
         if (!host) {
             throw new Error('MQTT host is required. Provide it via MQTTConfig or TIER0_MQTT_HOST environment variable.');
         }
@@ -93,59 +131,234 @@ class Tier0MQClient {
         const useSecure = secure ?? ((0, broker_js_1.isBrowserHttps)() || effectivePort === broker_js_1.DEFAULT_WSS_PORT);
         return `${useSecure ? 'wss' : 'ws'}://${hostname}:${effectivePort}/mqtt`;
     }
-    // 内部确保已连接（懒连接）
-    async ensureConnected() {
+    /**
+     * Where the credential comes from; undefined when a fixed password is used.
+     * `proxy`: platform proxy mode, the node proxy puts in the App's key and
+     * the SDK sends none.
+     */
+    tokenSource(config = this.config) {
+        if (config?.password)
+            return undefined;
+        return (0, platform_proxy_js_1.platformProxyMode)() ? 'proxy' : undefined;
+    }
+    /** Local preflight before a transport exists: address and credentials must be usable. */
+    validateConnectionConfig(config) {
+        void this.connectionParams(config);
+    }
+    /**
+     * What the next connection presents. Through the node proxy the same
+     * identity reconnects, and the proxy puts in the App's current key.
+     */
+    connectionParams(config = this.config) {
+        if (this.tokenSource(config) === 'proxy') {
+            const identity = (0, platform_proxy_js_1.platformIdentity)();
+            if (!identity) {
+                throw new Error('Tier0 SDK v2: TIER0_WORKSPACE_ID and TIER0_APP_ID are required for MQTT in the platform.');
+            }
+            // Only `mqtt://` from the platform goes over TCP to the proxy; an explicit host means WebSocket.
+            const envUrl = (0, runtime_env_js_1.getEnvVar)('TIER0_MQTT_URL')?.trim();
+            const tcp = envUrl !== undefined && /^mqtt:\/\//i.test(envUrl) && config.host === envUrl;
+            // The proxy accepts only `<ws>&open` and `<ws>&h.<app>.<random>`, and puts the App's key in as the password.
+            return {
+                url: tcp ? envUrl : this.mqttUrlFor(config),
+                username: config.username ?? `${identity.ws}&open`,
+                clientId: config.clientId ?? `${identity.ws}&h.${identity.app}.${this.clientSuffix}`,
+            };
+        }
+        const { username, clientId, password } = config;
+        const url = this.mqttUrlFor(config);
+        if (!password || !username || !clientId) {
+            throw new Error('Tier0 SDK v2: provide a workspace-encoded API key or explicit MQTT username, clientId and password.');
+        }
+        return { url, username, clientId, password };
+    }
+    // 内部确保已连接（懒连接）。已有客户端时只等它重连，绝不另建：
+    // 同一 clientId 的新旧客户端会互相顶掉。
+    async ensureConnected(onTransportCreationFailure) {
         if (this._connected)
             return;
         if (this.connectingPromise)
             return this.connectingPromise;
-        void this.mqttUrl;
-        if (!this.config.password || !this.config.username || !this.config.clientId) {
-            throw new Error('Tier0 SDK v2: provide a workspace-encoded API key or explicit MQTT username, clientId and password.');
+        if (this.client) {
+            return new Promise((resolve, reject) => this.connectWaiters.push({ resolve, reject }));
         }
-        this.connectingPromise = this.doConnect();
-        return this.connectingPromise;
+        const pending = this.doConnect(this.connectionParams(), onTransportCreationFailure);
+        // mqtt.connect may throw synchronously before creating a client. Do not
+        // retain that already-failed attempt until the rejection microtask runs.
+        if (!this.client)
+            return pending;
+        this.connectingPromise = pending;
+        void pending.catch(() => {
+            if (this.connectingPromise === pending)
+                this.connectingPromise = null;
+        });
+        return pending;
+    }
+    clearReconnect() {
+        if (this.reconnectTimer !== null)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
     }
-    doConnect() {
+    reconnectDelay() {
+        const attempt = this.reconnectAttempts;
+        this.reconnectAttempts += 1;
+        if (attempt === 0)
+            return Math.random() * FIRST_RECONNECT_MS;
+        const base = this.config.reconnectPeriod ?? 5000;
+        const ceiling = Math.min(RECONNECT_MAX_MS, base * 2 ** (attempt - 1));
+        return ceiling / 2 + Math.random() * (ceiling / 2);
+    }
+    scheduleReconnect() {
+        if (!this.client || this._connected || this.reconnectTimer !== null)
+            return;
+        if (this.config.reconnectPeriod === 0)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.reconnect();
+        }, this.reconnectDelay());
+    }
+    /** The same client: mqtt.js keeps its session and offline queue. */
+    reconnect() {
+        const client = this.client;
+        if (!client || this._connected)
+            return;
+        let params;
+        try {
+            params = this.connectionParams();
+        }
+        catch (error) {
+            this.emit('error', error);
+            this.scheduleReconnect();
+            return;
+        }
+        client.options.username = params.username;
+        client.options.clientId = params.clientId;
+        if (params.password === undefined)
+            delete client.options.password;
+        else
+            client.options.password = params.password;
+        client.reconnect();
+    }
+    doConnect(params, onTransportCreationFailure) {
         return new Promise((resolve, reject) => {
+            const generation = this.generation;
+            this.rejectPendingConnect = reject;
             const options = {
-                clientId: this.config.clientId,
-                username: this.config.username,
-                password: this.config.password,
+                clientId: params.clientId,
+                username: params.username,
+                ...(params.password === undefined ? {} : { password: params.password }),
                 keepalive: this.config.keepAlive,
-                reconnectPeriod: this.config.reconnectPeriod,
+                // Reconnects are ours, with their own backoff.
+                reconnectPeriod: 0,
+                // Without it a refused CONNACK leaves the client disconnected for good.
+                reconnectOnConnackError: true,
                 connectTimeout: this.config.connectTimeout,
                 clean: this.config.clean,
+                // The SDK owns resubscription so every SUBACK reaches its callback.
+                resubscribe: false,
             };
-            this.client = mqtt_1.default.connect(this.mqttUrl, options);
-            this.client.on('connect', () => {
+            let client;
+            try {
+                client = mqtt_1.default.connect(params.url, options);
+            }
+            catch (err) {
+                this.rejectPendingConnect = null;
+                onTransportCreationFailure?.();
+                reject(err);
+                return;
+            }
+            this.client = client;
+            const current = () => this.client === client && this.generation === generation;
+            // mqtt.js 5.3 synthesizes the requested QoS if a malformed SUBACK has
+            // no grants, and can throw when it contains too many. Track wire packet
+            // ids so malformed acknowledgements never become apparent success.
+            client.on('packetsend', (packet) => {
+                if (!current() || packet.cmd !== 'subscribe' || packet.subscriptions.length !== 1)
+                    return;
+                const topic = packet.subscriptions[0]?.topic;
+                if (!topic || typeof packet.messageId !== 'number')
+                    return;
+                const queue = this.pendingTopicPackets.get(topic);
+                const attempt = queue?.shift();
+                if (queue?.length === 0)
+                    this.pendingTopicPackets.delete(topic);
+                if (attempt)
+                    this.sentTopicPackets.set(packet.messageId, attempt);
+            });
+            client.on('packetreceive', (packet) => {
+                if (!current() || packet.cmd !== 'suback' || typeof packet.messageId !== 'number')
+                    return;
+                const attempt = this.sentTopicPackets.get(packet.messageId);
+                this.sentTopicPackets.delete(packet.messageId);
+                if (!attempt)
+                    return;
+                if (!Array.isArray(packet.granted) || packet.granted.length !== 1 ||
+                    (packet.granted[0] !== 0 && packet.granted[0] !== 1)) {
+                    attempt.invalidSuback = true;
+                    // Keep old mqtt.js from indexing past its single requested topic.
+                    packet.granted = [128];
+                }
+            });
+            client.on('connect', () => {
+                if (!current())
+                    return;
                 this._connected = true;
+                this.clearTopicState();
+                for (const sub of this.subscriptions)
+                    sub.pendingConnect = false;
                 this.connectingPromise = null;
+                this.rejectPendingConnect = null;
+                this.clearReconnect();
+                this.reconnectAttempts = 0;
+                resolve();
                 this.emit('connect');
                 // 断连重连后自动恢复所有订阅
-                this.resubscribeAll();
-                resolve();
+                if (current())
+                    this.resubscribeAll();
+                const waiters = this.connectWaiters;
+                this.connectWaiters = [];
+                waiters.forEach((waiter) => waiter.resolve());
             });
-            this.client.on('error', (err) => {
-                this.emit('error', err);
+            client.on('error', (err) => {
+                if (!current())
+                    return;
+                // Remove failed pending subscriptions before an error listener can
+                // synchronously cause this same client to reconnect and resubscribe.
+                this.subscriptions = this.subscriptions.filter((sub) => !sub.pendingConnect);
                 this.connectingPromise = null;
+                this.rejectPendingConnect = null;
                 reject(err);
+                this.emit('error', err);
             });
-            this.client.on('disconnect', () => {
+            client.on('disconnect', () => {
+                if (!current())
+                    return;
                 this._connected = false;
+                this.clearTopicState();
                 this.emit('disconnect');
             });
-            this.client.on('close', () => {
+            client.on('close', () => {
+                if (!current())
+                    return;
                 this._connected = false;
+                this.clearTopicState();
+                this.scheduleReconnect();
             });
-            this.client.on('message', (topic, payload, _packet) => {
+            client.on('message', (topic, payload, _packet) => {
+                if (!current())
+                    return;
                 const payloadStr = payload.toString();
                 // 复制一份快照：handler 触发背压自动退订时会重建 this.subscriptions
                 this.subscriptions.slice().forEach((sub) => {
+                    if (!current() || !this.subscriptions.includes(sub))
+                        return;
                     if (this.topicMatch(sub.topic, topic)) {
                         try {
                             // 公开类型为 void 返回（兼容 async/简写 handler），运行时仅识别严格的 false
                             const accepted = sub.handler(topic, payloadStr);
+                            if (!current() || !this.subscriptions.includes(sub))
+                                return;
                             if (accepted === false) {
                                 sub.backpressuredCount = (sub.backpressuredCount ?? 0) + 1;
                                 const limit = this.config.maxBackpressuredDeliveries ?? 0;
@@ -162,7 +375,8 @@ class Tier0MQClient {
                             }
                         }
                         catch (e) {
-                            this.emit('error', e);
+                            if (current())
+                                this.emit('error', e);
                         }
                     }
                 });
@@ -171,25 +385,85 @@ class Tier0MQClient {
     }
     // 显式连接（需要等待连接完成时使用）
     async connect(config) {
-        if (config) {
-            const previousPassword = this.config.password;
-            this.config = { ...this.config, ...config };
-            if (config.clientId !== undefined)
-                this.explicitClientId = true;
-            if (config.username !== undefined)
-                this.explicitUsername = true;
+        const snapshot = snapshotConfig(config);
+        // An explicitly missing password must never reuse a previous or environment key.
+        if (snapshot && Object.hasOwn(snapshot, 'password') && snapshot.password === undefined) {
+            throw new TypeError('MQTT password was explicitly undefined; provide a credential or omit the password field.');
+        }
+        // Other undefined fields mean no override, not a request to erase settings.
+        const update = snapshot
+            ? Object.fromEntries(Object.entries(snapshot).filter(([, value]) => value !== undefined))
+            : undefined;
+        if (this.client || this.connectingPromise) {
+            // mqtt.js snapshots its connection options. Changing our config while a
+            // client exists (connecting, connected or reconnecting) would leave the
+            // old credentials in use, including on reconnect. Refuse the change
+            // before mutating anything.
+            const connectionFields = [
+                'host', 'port', 'secure', 'clientId', 'username', 'password',
+                'keepAlive', 'reconnectPeriod', 'connectTimeout', 'clean',
+            ];
+            if (update && connectionFields.some((field) => update[field] !== undefined && update[field] !== this.config[field])) {
+                throw new Error('MQTT connection settings cannot change while a client exists; disconnect and create a new client');
+            }
+            const generation = this.generation;
+            // A reconnecting client is waited for, never replaced: the SDK keeps reconnecting it.
+            await this.ensureConnected();
+            if (this.generation !== generation || !this.client || !this._connected) {
+                throw new Error('MQTT connection changed before connect completed');
+            }
+            if (update) {
+                this.config = { ...this.config, ...update };
+                if (update.clientId !== undefined)
+                    this.explicitClientId = true;
+                if (update.username !== undefined)
+                    this.explicitUsername = true;
+            }
+            return;
+        }
+        const previousConfig = this.config;
+        const previousExplicitClientId = this.explicitClientId;
+        const previousExplicitUsername = this.explicitUsername;
+        const candidate = update ? { ...previousConfig, ...update } : previousConfig;
+        const explicitClientId = previousExplicitClientId || update?.clientId !== undefined;
+        const explicitUsername = previousExplicitUsername || update?.username !== undefined;
+        if (update) {
+            const previousPassword = previousConfig.password;
             // A connect-time key may belong to a different workspace. Preserve only
             // caller-supplied identity fields, not values derived from the previous key.
-            if (config.password !== undefined && config.password !== previousPassword) {
-                const workspaceID = parseWorkspaceIDFromApiKey(config.password);
-                if (!this.explicitClientId) {
-                    this.config.clientId = workspaceID ? workspaceID + '&' + generateRandomString(8) : undefined;
+            if (update.password !== undefined && update.password !== previousPassword) {
+                const workspaceID = parseWorkspaceIDFromApiKey(update.password);
+                if (!explicitClientId) {
+                    candidate.clientId = workspaceID ? workspaceID + '&' + generateRandomString(8) : undefined;
                 }
-                if (!this.explicitUsername)
-                    this.config.username = workspaceID ? workspaceID + '&open' : undefined;
+                if (!explicitUsername)
+                    candidate.username = workspaceID ? workspaceID + '&open' : undefined;
+            }
+        }
+        this.validateConnectionConfig(candidate);
+        const generation = this.generation;
+        this.config = candidate;
+        this.explicitClientId = explicitClientId;
+        this.explicitUsername = explicitUsername;
+        const rollbackBeforeTransport = () => {
+            if (!this.client && this.generation === generation && this.config === candidate) {
+                this.config = previousConfig;
+                this.explicitClientId = previousExplicitClientId;
+                this.explicitUsername = previousExplicitUsername;
             }
+        };
+        try {
+            await this.ensureConnected(rollbackBeforeTransport);
+        }
+        catch (err) {
+            // If no transport was created, the attempted settings have no owner.
+            // Do not roll back a newer generation or another caller's settings.
+            rollbackBeforeTransport();
+            throw err;
+        }
+        if (this.generation !== generation || !this.client || !this._connected) {
+            throw new Error('MQTT connection changed before connect completed');
         }
-        return this.ensureConnected();
     }
     // 订阅 topic，内部 qos 固定为 1，handler 接收 (topic, payload)
     // 无需先调用 connect()，自动处理连接
@@ -199,20 +473,25 @@ class Tier0MQClient {
         if (exists) {
             return;
         }
-        this.subscriptions.push({ topic, handler });
+        // Only a subscription made before the first connection completes is
+        // undone when that connection fails. One made while the SDK reconnects
+        // an existing client is kept and restored after the reconnect.
+        const pendingConnect = !this._connected && (!this.client || this.connectingPromise !== null);
+        const sub = { topic, handler, pendingConnect };
+        this.subscriptions.push(sub);
+        const generation = this.generation;
         if (this._connected && this.client) {
-            this.client.subscribe(topic, { qos: 1 }, (err) => {
-                if (err) {
+            this.subscribeTopic(topic, this.client, generation);
+        }
+        else {
+            // 未连接时触发懒连接（已有客户端时等待它重连），连接成功后 resubscribeAll 会自动 subscribe
+            this.ensureConnected().catch((err) => {
+                if (this.generation === generation && this.subscriptions.includes(sub)) {
+                    this.subscriptions = this.subscriptions.filter((item) => item !== sub);
                     this.emit('error', err);
-                    // 订阅失败时回滚
-                    this.subscriptions = this.subscriptions.filter((s) => !(s.topic === topic && s.handler === handler));
                 }
             });
         }
-        else {
-            // 未连接时触发懒连接，连接成功后 resubscribeAll 会自动 subscribe
-            this.ensureConnected().catch((err) => this.emit('error', err));
-        }
     }
     // 取消订阅：如果提供了 handler 则仅移除该 handler，否则移除该 topic 下所有 handler
     unsubscribe(topic, handler) {
@@ -224,10 +503,15 @@ class Tier0MQClient {
         }
         if (!this.client)
             return;
+        const client = this.client;
+        const generation = this.generation;
         // 如果该 topic 下已无任何 handler，则向 broker 发送 unsubscribe
         const stillHasHandler = this.subscriptions.some((s) => s.topic === topic);
         if (!stillHasHandler) {
-            this.client.unsubscribe(topic, (err) => {
+            this.topicSubscriptions.delete(topic);
+            client.unsubscribe(topic, (err) => {
+                if (this.client !== client || this.generation !== generation)
+                    return;
                 if (err) {
                     this.emit('error', err);
                 }
@@ -236,23 +520,41 @@ class Tier0MQClient {
     }
     // 发布消息，无需先调用 connect()，内部自动处理连接
     async publish(topic, payload, options) {
-        await this.ensureConnected();
+        const generation = this.generation;
+        // A disconnected client queues the message and sends it after reconnecting.
+        if (!this.client)
+            await this.ensureConnected();
         const message = typeof payload === 'string' ? payload : JSON.stringify(payload);
-        this.client.publish(topic, message, {
-            qos: (options?.qos ?? 0),
-            retain: options?.retain ?? false,
-        });
+        const qos = (options?.qos ?? 0);
+        const retain = options?.retain ?? false;
+        const client = this.client;
+        if (this.generation !== generation || !client) {
+            throw new Error('MQTT connection changed before publish; message was not submitted');
+        }
+        client.publish(topic, message, { qos, retain });
     }
     disconnect() {
-        if (!this.client)
-            return;
-        this.client.end(true, () => {
-            this.emit('disconnect');
-        });
+        this.clearReconnect();
+        const generation = ++this.generation;
+        const client = this.client;
         this.client = null;
         this._connected = false;
         this.connectingPromise = null;
+        const rejectPendingConnect = this.rejectPendingConnect;
+        this.rejectPendingConnect = null;
+        const waiters = this.connectWaiters;
+        this.connectWaiters = [];
         this.subscriptions = [];
+        this.clearTopicState();
+        const cancelled = new Error(CANCELLED_BY_DISCONNECT);
+        rejectPendingConnect?.(cancelled);
+        waiters.forEach((waiter) => waiter.reject(cancelled));
+        if (!client)
+            return;
+        client.end(true, () => {
+            if (!this.client && this.generation === generation)
+                this.emit('disconnect');
+        });
     }
     on(event, handler) {
         if (!this.listeners[event]) {
@@ -279,14 +581,47 @@ class Tier0MQClient {
     resubscribeAll() {
         if (!this.client)
             return;
+        const client = this.client;
+        const generation = this.generation;
         // 按 topic 去重，每个 topic 只订阅一次
         const uniqueTopics = Array.from(new Set(this.subscriptions.map((s) => s.topic)));
-        uniqueTopics.forEach((topic) => {
-            this.client.subscribe(topic, { qos: 1 }, (err) => {
-                if (err) {
-                    this.emit('error', err);
-                }
-            });
+        uniqueTopics.forEach((topic) => this.subscribeTopic(topic, client, generation));
+    }
+    clearTopicState() {
+        this.topicSubscriptions.clear();
+        this.pendingTopicPackets.clear();
+        this.sentTopicPackets.clear();
+    }
+    subscribeTopic(topic, client, generation) {
+        if (this.client !== client || this.generation !== generation || !this._connected ||
+            this.topicSubscriptions.has(topic) || !this.subscriptions.some((sub) => sub.topic === topic))
+            return;
+        const attempt = {};
+        this.topicSubscriptions.set(topic, attempt);
+        const pending = this.pendingTopicPackets.get(topic) ?? [];
+        pending.push(attempt);
+        this.pendingTopicPackets.set(topic, pending);
+        client.subscribe(topic, { qos: 1 }, (err, granted) => {
+            const queue = this.pendingTopicPackets.get(topic);
+            if (queue) {
+                const index = queue.indexOf(attempt);
+                if (index >= 0)
+                    queue.splice(index, 1);
+                if (!queue.length)
+                    this.pendingTopicPackets.delete(topic);
+            }
+            if (this.client !== client || this.generation !== generation || this.topicSubscriptions.get(topic) !== attempt)
+                return;
+            // mqtt.js 5.3 reports SUBACK failure codes in granted with err=null.
+            // A QoS 1 request may only be granted QoS 0 or 1, for this one topic.
+            const accepted = Array.isArray(granted) && granted.length === 1 &&
+                granted[0]?.topic === topic && (granted[0]?.qos === 0 || granted[0]?.qos === 1);
+            if (err || attempt.invalidSuback || !accepted) {
+                this.topicSubscriptions.delete(topic);
+                // Every handler shares this broker subscription and its SUBACK.
+                this.subscriptions = this.subscriptions.filter((sub) => sub.topic !== topic);
+                this.emit('error', new Error(`MQTT subscription failed for topic ${topic}`, { cause: err ?? undefined }));
+            }
         });
     }
     // 判断接收到的 topic 是否匹配订阅的 topic（支持通配符 # 和 +）