feat: ama-mfe consumer accept semver messages

mrednic-1A · mrednic-1A · commit fc8bb6daa769 · 2026-05-05T08:54:28.000+02:00
diff --git a/packages/@ama-mfe/messages/README.md b/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.
diff --git a/packages/@ama-mfe/messages/src/messages/navigation/navigation-versions.ts b/packages/@ama-mfe/messages/src/messages/navigation/navigation-versions.ts
@@ -24,13 +24,9 @@ export interface NavigationV1_0 extends VersionedMessage {
  * 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 VersionedMessage {
-  /** @inheritdoc */
-  type: typeof NAVIGATION_MESSAGE_TYPE;
+export interface NavigationV1_1 extends Omit<NavigationV1_0, 'version'> {
   /** @inheritdoc */
   version: '1.1';
-  /** The url updated */
-  url: string;
   /** Subset of NavigationExtras forwarded across the iframe boundary. */
   extras?: {
     /** Navigate while replacing the current history entry instead of pushing a new one. */
diff --git a/packages/@ama-mfe/ng-utils/README.md b/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.
diff --git a/packages/@ama-mfe/ng-utils/src/managers/consumer-manager-service.spec.ts b/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();
+    });
+  });
 });
diff --git a/packages/@ama-mfe/ng-utils/src/managers/consumer-manager-service.ts b/packages/@ama-mfe/ng-utils/src/managers/consumer-manager-service.ts
@@ -31,6 +31,18 @@ import {
   ProducerManagerService,
 } from './producer-manager-service';
 
+/**
+ * Parses a "major.minor" version string. Returns undefined if the string is malformed.
+ * @param version
+ */
+const parseVersion = (version: string): { major: number; minor: number; raw: string } | undefined => {
+  const match = /^(\d+)\.(\d+)$/.exec(version);
+  if (!match) {
+    return undefined;
+  }
+  return { major: Number(match[1]), minor: Number(match[2]), raw: version };
+};
+
 @Injectable({
   providedIn: 'root'
 })
@@ -46,7 +58,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 +105,36 @@ 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 { major: number; minor: number; raw: string } =>
+              !!v && v.major === messageVersion.major && v.minor <= messageVersion.minor)
+            .toSorted((a, b) => b.minor - a.minor)[0];
+          return fallbackVersion ? { consumer, version: fallbackVersion.raw } : undefined;
+        })
+        .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 });
diff --git a/packages/@ama-mfe/ng-utils/src/navigation/README.md b/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.
diff --git a/packages/@ama-mfe/ng-utils/src/navigation/navigation-consumer-service.spec.ts b/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: {
diff --git a/packages/@ama-mfe/ng-utils/src/navigation/navigation-consumer-service.ts b/packages/@ama-mfe/ng-utils/src/navigation/navigation-consumer-service.ts
@@ -71,6 +71,7 @@ export class NavigationConsumerService implements MessageConsumer<NavigationMess
      * so the host router reproduces the original history semantics.
      * @param message message to consume
      */
+    // eslint-disable-next-line @stylistic/quote-props -- keep quotes for consistency with '1.0'
     '1.1': (message: RoutedMessage<NavigationV1_1>) => {
       const channelId = message.from || undefined;
       this.requestedUrl.next({ url: message.payload.url, channelId });
diff --git a/packages/@ama-mfe/ng-utils/src/navigation/routing-service.spec.ts b/packages/@ama-mfe/ng-utils/src/navigation/routing-service.spec.ts
diff --git a/packages/@ama-mfe/ng-utils/src/navigation/routing-service.ts b/packages/@ama-mfe/ng-utils/src/navigation/routing-service.ts
