mqtt-plus 1.4.8 → 1.4.10

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 ChangeLog
 =========
 
+1.4.10 (2026-03-01)
+-------------------
+
+- IMPROVEMENT: improve performance
+- IMPROVEMENT: improve typing and export more public API types
+- IMPROVEMENT: improve description
+- BUGFIX: fix error handling and destruction problems
+- BUGFIX: fix name of module
+- BUGFIX: do not make fields exclusive
+- UPDATE: upgrade NPM dependencies
+- CLEANUP: various code cleanups (simplification, formatting, comments, output polishing)
+- CLEANUP: cleanups for error handling
+
+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), `sending error response 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

@@ -39,7 +39,7 @@ export class SinkTrait extends SourceTrait {
     /*  destroy sink trait  */
     async destroy() {
         for (const stream of this.pushStreams.values())
-            stream.destroy();
+            stream.destroy(new Error("sink destroyed"));
         for (const spool of this.pushSpools.values())
             await spool.unroll();
         this.pushStreams.clear();
@@ -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,33 @@ 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) => {
+                await callback(...params, info);
+            }
+            catch (err) {
+                const error = ensureError(err, `handler for sink "${name}" failed`);
                 /*  cleanup resources  */
                 const stream = this.pushStreams.get(requestId);
                 if (stream !== undefined)
-                    stream.destroy(err);
-                reqSpool.unroll();
-                /*  send error (nak response)  */
-                this.error(err);
-                await sendResponse(err.message).catch(() => { });
-            });
+                    stream.destroy(error);
+                await reqSpool.unroll();
+                /*  send error as nak response or as mid-stream error response  */
+                this.error(error);
+                if (ackSent) {
+                    const responseMsg = this.msg.makeSinkPushResponse(requestId, name, error.message, this.options.id, sender);
+                    const message = this.codec.encode(responseMsg);
+                    await this.publishToTopic(responseTopic, 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 +251,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 }));
@@ -278,10 +292,6 @@ export class SinkTrait extends SourceTrait {
                     }
                 });
                 spool.roll(() => { this.onResponse.delete(`sink-push-response:${requestId}`); });
-                this.onResponse.set(`sink-push-credit:${requestId}`, (_response) => {
-                    refreshTimeout();
-                });
-                spool.roll(() => { this.onResponse.delete(`sink-push-credit:${requestId}`); });
                 /*  generate and send request message  */
                 const auth = this.authenticate();
                 const metaStore = this.metaStore(meta);
@@ -312,6 +322,7 @@ export class SinkTrait extends SourceTrait {
                     gate.replenish(response.credit);
                     refreshTimeout();
                 });
+                spool.roll(() => { this.onResponse.delete(`sink-push-credit:${requestId}`); });
             }
             /*  generate corresponding MQTT topic for chunks  */
             const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver);
@@ -331,11 +342,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 ?? [];
@@ -96,9 +96,13 @@ export class SourceTrait extends ServiceTrait {
                 const message = this.codec.encode(response);
                 await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 });
             };
+            /*  define abort controller and signal  */
+            const abortController = new AbortController();
+            const abortSignal = abortController.signal;
             /*  utility functions for timeout management  */
             const sourceTimerId = `source-fetch-send:${requestId}`;
             const refreshSourceTimeout = () => this.timerRefresh(sourceTimerId, () => {
+                abortController.abort(new Error(`source fetch "${name}" timed out`));
                 const gate = this.sourceCreditGates.get(requestId);
                 if (gate !== undefined)
                     gate.abort();
@@ -112,28 +116,29 @@ export class SourceTrait extends ServiceTrait {
                 const message = this.codec.encode(chunkMsg);
                 await this.publishToTopic(chunkTopic, message, { qos: options.qos ?? 2 });
             };
-            /*  handle credit-based flow control (if credit provided in request)  */
-            const initialCredit = request.credit;
-            const creditGate = (initialCredit !== undefined && initialCredit > 0)
-                ? new CreditGate(initialCredit) : undefined;
-            if (creditGate) {
-                this.sourceCreditGates.set(requestId, creditGate);
-                this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed) => {
-                    creditGate.replenish(creditParsed.credit);
-                    refreshSourceTimeout();
-                });
-            }
             /*  call the handler callback  */
             let ackSent = false;
-            Promise.resolve().then(async () => {
+            let creditGate;
+            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 () => {
+                /*  handle credit-based flow control (if credit provided in request)  */
+                const initialCredit = request.credit;
+                creditGate = (initialCredit !== undefined && initialCredit > 0)
+                    ? new CreditGate(initialCredit) : undefined;
+                if (creditGate) {
+                    const gate = creditGate;
+                    this.sourceCreditGates.set(requestId, gate);
+                    this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed) => {
+                        gate.replenish(creditParsed.credit);
+                        refreshSourceTimeout();
+                    });
+                }
+                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");
@@ -145,19 +150,24 @@ export class SourceTrait extends ServiceTrait {
                 /*  dispatch according to data type  */
                 if (info.stream instanceof Readable)
                     /*  handle Readable stream result  */
-                    await sendStreamAsChunks(info.stream, this.options.chunkSize, sendChunk, creditGate);
+                    await sendStreamAsChunks(info.stream, this.options.chunkSize, sendChunk, creditGate, abortSignal);
                 else if (info.buffer instanceof Promise)
                     /*  handle Buffer result  */
-                    await sendBufferAsChunks(await info.buffer, this.options.chunkSize, sendChunk, creditGate);
-            }).catch((err) => {
+                    await sendBufferAsChunks(await info.buffer, this.options.chunkSize, sendChunk, creditGate, abortSignal);
+            }
+            catch (err) {
+                /*  cleanup stream resource (if provided by handler)  */
+                const error = ensureError(err, `handler for source "${name}" failed`);
+                if (info.stream instanceof Readable && !info.stream.destroyed)
+                    info.stream.destroy(error);
                 /*  send error as nak response or as error chunk  */
-                const error = ensureError(err);
-                this.error(error, `handler for source "${name}" failed`);
+                this.error(error);
                 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 +175,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 +208,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);
@@ -232,6 +242,7 @@ export class SourceTrait extends ServiceTrait {
                     this.publishToTopic(creditTopic, encoded, { qos: options.qos ?? 2 }).catch((err) => {
                         this.error(err, `sending credit for fetch "${name}" failed`);
                     });
+                    refreshTimeout();
                 }
             }
         });
@@ -242,7 +253,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,18 +270,29 @@ 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);
             if (response.error) {
                 stream.destroy(new Error(response.error));
                 spool.unroll();
             }
-            else
+            else {
+                metaResolve(response.meta);
                 refreshTimeout();
+            }
         });
         /*  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) {