mqtt-plus 1.4.22 → 1.4.24

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                           "mqtt-plus",
-    "version":                        "1.4.22",
+    "version":                        "1.4.24",
     "description":                    "MQTT Communication Patterns",
     "keywords":                       [   "mqtt",
                                           "event", "emit",

package/src/mqtt-plus-api.ts

@@ -23,7 +23,7 @@
 */
 
 /*  utility type for branding  */
-type Brand<T> = T & { readonly __brand: unique symbol }
+type Brand<T, K extends string> = T & { readonly __brand: K }
 
 /*  endpoint types  */
 export type APIEndpoint        = APIEndpointEvent | APIEndpointService | APIEndpointSource | APIEndpointSink
@@ -33,10 +33,10 @@ export type APIEndpointSource  = (...args: any[]) => void | Promise<void>
 export type APIEndpointSink    = (...args: any[]) => void | Promise<void>
 
 /*  API marker types  */
-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">
 
 /*  type utilities for generic API  */
 export type APISchema = Record<string, APIEndpoint>

package/src/mqtt-plus-base.ts

@@ -28,6 +28,7 @@ import { type MqttClient,
     type IClientSubscribeOptions,
     type IClientPublishOptions,
     type IPublishPacket }               from "mqtt"
+import { nanoid }                       from "nanoid"
 
 /*  internal requirements  */
 import type { APISchema, Registration } from "./mqtt-plus-api"
@@ -79,6 +80,19 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
         /*  store MQTT client  */
         this.mqtt = mqtt
 
+        /*  resolve the instance "id": if the user did not provide an
+            explicit one, fetch the "clientId" from the underlying MQTT
+            client, and only as a last resort fall back to a generated id
+            (e.g. for the fake proxy MQTT client without a real clientId)  */
+        if (this.options.id === "") {
+            const clientId = (mqtt as any).isFakeProxy
+                ? undefined
+                : mqtt.options?.clientId
+            this.options.id = (typeof clientId === "string" && clientId !== "")
+                ? clientId
+                : nanoid()
+        }
+
         /*  hook into the MQTT message processing  */
         this.log("info", "hooking into MQTT client")
         this.messageHandler = (topic, message, packet) => {
@@ -96,8 +110,10 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
                 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)
@@ -133,11 +149,19 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     protected async subscribeTopic (topic: string, options: Partial<IClientSubscribeOptions> = {}): Promise<void> {
         this.log("info", `subscribing to MQTT topic "${topic}"`)
         return new Promise<void>((resolve, reject) => {
-            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err: Error | null, _granted: any) => {
+            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err: Error | null, granted: any) => {
                 if (err) {
                     this.error(err, `subscribing to MQTT topic "${topic}" failed`)
                     reject(err)
                 }
+                else if (Array.isArray(granted)
+                    && granted.some((grant: any) => 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: any) => grant?.qos).join(", ")})`)
+                    this.error(error, `subscribing to MQTT topic "${topic}" failed`)
+                    reject(error)
+                }
                 else
                     resolve()
             })
@@ -208,7 +232,14 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
             return
 
         /*  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
 

package/src/mqtt-plus-codec.ts

@@ -39,17 +39,24 @@ export class JSONX {
         return new Uint8Array(Buffer.from(base64, "base64"))
     }
     static stringify (obj: unknown): string {
-        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: unknown = this[key]
+            return orig instanceof Buffer
+                ? { __Buffer:     JSONX.uint8ArrayToBase64(orig) }
+                : orig instanceof Uint8Array
+                    ? { __Uint8Array: JSONX.uint8ArrayToBase64(orig) }
+                    : value
+        })
     }
     static parse (json: string): unknown {
         return JSON.parse(json, (_, value) =>
-            typeof value?.__Uint8Array === "string"
-                ? this.base64ToUint8Array(value.__Uint8Array)
-                : value
+            typeof value?.__Buffer === "string"
+                ? Buffer.from(value.__Buffer, "base64")
+                : typeof value?.__Uint8Array === "string"
+                    ? this.base64ToUint8Array(value.__Uint8Array)
+                    : value
         )
     }
 }

package/src/mqtt-plus-error.ts

@@ -201,6 +201,43 @@ function runUnroll (isAsync: boolean, spool?: Spool): Promise<void> | void {
     return result
 }
 
+/*  helper function for settling the epilog of "run": run the finally
+    code isolated, unroll the spool, and preserve a pending error  */
+function runSettle (isAsync: false,   pending: boolean, spool?: Spool, onfinally?: () => void,                  description?: string): void
+function runSettle (isAsync: true,    pending: boolean, spool?: Spool, onfinally?: () => Promise<void> | void,  description?: string): Promise<void>
+function runSettle (isAsync: boolean, pending: boolean, spool?: Spool, onfinally?: () => Promise<void> | void,  description?: string): Promise<void> | void {
+    if (!isAsync) {
+        let failure: Error | undefined
+        try {
+            runFinally(false, onfinally as (() => void) | undefined, description)
+        }
+        catch (arg: unknown) {
+            failure = ensureError(arg, description)
+        }
+        if (pending || failure !== undefined) {
+            runUnroll(false, spool)
+            if (!pending && failure !== undefined)
+                throw failure
+        }
+    }
+    else {
+        return (async () => {
+            let failure: Error | undefined
+            try {
+                await runFinally(true, onfinally, description)
+            }
+            catch (arg: unknown) {
+                failure = ensureError(arg, description)
+            }
+            if (pending || failure !== undefined) {
+                await runUnroll(true, spool)
+                if (!pending && failure !== undefined)
+                    throw failure
+            }
+        })()
+    }
+}
+
 /*  helper type for ensuring T contains no Promise  */
 type RunNoPromise<T> =
     [ T ] extends [ Promise<any> ] ? never : T
@@ -350,50 +387,51 @@ export function run<T> (
             }
             catch (arg: unknown) {
                 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 as SpoolCleanup<unknown>)
+            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 as SpoolCleanup<unknown>)
+            await runSettle(true, false, spool, onfinally, description)
             return result
         }, async (arg: unknown) => {
             /*  asynchronous case (error branch)  */
             let error = ensureError(arg, description)
             if (oncatch) {
+                let result: T
                 try {
-                    const result = await oncatch(error)
-                    await runFinally(true, onfinally, description)
-                    return result
+                    result = await oncatch(error)
                 }
                 catch (arg: unknown) {
                     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 as SpoolCleanup<unknown>)
+                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 as SpoolCleanup<unknown>)
+        runSettle(false, false, spool, onfinally, description)
         return result
     }
 }

package/src/mqtt-plus-event.ts

@@ -168,7 +168,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
 
             /*  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/src/mqtt-plus-options.ts

@@ -22,9 +22,6 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
-/*  external requirements  */
-import { nanoid }           from "nanoid"
-
 /*  internal requirements  */
 import type { APISchema }   from "./mqtt-plus-api"
 
@@ -55,7 +52,7 @@ export class OptionsTrait<_T extends APISchema = APISchema> {
     ) {
         /*  determine options and provide defaults  */
         this.options = {
-            id:          nanoid(),
+            id:          "", /*  intentionally resolved later in BaseTrait  */
             codec:       "cbor",
             timeout:     10 * 1000,
             share:       "",

package/src/mqtt-plus-service.ts

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

package/src/mqtt-plus-sink.ts

@@ -229,7 +229,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 if (topicName !== request.name)
                     throw new Error(`sink name mismatch (topic: "${topicName}", payload: "${request.name}")`)
                 let authenticated: boolean | undefined = undefined
-                if (auth)
+                if (auth !== undefined)
                     authenticated = await this.authenticated(sender, request.auth, auth, `sink "${name}"`)
 
                 /*  initialize credit-based flow control state  */
@@ -247,7 +247,16 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 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) {
@@ -666,6 +675,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
             pushInitialResolve   = resolve
             pushInitialReject    = reject
         })
+        pushInitial.catch(() => {})  /*  avoid unhandled promise rejection  */
         this.onResponse.set(`sink-push-response:${requestId}`, (response: SinkPushResponse) => {
             if (response.name !== name) {
                 const error = new Error(`sink response name mismatch (expected "${name}", got "${response.name}")`)

package/src/mqtt-plus-source.ts

@@ -50,8 +50,14 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
     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"))
         for (const gate of this.sourceCreditGates.values())
@@ -143,8 +149,6 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
 
             /*  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 === "") {
@@ -180,6 +184,8 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
             }
             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: InfoSource = { sender, signal: abortSignal }
@@ -295,7 +301,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                 })
 
                 /*  check for authentication  */
-                if (auth)
+                if (auth !== undefined)
                     info.authenticated = await this.authenticated(sender, request.auth, auth, `source "${name}"`)
 
                 /*  finally call the handler callback  */
@@ -566,6 +572,10 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
             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?: unknown) => {

package/src/mqtt-plus-subscription.ts

@@ -127,11 +127,16 @@ class RefCountedSubscription {
         }
     }
 
-    /*  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: string): Promise<void> {
         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/src/mqtt-plus-timer.ts

@@ -82,7 +82,8 @@ export class TimerTrait<T extends APISchema = APISchema> extends SubscriptionTra
                     ac.abort()
                 resolve()
             }, durationMs)
-            timer.unref()
+            if (typeof timer.unref === "function")
+                timer.unref()
             if (signal !== undefined) {
                 if (ac !== undefined)
                     signal.addEventListener("abort", () => {
@@ -109,7 +110,8 @@ export class TimerTrait<T extends APISchema = APISchema> extends SubscriptionTra
                     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", () => {

package/tst/mqtt-plus-4-sink.spec.ts

@@ -319,5 +319,48 @@ describe("MQTT+ Sink Push", function () {
         /*  cleanup  */
         await sinking.destroy()
     })
+
+    /*  test case: Sink Push (Stalled After Early Callback)  */
+    it("MQTT+ Sink Push (Stalled After Early Callback)", async function () {
+        /*  setup  */
+        this.slow(4000)
+        this.timeout(4000)
+        const spy = sinon.spy()
+
+        /*  establish sink whose callback resolves immediately, ignoring stream/buffer  */
+        const sinking = await ctx.apiS.sink("example/server/upload", (name: string, _info) => {
+            spy("sink")
+            expect(name).to.be.equal("foo")
+            /*  intentionally do not consume info.stream or info.buffer  */
+        })
+
+        /*  create a readable that emits one chunk and then stalls forever  */
+        const chunkSize = 16 * 1024
+        let emitted = false
+        const readable = new stream.Readable({
+            read () {
+                if (!emitted) {
+                    emitted = true
+                    this.push(Buffer.from(crypto.randomBytes(chunkSize)))
+                }
+                /*  never push more and never end -- simulate a stalled sender  */
+            }
+        })
+
+        /*  the push must fail (via receiver push timeout) instead of hanging  */
+        await ctx.apiC.push("example/server/upload", readable, "foo").then(() => {
+            spy("push-success")
+        }).catch(() => {
+            spy("push-error")
+        })
+
+        /*  wait for receiver-side cleanup to settle  */
+        await new Promise((resolve) => { setTimeout(resolve, 200) })
+        expect(spy.getCalls().map((call) => call.firstArg))
+            .to.be.same.deep.members([ "sink", "push-error" ])
+
+        /*  cleanup  */
+        await sinking.destroy()
+    })
 })
 

package/tst/mqtt-plus-5-source.spec.ts

@@ -31,8 +31,13 @@ import { Buffer }           from "node:buffer"
 import { describe, it }     from "mocha"
 import * as chai            from "chai"
 
+/*  external dependencies (application)  */
+import MQTT                 from "mqtt"
+
 /*  internal dependencies  */
+import MQTTp                from "mqtt-plus"
 import { ctx }              from "./mqtt-plus-0-fixture"
+import type { API }         from "./mqtt-plus-0-fixture"
 
 /*  setup test suite infrastructure  */
 chai.config.includeStack = true
@@ -263,5 +268,35 @@ describe("MQTT+ Source Fetch", function () {
         /*  cleanup  */
         await sourcing.destroy()
     })
+
+    /*  test case: Source Fetch (Destroy In-Flight)  */
+    it("MQTT+ Source Fetch (Destroy In-Flight)", async function () {
+        /*  setup  */
+        this.slow(2000)
+        this.timeout(2000)
+
+        /*  connect to broker as a dedicated client with a long communication timeout  */
+        const mqttClient = MQTT.connect("mqtt://127.0.0.1:1883")
+        await new Promise<void>((resolve, reject) => {
+            mqttClient.once("connect", ()           => { resolve() })
+            mqttClient.once("error",   (err: Error) => { reject(err) })
+        })
+        const apiClient = new MQTTp<API>(mqttClient, { timeout: 60 * 1000 })
+
+        /*  start fetching a source nobody responds to  */
+        const result = await apiClient.fetch("example/server/download", "foo")
+
+        /*  destroy the instance while the fetch is still in-flight  */
+        await apiClient.destroy()
+
+        /*  expect meta and buffer to settle well below the communication timeout  */
+        const errorMeta = await result.meta.catch((err: Error) => err.message)
+        expect(errorMeta).to.be.equal("instance destroyed")
+        const errorBuffer = await result.buffer.catch((err: Error) => err.message)
+        expect(errorBuffer).to.be.equal("instance destroyed")
+
+        /*  cleanup  */
+        await mqttClient.endAsync()
+    })
 })
 

package/tst/mqtt-plus-6-misc.spec.ts

@@ -36,6 +36,7 @@ import MQTT                 from "mqtt"
 
 /*  internal dependencies  */
 import MQTTp                from "mqtt-plus"
+import type { Event }       from "mqtt-plus"
 import { ctx }              from "./mqtt-plus-0-fixture"
 import type { API }         from "./mqtt-plus-0-fixture"
 import { makeMutuallyExclusiveFields } from "../src/mqtt-plus-util"
@@ -113,31 +114,76 @@ describe("MQTT+ Miscellaneous", function () {
         /*  setup  */
         this.slow(2000)
         this.timeout(2000)
-        const spy = sinon.spy()
+        const spy  = sinon.spy()
+        const spyB = sinon.spy()
 
         /*  create JSON codec API instances on existing MQTT connections  */
-        const apiJsonS = new MQTTp<API>(ctx.mqttS, { id: "json-server", codec: "json", timeout: 500 })
-        const apiJsonC = new MQTTp<API>(ctx.mqttC, { id: "json-client", codec: "json", timeout: 500 })
+        type APIX = API & { "example/server/binary": Event<(data: Buffer) => void> }
+        const apiJsonS = new MQTTp<APIX>(ctx.mqttS, { id: "json-server", codec: "json", timeout: 500 })
+        const apiJsonC = new MQTTp<APIX>(ctx.mqttC, { id: "json-client", codec: "json", timeout: 500 })
 
-        /*  register event handler  */
+        /*  register event handlers  */
         const registration = await apiJsonS.event("example/server/sample", (str: string, num: number) => {
             spy("event", str, num)
         })
+        const registrationB = await apiJsonS.event("example/server/binary", (data: Buffer) => {
+            spyB(data)
+        })
 
-        /*  emit event via JSON codec  */
+        /*  emit events via JSON codec  */
         apiJsonC.emit("example/server/sample", "hello", 99)
+        apiJsonC.emit("example/server/binary", Buffer.from([ 0x01, 0x02, 0x03, 0xff ]))
         await new Promise((resolve) => { setTimeout(resolve, 100) })
 
         /*  verify round-trip  */
         expect(spy.getCalls().length).to.equal(1)
         expect(spy.getCalls()[0].args).to.deep.equal([ "event", "hello", 99 ])
 
+        /*  verify Buffer round-trip  */
+        expect(spyB.getCalls().length).to.equal(1)
+        const data: Buffer = spyB.getCalls()[0].args[0]
+        expect(data).to.be.instanceOf(Buffer)
+        expect(data.equals(Buffer.from([ 0x01, 0x02, 0x03, 0xff ]))).to.equal(true)
+
         /*  cleanup  */
         await registration.destroy()
+        await registrationB.destroy()
         apiJsonS.destroy()
         apiJsonC.destroy()
     })
 
+    /*  test case: Error Event on throwing topicMatch  */
+    it("MQTT+ Error Event on Throwing topicMatch", async function () {
+        /*  setup  */
+        this.slow(2000)
+        this.timeout(2000)
+        const spy = sinon.spy()
+
+        /*  create API instances with a throwing user-supplied topicMatch on the receiver side  */
+        const apiThrowS = new MQTTp<API>(ctx.mqttS, { id: "throw-server", timeout: 500,
+            topicMatch: () => { throw new Error("intentionally failing topicMatch") } })
+        const apiThrowC = new MQTTp<API>(ctx.mqttC, { id: "throw-client", timeout: 500 })
+
+        /*  observe MQTT+ error events  */
+        apiThrowS.on("error", (err: Error) => { spy(err.message) })
+
+        /*  register event handler to subscribe the topic  */
+        const registration = await apiThrowS.event("example/server/sample", () => {})
+
+        /*  emit event to trigger the inbound message processing  */
+        apiThrowC.emit("example/server/sample", "hello", 42)
+        await new Promise((resolve) => { setTimeout(resolve, 100) })
+
+        /*  ensure the exception surfaced as MQTT+ "error" event  */
+        expect(spy.getCalls().length).to.be.at.least(1)
+        expect(spy.getCalls()[0].args[0]).to.match(/failed to match MQTT topic/)
+
+        /*  cleanup  */
+        await registration.destroy()
+        apiThrowS.destroy()
+        apiThrowC.destroy()
+    })
+
     /*  test case: Authentication  */
     it("MQTT+ Authentication", async function () {
         /*  setup  */
@@ -222,6 +268,37 @@ describe("MQTT+ Miscellaneous", function () {
         await registration2.destroy()
     })
 
+    /*  test case: Authentication with Empty Role  */
+    it("MQTT+ Authentication with Empty Role", async function () {
+        /*  setup  */
+        this.slow(2000)
+        this.timeout(2000)
+        const spy = sinon.spy()
+
+        /*  server-side: provide hello service with falsy-but-valid empty role  */
+        const registration = await ctx.apiS.service({
+            name: "example/server/hello",
+            auth: "",
+            callback: (str: string, num: number) => {
+                spy("hello")
+                return `${str}:${num}`
+            }
+        })
+
+        /*  call service and expect fail-closed rejection  */
+        await ctx.apiC.call("example/server/hello", "world", 42).then(async (_result) => {
+            spy("call-success")
+        }).catch((err: Error) => {
+            spy("call-error")
+            expect(err.message).to.match(/failed authentication/)
+        })
+        expect(spy.getCalls().map((call) => call.firstArg))
+            .to.be.deep.equal([ "call-error" ])
+
+        /*  cleanup  */
+        await registration.destroy()
+    })
+
     /*  test case: Unit: arr2buf/buf2arr  */
     it("MQTT+ Unit: arr2buf/buf2arr", function () {
         /*  create a dry-run MQTTp instance for accessing encode methods  */