Expert/mqtt FrontEnd scaffolding by cstns · Pull Request #7004 · FlowFuse/flowfuse

cstns · 2026-03-31T13:00:35Z

Description

This PR scaffolds frontend MQTT support and restructures service startup/cleanup into a centralized orchestrator, while updating dependent code and adding tests.

Replaces the old service.factory with a new services.orchestrator that boots and tears down frontend services more cleanly.
Adds a new, substantial mqtt.service.js that manages MQTT connections, publishing, subscribing, lifecycle cleanup, payload serialization, and validation.
Renames the messaging service class/file to post-message.service.js and updates consumers accordingly.
Updates app bootstrap (main.js) to use the new orchestrator and initialize services through it.
Adjusts a drawer helper and product assistant store to reference the new service setup.
Adds @types/mqtt to dev dependencies.
Includes extensive unit tests for the new MQTT service and related service wiring.

Related Issue(s)

closes #6962

Checklist

Labels

Includes a DB migration? -> add the area:migration label

…rchestrator`, add MQTT service integration, and update dependencies

…es across the codebase

…arity (`$connections` to `$clients`, `$mqttClient` to `$mqtt`) and update all references accordingly

…tClient`, update method names and references for consistency

…ation queue to ensure serialized client creation and destruction

… promise

…ties in `MqttService`

…dling, error cases, and payload normalization logic

…ost-message.service`

…eanup, singleton behavior, and service dependency injection

codecov · 2026-03-31T13:16:25Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.29%. Comparing base (7fc8fdf) to head (6b20341).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7004   +/-   ##
=======================================
  Coverage   76.29%   76.29%           
=======================================
  Files         405      405           
  Lines       20348    20348           
  Branches     4895     4895           
=======================================
  Hits        15525    15525           
  Misses       4823     4823

Flag	Coverage Δ
backend	`76.29% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ce runtime contract validation, clean up custom disposal logic, and update unit tests

…th `post-message` service

…lated components for consistency.

… enhance error handling; update unit tests to reflect changes.

…-out of connection waiting, and update unit tests accordingly.

…qtt-fe-scaffolding

…e reconnect attempts; enhance error handling, adjust lifecycle logic, and update unit tests accordingly.

# Conflicts: # frontend/src/main.js # frontend/src/services/bootstrap.service.js # frontend/src/services/post-message.service.js # frontend/src/services/service.factory.js # package-lock.json # package.json

n-lark · 2026-04-16T14:08:44Z

+    setupReadyPromise(): void
+    waitForAppMount(): Promise<void>
+    waitForRouterReady(): Promise<void>
+    checkUser(): Promise<unknown>


Lets not use <unknown> here please - could probably be Promise<void> from looking at the implementation.

n-lark

Hey! This is just the typescript stuff I found I will also poke this with a stick - great work so excited to see .ts files in the codebase!

Update - I poked with a stick and didn't find anything unusual.

n-lark · 2026-04-16T14:40:02Z

+        this.$app = app
+        this.$router = router
+        this.$services = services
+    }


{ name: string } & CreateServiceOptions - this is an implicit any.

n-lark · 2026-04-16T14:43:20Z

+
+    protected $router: Router = null
+
+    protected $services: ServiceInstances = null


protected $app: Maybe<App> = null protected $router: Maybe<Router> = null protected $services: Maybe<ServiceInstances> = null

These could utilize the Maybe<T> - that should probably be an exported shared utility type.

export type Maybe<T> = T | null | undefined

n-lark · 2026-04-16T14:44:59Z

-        this.$services = services
+class BootstrapService extends BaseService implements BootstrapServiceI {
+    protected isReady: boolean = false
+    protected readyPromise: Promise<never> | null = null


Promise<void>?

n-lark · 2026-04-16T14:45:27Z

@@ -116,15 +117,7 @@ class BootstrapService {

 let BootstrapServiceInstance = null


Maybe<BootstrapService>

n-lark · 2026-04-16T14:55:59Z

+            }
+            client.on(eventName, wrapped)
+            managed.listeners.add(() => client.off(eventName, wrapped))
+        }


