mqtt-plus 1.4.0 → 1.4.2

package/src/mqtt-plus-sink.ts

@@ -31,7 +31,7 @@ import type { IClientPublishOptions,
 import { nanoid }                                         from "nanoid"
 
 /*  internal requirements  */
-import { CreditGate, RefCountedSubscription,
+import { CreditGate,
     streamToBuffer, sendBufferAsChunks,
     sendStreamAsChunks, makeMutuallyExclusiveFields }     from "./mqtt-plus-util"
 import { run, Spool }                                     from "./mqtt-plus-error"
@@ -45,47 +45,8 @@ import type { AuthOption }                                from "./mqtt-plus-auth
 /*  Sink Push Trait  */
 export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
     /*  sink state  */
-    private sinks                 = new Map<string, (request: SinkPushRequest, topicName: string) => void>()
-    private pushStreams           = new Map<string, Readable>()
-    private pushSpools            = new Map<string, Spool>()
-    private pushTimers            = new Map<string, ReturnType<typeof setTimeout>>()
-    private pushChunkCallbacks    = new Map<string, (response: SinkPushChunk, topicName: string) => void>()
-    private pushResponseCallbacks = new Map<string, (response: SinkPushResponse) => void>()
-    private pushCreditCallbacks   = new Map<string, (response: SinkPushCredit) => void>()
-    private pushSubscriptions     = new RefCountedSubscription(
-        (topic, options) => this._subscribeTopic(topic, options),
-        (topic)          => this._unsubscribeTopic(topic)
-    )
-
-    /*  destroy sink trait  */
-    override destroy () {
-        super.destroy()
-        this.pushSubscriptions.flush()
-    }
-
-    /*  refresh push timer for a specific request  */
-    private _refreshPushTimer (requestId: string) {
-        const timer = this.pushTimers.get(requestId)
-        if (timer !== undefined)
-            clearTimeout(timer)
-        this.pushTimers.set(requestId, setTimeout(() => {
-            this.pushTimers.delete(requestId)
-            const stream = this.pushStreams.get(requestId)
-            if (stream !== undefined)
-                stream.destroy(new Error("push stream timeout"))
-            const spool = this.pushSpools.get(requestId)
-            spool?.unroll()
-        }, this.options.timeout))
-    }
-
-    /*  clear push timer for a specific request  */
-    private _clearPushTimer (requestId: string) {
-        const timer = this.pushTimers.get(requestId)
-        if (timer !== undefined) {
-            clearTimeout(timer)
-            this.pushTimers.delete(requestId)
-        }
-    }
+    private pushStreams = new Map<string, Readable>()
+    private pushSpools  = new Map<string, Spool>()
 
     /*  register a sink  */
     async sink<K extends SinkKeys<T> & string> (
@@ -135,7 +96,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         const spool = new Spool()
 
         /*  sanity check situation  */
-        if (this.sinks.has(name))
+        if (this.onRequest.has(`sink-push-request:${name}`))
             throw new Error(`sink: sink "${name}" already established`)
 
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
@@ -145,7 +106,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         const topicChunkD = this.options.topicMake(name,   "sink-push-chunk",   this.options.id)
 
         /*  remember the registration  */
-        this.sinks.set(name, (request: SinkPushRequest, topicName: string) => {
+        this.onRequest.set(`sink-push-request:${name}`, (request: SinkPushRequest, topicName: string) => {
             /*  determine information  */
             const requestId = request.id
             const params    = request.params ?? []
@@ -195,8 +156,14 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 } : undefined
 
                 /*  utility functions for timeout management  */
-                const refreshPushTimeout = () => this._refreshPushTimer(requestId)
-                const clearPushTimeout   = () => this._clearPushTimer(requestId)
+                const refreshPushTimeout = () => this.timerRefresh(requestId, () => {
+                    const stream = this.pushStreams.get(requestId)
+                    if (stream !== undefined)
+                        stream.destroy(new Error("push stream timeout"))
+                    const spool = this.pushSpools.get(requestId)
+                    spool?.unroll()
+                })
+                const clearPushTimeout   = () => this.timerClear(requestId)
 
                 /*  create a readable for buffering received chunks  */
                 const readable = new Readable({
@@ -226,7 +193,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 readable.once("error", () => reqSpool.unroll())
 
                 /*  register chunk dispatch callback  */
-                this.pushChunkCallbacks.set(requestId, (chunkParsed: SinkPushChunk, chunkTopicName: string) => {
+                this.onResponse.set(`sink-push-chunk:${requestId}`, (chunkParsed: SinkPushChunk, chunkTopicName: string) => {
                     if (chunkTopicName !== chunkParsed.name)
                         throw new Error(`sink name mismatch between topic "${chunkTopicName}" ` +
                             `and payload "${chunkParsed.name}"`)
@@ -247,7 +214,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                         }
                     }
                 })
-                reqSpool.roll(() => { this.pushChunkCallbacks.delete(requestId) })
+                reqSpool.roll(() => { this.onResponse.delete(`sink-push-chunk:${requestId}`) })
 
                 /*  start timeout for push stream cleanup  */
                 refreshPushTimeout()
@@ -276,7 +243,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 await sendResponse(err.message).catch(() => {})
             })
         })
-        spool.roll(() => { this.sinks.delete(name) })
+        spool.roll(() => { this.onRequest.delete(`sink-push-request:${name}`) })
 
         /*  subscribe to MQTT topics  */
         await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () =>
@@ -292,7 +259,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         /*  provide a registration for subsequent destruction  */
         return {
             destroy: async (): Promise<void> => {
-                if (!this.sinks.has(name))
+                if (!this.onRequest.has(`sink-push-request:${name}`))
                     throw new Error(`destroy: sink "${name}" not established`)
                 await spool.unroll(false)?.catch((err: Error) => {
                     this.error(err, `destroy: failed to cleanup: ${err.message}`)
@@ -360,8 +327,8 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         /*  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.pushSubscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
-        spool.roll(() => this.pushSubscriptions.unsubscribe(responseTopic))
+            this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
+        spool.roll(() => this.subscriptions.unsubscribe(responseTopic))
 
         /*  define abort controller and signal  */
         const abortController = new AbortController()
@@ -400,7 +367,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 spool.roll(() => { abortSignal.removeEventListener("abort", onAbort) })
 
                 /*  register handlers for initial response  */
-                this.pushResponseCallbacks.set(requestId, (response: SinkPushResponse) => {
+                this.onResponse.set(`sink-push-response:${requestId}`, (response: SinkPushResponse) => {
                     if (response.error)
                         reject(new Error(response.error))
                     else {
@@ -410,11 +377,11 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                         resolve()
                     }
                 })
-                spool.roll(() => { this.pushResponseCallbacks.delete(requestId) })
-                this.pushCreditCallbacks.set(requestId, (_response: SinkPushCredit) => {
+                spool.roll(() => { this.onResponse.delete(`sink-push-response:${requestId}`) })
+                this.onResponse.set(`sink-push-credit:${requestId}`, (_response: SinkPushCredit) => {
                     refreshTimeout()
                 })
-                spool.roll(() => { this.pushCreditCallbacks.delete(requestId) })
+                spool.roll(() => { this.onResponse.delete(`sink-push-credit:${requestId}`) })
 
                 /*  generate and send request message  */
                 const auth      = this.authenticate()
@@ -430,7 +397,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
             })
 
             /*  override handler for mid-stream (error) responses  */
-            this.pushResponseCallbacks.set(requestId, (response: SinkPushResponse) => {
+            this.onResponse.set(`sink-push-response:${requestId}`, (response: SinkPushResponse) => {
                 if (response.error)
                     abortController.abort(new Error(response.error))
             })
@@ -443,13 +410,13 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
             if (creditGate) {
                 const creditTopic = this.options.topicMake(name, "sink-push-credit", this.options.id)
                 await run(`subscribe to MQTT topic "${creditTopic}"`, spool, () =>
-                    this.pushSubscriptions.subscribe(creditTopic, { qos: 2 }))
-                spool.roll(() => this.pushSubscriptions.unsubscribe(creditTopic))
+                    this.subscriptions.subscribe(creditTopic, { qos: 2 }))
+                spool.roll(() => this.subscriptions.unsubscribe(creditTopic))
                 const gate = creditGate
                 spool.roll(() => { gate.abort() })
 
                 /*  update credit callback to include gate replenish  */
-                this.pushCreditCallbacks.set(requestId, (response: SinkPushCredit) => {
+                this.onResponse.set(`sink-push-credit:${requestId}`, (response: SinkPushCredit) => {
                     gate.replenish(response.credit)
                     refreshTimeout()
                 })
@@ -459,7 +426,11 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
             const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver)
 
             /*  callback for creating and sending a chunk message  */
-            const sendChunk = async (chunk: Uint8Array | undefined, error: string | undefined, final: boolean): Promise<void> => {
+            const sendChunk = async (
+                chunk: Uint8Array | undefined,
+                error: string | undefined,
+                final: boolean
+            ): Promise<void> => {
                 refreshTimeout()
                 const chunkMsg = this.msg.makeSinkPushChunk(requestId,
                     name, chunk, error, final, this.options.id, receiver)
@@ -489,48 +460,4 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         }
     }
 
-    /*  dispatch incoming MQTT message  */
-    protected override async _dispatchMessage (topic: string, message: any) {
-        /*  forward dispatching to other traits  */
-        await super._dispatchMessage(topic, message)
-
-        /*  match the MQTT topic  */
-        const topicMatch = this.options.topicMatch(topic)
-
-        /*  handle sink push request (on server-side)  */
-        if (topicMatch !== null
-            && topicMatch.operation === "sink-push-request"
-            && message instanceof SinkPushRequest) {
-            const handler = this.sinks.get(message.name)
-            if (handler !== undefined)
-                handler(message, topicMatch.name)
-        }
-
-        /*  handle sink push response (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "sink-push-response"
-            && message instanceof SinkPushResponse) {
-            const handler = this.pushResponseCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-
-        /*  handle sink push chunk (on server-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "sink-push-chunk"
-            && message instanceof SinkPushChunk) {
-            const handler = this.pushChunkCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message, topicMatch.name)
-        }
-
-        /*  handle sink push credit (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "sink-push-credit"
-            && message instanceof SinkPushCredit) {
-            const handler = this.pushCreditCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-    }
 }

package/src/mqtt-plus-source.ts

@@ -31,7 +31,7 @@ import type { IClientPublishOptions,
 import { nanoid }                                         from "nanoid"
 
 /*  internal requirements  */
-import { CreditGate, RefCountedSubscription,
+import { CreditGate,
     streamToBuffer, sendBufferAsChunks,
     sendStreamAsChunks, makeMutuallyExclusiveFields }     from "./mqtt-plus-util"
 import { run, Spool, ensureError }                        from "./mqtt-plus-error"
@@ -45,44 +45,7 @@ import type { AuthOption }                                from "./mqtt-plus-auth
 /*  Source Fetch Trait  */
 export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T> {
     /*  source state  */
-    private sources                = new Map<string, (request: SourceFetchRequest, topicName: string) => void>()
-    private fetchResponseCallbacks = new Map<string, (response: SourceFetchResponse) => void>()
-    private fetchChunkCallbacks    = new Map<string, (response: SourceFetchChunk) => void>()
-    private sourceCreditCallbacks  = new Map<string, (response: SourceFetchCredit) => void>()
-    private sourceCreditGates      = new Map<string, CreditGate>()
-    private sourceTimers           = new Map<string, ReturnType<typeof setTimeout>>()
-    private fetchSubscriptions     = new RefCountedSubscription(
-        (topic, options) => this._subscribeTopic(topic, options),
-        (topic)          => this._unsubscribeTopic(topic)
-    )
-
-    /*  refresh source timer for a specific request  */
-    private _refreshSourceTimer (requestId: string) {
-        const timer = this.sourceTimers.get(requestId)
-        if (timer !== undefined)
-            clearTimeout(timer)
-        this.sourceTimers.set(requestId, setTimeout(() => {
-            this.sourceTimers.delete(requestId)
-            const gate = this.sourceCreditGates.get(requestId)
-            if (gate !== undefined)
-                gate.abort()
-        }, this.options.timeout))
-    }
-
-    /*  clear source timer for a specific request  */
-    private _clearSourceTimer (requestId: string) {
-        const timer = this.sourceTimers.get(requestId)
-        if (timer !== undefined) {
-            clearTimeout(timer)
-            this.sourceTimers.delete(requestId)
-        }
-    }
-
-    /*  destroy source trait  */
-    override destroy () {
-        super.destroy()
-        this.fetchSubscriptions.flush()
-    }
+    private sourceCreditGates = new Map<string, CreditGate>()
 
     /*  establish a source (for fetch requests)  */
     async source<K extends SourceKeys<T> & string> (
@@ -132,7 +95,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         const spool = new Spool()
 
         /*  sanity check situation  */
-        if (this.sources.has(name))
+        if (this.onRequest.has(`source-fetch-request:${name}`))
             throw new Error(`source: source "${name}" already established`)
 
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
@@ -142,7 +105,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         const topicCreditD = this.options.topicMake(name,   "source-fetch-credit",  this.options.id)
 
         /*  remember the registration  */
-        this.sources.set(name, (request: SourceFetchRequest, topicName: string) => {
+        this.onRequest.set(`source-fetch-request:${name}`, (request: SourceFetchRequest, topicName: string) => {
             /*  determine information  */
             const requestId = request.id
             const params    = request.params ?? []
@@ -171,12 +134,20 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
             }
 
             /*  utility functions for timeout management  */
-            const refreshSourceTimeout = () => this._refreshSourceTimer(requestId)
-            const clearSourceTimeout   = () => this._clearSourceTimer(requestId)
+            const refreshSourceTimeout = () => this.timerRefresh(requestId, () => {
+                const gate = this.sourceCreditGates.get(requestId)
+                if (gate !== undefined)
+                    gate.abort()
+            })
+            const clearSourceTimeout   = () => this.timerClear(requestId)
             refreshSourceTimeout()
 
             /*  callback for creating and sending a chunk message  */
-            const sendChunk = async (chunk: Uint8Array | undefined, error: string | undefined, final: boolean): Promise<void> => {
+            const sendChunk = async (
+                chunk: Uint8Array | undefined,
+                error: string | undefined,
+                final: boolean
+            ): Promise<void> => {
                 refreshSourceTimeout()
                 const chunkMsg = this.msg.makeSourceFetchChunk(requestId,
                     name, chunk, error, final, this.options.id, sender)
@@ -190,9 +161,9 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                 ? new CreditGate(initialCredit) : undefined
             if (creditGate) {
                 this.sourceCreditGates.set(requestId, creditGate)
-                this.sourceCreditCallbacks.set(requestId, (creditParsed: SourceFetchCredit) => {
+                this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed: SourceFetchCredit) => {
                     creditGate.replenish(creditParsed.credit)
-                    this._refreshSourceTimer(requestId)
+                    refreshSourceTimeout()
                 })
             }
 
@@ -239,10 +210,10 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                     creditGate.abort()
                     this.sourceCreditGates.delete(requestId)
                 }
-                this.sourceCreditCallbacks.delete(requestId)
+                this.onResponse.delete(`source-fetch-credit:${requestId}`)
             })
         })
-        spool.roll(() => { this.sources.delete(name) })
+        spool.roll(() => { this.onRequest.delete(`source-fetch-request:${name}`) })
 
         /*  subscribe to MQTT topics  */
         await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () =>
@@ -258,7 +229,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         /*  provide a registration for subsequent destruction  */
         return {
             destroy: async (): Promise<void> => {
-                if (!this.sources.has(name))
+                if (!this.onRequest.has(`source-fetch-request:${name}`))
                     throw new Error(`destroy: source "${name}" not established`)
                 await spool.unroll(false)?.catch((err: Error) => {
                     this.error(err, `destroy: failed to cleanup: ${err.message}`)
@@ -333,11 +304,11 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         const responseTopic = this.options.topicMake(name, "source-fetch-response", this.options.id)
         const chunkTopic    = this.options.topicMake(name, "source-fetch-chunk",    this.options.id)
         await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () =>
-            this.fetchSubscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
-        spool.roll(() => this.fetchSubscriptions.unsubscribe(responseTopic))
+            this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
+        spool.roll(() => this.subscriptions.unsubscribe(responseTopic))
         await run(`subscribe to MQTT topic "${chunkTopic}"`, spool, () =>
-            this.fetchSubscriptions.subscribe(chunkTopic, { qos: options.qos ?? 2 }))
-        spool.roll(() => this.fetchSubscriptions.unsubscribe(chunkTopic))
+            this.subscriptions.subscribe(chunkTopic, { qos: options.qos ?? 2 }))
+        spool.roll(() => this.subscriptions.unsubscribe(chunkTopic))
 
         /*  credit-based flow control state  */
         const chunkCredit  = this.options.chunkCredit
@@ -349,7 +320,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         const stream = new Readable({
             highWaterMark: chunkCredit > 0 ? chunkCredit * this.options.chunkSize : 16 * 1024,
             read: (_size) => {
-                if (chunkCredit <= 0 || !this.fetchChunkCallbacks.has(requestId))
+                if (chunkCredit <= 0 || !this.onResponse.has(`source-fetch-chunk:${requestId}`))
                     return
                 const targetId = serverId ?? receiver
                 if (!targetId)
@@ -405,7 +376,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         stream.once("error", () => spool.unroll())
 
         /*  register response dispatch callback  */
-        this.fetchResponseCallbacks.set(requestId, (response: SourceFetchResponse) => {
+        this.onResponse.set(`source-fetch-response:${requestId}`, (response: SourceFetchResponse) => {
             if (response.sender)
                 serverId = response.sender
             metaResolve?.(response.meta)
@@ -418,7 +389,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         })
 
         /*  register chunk dispatch callback  */
-        this.fetchChunkCallbacks.set(requestId, (response: SourceFetchChunk) => {
+        this.onResponse.set(`source-fetch-chunk:${requestId}`, (response: SourceFetchChunk) => {
             if (response.sender)
                 serverId = response.sender
             if (response.error) {
@@ -438,8 +409,8 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
             }
         })
         spool.roll(() => {
-            this.fetchResponseCallbacks.delete(requestId)
-            this.fetchChunkCallbacks.delete(requestId)
+            this.onResponse.delete(`source-fetch-response:${requestId}`)
+            this.onResponse.delete(`source-fetch-chunk:${requestId}`)
         })
 
         /*  generate encoded message  */
@@ -466,45 +437,4 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
         return result
     }
 
-    /*  dispatch message (Source Fetch pattern handling)  */
-    protected override async _dispatchMessage (topic: string, message: any) {
-        await super._dispatchMessage(topic, message)
-        const topicMatch = this.options.topicMatch(topic)
-
-        /*  handle source fetch request (on server-side)  */
-        if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-request"
-            && message instanceof SourceFetchRequest) {
-            const handler = this.sources.get(message.name)
-            if (handler !== undefined)
-                handler(message, topicMatch.name)
-        }
-
-        /*  handle source fetch response (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-response"
-            && message instanceof SourceFetchResponse) {
-            const handler = this.fetchResponseCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-
-        /*  handle source fetch chunk (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-chunk"
-            && message instanceof SourceFetchChunk) {
-            const handler = this.fetchChunkCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-
-        /*  handle source fetch credit (on server-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-credit"
-            && message instanceof SourceFetchCredit) {
-            const handler = this.sourceCreditCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-    }
 }

package/src/mqtt-plus-subscription.ts

@@ -0,0 +1,141 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/*  external requirements  */
+import type { IClientSubscribeOptions } from "mqtt"
+
+/*  internal requirements  */
+import type { APISchema }               from "./mqtt-plus-api"
+import { BaseTrait }                    from "./mqtt-plus-base"
+
+/*  reference-counted subscription helper  */
+class RefCountedSubscription {
+    private counts  = new Map<string, number>()
+    private pending = new Map<string, Promise<void>>()
+    private lingers = new Map<string, ReturnType<typeof setTimeout>>()
+    constructor (
+        private subscribeFn:   (topic: string, options: IClientSubscribeOptions) => Promise<void>,
+        private unsubscribeFn: (topic: string) => Promise<void>,
+        private lingerMs:      number = 30 * 1000
+    ) {}
+
+    /*  subscribe to a topic (reference-counted)  */
+    async subscribe (topic: string, options: IClientSubscribeOptions = { qos: 2 }): Promise<void> {
+        /*  increment count first to reserve our interest  */
+        const count = this.counts.get(topic) ?? 0
+        this.counts.set(topic, count + 1)
+
+        /*  optionally just cancel a pending linger unsubscription
+            (subscription is still kept active on the broker)  */
+        const linger = this.lingers.get(topic)
+        if (linger) {
+            clearTimeout(linger)
+            this.lingers.delete(topic)
+            return
+        }
+
+        /*  if we are the first, we must perform the actual subscription  */
+        if (count === 0) {
+            const promise = this.subscribeFn(topic, options).finally(() => {
+                this.pending.delete(topic)
+            }).catch((err: Error) => {
+                const count = this.counts.get(topic)
+                if (count) {
+                    if (count <= 1)
+                        this.counts.delete(topic)
+                    else
+                        this.counts.set(topic, count - 1)
+                }
+                throw err
+            })
+            this.pending.set(topic, promise)
+            return promise
+        }
+        else {
+            /*  perhaps still need to wait for a pending subscription  */
+            const pending = this.pending.get(topic)
+            if (pending)
+                return pending.catch((err: Error) => {
+                    const count = this.counts.get(topic)
+                    if (count) {
+                        if (count <= 1)
+                            this.counts.delete(topic)
+                        else
+                            this.counts.set(topic, count - 1)
+                    }
+                    throw err
+                })
+        }
+    }
+
+    /*  unsubscribe from a topic (reference-counted)  */
+    async unsubscribe (topic: string): Promise<void> {
+        const count = this.counts.get(topic)
+        if (count) {
+            if (count <= 1) {
+                this.counts.delete(topic)
+                if (this.lingerMs > 0) {
+                    /*  defer the actual broker unsubscription  */
+                    const timer = setTimeout(() => {
+                        this.lingers.delete(topic)
+                        this.unsubscribeFn(topic).catch(() => {})
+                    }, this.lingerMs)
+                    this.lingers.set(topic, timer)
+                }
+                else
+                    await this.unsubscribeFn(topic).catch(() => {})
+            }
+            else
+                this.counts.set(topic, count - 1)
+        }
+    }
+
+    /*  flush all pending linger timers and unsubscribe  */
+    async flush (): Promise<void> {
+        /*  cancel all pending linger timers first (synchronously)  */
+        const topics = [ ...this.lingers.keys() ]
+        for (const topic of topics) {
+            clearTimeout(this.lingers.get(topic))
+            this.lingers.delete(topic)
+        }
+
+        /*  then unsubscribe from all lingered topics  */
+        for (const topic of topics)
+            await this.unsubscribeFn(topic).catch(() => {})
+    }
+}
+
+/*  Subscription trait with shared MQTT subscription management  */
+export class SubscriptionTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
+    protected subscriptions = new RefCountedSubscription(
+        (topic, options) => this._subscribeTopic(topic, options),
+        (topic)          => this._unsubscribeTopic(topic)
+    )
+
+    /*  destroy topic trait  */
+    override async destroy () {
+        await this.subscriptions.flush()
+        await super.destroy()
+    }
+}