add review

===

chore(platform): drop deprecated API and backward compatibility

To prepare for `1.0.0` major release, deprecated API has been removed.
- support for legacy heartbeat liveness, request-response subscription and intent subscription protocols
- legacy notation for optional and required parameters
- checks for optional wildcard characters in capability and intention qualifiers

closes #196

BREAKING CHANGE: dropping deprecated API and backward compatibility introduced a breaking change for host and client applications.

To migrate:
- Update host and clients to version `1.0.0-rc.13` or higher.
- Deprecated property `ManifestService.lookupApplications$` has been removed; use `ManifestService.applications` instead.
- Deprecated property `Capability.requiredParams` has been removed; declare required parameters via `Capability.params` instead and mark it as required.
- Deprecated property `Capability.optionalParams` has been removed; declare optional parameters via `Capability.params` instead and mark it as non-required.

apps/microfrontend-platform-devtools/src/app/app.module.ts

@@ -44,6 +44,8 @@ import {Beans} from '@scion/toolkit/bean-manager';
 import {A11yModule} from '@angular/cdk/a11y';
 import {AppNamePipe} from './app-name.pipe';
 import {CustomParamMetadataPipe} from './custom-param-metadata.pipe';
+import {ParamsFilterPipe} from './params-filter.pipe';
+import {NullIfEmptyPipe} from './null-if-empty.pipe';
 
 @NgModule({
   declarations: [
@@ -64,6 +66,8 @@ import {CustomParamMetadataPipe} from './custom-param-metadata.pipe';
     QualifierChipListComponent,
     AppNamePipe,
     CustomParamMetadataPipe,
+    ParamsFilterPipe,
+    NullIfEmptyPipe,
   ],
   imports: [
     BrowserModule,

apps/microfrontend-platform-devtools/src/app/null-if-empty.pipe.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2018-2023 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import {Pipe, PipeTransform} from '@angular/core';
+
+/**
+ * Returns `null` if the given object is empty.
+ */
+@Pipe({name: 'devtoolsNullIfEmpty'})
+export class NullIfEmptyPipe implements PipeTransform {
+
+  public transform<T>(value: T): T {
+    if (value === null || value === undefined) {
+      return null;
+    }
+    else if (value instanceof Map || value instanceof Set) {
+      if (!value.size) {
+        return null;
+      }
+    }
+    else if (Array.isArray(value) || typeof value === 'string') {
+      if (!value.length) {
+        return null;
+      }
+    }
+    else if (typeof value === 'object') {
+      if (!Object.keys(value).length) {
+        return null;
+      }
+    }
+    return value;
+  }
+}

apps/microfrontend-platform-devtools/src/app/params-filter.pipe.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2018-2023 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import {Pipe, PipeTransform} from '@angular/core';
+import {ParamDefinition} from '@scion/microfrontend-platform';
+
+/**
+ * Filters required or optional parameters.
+ */
+@Pipe({name: 'devtoolsParamsFilter'})
+export class ParamsFilterPipe implements PipeTransform {
+
+  public transform(params: ParamDefinition[] | undefined | null, filter?: 'required' | 'optional'): ParamDefinition[] {
+    return params?.filter(param => !filter || (filter === 'required' ? param.required : !param.required)) ?? [];
+  }
+}

apps/microfrontend-platform-devtools/src/app/required-capabilities/required-capabilities.component.html

@@ -23,6 +23,16 @@
             <span>{{selectedCapability.description}}</span>
           </section>
 
+          <section class="required-params" *ngIf="selectedCapability.params | devtoolsParamsFilter:'required' | devtoolsNullIfEmpty as requiredParams ">
+            <header>Required Params:</header>
+            {{requiredParams.join(', ')}}
+          </section>
+
+          <section class="optional-params" *ngIf="selectedCapability.params | devtoolsParamsFilter:'optional' | devtoolsNullIfEmpty as optionalParams">
+            <header>Optional Params:</header>
+            {{optionalParams.join(', ')}}
+          </section>
+
           <section class="properties" *ngIf="selectedCapability.properties">
             <header>Properties:</header>
             <sci-property [properties]="selectedCapability.properties"></sci-property>

docs/adoc/microfrontend-platform-developer-guide/chapters/miscellaneous/compatibility/compatibility.adoc

@@ -3,7 +3,6 @@ include::{basedir}/_common.adoc[]
 
 [[chapter:compatibility-and-deprecation-policy]]
 == Compatibility and Deprecation Policy
-We are aware that you need stability from the SCION Microfrontend Platform, primarily because microfrontends with potential different lifecycles are involved. Therefore, you can expect a decent release cycle of one or two major releases per year with strict https://semver.org/[semantic versioning] policy. Changes to the communication protocol between the host and micro applications are backward compatible for at least one minor release. This allows for the host and its clients to be updated independently.
-
-Deprecation of APIs can occur in any release. Backward compatibility is mandatory for at least one minor release. Deprecated APIs are only removed in a major release.
+We are aware that you need stability from the SCION Microfrontend Platform, primarily because microfrontends with potential different lifecycles are involved. Therefore, you can expect a decent release cycle of one or two major releases per year with strict https://semver.org/[semantic versioning] policy. Changes to the communication protocol between the host and micro applications are backward compatible in the same major release. This allows for the host and its clients to update independently.
 
+Deprecation of APIs can occur in any release. Deprecated APIs are only removed in a major release.

docs/site/versioning.md

@@ -20,7 +20,9 @@ Patch versions fix bugs or optimize existing features without breaking changes.
   <img src="/docs/adoc/microfrontend-platform-developer-guide/images/semver.svg" alt="Versioning">
 </p>
 
-We are aware that you need stability from the SCION Microfrontend Platform, primarily because microfrontends with potential different lifecycles are involved. Therefore, you can expect a decent release cycle of one or two major releases per year. Changes in the communication protocol between the host and micro applications are backward compatible with the previous major version. When deprecating API, which can occur in any release, it will still be present in the next major release. Removal of deprecated API will occur only in a major release.
+We are aware that you need stability from the SCION Microfrontend Platform, primarily because microfrontends with potential different lifecycles are involved. Therefore, you can expect a decent release cycle of one or two major releases per year with strict [semantic versioning](https://semver.org) policy. Changes to the communication protocol between the host and micro applications are backward compatible in the same major release. This allows for the host and its clients to update independently.
+
+Deprecation of APIs can occur in any release. Deprecated APIs are only removed in a major release.
 
 [menu-home]: /README.md
 [menu-projects-overview]: /docs/site/projects-overview.md

projects/scion/microfrontend-platform/src/lib/client/messaging/messaging.spec.ts

@@ -1272,7 +1272,7 @@ describe('Messaging', () => {
             capabilities: [
               {
                 type: 'capability',
-                params: [{name: 'param1', required: true}, {name: 'param2', required: true}],
+                params: [{name: 'param1', required: true}],
               },
             ],
           },
@@ -1283,8 +1283,8 @@ describe('Messaging', () => {
       // publish
       const observeCaptor = new ObserveCaptor(paramsExtractFn);
       Beans.get(IntentClient).observe$<string>({type: 'capability'}).subscribe(observeCaptor);
-      await Beans.get(IntentClient).publish({type: 'capability', params: new Map().set('param1', 'value1').set('param2', 'value2')});
-      await expectEmissions(observeCaptor).toEqual(new Map().set('param1', 'value1').set('param2', 'value2'));
+      await Beans.get(IntentClient).publish({type: 'capability', params: new Map().set('param1', 'value1')});
+      await expectEmissions(observeCaptor).toEqual(new Map().set('param1', 'value1'));
     });
 
     it('should preserve data type of passed intent parameters', async () => {
@@ -1403,7 +1403,7 @@ describe('Messaging', () => {
             capabilities: [
               {
                 type: 'capability',
-                params: [{name: 'param1', required: false}, {name: 'param2', required: false}],
+                params: [{name: 'param1', required: false}],
               },
             ],
           },
@@ -1426,7 +1426,7 @@ describe('Messaging', () => {
             capabilities: [
               {
                 type: 'capability',
-                params: [{name: 'param1', required: true}, {name: 'param2', required: true}],
+                params: [{name: 'param1', required: true}],
               },
             ],
           },

projects/scion/microfrontend-platform/src/lib/host/manifest-registry/ɵmanifest-registry.ts

@@ -126,11 +126,13 @@ export class ɵManifestRegistry implements ManifestRegistry, PreDestroy {
       throw illegalQualifierError;
     }
 
+    assertCapabilityParamDefinitions(capability.params ?? []);
+
     // Let the host app intercept the capability to register.
     const capabilityToRegister = await interceptCapability({
       ...capability,
       qualifier: capability.qualifier ?? {},
-      params: coerceCapabilityParamDefinitions(capability),
+      params: capability.params ?? [],
       private: capability.private ?? true,
       metadata: {
         id: UUID.randomUUID(),
@@ -281,17 +283,6 @@ function assertIntentionRegisterApiEnabled(appSymbolicName: string): void {
   }
 }
 
-function coerceCapabilityParamDefinitions(capability: Capability): ParamDefinition[] {
-  const params: ParamDefinition[] = [];
-
-  capability.params?.forEach(param => {
-    params.push(param);
-  });
-
-  assertCapabilityParamDefinitions(params);
-  return params;
-}
-
 /**
  * Asserts given parameter definitions to be valid.
  */