mqtt-plus 1.4.23 → 1.4.24

package/.ase/task/TASK-P18.md

@@ -0,0 +1,47 @@
+
+#   TASK P18: Guard pushInitial against unhandled rejection
+
+⎈   Created:  2026-07-07 00:01
+⚙   Modified: 2026-07-07 00:01
+
+##  CONTEXT
+
+-   **WHAT**: Add the missing rejection guard `pushInitial.catch(() => {})` in `push()` of `SinkTrait`
+    (`src/mqtt-plus-sink.ts:665-668`), mirroring the existing `pushFinalize` guard
+    (`src/mqtt-plus-sink.ts:637`).
+
+-   **WHY**: When publishing the push request fails (`src/mqtt-plus-sink.ts:795-796`), the `catch`
+    block aborts (`src/mqtt-plus-sink.ts:866`) and `onAbort` (`src/mqtt-plus-sink.ts:773-783`) calls
+    `pushInitialReject(error)` before `await pushInitial` (`src/mqtt-plus-sink.ts:797`) ever attached
+    a handler — an *unhandled promise rejection*, fatal by default in Node.js ≥ 15. The same hazard
+    exists for early rejections from the response/credit handlers while the publish is still pending.
+
+##  CHANGES
+
+-   **Guard**: Insert `pushInitial.catch(() => {})  /*  avoid unhandled promise rejection  */`
+    directly after the `pushInitial` promise creation, identical in style to the `pushFinalize`
+    guard and the three other existing guards in the code base. Unified diff preview:
+
+    ```diff
+    --- a/src/mqtt-plus-sink.ts
+    +++ b/src/mqtt-plus-sink.ts
+    @@ -665,6 +665,7 @@
+             const pushInitial        = new Promise<void>((resolve, reject) => {
+                 pushInitialResolve   = resolve
+                 pushInitialReject    = reject
+             })
+    +        pushInitial.catch(() => {})  /*  avoid unhandled promise rejection  */
+             this.onResponse.set(`sink-push-response:${requestId}`, (response: SinkPushResponse) => {
+    ```
+
+-   **Changelog**: Add a new `BUGFIX` bullet to the current `1.4.24` section of `CHANGELOG.md`,
+    aligned with its existing style: "BUGFIX: guard the sink push ack promise against an unhandled
+    promise rejection when publishing the push request fails".
+
+##  VERIFICATION
+
+-   **Regression**: Run `npm start build test` and require the complete unit test suite to pass.
+
+-   **Behavior**: `await pushInitial` (`src/mqtt-plus-sink.ts:797`) still observes rejections, since
+    `.catch()` only derives a separate guard promise; a failed request publish now surfaces solely
+    as the thrown `run()` error, without any unhandled promise rejection.

package/.ase/task/TASK-P2.md

