mqtt-plus 1.4.0 → 1.4.2

package/etc/knip.jsonc

@@ -28,7 +28,7 @@
         "src/mqtt-plus.ts",
         "etc/eslint.mts",
         "tst/mqtt-plus-0-mosquitto.ts",
-        "tst/mqtt-plus-0-fixtures.ts",
+        "tst/mqtt-plus-0-fixture.ts",
         "tst/mqtt-plus-1-api.spec.ts",
         "tst/mqtt-plus-2-event.spec.ts",
         "tst/mqtt-plus-3-service.spec.ts",

package/etc/stx.conf

@@ -35,10 +35,11 @@ build : lint
 
 #   documentation compilation
 build-doc
-    node etc/d2.mts doc/theme.d2 doc/mqtt-plus-1-event-emission.d2 doc/mqtt-plus-1-event-emission.svg
-    node etc/d2.mts doc/theme.d2 doc/mqtt-plus-2-service-call.d2   doc/mqtt-plus-2-service-call.svg
-    node etc/d2.mts doc/theme.d2 doc/mqtt-plus-3-sink-push.d2      doc/mqtt-plus-3-sink-push.svg
-    node etc/d2.mts doc/theme.d2 doc/mqtt-plus-4-source-fetch.d2   doc/mqtt-plus-4-source-fetch.svg
+    node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-comm-event-emission.d2 doc/mqtt-plus-comm-event-emission.svg
+    node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-comm-service-call.d2   doc/mqtt-plus-comm-service-call.svg
+    node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-comm-sink-push.d2      doc/mqtt-plus-comm-sink-push.svg
+    node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-comm-source-fetch.d2   doc/mqtt-plus-comm-source-fetch.svg
+    node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-architecture.d2        doc/mqtt-plus-architecture.svg
 
 #   development loop
 dev
@@ -50,6 +51,7 @@ dev
 
 #   run test suite
 test
+    tsc --project tst/tsc.json --noEmit && \
     eslint --config etc/eslint.mts tst/mqtt-plus-0-fixture.ts tst/mqtt-plus-0-mosquitto.ts tst/*.spec.ts && \
     NODE_OPTIONS="--import=tsx --trace-warnings" mocha --require tst/mqtt-plus-0-fixture.ts tst/*.spec.ts
 

package/package.json

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

package/src/mqtt-plus-base.ts

@@ -34,12 +34,17 @@ import { MqttClient,
 import type { APISchema }    from "./mqtt-plus-api"
 import type { APIOptions }   from "./mqtt-plus-options"
 import { TraceTrait }        from "./mqtt-plus-trace"
+import { ensureError }       from "./mqtt-plus-error"
 
 /*  MQTTp Base class with shared infrastructure  */
 export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     protected mqtt: MqttClient
     private _messageHandler: OnMessageCallback
 
+    /*  central message callback registries  */
+    protected onRequest  = new Map<string, (message: any, topicName: string) => void>()
+    protected onResponse = new Map<string, (message: any, topicName: string) => void>()
+
     /*  construct API class  */
     constructor (
         mqtt: MqttClient | null,
@@ -92,7 +97,7 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     }
 
     /*  destroy API class  */
-    destroy () {
+    async destroy () {
         this.log("info", "un-hooking from MQTT client")
         this.mqtt.off("message", this._messageHandler)
     }
@@ -171,36 +176,61 @@ export class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
     }
 
     /*  handle incoming MQTT message  */