Two anys here - could we benefit from a generic in this?

bindManagedListeners (managed: ManagedMqttClient, client: MqttClient) { const register = <K extends keyof MqttClientEventCallbacks>( eventName: K, handler: MqttClientEventCallbacks[K] ) => { const wrapped = ((...args: Parameters<MqttClientEventCallbacks[K]>) => { if (managed.destroyed || this.$destroyed || managed.client !== client) return ;(handler as Function)(...args) }) as MqttClientEventCallbacks[K] client.on(eventName, wrapped) managed.listeners.add(() => client.off(eventName, wrapped)) } register('connect', async () => { /* ... */ }) register('close', () => { /* ... */ }) register('error', (error: Error) => { /* ... */ }) register('message', (topic: string, message: Buffer, packet: IPublishPacket) => { /* ... */ }) }

n-lark · 2026-04-16T16:19:00Z

    }
 }

 let MessagingServiceInstance = null


Maybe<PostMessageService>

n-lark · 2026-04-16T16:19:55Z

+     */
+    $app: App = null
+
+    $router: Router = null


$app: Maybe<App> = null $router: Maybe<Router> = null

n-lark · 2026-04-16T16:20:23Z

+}
+
+// Create a singleton factory instance
+let orchestratorInstance = null


Maybe<ServiceOrchestrator>

n-lark · 2026-04-16T16:25:12Z