@@ -0,0 +1,76 @@
+
+#   TASK P2: Route inbound sync throws through error event
+
+⎈   Created:  2026-07-06 13:40
+⚙   Modified: 2026-07-06 13:40
+
+##  CONTEXT
+
+-   **WHAT**: Guard the two unprotected *synchronous throw sites* on the inbound MQTT `message` path
+    in `src/mqtt-plus-base.ts`: replace `throw new Error("invalid codec configured")` in the
+    `message` handler (line 114) with `this.error(...)` plus early `return`, and wrap the
+    *user-supplied* `this.options.topicMatch(topic)` call in `_onMessage` (line 225) in
+    `try`/`catch` routed to `this.error(ensureError(...))`.
+
+-   **WHY**: Both exceptions currently escape the `EventEmitter` `message` listener into MQTT.js
+    packet handling and surface as *uncaught exceptions*, while `codec.decode` and `msg.parse`
+    failures are already routed through the MQTT+ `error` event (`src/mqtt-plus-base.ts:235-251`)
+    -- this restores a *consistent error contract* on the hot inbound path.
+
+##  CHANGES
+
+-   **Codec guard**: in the `BaseTrait` message handler (`src/mqtt-plus-base.ts:113-114`), replace
+    the `else` branch `throw new Error("invalid codec configured")` with
+    `this.error(new Error("invalid codec configured"))` followed by an early `return`.
+
+-   **Topic match guard**: in `_onMessage` (`src/mqtt-plus-base.ts:225`), change
+    `const topicMatch = this.options.topicMatch(topic)` to a `let` declaration assigned inside
+    `try`/`catch`, with the `catch` calling `this.error(ensureError(err, "failed to match MQTT
+    topic"))` and returning -- mirroring the existing `codec.decode`/`msg.parse` guards.
+
+-   **Diff preview**:
+    ```diff
+    --- src/mqtt-plus-base.ts
+    +++ src/mqtt-plus-base.ts
+    @@ constructor: messageHandler @@
+                 else if (this.options.codec === "cbor")
+                     input = Buffer.isBuffer(message)
+                         ? new Uint8Array(message.buffer, message.byteOffset, message.byteLength)
+                         : message
+    -            else
+    -                throw new Error("invalid codec configured")
+    +            else {
+    +                this.error(new Error("invalid codec configured"))
+    +                return
+    +            }
+                 this._onMessage(topic, input, packet)
+    @@ _onMessage: topic parsing @@
+             /*  parse MQTT topic  */
+    -        const topicMatch = this.options.topicMatch(topic)
+    +        let topicMatch
+    +        try {
+    +            topicMatch = this.options.topicMatch(topic)
+    +        }
+    +        catch (err: unknown) {
+    +            this.error(ensureError(err, "failed to match MQTT topic"))
+    +            return
+    +        }
+             if (topicMatch === null)
+                 return
+    ```
+
+-   **Test**: add a test to `tst/mqtt-plus-6-misc.spec.ts` asserting that a throwing user-supplied
+    `topicMatch` raises the MQTT+ `error` event on message reception instead of an uncaught
+    exception.
+
+-   **CHANGELOG**: add a `- BUGFIX: ...` entry to `CHANGELOG.md`, aligned with its existing style,
+    describing that synchronous errors of the inbound MQTT message handler are now routed through
+    the `error` event instead of escaping into MQTT.js.
+
+##  VERIFICATION
+
+-   **Regression suite**: run `npm start build test` and confirm the full unit test suite passes
+    against the automatically started MQTT broker.
+
+-   **Behavioral check**: confirm the new `topicMatch` test fails before the fix (uncaught
+    exception) and passes after it (error surfaces via the MQTT+ `error` event).

package/.ase/task/TASK-P21.md

