mqtt-plus 1.4.8 → 1.4.9

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 ChangeLog
 =========
 
+1.4.9 (2026-02-22)
+------------------
+
+- BUGFIX: clear internal response handlers in destroy()
+- BUGFIX: correctly decrement counter in subscription handling
+- BUGFIX: let the registration's destroy() throw errors correctly
+- BUGFIX: correctly handle synchronous response handler failures
+- BUGFIX: fix internal chunkToBuffer() method for byte-length calculation
+- BUGFIX: apply the same limits on sender size for authenticate() as on receiver side
+- BUGFIX: check for name/topic mismatches also in source fetch()
+- REFACTOR: factor out topic subscription and spooling topic unsubscription into helper function
+- REFACTOR: make response handlers async functions to correctly catch their failures
+- IMPROVEMENT: use a cached TextEncoder in utility functions
+- IMPROVEMENT: ensure generated NanoIDs do not conflict with pending requests
+
 1.4.8 (2026-02-22)
 ------------------
 

package/dst-stage1/mqtt-plus-auth.js

@@ -27,6 +27,8 @@ import { jwtVerify } from "jose/jwt/verify";
 import * as pbkdf2 from "@stablelib/pbkdf2";
 import * as sha256 from "@stablelib/sha256";
 import { MetaTrait } from "./mqtt-plus-meta";
