mqtt-plus 1.4.23 → 1.4.25

package/package.d/{vite+8.0.13.patch → vite+8.1.4.patch}

@@ -1,8 +1,8 @@
 diff --git a/node_modules/vite/dist/node/chunks/node.js b/node_modules/vite/dist/node/chunks/node.js
-index 07bab15..3e9d0d0 100644
+index 69b9f8c..f661ab9 100644
 --- a/node_modules/vite/dist/node/chunks/node.js
 +++ b/node_modules/vite/dist/node/chunks/node.js
-@@ -34918,7 +34918,6 @@ async function runConfigHook(config, plugins, configEnv) {
+@@ -36150,7 +36150,6 @@ async function runConfigHook(config, plugins, configEnv) {
  		const res = await getHookHandler(hook).call(context, conf, configEnv);
  		if (res && res !== conf) {
  			if (hasBothRollupOptionsAndRolldownOptions(res)) context.warn(`Both \`rollupOptions\` and \`rolldownOptions\` were specified by ${JSON.stringify(p.name)} plugin. \`rollupOptions\` specified by that plugin will be ignored.`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                           "mqtt-plus",
-    "version":                        "1.4.23",
+    "version":                        "1.4.25",
     "description":                    "MQTT Communication Patterns",
     "keywords":                       [   "mqtt",
                                           "event", "emit",
@@ -31,30 +31,30 @@
     },
     "devDependencies": {
         "patch-package":              "8.0.1",
-        "@rse/stx":                   "1.1.5",
+        "@rse/stx":                   "1.1.6",
         "shx":                        "0.4.0",
-        "eslint":                     "10.3.0",
-        "globals":                    "17.6.0",
+        "eslint":                     "10.7.0",
+        "globals":                    "17.7.0",
         "@eslint/js":                 "10.0.1",
-        "@eslint/eslintrc":           "3.3.5",
-        "knip":                       "6.13.1",
+        "@eslint/eslintrc":           "3.3.6",
+        "knip":                       "6.26.0",
         "jiti":                       "2.7.0",
-        "tsx":                        "4.22.0",
-        "mocha":                      "11.7.5",
+        "tsx":                        "4.23.0",
+        "mocha":                      "11.7.6",
         "chai":                       "6.2.2",
         "sinon-chai":                 "4.0.1",
         "sinon":                      "22.0.0",
         "c8":                         "11.0.0",
         "source-map-support":         "0.5.21",
         "typescript":                 "6.0.3",
-        "typescript-eslint":          "8.59.3",
-        "@typescript-eslint/parser":  "8.59.3",
-        "mqtt":                       "5.15.1",
-        "aedes":                      "1.0.2",
+        "typescript-eslint":          "8.63.0",
+        "@typescript-eslint/parser":  "8.63.0",
+        "mqtt":                       "5.15.2",
+        "aedes":                      "1.1.1",
         "mosquitto":                  "1.1.0",
         "textframe":                  "1.2.1",
-        "vite":                       "8.0.13",
-        "vite-plugin-node-polyfills": "0.26.0",
+        "vite":                       "8.1.4",
+        "vite-plugin-node-polyfills": "0.28.0",
         "@rollup/plugin-replace":     "6.0.3",
         "@wroud/vite-plugin-tsc":     "0.12.3",
         "@terrastruct/d2":            "0.1.33",
@@ -63,28 +63,26 @@
         "open-cli":                   "9.0.0",
         "cross-env":                  "10.1.0",
 
-        "@types/node":                "25.7.0",
+        "@types/node":                "26.1.1",
         "@types/mocha":               "10.0.10",
         "@types/chai":                "5.2.3",
         "@types/sinon-chai":          "4.0.0",
-        "@types/sinon":               "21.0.1"
+        "@types/sinon":               "22.0.0"
     },
     "peerDependencies": {
         "mqtt":                       ">=4.0.0"
     },
     "overrides": {
-        "vite-plugin-node-polyfills":           { "vite": ">=7.0.0" },
-        "typescript-eslint":                    { "typescript": ">=5.9.0" },
-        "@typescript-eslint/parser":            { "typescript": ">=5.9.0" },
-        "@typescript-eslint/project-service":   { "typescript": ">=5.9.0" },
-        "@typescript-eslint/typescript-estree": { "typescript": ">=5.9.0" },
-        "@typescript-eslint/tsconfig-utils":    { "typescript": ">=5.9.0" }
+        "vite-plugin-node-polyfills":           { "vite": ">=7.0.0" }
+    },
+    "allowScripts": {
+        "esbuild":                    true
     },
     "dependencies": {
-        "nanoid":                     "5.1.11",
+        "nanoid":                     "5.1.16",
         "cbor2":                      "2.3.0",
         "p-lazy":                     "5.0.0",
-        "valibot":                    "1.4.0",
+        "valibot":                    "1.4.2",
         "jose":                       "6.2.3",
         "@stablelib/pbkdf2":          "2.0.1",
         "@stablelib/sha256":          "2.0.1"

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

@@ -110,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)
@@ -147,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()
             })
@@ -222,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-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()
+    })
 })