@@ -0,0 +1,75 @@
+
+#   TASK P21: Abort in-flight fetches on destroy
+
+⎈   Created:  2026-07-06 21:42
+⚙   Modified: 2026-07-06 21:42
+
+##  CONTEXT
+
+-   **WHAT**: Track every in-flight `fetch()` in a new instance-level `SourceTrait` map `fetchAborts`
+    and abort all entries in `destroy()` through the existing per-fetch `endWithError` teardown path.
+
+-   **WHY**: `destroy()` cannot reach the fetcher-side closure state (`src/mqtt-plus-source.ts:457`),
+    so pending `fetch()` consumers hang forever on `stream`/`buffer`/`meta` (the timeout timer is
+    cleared and neutralized, the `onResponse` handlers are dropped); aborting settles all three with
+    *"instance destroyed"*, analogous to the service-caller `pendingCalls` pattern
+    (`src/mqtt-plus-service.ts:51-54`).
+
+##  CHANGES
+
+-   **State**: add `private fetchAborts = new Map<string, (error: Error) => void>()` as new
+    *fetch state* to `SourceTrait` (`src/mqtt-plus-source.ts`).
+
+-   **Destroy**: in `SourceTrait#destroy`, before the source-side cleanup, invoke every registered
+    abort handler with `new Error("instance destroyed")` and clear the map. `endWithError` sets
+    `streamEnded` (suppresses the cancel-credit publish), rejects `meta`, destroys the `ReadableTee`
+    (rejects `buffer`, errors `stream`) and triggers the spool unroll via the `close`/`error`
+    listeners.
+
+-   **Registration**: in `fetch()`, directly after the `endWithError` definition, register it via
+    `this.fetchAborts.set(requestId, endWithError)` and deregister via
+    `spool.roll(() => { this.fetchAborts.delete(requestId) })`, so every normal, error, or cancel
+    completion removes the entry.
+
+-   **CHANGELOG**: add entry `- BUGFIX: track in-flight fetch() operations and abort them on
+    destroy() so their stream/buffer/meta settle` to `CHANGELOG.md`, aligned with existing style.
+
+-   **Diff preview**:
+
+    ```diff
+    --- a/src/mqtt-plus-source.ts
+    +++ b/src/mqtt-plus-source.ts
+    @@ -50,8 +50,14 @@
+         private sourceSpools      = new Map<string, Spool>()
+         private sourceRequests    = new Map<string, Set<string>>()
+
+    +    /*  fetch state  */
+    +    private fetchAborts       = new Map<string, (error: Error) => void>()
+    +
+         /*  destroy source trait  */
+         override async destroy () {
+    +        for (const abort of this.fetchAborts.values())
+    +            abort(new Error("instance destroyed"))
+    +        this.fetchAborts.clear()
+             for (const controller of this.sourceControllers.values())
+                 controller.abort(new Error("source destroyed"))
+    @@ -562,6 +568,10 @@
+             const endWithError = (error: Error) => {
+                 streamEnded = true
+                 metaReject(error)
+                 stream.destroy(error)
+             }
+    +
+    +        /*  register abort handler at instance level (for destroy)  */
+    +        this.fetchAborts.set(requestId, endWithError)
+    +        spool.roll(() => { this.fetchAborts.delete(requestId) })
+    ```
+
+##  VERIFICATION
+
+-   **Unit test**: in `tst/mqtt-plus-5-source.spec.ts`, start a `fetch()` whose source never
+    responds, call `destroy()`, and expect `meta`/`buffer` to reject with *"instance destroyed"*
+    (and `stream` to emit the same error) well below the communication timeout.
+
+-   **Regression**: run `npm start build test` (lint-free build, full unit test suite against the
+    auto-started broker) and expect all existing source and fetch tests to still pass.

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsx *)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 ChangeLog
 =========
 
+1.4.24 (2026-07-06)
+-------------------
+
+- BUGFIX: isolate failing onfinally callbacks in run() so the spool is still unrolled and the original error is preserved
+- BUGFIX: destroy the sink push receive stream on push timeout so a receiver whose callback completed early no longer hangs at the stream drain and leaks per-request state
+- BUGFIX: register source request cleanup spool only after duplicate-request-id guard, so a duplicate request no longer corrupts the spool tracking of the in-flight original request
+- BUGFIX: guard the sink push ack promise against an unhandled promise rejection when publishing the push request fails
+- BUGFIX: reject requests instead of skipping authentication when the falsy-but-valid auth option value "" is used (event/service/source/sink traits)
+- BUGFIX: never linger the unsubscription of shared subscriptions ("$share/..."), as a lingering group member still receives and silently drops its round-robin share of messages and causes duplicate deliveries alongside overlapping non-shared subscriptions
+- BUGFIX: reject subscribeTopic() promise when the broker denies a subscription via SUBACK grant/reason codes >= 0x80 instead of silently resolving
+- BUGFIX: guard timer.unref() calls in sleep()/timeout() against browser runtimes where setTimeout() returns a plain number
+- BUGFIX: use distinct type brands per API marker type so endpoint kinds Event/Service/Source/Sink are discriminated nominally instead of structurally
+- BUGFIX: route synchronous errors of the inbound MQTT message handler through the "error" event instead of letting them escape into MQTT.js
+- BUGFIX: track in-flight fetch() operations and abort them on destroy() so their stream/buffer/meta settle
+- BUGFIX: encode Buffer values correctly with the JSON codec, as Buffer.prototype.toJSON runs before the JSON.stringify replacer
+- BUGFIX: register the oncatch recovery value with oncleanup on the spool in run() so fallback resources are disposed on unroll
+- BUGFIX: invoke the onfinally callback of run() only once when oncatch recovers but onfinally fails
+
 1.4.22 (2026-06-08)
 -------------------
 

package/README.md