-    private _onMessage (topic: string, message: string | Uint8Array, packet: IPublishPacket): void {
-        /*  try to parse message as payload  */
-        if (typeof message === "string")
-            this.log("info", `received from MQTT topic "${topic}" (type: string, length: ${message.length} chars)`)
+    private _onMessage (topic: string, data: string | Uint8Array, packet: IPublishPacket): void {
+        /*  parse MQTT topic  */
+        const topicMatch = this.options.topicMatch(topic)
+        if (topicMatch === null)
+            return
+
+        /*  parse MQTT data into payload object  */
+        if (typeof data === "string")
+            this.log("info", `received from MQTT topic "${topic}" (type: string, length: ${data.length} chars)`)
         else
-            this.log("info", `received from MQTT topic "${topic}" (type: buffer, length: ${message.byteLength} bytes)`)
-        let parsed: any
+            this.log("info", `received from MQTT topic "${topic}" (type: buffer, length: ${data.byteLength} bytes)`)
+        let payload: any
         try {
-            const payload = this.codec.decode(message)
-            parsed = this.msg.parse(payload)
+            payload = this.codec.decode(data)
         }
-        catch (_err: unknown) {
-            const err = _err instanceof Error
-                ? new Error(`failed to parse message: ${_err.message}`, { cause: _err })
-                : new Error("failed to parse message")
-            this.error(err)
+        catch (err: unknown) {
+            this.error(ensureError(err, "failed to parse message into object"))
             return
         }
-        this.log("debug", `received from MQTT topic "${topic}"`, { message: parsed })
 
-        /*  dispatch to trait handlers  */
-        this._dispatchMessage(topic, parsed).catch((err: Error) => {
-            this.error(err, `dispatching message from MQTT topic "${topic}" failed`)
-        })
+        /*  parse payload object into typed MQTT+ message  */
+        let message: any
+        try {
+            message = this.msg.parse(payload)
+        }
+        catch (err: unknown) {
+            this.error(ensureError(err, "failed to parse object into typed message object"))
+            return
+        }
+        this.log("debug", `received from MQTT topic "${topic}"`, { message })
+
+        /*  dispatch MQTT+ message  */
+        if (this.msg.isRequest(message)) {
+            /*  dispatch request message  */
+            const handler = this.onRequest.get(`${topicMatch.operation}:${message.name}`)
+            if (handler !== undefined) {
+                try {
+                    handler(message, topicMatch.name)
+                }
+                catch (err: unknown) {
+                    this.error(ensureError(err, `dispatching request message from MQTT topic "${topic}" failed`))
+                }
+            }
+        }
+        else if (this.msg.isResponse(message)) {
+            /*  dispatch response message  */
+            const handler = this.onResponse.get(`${topicMatch.operation}:${message.id}`)
+            if (handler !== undefined) {
+                try {
+                    handler(message, topicMatch.name)
+                }
+                catch (err: unknown) {
+                    this.error(ensureError(err, `dispatching response message from MQTT topic "${topic}" failed`))
+                }
+            }
+        }
     }
-
-    /*  dispatch parsed message to appropriate handler
-        (base implementation, to be overridden in sub-traits)  */
-    protected async _dispatchMessage (
-        _topic:  string,
-        _parsed: any
-    ): Promise<void> {}
 }

package/src/mqtt-plus-event.ts

@@ -37,9 +37,6 @@ import { run, Spool, ensureError }    from "./mqtt-plus-error"
 
 /*  Event Emission Trait  */
 export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
-    /*  internal state  */
-    private events = new Map<string, (request: EventEmission, topicName: string) => void>()
-
     /*  register an event handler  */
     async event<K extends EventKeys<T> & string> (
         name:     K,
@@ -88,7 +85,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
         const spool = new Spool()
 
         /*  sanity check situation  */
-        if (this.events.has(name))
+        if (this.onRequest.has(`event-emission:${name}`))
             throw new Error(`event: event "${name}" already registered`)
 
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
@@ -97,7 +94,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
         const topicD = this.options.topicMake(name, "event-emission", this.options.id)
 
         /*  remember the registration  */
-        this.events.set(name, (request: EventEmission, topicName: string) => {
+        this.onRequest.set(`event-emission:${name}`, (request: EventEmission, topicName: string) => {
             /*  determine event information  */
             const senderId = request.sender
             const params   = request.params ?? []
@@ -123,7 +120,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
                 this.error(error, `handler for event "${name}" failed`)
             })
         })
-        spool.roll(() => { this.events.delete(name) })
+        spool.roll(() => { this.onRequest.delete(`event-emission:${name}`) })
 
         /*  subscribe to MQTT topics  */
         await run(`subscribe to MQTT topic "${topicB}"`, spool, () =>
@@ -136,7 +133,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
         /*  provide a registration for subsequent destruction  */
         return {
             destroy: async (): Promise<void> => {
-                if (!this.events.has(name))
+                if (!this.onRequest.has(`event-emission:${name}`))
                     throw new Error(`destroy: event "${name}" not registered`)
                 await spool.unroll(false)?.catch((err: Error) => {
                     this.error(err, `destroy: failed to cleanup: ${err.message}`)
@@ -185,7 +182,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
         let params:    Parameters<T[K]>
         let receiver:  string | undefined
         let options:   IClientPublishOptions = {}
-        let meta:      Record<string, any> = {}
+        let meta:      Record<string, any> | undefined
         let dry:       boolean | undefined
         if (typeof eventOrConfig === "object" && eventOrConfig !== null) {
             /*  object-based API  */
@@ -193,7 +190,7 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
             params   = eventOrConfig.params
             receiver = eventOrConfig.receiver
             options  = eventOrConfig.options ?? {}
-            meta     = eventOrConfig.meta ?? {}
+            meta     = eventOrConfig.meta
             dry      = eventOrConfig.dry
         }
         else {
@@ -208,7 +205,8 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
         /*  generate encoded message  */
         const auth      = this.authenticate()
         const metaStore = this.metaStore(meta)
-        const request   = this.msg.makeEventEmission(requestId, event, params, this.options.id, receiver, auth, metaStore)
+        const request   = this.msg.makeEventEmission(requestId, event, params,
+            this.options.id, receiver, auth, metaStore)
         const message   = this.codec.encode(request)
 
         /*  generate corresponding MQTT topic  */
@@ -225,18 +223,4 @@ export class EventTrait<T extends APISchema = APISchema> extends AuthTrait<T> {
             })
     }
 
-    /*  dispatch message (Event pattern handling)  */
-    protected override async _dispatchMessage (topic: string, message: any) {
-        await super._dispatchMessage(topic, message)
-        const topicMatch = this.options.topicMatch(topic)
-
-        /*  on server-side handle event emission request  */
-        if (topicMatch !== null
-            && topicMatch.operation === "event-emission"
-            && message instanceof EventEmission) {
-            const handler = this.events.get(message.name)
-            if (handler !== undefined)
-                handler(message, topicMatch.name)
-        }
-    }
 }

package/src/mqtt-plus-meta.ts

@@ -23,11 +23,11 @@
 */
 
 /*  internal requirements  */
-import type { APISchema } from "./mqtt-plus-api"
-import { BaseTrait }      from "./mqtt-plus-base"
+import type { APISchema }     from "./mqtt-plus-api"
+import { TimerTrait }         from "./mqtt-plus-timer"
 
 /*  Meta trait with meta information management  */
-export class MetaTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
+export class MetaTrait<T extends APISchema = APISchema> extends TimerTrait<T> {
     /*  internal state  */
     private _meta: Map<string, any> = new Map()
 

package/src/mqtt-plus-msg.ts

@@ -509,6 +509,34 @@ class Msg {
         else
             throw new Error("invalid object: not of any known type")
     }
+
+    /*  guard for request messages  */
+    isRequest (msg: any): msg is (
+        EventEmission | ServiceCallRequest | SourceFetchRequest | SinkPushRequest
+    ) {
+        return (
+            msg instanceof EventEmission
+            || msg instanceof ServiceCallRequest
+            || msg instanceof SourceFetchRequest
+            || msg instanceof SinkPushRequest
+        )
+    }
+
+    /*  guard for response messages  */
+    isResponse (msg: any): msg is (
+        ServiceCallResponse | SinkPushResponse | SinkPushChunk | SinkPushCredit |
+        SourceFetchResponse | SourceFetchChunk | SourceFetchCredit
+    ) {
+        return (
+            msg instanceof ServiceCallResponse
+            || msg instanceof SinkPushResponse
+            || msg instanceof SinkPushChunk
+            || msg instanceof SinkPushCredit
+            || msg instanceof SourceFetchResponse
+            || msg instanceof SourceFetchChunk
+            || msg instanceof SourceFetchCredit
+        )
+    }
 }
 
 /*  message trait  */

package/src/mqtt-plus-service.ts

@@ -28,7 +28,6 @@ import type { IClientPublishOptions,
 import { nanoid }                     from "nanoid"
 
 /*  internal requirements  */
-import { RefCountedSubscription }     from "./mqtt-plus-util"
 import { run, Spool, ensureError }    from "./mqtt-plus-error"
 import { ServiceCallRequest,
     ServiceCallResponse }             from "./mqtt-plus-msg"
@@ -40,19 +39,6 @@ import type { AuthOption }            from "./mqtt-plus-auth"
 
 /*  Service Call Trait  */
 export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T> {
-    /*  internal state  */
-    private services          = new Map<string, (request: ServiceCallRequest, topicName: string) => void>()
-    private callCallbacks     = new Map<string, (response: ServiceCallResponse) => void>()
-    private callSubscriptions = new RefCountedSubscription(
-        (topic, options) => this._subscribeTopic(topic, options),
-        (topic)          => this._unsubscribeTopic(topic)
-    )
-
-    /*  destroy service trait  */
-    override destroy () {
-        super.destroy()
-        this.callSubscriptions.flush()
-    }
 
     /*  register a service call handler  */
     async service<K extends ServiceKeys<T> & string> (
@@ -102,8 +88,8 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         const spool = new Spool()
 
         /*  sanity check situation  */
-        if (this.services.has(name))
-            throw new Error(`register: service "${name}" already registered`)
+        if (this.onRequest.has(`service-call-request:${name}`))
+            throw new Error(`service: service "${name}" already registered`)
 
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
         const topicS = `$share/${share}/${name}`
@@ -111,7 +97,7 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         const topicD = this.options.topicMake(name,   "service-call-request", this.options.id)
 
         /*  remember the registration  */
-        this.services.set(name, (request: ServiceCallRequest, topicName: string) => {
+        this.onRequest.set(`service-call-request:${name}`, (request: ServiceCallRequest, topicName: string) => {
             /*  determine request information  */
             const requestId = request.id
             const senderId  = request.sender
@@ -154,7 +140,7 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
                 this.error(err, `handler for service "${name}" failed`)
             })
         })
-        spool.roll(() => { this.services.delete(name) })
+        spool.roll(() => { this.onRequest.delete(`service-call-request:${name}`) })
 
         /*  subscribe to MQTT topics  */
         await run(`subscribe to MQTT topic "${topicB}"`, spool, () =>
@@ -167,8 +153,8 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         /*  provide a registration for subsequent destruction  */
         return {
             destroy: async (): Promise<void> => {
-                if (!this.services.has(name))
-                    throw new Error(`destroy: service "${name}" no longer registered`)
+                if (!this.onRequest.has(`service-call-request:${name}`))
+                    throw new Error(`destroy: service "${name}" not registered`)
                 await spool.unroll(false)?.catch((err: Error) => {
                     this.error(err, `destroy: failed to cleanup: ${err.message}`)
                 })
@@ -205,14 +191,14 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         let params:    Parameters<T[K]>
         let receiver:  string | undefined
         let options:   IClientPublishOptions = {}
-        let meta:      Record<string, any> = {}
+        let meta:      Record<string, any> | undefined
         if (typeof nameOrConfig === "object" && nameOrConfig !== null) {
             /*  object-based API  */
             name     = nameOrConfig.name
             params   = nameOrConfig.params
             receiver = nameOrConfig.receiver
             options  = nameOrConfig.options ?? {}
-            meta     = nameOrConfig.meta ?? {}
+            meta     = nameOrConfig.meta
         }
         else {
             /*  positional API  */
@@ -229,8 +215,8 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         /*  subscribe to MQTT response topic  */
         const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id)
         await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () =>
-            this.callSubscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
-        spool.roll(() => this.callSubscriptions.unsubscribe(responseTopic))
+            this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }))
+        spool.roll(() => this.subscriptions.unsubscribe(responseTopic))
 
         /*  create promise for MQTT response handling  */
         const promise: Promise<ReturnType<T[K]>> = new Promise((resolve, reject) => {
@@ -245,14 +231,14 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
                     timer = null
                 }
             })
-            this.callCallbacks.set(requestId, async (response: ServiceCallResponse) => {
+            this.onResponse.set(`service-call-response:${requestId}`, async (response: ServiceCallResponse) => {
                 await spool.unroll()
                 if (response.error !== undefined)
                     reject(new Error(response.error))
                 else
                     resolve(response.result)
             })
-            spool.roll(() => { this.callCallbacks.delete(requestId) })
+            spool.roll(() => { this.onResponse.delete(`service-call-response:${requestId}`) })
         })
 
         /*  generate encoded message  */
@@ -272,28 +258,4 @@ export class ServiceTrait<T extends APISchema = APISchema> extends EventTrait<T>
         return promise
     }
 
-    /*  dispatch message (Service pattern handling)  */
-    protected override async _dispatchMessage (topic: string, message: any) {
-        await super._dispatchMessage(topic, message)
-        const topicMatch = this.options.topicMatch(topic)
-
-        /*  on server-side handle service call request  */
-        if (topicMatch !== null
-            && topicMatch.operation === "service-call-request"
-            && message instanceof ServiceCallRequest) {
-            const handler = this.services.get(message.name)
-            if (handler !== undefined)
-                handler(message, topicMatch.name)
-        }
-
-        /*  on client-side handle service call response  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "service-call-response"
-            && topicMatch.peerId === this.options.id
-            && message instanceof ServiceCallResponse) {
-            const handler = this.callCallbacks.get(message.id)
-            if (handler !== undefined)
-                handler(message)
-        }
-    }
 }