+/*  reusable encoder instance  */
+const textEncoder = new TextEncoder();
 /*  authentication trait  */
 export class AuthTrait extends MetaTrait {
     constructor() {
@@ -41,8 +43,8 @@ export class AuthTrait extends MetaTrait {
         if (credential.length === 0)
             throw new Error("credential must not be empty");
         /*  use a derived key with minimum length of 32 for JWT HS256  */
-        const pass = new TextEncoder().encode(credential);
-        const salt = new TextEncoder().encode("mqtt-plus");
+        const pass = textEncoder.encode(credential);
+        const salt = textEncoder.encode("mqtt-plus");
         this._credential = pbkdf2.deriveKey(sha256.SHA256, pass, salt, 600000, 32);
     }
     /*  issue client-side token on server-side  */
@@ -59,12 +61,19 @@ export class AuthTrait extends MetaTrait {
         return token;
     }
     authenticate(token, remove) {
-        if (token === undefined)
-            return this._tokens.size > 0 ? Array.from(this._tokens) : undefined;
+        if (token === undefined) {
+            const tokens = Array.from(this._tokens).filter((token) => token.length <= 8192).slice(0, 8);
+            return tokens.length > 0 ? tokens : undefined;
+        }
         else if (remove === true)
             this._tokens.delete(token);
-        else
+        else {
+            if (token.length > 8192)
+                throw new Error("token must not exceed 8192 characters");
+            if (!this._tokens.has(token) && this._tokens.size >= 8)
+                throw new Error("at most 8 tokens can be authenticated at once");
             this._tokens.add(token);
+        }
     }
     /*  validate client-side token on server-side  */
     async validateToken(token) {

package/dst-stage1/mqtt-plus-base.d.ts

@@ -2,7 +2,7 @@ import { MqttClient, type IClientSubscribeOptions, type IClientPublishOptions }
 import type { APISchema, Registration } from "./mqtt-plus-api";
 import type { APIOptions } from "./mqtt-plus-options";
 import { TraceTrait } from "./mqtt-plus-trace";
-import type { Spool } from "./mqtt-plus-error";
+import { Spool } from "./mqtt-plus-error";
 export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     private mqtt;
     private messageHandler;
@@ -11,6 +11,7 @@ export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTra
     constructor(mqtt: MqttClient | null, options?: Partial<APIOptions>);
     destroy(): Promise<void>;
     protected makeRegistration(spool: Spool, kind: string, name: string, key: string): Registration;
+    protected subscribeTopicAndSpool(spool: Spool, topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
     protected subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
     protected unsubscribeTopic(topic: string): Promise<void>;
     protected publishToTopic(topic: string, message: string | Uint8Array, options?: IClientPublishOptions): Promise<void>;

package/dst-stage1/mqtt-plus-base.js

@@ -22,7 +22,7 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { TraceTrait } from "./mqtt-plus-trace";
-import { ensureError } from "./mqtt-plus-error";
+import { run, ensureError } from "./mqtt-plus-error";
 import { PLazy } from "./mqtt-plus-util";
 /*  MQTTp Base class with shared infrastructure  */
 export class BaseTrait extends TraceTrait {
@@ -77,6 +77,8 @@ export class BaseTrait extends TraceTrait {
     async destroy() {
         this.log("info", "un-hooking from MQTT client");
         this.mqtt.off("message", this.messageHandler);
+        this.onRequest.clear();
+        this.onResponse.clear();
     }
     /*  create a registration for subsequent destruction  */
     makeRegistration(spool, kind, name, key) {
@@ -85,11 +87,18 @@ export class BaseTrait extends TraceTrait {
                 if (!this.onRequest.has(key))
                     throw new Error(`destroy: ${kind} "${name}" not registered`);
                 await spool.unroll(false)?.catch((err) => {
-                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
+                    const error = ensureError(err, `destroy: ${kind} "${name}" failed to cleanup`);
+                    this.error(error);
+                    throw error;
                 });
             }
         };
     }
+    /*  subscribe to an MQTT topic and spool the unsubscription  */
+    async subscribeTopicAndSpool(spool, topic, options = {}) {
+        await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscribeTopic(topic, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topic).catch(() => { }));
+    }
     /*  subscribe to an MQTT topic (Promise-based)  */
     async subscribeTopic(topic, options = {}) {
         this.log("info", `subscribing to MQTT topic "${topic}"`);
@@ -155,7 +164,7 @@ export class BaseTrait extends TraceTrait {
         });
     }
     /*  handle incoming MQTT message  */
-    _onMessage(topic, data, packet) {
+    _onMessage(topic, data, _packet) {
         /*  parse MQTT topic  */
         const topicMatch = this.options.topicMatch(topic);
         if (topicMatch === null)
@@ -188,7 +197,7 @@ export class BaseTrait extends TraceTrait {
             /*  dispatch request message  */
             const handler = this.onRequest.get(`${topicMatch.operation}:${message.name}`);
             if (handler !== undefined) {
-                Promise.resolve(handler(message, topicMatch.name)).catch((err) => {
+                Promise.resolve().then(() => handler(message, topicMatch.name)).catch((err) => {
                     this.error(ensureError(err, `dispatching request message from MQTT topic "${topic}" failed`));
                 });
             }
@@ -197,7 +206,7 @@ export class BaseTrait extends TraceTrait {
             /*  dispatch response message  */
             const handler = this.onResponse.get(`${topicMatch.operation}:${message.id}`);
             if (handler !== undefined) {
-                Promise.resolve(handler(message, topicMatch.name)).catch((err) => {
+                Promise.resolve().then(() => handler(message, topicMatch.name)).catch((err) => {
                     this.error(ensureError(err, `dispatching response message from MQTT topic "${topic}" failed`));
                 });
             }

package/dst-stage1/mqtt-plus-error.js

@@ -167,7 +167,7 @@ export function run(...args) {
     }
     else if (typeof args[0] === "string") {
         description = args[0];
-        if (args[1] instanceof Spool) {
+        if (args[1] instanceof Spool || (args[1] === undefined && typeof args[2] === "function")) {
             spool = args[1];
             action = args[2];
             oncatch = args[3];
@@ -182,7 +182,7 @@ export function run(...args) {
         }
     }
     else {
-        if (args[0] instanceof Spool) {
+        if (args[0] instanceof Spool || (args[0] === undefined && typeof args[1] === "function")) {
             spool = args[0];
             action = args[1];
             oncatch = args[2];

package/dst-stage1/mqtt-plus-event.js

@@ -23,7 +23,7 @@
 */
 import { nanoid } from "nanoid";
 import { AuthTrait } from "./mqtt-plus-auth";
-import { run, Spool, ensureError } from "./mqtt-plus-error";
+import { Spool, ensureError } from "./mqtt-plus-error";
 /*  Event Emission Trait  */
 export class EventTrait extends AuthTrait {
     async event(nameOrConfig, ...args) {
@@ -56,36 +56,37 @@ export class EventTrait extends AuthTrait {
         const topicB = this.options.topicMake(topicS, "event-emission");
         const topicD = this.options.topicMake(name, "event-emission", this.options.id);
         /*  remember the registration  */
-        this.onRequest.set(`event-emission:${name}`, (request, topicName) => {
+        this.onRequest.set(`event-emission:${name}`, async (request, topicName) => {
             /*  determine event information  */
             const senderId = request.sender;
+            if (senderId === undefined || senderId === "")
+                throw new Error("invalid request: missing sender");
             const params = request.params ?? [];
             /*  create information object  */
-            const info = { sender: senderId ?? "" };
+            const info = { sender: senderId };
             if (request.receiver)
                 info.receiver = request.receiver;
             if (request.meta)
                 info.meta = request.meta;
             /*  asynchronously execute handler  */
-            Promise.resolve().then(async () => {
+            try {
                 if (topicName !== request.name)
                     throw new Error(`event name mismatch (topic: "${topicName}", payload: "${request.name}")`);
                 if (auth)
                     info.authenticated = await this.authenticated(request.sender, request.auth, auth);
                 if (info.authenticated !== undefined && !info.authenticated)
                     throw new Error(`authentication on event "${name}" failed`);
-                return callback(...params, info);
-            }).catch((result) => {
+                await callback(...params, info);
+            }
+            catch (result) {
                 const error = ensureError(result);
                 this.error(error, `handler for event "${name}" failed`);
-            });
+            }
         });
         spool.roll(() => { this.onRequest.delete(`event-emission:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this.subscribeTopic(topicB, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this.subscribeTopic(topicD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicD).catch(() => { }));
+        await this.subscribeTopicAndSpool(spool, topicB, options);
+        await this.subscribeTopicAndSpool(spool, topicD, options);
         /*  provide a registration for subsequent destruction  */
         return this.makeRegistration(spool, "event", name, `event-emission:${name}`);
     }

package/dst-stage1/mqtt-plus-service.js

@@ -57,7 +57,7 @@ export class ServiceTrait extends EventTrait {
         const topicB = this.options.topicMake(topicS, "service-call-request");
         const topicD = this.options.topicMake(name, "service-call-request", this.options.id);
         /*  remember the registration  */
-        this.onRequest.set(`service-call-request:${name}`, (request, topicName) => {
+        this.onRequest.set(`service-call-request:${name}`, async (request, topicName) => {
             /*  determine request information  */
             const requestId = request.id;
             const senderId = request.sender;
@@ -70,38 +70,42 @@ export class ServiceTrait extends EventTrait {
                 info.receiver = request.receiver;
             if (request.meta)
                 info.meta = request.meta;
-            /*  asynchronously execute handler and send response  */
-            Promise.resolve().then(async () => {
+            /*  execute handler and send response  */
+            try {
                 if (topicName !== request.name)
                     throw new Error(`service name mismatch (topic: "${topicName}", payload: "${request.name}")`);
                 if (auth)
                     info.authenticated = await this.authenticated(senderId, request.auth, auth);
                 if (info.authenticated !== undefined && !info.authenticated)
                     throw new Error(`service "${name}" failed authentication`);
-                return callback(...params, info);
-            }).then((result) => {
+                const result = await callback(...params, info);
                 /*  create success response message  */
-                return this.msg.makeServiceCallResponse(requestId, result, undefined, this.options.id, senderId);
-            }, (result) => {
-                /*  create error response message  */
-                const error = ensureError(result);
-                this.error(error, `handler for service "${name}" failed`);
-                return this.msg.makeServiceCallResponse(requestId, undefined, error.message, this.options.id, senderId);
-            }).then((rpcResponse) => {
+                const rpcResponse = this.msg.makeServiceCallResponse(requestId, result, undefined, this.options.id, senderId);
                 /*  send response message  */
                 const encoded = this.codec.encode(rpcResponse);
                 const topic = this.options.topicMake(name, "service-call-response", senderId);
-                return this.publishToTopic(topic, encoded, { qos: options.qos ?? 2 });
-            }).catch((err) => {
-                this.error(err, `handler for service "${name}" failed`);
-            });
+                await this.publishToTopic(topic, encoded, { qos: options.qos ?? 2 });
+            }
+            catch (err) {
+                const error = ensureError(err);
+                /*  create error response message  */
+                this.error(error, `handler for service "${name}" failed`);
+                const rpcResponse = this.msg.makeServiceCallResponse(requestId, undefined, error.message, this.options.id, senderId);
+                /*  send response message  */
+                try {
+                    const encoded = this.codec.encode(rpcResponse);
+                    const topic = this.options.topicMake(name, "service-call-response", senderId);
+                    await this.publishToTopic(topic, encoded, { qos: options.qos ?? 2 });
+                }
+                catch (err2) {
+                    this.error(ensureError(err2), `handler for service "${name}" failed`);
+                }
+            }
         });
         spool.roll(() => { this.onRequest.delete(`service-call-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this.subscribeTopic(topicB, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this.subscribeTopic(topicD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicD).catch(() => { }));
+        await this.subscribeTopicAndSpool(spool, topicB, options);
+        await this.subscribeTopicAndSpool(spool, topicD, options);
         /*  provide a registration for subsequent destruction  */
         return this.makeRegistration(spool, "service", name, `service-call-request:${name}`);
     }
@@ -128,7 +132,9 @@ export class ServiceTrait extends EventTrait {
         /*  create a resource spool  */
         const spool = new Spool();
         /*  generate unique request id  */
-        const requestId = nanoid();
+        let requestId = nanoid();
+        while (this.onResponse.has(`service-call-response:${requestId}`))
+            requestId = nanoid();
         /*  subscribe to MQTT response topic  */
         const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id);
         await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));

package/dst-stage1/mqtt-plus-sink.js

@@ -77,7 +77,7 @@ export class SinkTrait extends SourceTrait {
         const topicReqD = this.options.topicMake(name, "sink-push-request", this.options.id);
         const topicChunkD = this.options.topicMake(name, "sink-push-chunk", this.options.id);
         /*  remember the registration  */
-        this.onRequest.set(`sink-push-request:${name}`, (request, topicName) => {
+        this.onRequest.set(`sink-push-request:${name}`, async (request, topicName) => {
             /*  determine information  */
             const requestId = request.id;
             const params = request.params ?? [];
@@ -100,7 +100,8 @@ export class SinkTrait extends SourceTrait {
             this.pushSpools.set(requestId, reqSpool);
             reqSpool.roll(() => { this.pushSpools.delete(requestId); });
             /*  check authentication and prepare stream  */
-            Promise.resolve().then(async () => {
+            let ackSent = false;
+            try {
                 if (topicName !== request.name)
                     throw new Error(`sink name mismatch (topic: "${topicName}", payload: "${request.name}")`);
                 let authenticated = undefined;
@@ -148,8 +149,12 @@ export class SinkTrait extends SourceTrait {
                 readable.once("error", () => reqSpool.unroll());
                 /*  register chunk dispatch callback  */
                 this.onResponse.set(`sink-push-chunk:${requestId}`, (chunkParsed, chunkTopicName) => {
-                    if (chunkTopicName !== chunkParsed.name)
-                        throw new Error(`sink name mismatch (topic: "${chunkTopicName}", payload: "${chunkParsed.name}")`);
+                    if (chunkTopicName !== chunkParsed.name) {
+                        const error = new Error(`sink name mismatch (topic: "${chunkTopicName}", payload: "${chunkParsed.name}")`);
+                        readable.destroy(error);
+                        reqSpool.unroll();
+                        return;
+                    }
                     if (chunkParsed.error !== undefined) {
                         readable.destroy(new Error(chunkParsed.error));
                         reqSpool.unroll();
@@ -187,27 +192,34 @@ export class SinkTrait extends SourceTrait {
                 makeMutuallyExclusiveFields(info, "stream", "buffer");
                 /*  send ack response  */
                 await sendResponse();
+                ackSent = true;
                 /*  call handler  */
-                return callback(...params, info);
-            }).catch(async (err) => {
+                return await callback(...params, info);
+            }
+            catch (err) {
+                const error = ensureError(err);
                 /*  cleanup resources  */
                 const stream = this.pushStreams.get(requestId);
                 if (stream !== undefined)
-                    stream.destroy(err);
+                    stream.destroy(error);
                 reqSpool.unroll();
-                /*  send error (nak response)  */
-                this.error(err);
-                await sendResponse(err.message).catch(() => { });
-            });
+                /*  send error as nak response or as error chunk  */
+                this.error(error);
+                if (ackSent) {
+                    const chunkTopic = this.options.topicMake(name, "sink-push-chunk", sender);
+                    const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error.message, true, this.options.id, sender);
+                    const message = this.codec.encode(chunkMsg);
+                    await this.publishToTopic(chunkTopic, message, { qos: options.qos ?? 2 }).catch(() => { });
+                }
+                else
+                    await sendResponse(error.message).catch(() => { });
+            }
         });
         spool.roll(() => { this.onRequest.delete(`sink-push-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this.subscribeTopic(topicReqB, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicReqB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this.subscribeTopic(topicReqD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicReqD).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicChunkD}"`, spool, () => this.subscribeTopic(topicChunkD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicChunkD).catch(() => { }));
+        await this.subscribeTopicAndSpool(spool, topicReqB, options);
+        await this.subscribeTopicAndSpool(spool, topicReqD, options);
+        await this.subscribeTopicAndSpool(spool, topicChunkD, options);
         /*  provide a registration for subsequent destruction  */
         return this.makeRegistration(spool, "sink", name, `sink-push-request:${name}`);
     }
@@ -240,7 +252,10 @@ export class SinkTrait extends SourceTrait {
         /*  create a resource spool  */
         const spool = new Spool();
         /*  generate unique request id  */
-        const requestId = nanoid();
+        let requestId = nanoid();
+        while (this.onResponse.has(`sink-push-response:${requestId}`)
+            || this.onResponse.has(`sink-push-credit:${requestId}`))
+            requestId = nanoid();
         /*  subscribe to response topic (for ack/nak)  */
         const responseTopic = this.options.topicMake(name, "sink-push-response", this.options.id);
         await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
@@ -331,11 +346,15 @@ export class SinkTrait extends SourceTrait {
                 await sendBufferAsChunks(data, this.options.chunkSize, sendChunk, creditGate, abortSignal);
         }
         catch (err) {
-            const error = ensureError(err).message;
-            const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver);
-            const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error, true, this.options.id, receiver);
-            const message = this.codec.encode(chunkMsg);
-            await this.publishToTopic(chunkTopic, message, { qos: 2, ...options }).catch(() => { });
+            /*  send error chunk only if receiver is known
+                (otherwise the sink already received the error via the nak response)  */
+            if (receiver !== undefined) {
+                const error = ensureError(err).message;
+                const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver);
+                const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error, true, this.options.id, receiver);
+                const message = this.codec.encode(chunkMsg);
+                await this.publishToTopic(chunkTopic, message, { qos: 2, ...options }).catch(() => { });
+            }
             throw err;
         }
         finally {

package/dst-stage1/mqtt-plus-source.js

@@ -73,7 +73,7 @@ export class SourceTrait extends ServiceTrait {
         const topicReqD = this.options.topicMake(name, "source-fetch-request", this.options.id);
         const topicCreditD = this.options.topicMake(name, "source-fetch-credit", this.options.id);
         /*  remember the registration  */
-        this.onRequest.set(`source-fetch-request:${name}`, (request, topicName) => {
+        this.onRequest.set(`source-fetch-request:${name}`, async (request, topicName) => {
             /*  determine information  */
             const requestId = request.id;
             const params = request.params ?? [];
@@ -125,15 +125,14 @@ export class SourceTrait extends ServiceTrait {
             }
             /*  call the handler callback  */
             let ackSent = false;
-            Promise.resolve().then(async () => {
+            try {
                 if (topicName !== request.name)
                     throw new Error(`source name mismatch (topic: "${topicName}", payload: "${request.name}")`);
                 if (auth)
                     info.authenticated = await this.authenticated(request.sender, request.auth, auth);
                 if (info.authenticated !== undefined && !info.authenticated)
                     throw new Error(`source "${name}" failed authentication`);
-                return callback(...params, info);
-            }).then(async () => {
+                await callback(...params, info);
                 /*  check for valid data source  */
                 if (!(info.stream instanceof Readable) && !(info.buffer instanceof Promise))
                     throw new Error("handler did not provide data via info.stream or info.buffer fields");
@@ -149,15 +148,17 @@ export class SourceTrait extends ServiceTrait {
                 else if (info.buffer instanceof Promise)
                     /*  handle Buffer result  */
                     await sendBufferAsChunks(await info.buffer, this.options.chunkSize, sendChunk, creditGate);
-            }).catch((err) => {
+            }
+            catch (err) {
                 /*  send error as nak response or as error chunk  */
                 const error = ensureError(err);
                 this.error(error, `handler for source "${name}" failed`);
                 if (ackSent)
-                    return sendChunk(undefined, error.message, true).catch(() => { });
+                    await sendChunk(undefined, error.message, true).catch(() => { });
                 else
-                    return sendResponse(error.message).catch(() => { });
-            }).finally(() => {
+                    await sendResponse(error.message).catch(() => { });
+            }
+            finally {
                 /*  cleanup resources  */
                 clearSourceTimeout();
                 if (creditGate) {
@@ -165,16 +166,13 @@ export class SourceTrait extends ServiceTrait {
                     this.sourceCreditGates.delete(requestId);
                 }
                 this.onResponse.delete(`source-fetch-credit:${requestId}`);
-            });
+            }
         });
         spool.roll(() => { this.onRequest.delete(`source-fetch-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this.subscribeTopic(topicReqB, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicReqB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this.subscribeTopic(topicReqD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicReqD).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicCreditD}"`, spool, () => this.subscribeTopic(topicCreditD, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topicCreditD).catch(() => { }));
+        await this.subscribeTopicAndSpool(spool, topicReqB, options);
+        await this.subscribeTopicAndSpool(spool, topicReqD, options);
+        await this.subscribeTopicAndSpool(spool, topicCreditD, options);
         /*  provide a registration for subsequent destruction  */
         return this.makeRegistration(spool, "source", name, `source-fetch-request:${name}`);
     }
@@ -201,7 +199,10 @@ export class SourceTrait extends ServiceTrait {
         /*  create a resource spool  */
         const spool = new Spool();
         /*  generate unique request id  */
-        const requestId = nanoid();
+        let requestId = nanoid();
+        while (this.onResponse.has(`source-fetch-response:${requestId}`)
+            || this.onResponse.has(`source-fetch-chunk:${requestId}`))
+            requestId = nanoid();
         /*  subscribe to response topic (for ack/nak) and chunk topic (for data)  */
         const responseTopic = this.options.topicMake(name, "source-fetch-response", this.options.id);
         const chunkTopic = this.options.topicMake(name, "source-fetch-chunk", this.options.id);
@@ -242,7 +243,7 @@ export class SourceTrait extends ServiceTrait {
         const metaP = new Promise((resolve) => {
             metaResolve = resolve;
         });
-        spool.roll(() => { metaResolve?.(undefined); });
+        spool.roll(() => { metaResolve(undefined); });
         /*  define timer  */
         const timerId = `source-fetch:${requestId}`;
         const refreshTimeout = () => {
@@ -259,9 +260,14 @@ export class SourceTrait extends ServiceTrait {
         stream.once("error", () => spool.unroll());
         /*  register response dispatch callback  */
         this.onResponse.set(`source-fetch-response:${requestId}`, (response) => {
+            if (response.name !== name) {
+                stream.destroy(new Error(`source name mismatch (expected "${name}", got "${response.name}")`));
+                spool.unroll();
+                return;
+            }
             if (response.sender)
                 serverId = response.sender;
-            metaResolve?.(response.meta);
+            metaResolve(response.meta);
             if (response.error) {
                 stream.destroy(new Error(response.error));
                 spool.unroll();
@@ -271,6 +277,11 @@ export class SourceTrait extends ServiceTrait {
         });
         /*  register chunk dispatch callback  */
         this.onResponse.set(`source-fetch-chunk:${requestId}`, (response) => {
+            if (response.name !== name) {
+                stream.destroy(new Error(`source name mismatch (expected "${name}", got "${response.name}")`));
+                spool.unroll();
+                return;
+            }
             if (response.sender)
                 serverId = response.sender;
             if (response.error) {

package/dst-stage1/mqtt-plus-subscription.js

@@ -44,7 +44,7 @@ class RefCountedSubscription {
     /*  decrement reference count for a topic  */
     decrementCount(topic) {
         const count = this.counts.get(topic);
-        if (count) {
+        if (count !== undefined) {
             if (count <= 1) {
                 this.counts.delete(topic);
                 return 0;
@@ -136,15 +136,25 @@ class RefCountedSubscription {
     /*  flush all pending linger timers and unsubscribe  */
     async flush() {
         /*  determine all topics with potentially active subscriptions  */
-        const topics = new Set([...this.counts.keys(), ...this.lingers.keys()]);
+        const topics = new Set([
+            ...this.counts.keys(),
+            ...this.lingers.keys(),
+            ...this.pending.keys(),
+            ...this.unsubbing.keys()
+        ]);
         /*  cancel all pending linger timers first (synchronously)  */
         for (const topic of this.lingers.keys())
             clearTimeout(this.lingers.get(topic));
         this.lingers.clear();
         this.counts.clear();
+        /*  wait for any in-flight subscribe/unsubscribe operations to settle first  */
+        await Promise.allSettled([...this.pending.values(), ...this.unsubbing.values()]);
         /*  then unsubscribe from all potentially active topics  */
         for (const topic of topics)
             await this.unsubscribeFn(topic).catch(() => { });
+        /*  clear remaining internal state  */
+        this.pending.clear();
+        this.unsubbing.clear();
     }
 }
 /*  Subscription trait with shared MQTT subscription management  */

package/dst-stage1/mqtt-plus-util.js

@@ -80,6 +80,8 @@ export class CreditGate {
             this.waiters.shift()(true);
     }
 }
+/*  reusable encoder instance  */
+const textEncoder = new TextEncoder();
 /*  concatenate elements of a Uint8Array array  */
 function uint8ArrayConcat(arrays) {
     const totalLength = arrays.reduce((acc, value) => acc + value.byteLength, 0);
@@ -95,11 +97,11 @@ function uint8ArrayConcat(arrays) {
 function chunkToBuffer(chunk) {
     let buffer;
     if (chunk instanceof Buffer)
-        buffer = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.length);
+        buffer = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
     else if (chunk instanceof Uint8Array)
         buffer = chunk;
     else if (typeof chunk === "string")
-        buffer = new TextEncoder().encode(chunk);
+        buffer = textEncoder.encode(chunk);
     else
         throw new Error("invalid chunk type: expected Buffer, Uint8Array, or string");
     return buffer;

package/dst-stage1/mqtt-plus-version.js

@@ -29,7 +29,7 @@ export const versionToNum = (str) => {
     const minor = parseInt(m[2], 10);
     if (minor > 99)
         throw new Error("invalid version string: minor version exceeds 99");
-    return parseInt(m[1], 10) + minor / 100;
+    return parseInt(m[1], 10) * 100 + minor;
 };
 export const VERSION = __VERSION__;
 /*  package version (numeric format)  */