Add readme doc for cross compatibility service

Signed-off-by: Manasvini B Suryanarayana <[email protected]>

src/core/public/plugins/plugin.test.ts

@@ -45,7 +45,7 @@ function createManifest(
     requiredPlugins: required,
     optionalPlugins: optional,
     requiredBundles: [],
-    requiredEnginePlugins: { 'plugin-1': 'some-version' },
+    requiredEnginePlugins: {},
   } as DiscoveredPlugin;
 }
 

src/core/server/cross_compatibility/README.md

@@ -0,0 +1,62 @@
+## Cross Compatibility Service
+
+The cross compatibility service provides a way for OpenSearch Dashboards plugins to check if they are compatible with the installed OpenSearch plugins. This allows plugins to gracefully degrade their functionality or disable themselves if they are not compatible with the current OpenSearch plugin version.
+
+### Overview
+
+OpenSearch Dashboards plugins depend on specific versions of OpenSearch plugins. When a plugin is installed, OpenSearch Dashboards checks to make sure that the required OpenSearch plugins are installed and compatible. If a required plugin is not installed or is not compatible, OpenSearch Dashboards will log a warning but will still allow the plugin to start.
+
+The cross compatibility service provides a way for plugins to check for compatibility with their OpenSearch counterparts. This allows plugins to make informed decisions about how to behave when they are not compatible. For example, a plugin could disable itself, limit its functionality, or notify the user that they are using an incompatible plugin.
+
+### Usage
+
+To use the Cross Compatibility service, plugins can call the `verifyOpenSearchPluginsState()` API. This API checks the compatibility of the plugin with the installed OpenSearch plugins. The API returns a list of `CrossCompatibilityResult` objects, which contain information about the compatibility of each plugin.
+
+The `CrossCompatibilityResult` object has the following properties:
+
+`pluginName`: The OpenSearch Plugin name.
+`isCompatible`: A boolean indicating whether the plugin is compatible.
+`incompatibilityReason`: The reason the OpenSearch Plugin version is not compatible with the plugin.
+`installedVersions`: The version of the plugin that is installed.
+
+Plugins can use the information in the `CrossCompatibilityResult` object to decide how to behave. For example, a plugin could disable itself if the `isCompatible` property is false.
+
+The `verifyOpenSearchPluginsState()` API should be called from the `start()` lifecycle method. This allows plugins to check for compatibility before they start.
+
+### Example usage inside DashboardsSample Plugin
+
+```
+export class DashboardsSamplePlugin implements Plugin<DashboardsSamplePluginSetup, DashboardsSamplePluginStart> {
+
+    public start(core: CoreStart) {
+        this.logger.debug('Dashboard sample plugin: Started');
+        exampleCompatibilityCheck(core.versionCompatibility);
+        return {};
+    }
+    ......
+
+    function exampleCompatibilityCheck(versionCompatibility: VersionCompatibilityServiceStart) {
+        const pluginName = 'DashboardsSample';
+        const result = await versionCompatibility.verifyOpenSearchPluginsState(pluginName);
+        result.forEach((mustHavePlugin) => {
+            if (mustHavePlugin.isCompatible) { // feature to enable when plugin has compatible version installed }
+            else { // logic to gracefully degrade when engine plugin counterpart is not compatible }
+        });
+        ......
+    }
+    .....
+}
+
+```
+The `exampleCompatibilityCheck()` function uses the `verifyOpenSearchPluginsState()` API to check for compatibility with the `DashboardsSample` plugin. If the plugin is compatible, the function enables the plugin's features. If the plugin is not compatible, the function gracefully degrades the plugin's functionality.
+
+### Use cases:
+
+The cross compatibility service can be used by plugins to:
+
+* Disable themselves if they are not compatible with the installed OpenSearch plugins.
+* Limit their functionality if they are not fully compatible with the installed OpenSearch plugins.
+* Notify users if they are using incompatible plugins.
+* Provide information to users about how to upgrade their plugins.
+
+The cross compatibility service is a valuable tool for developers who are building plugins for OpenSearch Dashboards. It allows plugins to be more resilient to changes in the OpenSearch ecosystem.

src/core/server/cross_compatibility/cross_compatibility_service.test.ts

@@ -26,7 +26,7 @@ describe('CrossCompatibilityService', () => {
     } as any);
 
     plugins?.set('foo', { 'os-plugin': '1.0.0 - 2.0.0' });
-    plugins?.set('bar', { 'os-plugin': '^3.0.0' });
+    plugins?.set('incompatiblePlugin', { 'os-plugin': '^3.0.0' });
     plugins?.set('test', {});
     service = new CrossCompatibilityService(mockCoreContext.create());
   });
