fix(web_serviceworker): Standardize DeesComms message format in service worker backend

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2025-12-04 - 7.7.1 - fix(web_serviceworker)
+Standardize DeesComms message format in service worker backend
+
+- Add createMessage helper to generate consistent TypedRequest-shaped messages (includes messageId and correlation.id/phase).
+- Replace inline postMessage payloads with createMessage(...) calls across ServiceworkerBackend (status updates, new-version broadcasts, alerts, event pushes, metrics updates, resource-cached notifications).
+- Improves message consistency and enables easier correlation/tracing of DeesComms messages; behavior should remain backward-compatible.
+
 ## 2025-12-04 - 7.7.0 - feat(typedserver)
 Add SPA fallback support to TypedServer
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@api.global/typedserver',
-  version: '7.7.0',
+  version: '7.7.1',
   description: 'A TypeScript-based project for easy serving of static files with support for live reloading, compression, and typed requests.'
 }

ts_web_serviceworker/classes.backend.ts

@@ -52,6 +52,22 @@ export class ServiceworkerBackend {
   private pendingMetricsUpdate = false;
   private readonly METRICS_THROTTLE_MS = 500;
 
+  /**
+   * Helper to create properly formatted TypedRequest messages for DeesComms
+   */
+  private createMessage<T>(method: string, request: T): any {
+    const id = `${method}_${Date.now()}`;
+    return {
+      method,
+      request,
+      messageId: id,
+      correlation: {
+        id,
+        phase: 'request' as const
+      }
+    };
+  }
+
   constructor(optionsArg: {
     self: any;
     purgeCache: (reqArg: interfaces.serviceworker.IRequest_PurgeServiceWorkerCache['request']) => Promise<interfaces.serviceworker.IRequest_PurgeServiceWorkerCache['response']>;
@@ -244,11 +260,7 @@ export class ServiceworkerBackend {
    */
   public async broadcastStatusUpdate(status: interfaces.serviceworker.IStatusUpdate): Promise<void> {
     try {
-      await this.deesComms.postMessage({
-        method: 'serviceworker_statusUpdate',
-        request: status,
-        messageId: `sw_status_${Date.now()}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_statusUpdate', status));
       logger.log('info', `Status update broadcast: ${status.source}:${status.type} - ${status.message}`);
     } catch (error) {
       logger.log('warn', `Failed to broadcast status update: ${error}`);
@@ -290,11 +302,7 @@ export class ServiceworkerBackend {
 
       // Send update message via DeesComms
       // This will be picked up by clients that have registered a handler for 'serviceworker_newVersion'
-      await this.deesComms.postMessage({
-        method: 'serviceworker_newVersion',
-        request: {},
-        messageId: `sw_update_${Date.now()}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_newVersion', {}));
 
       // As a fallback, also use the clients API to reload clients that might not catch the broadcast
       const clients = await this.swSelf.clients.matchAll({ type: 'window' });
@@ -360,11 +368,7 @@ export class ServiceworkerBackend {
 
     // Send message to clients who might be able to show an actual alert
     try {
-      await this.deesComms.postMessage({
-        method: 'serviceworker_alert',
-        request: { message: alertText },
-        messageId: `sw_alert_${Date.now()}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_alert', { message: alertText }));
       logger.log('info', `Alert message sent to clients: ${alertText}`);
     } catch (error) {
       logger.log('error', `Failed to send alert to clients: ${error instanceof Error ? error.message : String(error)}`);
@@ -381,11 +385,7 @@ export class ServiceworkerBackend {
    */
   public async pushEvent(entry: interfaces.serviceworker.IEventLogEntry): Promise<void> {
     try {
-      await this.deesComms.postMessage({
-        method: 'serviceworker_eventLogged',
-        request: entry,
-        messageId: `sw_event_${entry.id}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_eventLogged', entry));
       logger.log('note', `Pushed event to clients: ${entry.type}`);
     } catch (error) {
       logger.log('warn', `Failed to push event: ${error}`);
@@ -446,11 +446,7 @@ export class ServiceworkerBackend {
     };
 
     try {
-      await this.deesComms.postMessage({
-        method: 'serviceworker_metricsUpdate',
-        request: snapshot,
-        messageId: `sw_metrics_${Date.now()}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_metricsUpdate', snapshot));
     } catch (error) {
       logger.log('warn', `Failed to push metrics update: ${error}`);
     }
@@ -461,11 +457,7 @@ export class ServiceworkerBackend {
    */
   public async pushResourceCached(url: string, contentType: string, size: number, cached: boolean): Promise<void> {
     try {
-      await this.deesComms.postMessage({
-        method: 'serviceworker_resourceCached',
-        request: { url, contentType, size, cached },
-        messageId: `sw_resource_${Date.now()}`
-      });
+      await this.deesComms.postMessage(this.createMessage('serviceworker_resourceCached', { url, contentType, size, cached }));
     } catch (error) {
       logger.log('warn', `Failed to push resource cached: ${error}`);
     }