+    }
+
+    async dispose () {
+        for (const service of Object.keys(this.$serviceInstances)) {


So Object.keys loses the type inference and returns Array<string> - can just cast here. Will yell at you in strict mode.

for (const service of Object.keys(this.$serviceInstances) as Array<keyof ServiceInstances>) { await this.$serviceInstances[service]?.destroy?.() // is now BootstrapServiceI | PostMessageServiceI | MqttServiceI | null this.$serviceInstances[service] = null }

n-lark · 2026-04-16T16:31:10Z

+    { key: 'bootstrap', create: createBootstrapService, requiredLifecycle: ['init', 'destroy'] },
+    { key: 'postMessage', create: createMessagingService, requiredLifecycle: ['destroy'] },
+    { key: 'mqtt', create: createMqttService, requiredLifecycle: ['destroy'] }
+]


You do get an implicit type here but if you want the key to not be string could do this:

export default [ { key: 'bootstrap' as const, create: createBootstrapService, requiredLifecycle: ['init', 'destroy'] as const }, { key: 'postMessage' as const, create: createMessagingService, requiredLifecycle: ['destroy'] as const }, { key: 'mqtt' as const, create: createMqttService, requiredLifecycle: ['destroy'] as const } ]

Without this, key is string and can't safely index ServiceInstances:

for (const serviceDefinition of SERVICE_REGISTRY) { this.$serviceInstances[serviceDefinition.key] = serviceDefinition.create({ ... }) // .key is a string so cannot index errrr }

…ugh the serviceOrchestrator

cstns added 14 commits March 30, 2026 14:00

Refactor service management: replace ServiceFactory with `ServicesO…

9f34443

…rchestrator`, add MQTT service integration, and update dependencies

Rename MessagingService to PostMessageService and update referenc…

72bc909

…es across the codebase

Refactor MqttService: rename internal properties and methods for cl…

e649974

…arity (`$connections` to `$clients`, `$mqttClient` to `$mqtt`) and update all references accordingly

Remove debug log from MqttService publish method

b9cd3ab

Add clientId support to MqttService configuration options

029fc91

Refactor MqttService: rename ManagedMqttConnection to `ManagedMqt…

e56a9d7

…tClient`, update method names and references for consistency

Add unit tests for MqttService and implement per-key lifecycle oper…

0190664

…ation queue to ensure serialized client creation and destruction

Ensure proper cleanup of MQTT client connections using callback-based…

05fa58e

… promise

Add connection check before MQTT topic unsubscription in MqttService

46c9a2f

Add custom payload serialization modes and unit tests to MqttService

7e6cfee

Add circular payload detection and unit tests to MqttService

7225123

Add validation for publishMessage options and normalize MQTT proper…

ec9637c

…ties in `MqttService`

Expand MqttService unit tests to cover lifecycle methods, event han…

21b76a5

…dling, error cases, and payload normalization logic

Update mocked service in product-assistant store unit tests to use `p…

050e8b1

…ost-message.service`

cstns self-assigned this Mar 31, 2026

cstns marked this pull request as draft March 31, 2026 13:00

cstns changed the title ~~Expert/mqtt fe scaffolding~~ Expert/mqtt FrontEnd scaffolding Mar 31, 2026

cstns temporarily deployed to staging March 31, 2026 13:04 — with GitHub Actions Inactive

Add unit tests for ServicesOrchestrator to cover initialization, cl…

2ee32f2

…eanup, singleton behavior, and service dependency injection

cstns added 2 commits March 31, 2026 17:30

Refactor service lifecycle management: implement BaseService, enfor…

cb7a74c

…ce runtime contract validation, clean up custom disposal logic, and update unit tests

Update unit tests in ServicesOrchestrator to replace messaging wi…

dde8c0e

…th `post-message` service

cstns temporarily deployed to staging March 31, 2026 14:47 — with GitHub Actions Inactive

cstns requested a review from Steve-Mcl March 31, 2026 14:49

Rename post-message to postMessage across services, tests, and re…

eb660d2

…lated components for consistency.

cstns temporarily deployed to staging March 31, 2026 17:28 — with GitHub Actions Inactive

cstns added 2 commits April 1, 2026 11:33

improve connection management, standardize payload normalization, and…

d670086

… enhance error handling; update unit tests to reflect changes.

Expand MQTT service type definitions, enhance publishMessage to opt…

8a4f0c6

…-out of connection waiting, and update unit tests accordingly.

cstns temporarily deployed to staging April 1, 2026 09:23 — with GitHub Actions Inactive

Merge remote-tracking branch 'refs/remotes/origin/main' into expert/m…

8d66c68

…qtt-fe-scaffolding

cstns temporarily deployed to staging April 1, 2026 09:30 — with GitHub Actions Inactive

Merge branch 'main' into expert/mqtt-fe-scaffolding

400dd79

cstns temporarily deployed to staging April 7, 2026 10:12 — with GitHub Actions Inactive

Mark terminal connection failures in MqttService to prevent infinit…

03f683e

…e reconnect attempts; enhance error handling, adjust lifecycle logic, and update unit tests accordingly.

cstns temporarily deployed to staging April 7, 2026 15:05 — with GitHub Actions Inactive

cstns marked this pull request as ready for review April 7, 2026 15:08

Merge branch 'refs/heads/main' into expert/mqtt-fe-scaffolding

5131417

# Conflicts: # frontend/src/main.js # frontend/src/services/bootstrap.service.js # frontend/src/services/post-message.service.js # frontend/src/services/service.factory.js # package-lock.json # package.json

cstns temporarily deployed to staging April 16, 2026 10:45 — with GitHub Actions Inactive

convert services to ts

995ee09

cstns temporarily deployed to staging April 16, 2026 13:31 — with GitHub Actions Inactive

use the mqtt service interface in the service registry type definition

4bdb8b4

cstns temporarily deployed to staging April 16, 2026 14:06 — with GitHub Actions Inactive

n-lark reviewed Apr 16, 2026

View reviewed changes

n-lark requested changes Apr 16, 2026

View reviewed changes

fix direct import of postMessage service, all services should go thro…

6b20341

…ugh the serviceOrchestrator

cstns temporarily deployed to staging April 17, 2026 15:38 — with GitHub Actions Inactive


		protected $router: Router = null

		protected $services: ServiceInstances = null

		@@ -116,15 +117,7 @@ class BootstrapService {

		let BootstrapServiceInstance = null

Conversation

cstns commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue(s)

Checklist

Labels

Uh oh!

codecov bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

n-lark Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

n-lark left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cstns commented Mar 31, 2026 •

edited

Loading

codecov bot commented Mar 31, 2026 •

edited

Loading

n-lark Apr 16, 2026 •

edited

Loading

n-lark left a comment •

edited

Loading