@@ -48,8 +48,8 @@ describe('CrossCompatibilityService', () => {
     expect(results.length).toEqual(1);
     expect(results[0].pluginName).toEqual('os-plugin');
     expect(results[0].isCompatible).toEqual(true);
-    expect(results[0].incompatibleReason).toEqual('');
-    expect(results[0].installedVersions).toEqual(new Set(['1.1.0.0']));
+    expect(results[0].incompatibilityReason).toEqual('');
+    expect(results[0].installedVersions).toEqual(['1.1.0.0']);
     expect(opensearch.client.asInternalUser.cat.plugins).toHaveBeenCalledTimes(1);
   });
 
@@ -64,18 +64,18 @@ describe('CrossCompatibilityService', () => {
   });
 
   it('should return an array of CrossCompatibilityResult objects with the incompatible reason if the plugin is not installed', async () => {
-    const pluginName = 'bar';
+    const pluginName = 'incompatiblePlugin';
     const startDeps = { opensearch, plugins };
     const startResult = await service.start(startDeps);
     const results = await startResult.verifyOpenSearchPluginsState(pluginName);
     expect(results).not.toBeUndefined();
     expect(results.length).toEqual(1);
     expect(results[0].pluginName).toEqual('os-plugin');
     expect(results[0].isCompatible).toEqual(false);
-    expect(results[0].incompatibleReason).toEqual(
+    expect(results[0].incompatibilityReason).toEqual(
       'OpenSearch plugin "os-plugin" in the version range "^3.0.0" is not installed on the OpenSearch for the OpenSearch Dashboards plugin to function as expected.'
     );
-    expect(results[0].installedVersions).toEqual(new Set(['1.1.0.0']));
+    expect(results[0].installedVersions).toEqual(['1.1.0.0']);
     expect(opensearch.client.asInternalUser.cat.plugins).toHaveBeenCalledTimes(1);
   });
 });

src/core/server/cross_compatibility/cross_compatibility_service.ts

@@ -18,15 +18,17 @@ export interface StartDeps {
 
 export class CrossCompatibilityService {
   private readonly log: Logger;
+  private dashboardsPluginName?: string;
 
   constructor(coreContext: CoreContext) {
-    this.log = coreContext.logger.get('version-compatibility-service');
+    this.log = coreContext.logger.get('cross-compatibility-service');
   }
 
   start({ opensearch, plugins }: StartDeps): CrossCompatibilityServiceStart {
-    this.log.warn('Starting version compatibility service');
+    this.log.warn('Starting cross compatibility service');
     return {
       verifyOpenSearchPluginsState: (pluginName: string) => {
+        this.dashboardsPluginName = pluginName;
         const pluginOpenSearchDeps = plugins.get(pluginName) || {};
         return this.verifyOpenSearchPluginsState(opensearch, pluginOpenSearchDeps);
       },
@@ -66,15 +68,15 @@ export class CrossCompatibilityService {
       results.push({
         pluginName,
         isCompatible: !isCompatible ? false : true,
-        incompatibleReason: !isCompatible
+        incompatibilityReason: !isCompatible
           ? `OpenSearch plugin "${pluginName}" in the version range "${versionRange}" is not installed on the OpenSearch for the OpenSearch Dashboards plugin to function as expected.`
           : '',
         installedVersions: installedPluginVersions,
       });
 
       if (!isCompatible) {
         this.log.warn(
-          `OpenSearch plugin "${pluginName}" is not installed on the cluster for the OpenSearch Dashboards plugin to function as expected.`
+          `OpenSearch plugin "${pluginName}" is not installed on the cluster for the OpenSearch Dashboards plugin "${this.dashboardsPluginName}" to function as expected.`
         );
       }
     }
@@ -85,7 +87,7 @@ export class CrossCompatibilityService {
     opensearch: OpenSearchServiceStart,
     pluginOpenSearchDeps: CompatibleEnginePluginVersions
   ): Promise<CrossCompatibilityResult[]> {
-    this.log.warn('Checking OpenSearch Plugin version compatibility');
+    this.log.info('Checking OpenSearch Plugin version compatibility');
     // make _cat/plugins?format=json call to the OpenSearch instance
     const opensearchInstalledPlugins = await this.getOpenSearchPlugins(opensearch);
     const results = await this.checkPluginVersionCompatibility(
@@ -110,6 +112,6 @@ export class CrossCompatibilityService {
         }
       }
     });
-    return { isCompatible, installedPluginVersions };
+    return { isCompatible, installedPluginVersions: [...installedPluginVersions] };
   }
 }

src/core/types/cross_compatibility.ts

@@ -15,11 +15,11 @@ export interface CrossCompatibilityResult {
    * The reason the OpenSearch Plugin version is not compatible with the plugin.
    * This will be `undefined` if the OpenSearch Plugin version is compatible.
    */
-  incompatibleReason?: string;
+  incompatibilityReason?: string;
 
   /**
-   * The set of versions of dependency OpenSearch Plugin if any present on the cluster.
-   * This will be empty set if the OpenSearch Plugin is not present.
+   * The array of versions of dependency OpenSearch Plugin if any present on the cluster.
+   * This will be empty if the OpenSearch Plugin is not present.
    */
-  installedVersions: Set<string>;
+  installedVersions: string[];
 }