@@ -176,22 +176,22 @@ Notice
 
 > [!Note]
 > **MQTT+** and its peer dependency **MQTT.js** provide a powerful
-> functionality, but are not small in size. **MQTT+** is 4.000 LoC
+> functionality, but are not small in size. **MQTT+** is 4,000 LoC
 > and 75 KB in size (ESM and CJS format). When bundled with all its
 > dependencies, it is 220 KB in size (UMD format). Its peer dependency
 > **MQTT.js** is 370 KB (ESM and CJS format) and 860 KB (UMD format) in
-> size. For a Node.js application, this usually doesn't matter. For a
+> size. For a Node.js application, this usually doesn't matter. For an
 > HTML5 SPA it matters more, but usually is still acceptable.
 
 > [!Note]
 > **MQTT+** is still somewhat similar to and originally derived from the weaker
 > [MQTT-JSON-RPC](https://github.com/rse/mqtt-json-rpc) library of the same
 > author. But instead of just JSON, MQTT+ encodes packets as JSON
-> or CBOR (default), uses an own packet format (allowing sender and
+> or CBOR (default), uses its own packet format (allowing sender and
 > receiver information), uses shorter NanoIDs instead of longer UUIDs
 > for identification of sender, receiver and requests, and additionally
 > provides source/sink transfer support (with fetch and push capabilities),
-> has an authentication mechanism, supports meta-data passing, and many more.
+> has an authentication mechanism, supports meta-data passing, and much more.
 
 License
 -------

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

@@ -1,15 +1,15 @@
-type Brand<T> = T & {
-    readonly __brand: unique symbol;
+type Brand<T, K extends string> = T & {
+    readonly __brand: K;
 };
 export type APIEndpoint = APIEndpointEvent | APIEndpointService | APIEndpointSource | APIEndpointSink;
 export type APIEndpointEvent = (...args: any[]) => void | Promise<void>;
 export type APIEndpointService = (...args: any[]) => any | Promise<any>;
 export type APIEndpointSource = (...args: any[]) => void | Promise<void>;
 export type APIEndpointSink = (...args: any[]) => void | Promise<void>;
-export type Event<T extends APIEndpointEvent> = Brand<T>;
-export type Service<T extends APIEndpointService> = Brand<T>;
-export type Source<T extends APIEndpointSource> = Brand<T>;
-export type Sink<T extends APIEndpointSink> = Brand<T>;
+export type Event<T extends APIEndpointEvent> = Brand<T, "event">;
+export type Service<T extends APIEndpointService> = Brand<T, "service">;
+export type Source<T extends APIEndpointSource> = Brand<T, "source">;
+export type Sink<T extends APIEndpointSink> = Brand<T, "sink">;
 export type APISchema = Record<string, APIEndpoint>;
 export type EventKeys<T> = string extends keyof T ? string : {
     [K in keyof T]: T[K] extends Event<infer _F> ? K : never;

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

@@ -84,8 +84,10 @@ export class BaseTrait extends TraceTrait {
                 input = Buffer.isBuffer(message)
                     ? new Uint8Array(message.buffer, message.byteOffset, message.byteLength)
                     : message;
-            else
-                throw new Error("invalid codec configured");
+            else {
+                this.error(new Error("invalid codec configured"));
+                return;
+            }
             this._onMessage(topic, input, packet);
         };
         this.mqtt.on("message", this.messageHandler);
@@ -118,11 +120,19 @@ export class BaseTrait extends TraceTrait {
     async subscribeTopic(topic, options = {}) {
         this.log("info", `subscribing to MQTT topic "${topic}"`);
         return new Promise((resolve, reject) => {
-            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err, _granted) => {
+            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err, granted) => {
                 if (err) {
                     this.error(err, `subscribing to MQTT topic "${topic}" failed`);
                     reject(err);
                 }
+                else if (Array.isArray(granted)
+                    && granted.some((grant) => typeof grant?.qos === "number" && grant.qos >= 0x80)) {
+                    /*  the broker rejected the subscription via SUBACK grant/reason code  */
+                    const error = new Error(`broker rejected subscription to MQTT topic "${topic}" ` +
+                        `(grant codes: ${granted.map((grant) => grant?.qos).join(", ")})`);
+                    this.error(error, `subscribing to MQTT topic "${topic}" failed`);
+                    reject(error);
+                }
                 else
                     resolve();
             });
@@ -183,7 +193,14 @@ export class BaseTrait extends TraceTrait {
         if (this.destroyed)
             return;
         /*  parse MQTT topic  */
-        const topicMatch = this.options.topicMatch(topic);
+        let topicMatch;
+        try {
+            topicMatch = this.options.topicMatch(topic);
+        }
+        catch (err) {
+            this.error(ensureError(err, "failed to match MQTT topic"));
+            return;
+        }
         if (topicMatch === null)
             return;
         /*  parse MQTT data into payload object  */

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

@@ -34,14 +34,23 @@ export class JSONX {
         return new Uint8Array(Buffer.from(base64, "base64"));
     }
     static stringify(obj) {
-        return JSON.stringify(obj, (_, value) => value instanceof Uint8Array
-            ? { __Uint8Array: this.uint8ArrayToBase64(value) }
-            : value);
+        return JSON.stringify(obj, function (key, value) {
+            /*  re-read the original value from the holder, as JSON.stringify
+                applies Buffer.prototype.toJSON before calling the replacer  */
+            const orig = this[key];
+            return orig instanceof Buffer
+                ? { __Buffer: JSONX.uint8ArrayToBase64(orig) }
+                : orig instanceof Uint8Array
+                    ? { __Uint8Array: JSONX.uint8ArrayToBase64(orig) }
+                    : value;
+        });
     }
     static parse(json) {
-        return JSON.parse(json, (_, value) => typeof value?.__Uint8Array === "string"
-            ? this.base64ToUint8Array(value.__Uint8Array)
-            : value);
+        return JSON.parse(json, (_, value) => typeof value?.__Buffer === "string"
+            ? Buffer.from(value.__Buffer, "base64")
+            : typeof value?.__Uint8Array === "string"
+                ? this.base64ToUint8Array(value.__Uint8Array)
+                : value);
     }
 }
 /*  the encoder/decoder abstraction  */

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

@@ -179,6 +179,38 @@ function runUnroll(isAsync, spool) {
         result = Promise.resolve(result);
     return result;
 }
+function runSettle(isAsync, pending, spool, onfinally, description) {
+    if (!isAsync) {
+        let failure;
+        try {
+            runFinally(false, onfinally, description);
+        }
+        catch (arg) {
+            failure = ensureError(arg, description);
+        }
+        if (pending || failure !== undefined) {
+            runUnroll(false, spool);
+            if (!pending && failure !== undefined)
+                throw failure;
+        }
+    }
+    else {
+        return (async () => {
+            let failure;
+            try {
+                await runFinally(true, onfinally, description);
+            }
+            catch (arg) {
+                failure = ensureError(arg, description);
+            }
+            if (pending || failure !== undefined) {
+                await runUnroll(true, spool);
+                if (!pending && failure !== undefined)
+                    throw failure;
+            }
+        })();
+    }
+}
 export function run(...args) {
     /*  support overloaded signatures  */
     let description;
@@ -243,50 +275,51 @@ export function run(...args) {
             }
             catch (arg) {
                 error = ensureError(arg, description);
-                runFinally(false, onfinally, description);
-                runUnroll(false, spool);
+                runSettle(false, true, spool, onfinally, description);
                 throw error;
             }
-            runFinally(false, onfinally, description);
+            if (spool && oncleanup)
+                spool.roll(result, oncleanup);
+            runSettle(false, false, spool, onfinally, description);
             return result;
         }
-        runFinally(false, onfinally, description);
-        runUnroll(false, spool);
+        runSettle(false, true, spool, onfinally, description);
         throw error;
     }
     if (result instanceof Promise) {
         /*  asynchronous case (result or error branch)  */
         return result.then(async (result) => {
-            await runFinally(true, onfinally, description);
             if (spool && oncleanup)
                 spool.roll(result, oncleanup);
+            await runSettle(true, false, spool, onfinally, description);
             return result;
         }, async (arg) => {
             /*  asynchronous case (error branch)  */
             let error = ensureError(arg, description);
             if (oncatch) {
+                let result;
                 try {
-                    const result = await oncatch(error);
-                    await runFinally(true, onfinally, description);
-                    return result;
+                    result = await oncatch(error);
                 }
                 catch (arg) {
                     error = ensureError(arg, description);
-                    await runFinally(true, onfinally, description);
-                    await runUnroll(true, spool);
+                    await runSettle(true, true, spool, onfinally, description);
                     throw error;
                 }
+                if (spool && oncleanup)
+                    spool.roll(result, oncleanup);
+                await runSettle(true, false, spool, onfinally, description);
+                return result;
             }
-            await runFinally(true, onfinally, description);
-            await runUnroll(true, spool);
+            await runSettle(true, true, spool, onfinally, description);
             throw error;
         });
     }
     else {
         /*  synchronous case (result branch)  */
-        runFinally(false, onfinally, description);
         if (spool && oncleanup)
             spool.roll(result, oncleanup);
+        runSettle(false, false, spool, onfinally, description);
         return result;
     }
 }

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

@@ -122,7 +122,7 @@ export class EventTrait extends AuthTrait {
                 info.meta = request.meta;
             /*  asynchronously execute handler  */
             try {
-                if (auth)
+                if (auth !== undefined)
                     info.authenticated = await this.authenticated(senderId, request.auth, auth, `event "${name}"`);
                 await callback(...params, info);
             }

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

@@ -138,7 +138,7 @@ export class ServiceTrait extends EventTrait {
             /*  execute handler and send response  */
             let removeAbortListener;
             try {
-                if (auth)
+                if (auth !== undefined)
                     info.authenticated = await this.authenticated(senderId, request.auth, auth, `service "${name}"`);
                 const abortPromise = new Promise((_resolve, reject) => {
                     const onAbort = () => {

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

@@ -172,7 +172,7 @@ export class SinkTrait extends SourceTrait {
                 if (topicName !== request.name)
                     throw new Error(`sink name mismatch (topic: "${topicName}", payload: "${request.name}")`);
                 let authenticated = undefined;
-                if (auth)
+                if (auth !== undefined)
                     authenticated = await this.authenticated(sender, request.auth, auth, `sink "${name}"`);
                 /*  initialize credit-based flow control state  */
                 const creditState = chunkCredit > 0 ? {
@@ -187,7 +187,14 @@ export class SinkTrait extends SourceTrait {
                 const refreshPushTimeout = () => this.timerRefresh(pushTimerId, () => {
                     if (streamEnded || this.destroying)
                         return;
-                    abortController.abort(new Error("push stream timeout"));
+                    const error = new Error("push stream timeout");
+                    abortController.abort(error);
+                    /*  destroy the push stream so that streamDone settles even when
+                        the callback already completed before the timeout fired  */
+                    streamEnded = true;
+                    const stream = this.pushStreams.get(requestId);
+                    if (stream !== undefined && !stream.destroyed)
+                        stream.destroy(error);
                     /*  eagerly notify sender so it stops publishing chunks
                         (suppress the spool-rollback cancel via errorResponseSent)  */
                     if (sender && !errorResponseSent) {
@@ -543,6 +550,7 @@ export class SinkTrait extends SourceTrait {
             pushInitialResolve = resolve;
             pushInitialReject = reject;
         });
+        pushInitial.catch(() => { }); /*  avoid unhandled promise rejection  */
         this.onResponse.set(`sink-push-response:${requestId}`, (response) => {
             if (response.name !== name) {
                 const error = new Error(`sink response name mismatch (expected "${name}", got "${response.name}")`);

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

@@ -9,6 +9,7 @@ export declare class SourceTrait<T extends APISchema = APISchema> extends Servic
     private sourceControllers;
     private sourceSpools;
     private sourceRequests;
+    private fetchAborts;
     destroy(): Promise<void>;
     source<K extends SourceKeys<T> & string>(name: K, callback: WithInfo<T[K], InfoSource>): Promise<Registration>;
     source<K extends SourceKeys<T> & string>(config: {

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

@@ -37,9 +37,14 @@ export class SourceTrait extends ServiceTrait {
         this.sourceControllers = new Map();
         this.sourceSpools = new Map();
         this.sourceRequests = new Map();
+        /*  fetch state  */
+        this.fetchAborts = new Map();
     }
     /*  destroy source trait  */
     async destroy() {
+        for (const abort of this.fetchAborts.values())
+            abort(new Error("instance destroyed"));
+        this.fetchAborts.clear();
         for (const controller of this.sourceControllers.values())
             controller.abort(new Error("source destroyed"));
         for (const gate of this.sourceCreditGates.values())
@@ -99,8 +104,6 @@ export class SourceTrait extends ServiceTrait {
             const receiver = request.receiver;
             /*  create a resource spool for request cleanup  */
             const reqSpool = new Spool();
-            this.sourceSpools.set(requestId, reqSpool);
-            reqSpool.roll(() => { this.sourceSpools.delete(requestId); });
             /*  sanity check sender  */
             if (sender === undefined || sender === "") {
                 this.error(new Error("invalid request: missing sender"));
@@ -129,6 +132,8 @@ export class SourceTrait extends ServiceTrait {
             }
             this.sourceControllers.set(requestId, abortController);
             reqSpool.roll(() => { this.sourceControllers.delete(requestId); });
+            this.sourceSpools.set(requestId, reqSpool);
+            reqSpool.roll(() => { this.sourceSpools.delete(requestId); });
             /*  provide info object  */
             const info = { sender, signal: abortSignal };
             if (receiver)
@@ -229,7 +234,7 @@ export class SourceTrait extends ServiceTrait {
                     this.onResponse.delete(`source-fetch-credit:${requestId}`);
                 });
                 /*  check for authentication  */
-                if (auth)
+                if (auth !== undefined)
                     info.authenticated = await this.authenticated(sender, request.auth, auth, `source "${name}"`);
                 /*  finally call the handler callback  */
                 const callbackPromise = Promise.resolve(callback(...params, info));
@@ -438,6 +443,9 @@ export class SourceTrait extends ServiceTrait {
             metaReject(error);
             stream.destroy(error);
         };
+        /*  register abort handler at instance level (for destroy)  */
+        this.fetchAborts.set(requestId, endWithError);
+        spool.roll(() => { this.fetchAborts.delete(requestId); });
         /*  ensure resources are released if consumer aborts stream early  */
         let cancelled = false;
         const cancelAndUnroll = (reason) => {

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

@@ -110,11 +110,16 @@ class RefCountedSubscription {
                 return pending;
         }
     }
-    /*  unsubscribe from a topic (reference-counted)  */
+    /*  unsubscribe from a topic (reference-counted)
+        NOTICE: shared subscriptions ("$share/...") are never lingered, as a
+        lingering group member would still receive its round-robin share of
+        the group's messages and silently drop them, and would additionally
+        cause duplicate deliveries once an overlapping non-shared
+        subscription is established on the same connection  */
     async unsubscribe(topic) {
         const count = this.decrementCount(topic);
         if (count === 0) {
-            if (this.lingerMs > 0) {
+            if (this.lingerMs > 0 && !topic.startsWith("$share/")) {
                 /*  defer the actual broker unsubscription  */
                 const timer = setTimeout(() => {
                     this.lingers.delete(topic);

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

@@ -76,7 +76,8 @@ export class TimerTrait extends SubscriptionTrait {
                     ac.abort();
                 resolve();
             }, durationMs);
-            timer.unref();
+            if (typeof timer.unref === "function")
+                timer.unref();
             if (signal !== undefined) {
                 if (ac !== undefined)
                     signal.addEventListener("abort", () => {
@@ -101,7 +102,8 @@ export class TimerTrait extends SubscriptionTrait {
                     ac.abort();
                 reject(new Error(info));
             }, durationMs);
-            timer.unref();
+            if (typeof timer.unref === "function")
+                timer.unref();
             if (signal !== undefined) {
                 if (ac !== undefined)
                     signal.addEventListener("abort", () => {