feat: ama-mfe consumer accept semver messages

Author: mrednic-1A

packages/@ama-mfe/messages/README.md

@@ -15,3 +15,14 @@ The message interfaces exposed in this package cover common use cases such as:
 - [Theme](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40ama-mfe/ng-utils/src/theme/: a host application requests its embedded module to apply a common css theme. 
 
 Messages are identified thanks to their type property and are versioned for backward compatibility.
+
+## Navigation messages
+### v1.0
+Carries the target `url` only.
+
+### v1.1
+Adds an optional `extras` field to forward a subset of Angular `NavigationExtras` across the iframe boundary so the
+receiving router can reproduce the original history/location semantics. Currently supports:
+- `replaceUrl`: when set, the host navigates by replacing the current history entry instead of pushing a new one. This is
+  the key fix for modules that call `router.navigate(..., { replaceUrl: true })` to skip a route from history — without
+  forwarding, the host still pushes a new entry and the browser back button gets stuck in a loop.

packages/@ama-mfe/messages/src/messages/core.ts

@@ -0,0 +1,11 @@
+import type {
+  VersionedMessage,
+} from '@amadeus-it-group/microfrontends';
+
+/** Base structure for all versioned messages in the communication protocol. */
+export interface StrictTypedVersionedMessage<V extends string, T extends string> extends VersionedMessage {
+  /** @inheritdoc */
+  version: V;
+  /** @inheritdoc */
+  type: T;
+}

packages/@ama-mfe/messages/src/messages/navigation/base.ts

@@ -1,2 +1,9 @@
+import type {
+  StrictTypedVersionedMessage,
+} from '../core';
+
 /** The navigation message type used at communication with iframes */
 export const NAVIGATION_MESSAGE_TYPE = 'navigation';
+
+/** Versioned navigation message */
+export interface VersionedNavigationMessage<V extends string> extends StrictTypedVersionedMessage<V, typeof NAVIGATION_MESSAGE_TYPE> {}

packages/@ama-mfe/messages/src/messages/navigation/navigation-versions.ts

@@ -1,39 +1,32 @@
 import type {
-  VersionedMessage,
-} from '@amadeus-it-group/microfrontends';
-import type {
-  NAVIGATION_MESSAGE_TYPE,
+  VersionedNavigationMessage,
 } from './base';
 
-/**
- * The navigation message object sent via the communication protocol.
- * Used in microfrontend architecture based on iframes where an iframe change its url and notify its parent with the url change
- * The parent should update its own url with the information received in order to allow the refresh and the deep link share
- */
-export interface NavigationV1_0 extends VersionedMessage {
-  /** @inheritdoc */
-  type: typeof NAVIGATION_MESSAGE_TYPE;
-  /** @inheritdoc */
-  version: '1.0';
+/** Navigation content for version 1.0 */
+export interface NavigationContentV1_0 {
   /** The url updated */
   url: string;
 }
 
 /**
  * The navigation message object sent via the communication protocol.
- * Carries a subset of NavigationExtras alongside the updated url so the receiving router
- * can reproduce the original history/location semantics (e.g. skipping a route from history).
+ * Used in microfrontend architecture based on iframes where an iframe change its url and notify its parent with the url change
+ * The parent should update its own url with the information received in order to allow the refresh and the deep link share
  */
-export interface NavigationV1_1 extends VersionedMessage {
-  /** @inheritdoc */
-  type: typeof NAVIGATION_MESSAGE_TYPE;
-  /** @inheritdoc */
-  version: '1.1';
-  /** The url updated */
-  url: string;
+export interface NavigationV1_0 extends NavigationContentV1_0, VersionedNavigationMessage<'1.0'> {}
+
+/** Navigation content for version 1.1 */
+export interface NavigationContentV1_1 extends NavigationContentV1_0 {
   /** Subset of NavigationExtras forwarded across the iframe boundary. */
   extras?: {
     /** Navigate while replacing the current history entry instead of pushing a new one. */
     replaceUrl?: boolean;
   };
 }
+
+/**
+ * The navigation message object sent via the communication protocol.
+ * Carries a subset of NavigationExtras alongside the updated url so the receiving router
+ * can reproduce the original history/location semantics (e.g. skipping a route from history).
+ */
+export interface NavigationV1_1 extends NavigationContentV1_1, VersionedNavigationMessage<'1.1'> {}

packages/@ama-mfe/messages/src/public_api.ts

@@ -1,3 +1,4 @@
+export * from './messages/core';
 export * from './messages/history/index';
 export * from './messages/navigation/index';
 export * from './messages/resize/index';

packages/@ama-mfe/ng-utils/README.md

@@ -180,6 +180,21 @@ export interface CustomMessageV1_0 extends Message {
 export type CustomMessageVersions = CustomMessageV1_0;
 ```
 
+#### Message version compatibility
+The `ConsumerManagerService` dispatches incoming messages with a semver-compatible fallback, applied uniformly to every
+message type in this package (navigation, theme, resize, user-activity, history, and custom messages).
+
+Within a major version, a consumer's highest declared minor ≤ the incoming minor, is used. This lets producers add
+optional fields in a new minor version (e.g. `v1.1`) without breaking consumers that only implement `v1.0` — the older
+handler runs and simply ignores the unknown fields.
+
+Majors are isolated — no cross-major fallback in either direction:
+- An incoming v2.x will never fall back to a v1.x handler (breaking changes are expected across majors).
+- A consumer declaring only v2.x will not match an incoming v1.x (the consumer is ahead of the producer).
+
+Both cross-major cases produce a `version_mismatch` error. Introducing a new major version therefore requires coordinated
+updates on both the producer and consumer sides.
+
 #### Consumer
 A consumer should implement the `MessageConsumer` interface and inject the `ConsumeManagerService` which handles the
 registration to the communication protocol.

packages/@ama-mfe/ng-utils/src/managers/consumer-manager-service.spec.ts

@@ -203,4 +203,122 @@ describe('ConsumerManagerService', () => {
     expect(loggerServiceMock.error).toHaveBeenCalledWith('Error while consuming message', internalError);
     expect(errorHelpers.sendError).toHaveBeenCalledWith(messagePeerService, { reason: 'internal_error', source: message.payload });
   });
+
+  describe('semver-compatible dispatch', () => {
+    it('should fall back to the highest declared minor when the incoming minor is newer', async () => {
+      const handlerV10 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerV10 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.1' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV10).toHaveBeenCalledWith(message);
+      expect(loggerServiceMock.warn).not.toHaveBeenCalled();
+    });
+
+    it('should prefer the exact minor when declared', async () => {
+      const handlerV10 = jest.fn();
+      const handlerV11 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerV10, 1.1: handlerV11 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.1' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV11).toHaveBeenCalledWith(message);
+      expect(handlerV10).not.toHaveBeenCalled();
+    });
+
+    it('should pick the highest compatible minor lower than or equal to the incoming minor', async () => {
+      const handlerV10 = jest.fn();
+      const handlerV12 = jest.fn();
+      const handlerV15 = jest.fn();
+      const consumer: BasicMessageConsumer = {
+        type: 'base_message',
+        supportedVersions: { '1.0': handlerV10, 1.2: handlerV12, 1.5: handlerV15 }
+      };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.3' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV12).toHaveBeenCalledWith(message);
+      expect(handlerV10).not.toHaveBeenCalled();
+      expect(handlerV15).not.toHaveBeenCalled();
+    });
+
+    it('should not cross major version boundaries when the consumer only declares an older major', async () => {
+      const handlerV10 = jest.fn();
+      const handlerV11 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerV10, 1.1: handlerV11 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '2.0' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV10).not.toHaveBeenCalled();
+      expect(handlerV11).not.toHaveBeenCalled();
+      expect(loggerServiceMock.warn).toHaveBeenCalledWith('No consumer found for message version: 2.0');
+      expect(errorHelpers.sendError).toHaveBeenCalledWith(messagePeerService, { reason: 'version_mismatch', source: message.payload });
+    });
+
+    it('should not match a consumer that only declares a newer major than the incoming message', async () => {
+      const handlerV20 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '2.0': handlerV20 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.5' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV20).not.toHaveBeenCalled();
+      expect(loggerServiceMock.warn).toHaveBeenCalledWith('No consumer found for message version: 1.5');
+      expect(errorHelpers.sendError).toHaveBeenCalledWith(messagePeerService, { reason: 'version_mismatch', source: message.payload });
+    });
+
+    it('should dispatch within the matching major when the consumer declares multiple majors', async () => {
+      const handlerV10 = jest.fn();
+      const handlerV20 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerV10, '2.0': handlerV20 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '2.3' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV20).toHaveBeenCalledWith(message);
+      expect(handlerV10).not.toHaveBeenCalled();
+    });
+
+    it('should not match a consumer declaring only a higher minor within the same major', async () => {
+      const handlerV11 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { 1.1: handlerV11 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.0' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV11).not.toHaveBeenCalled();
+      expect(errorHelpers.sendError).toHaveBeenCalledWith(messagePeerService, { reason: 'version_mismatch', source: message.payload });
+    });
+
+    it('should reject malformed incoming version strings', async () => {
+      const handlerV10 = jest.fn();
+      const consumer: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerV10 } };
+      service.register(consumer);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: 'not-a-version' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerV10).not.toHaveBeenCalled();
+      expect(errorHelpers.sendError).toHaveBeenCalledWith(messagePeerService, { reason: 'version_mismatch', source: message.payload });
+    });
+
+    it('should resolve each consumer to its own best-matching minor when multiple consumers share a type', async () => {
+      const handlerAV10 = jest.fn();
+      const handlerBV10 = jest.fn();
+      const handlerBV11 = jest.fn();
+      const consumerA: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerAV10 } };
+      const consumerB: BasicMessageConsumer = { type: 'base_message', supportedVersions: { '1.0': handlerBV10, 1.1: handlerBV11 } };
+      service.register(consumerA);
+      service.register(consumerB);
+      const message: RoutedMessage<VersionedMessage> = { payload: { type: 'base_message', version: '1.1' }, from: 'a', to: [] };
+      messagesSubjectMock.next(message);
+      await jest.runAllTimersAsync();
+      expect(handlerAV10).toHaveBeenCalledWith(message);
+      expect(handlerBV11).toHaveBeenCalledWith(message);
+      expect(handlerBV10).not.toHaveBeenCalled();
+    });
+  });
 });

packages/@ama-mfe/ng-utils/src/managers/consumer-manager-service.ts

@@ -31,6 +31,27 @@ import {
   ProducerManagerService,
 } from './producer-manager-service';
 
+const VERSION_MATCH = /^(\d+)\.(\d+)$/;
+
+interface ParsedVersion {
+  major: number;
+  minor: number;
+  raw: string;
+}
+
+/**
+ * Parses a "major.minor" version string. Returns undefined if the string is malformed.
+ * @param version
+ */
+const parseVersion = (version: string): ParsedVersion | undefined => {
+  const match = VERSION_MATCH.exec(version);
+  if (!match) {
+    return undefined;
+  }
+  const [major, minor] = match.slice(1).map(Number);
+  return { major, minor, raw: version };
+};
+
 @Injectable({
   providedIn: 'root'
 })
@@ -46,7 +67,7 @@ export class ConsumerManagerService {
   constructor() {
     this.messageService.messages$.pipe(takeUntilDestroyed()).subscribe((message) => this.consumeMessage(message));
 
-    // Each time a consumer is registered/unregistered update the list of registered messages
+    // Each time a consumer is registered/unregistered update the list of registered messages.
     effect(() => {
       const declareMessages = getAvailableConsumers(this.consumers());
 
@@ -93,20 +114,37 @@ export class ConsumerManagerService {
       return sendError(this.messageService, { reason: 'unknown_type', source: message.payload });
     }
 
-    const versionMatchingConsumers = typeMatchingConsumers
-      .filter((consumer) => consumer.supportedVersions[message.payload.version])
-      .flat();
+    // Semver-compatible dispatch: for an incoming v{major}.{minor}, pick each consumer's highest
+    // declared v{major}.{n} where n <= minor.
+    // Major versions are isolated: no cross-major fallback in either direction. An incoming v2.x
+    // will never fall back to a v1.x handler (breaking changes), and a consumer that declares
+    // only v2.x will not match an incoming v1.x (the consumer is ahead of the producer). Both
+    // result in a version_mismatch error.
+    const messageVersion = parseVersion(message.payload.version);
+    const resolvedConsumers = messageVersion
+      ? typeMatchingConsumers
+        .map((consumer) => {
+          const fallbackVersion = Object.keys(consumer.supportedVersions)
+            .map((version) => parseVersion(version))
+            .filter((v): v is ParsedVersion =>
+              !!v && v.major === messageVersion.major && v.minor <= messageVersion.minor)
+            .toSorted((a, b) => b.minor - a.minor)
+            .at(0);
+          return fallbackVersion && { consumer, version: fallbackVersion.raw };
+        })
+        .filter((entry): entry is { consumer: typeof typeMatchingConsumers[number]; version: string } => !!entry)
+      : [];
 
-    if (versionMatchingConsumers.length === 0) {
+    if (resolvedConsumers.length === 0) {
       this.logger.warn(`No consumer found for message version: ${message.payload.version}`);
       return sendError(this.messageService, { reason: 'version_mismatch', source: message.payload });
     }
 
     await Promise.all(
-      versionMatchingConsumers
-        .map(async (consumer) => {
+      resolvedConsumers
+        .map(async ({ consumer, version }) => {
           try {
-            await consumer.supportedVersions[message.payload.version](message);
+            await consumer.supportedVersions[version](message);
           } catch (error) {
             this.logger.error('Error while consuming message', error);
             sendError(this.messageService, { reason: 'internal_error', source: message.payload });

packages/@ama-mfe/ng-utils/src/navigation/README.md

@@ -54,3 +54,10 @@ the module route history.
 `memorizeRoute` will record the navigation history in the iframe.
 `restoreRoute` will forward the host query parameters to the iframe and look for the navigation history associated to the
 `memoryChannelId`.
+
+## Message versions
+Message shapes and versions are documented in the
+[@ama-mfe/messages README](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40ama-mfe/messages/README.md#navigation-messages).
+The producer always emits the latest version; consumers benefit from the semver fallback described in the
+[package README](../../README.md#message-version-compatibility), so an older consumer still receives the navigation and
+just ignores any unknown fields.

packages/@ama-mfe/ng-utils/src/navigation/navigation-consumer-service.spec.ts

@@ -1,8 +1,8 @@
-import {
-  NavigationMessage,
+import type {
+  NavigationV1_0,
   NavigationV1_1,
 } from '@ama-mfe/messages';
-import {
+import type {
   RoutedMessage,
 } from '@amadeus-it-group/microfrontends';
 import {
@@ -65,7 +65,7 @@ describe('Navigation Handler Service', () => {
 
   it('should call navigate when a supported message is received', () => {
     jest.spyOn(navHandlerService as any, 'navigate');
-    const navMessage: RoutedMessage<NavigationMessage> = {
+    const navMessage: RoutedMessage<NavigationV1_0> = {
       from: 'test',
       to: [],
       payload: {
@@ -81,7 +81,7 @@ describe('Navigation Handler Service', () => {
   // eslint-disable-next-line jest/no-done-callback -- use the callback function to finish the test
   it('should emit via the requestedUrl observable when a supported message is received', (done) => {
     jest.spyOn(navHandlerService as any, 'navigate');
-    const navMessage: RoutedMessage<NavigationMessage> = {
+    const navMessage: RoutedMessage<NavigationV1_0> = {
       from: 'test',
       to: [],
       payload: {
@@ -100,7 +100,7 @@ describe('Navigation Handler Service', () => {
 
   it('should call the router navigate when a supported message is received', () => {
     jest.spyOn(router, 'navigate');
-    const navMessage: RoutedMessage<NavigationMessage> = {
+    const navMessage: RoutedMessage<NavigationV1_0> = {
       from: 'test',
       to: [],
       payload: {