Add plugin status API (#75819)

Author: joshdover

docs/development/core/server/kibana-plugin-core-server.statusservicesetup.dependencies_.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [StatusServiceSetup](./kibana-plugin-core-server.statusservicesetup.md) &gt; [dependencies$](./kibana-plugin-core-server.statusservicesetup.dependencies_.md)
+
+## StatusServiceSetup.dependencies$ property
+
+Current status for all plugins this plugin depends on. Each key of the `Record` is a plugin id.
+
+<b>Signature:</b>
+
+```typescript
+dependencies$: Observable<Record<string, ServiceStatus>>;
+```

docs/development/core/server/kibana-plugin-core-server.statusservicesetup.derivedstatus_.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [StatusServiceSetup](./kibana-plugin-core-server.statusservicesetup.md) &gt; [derivedStatus$](./kibana-plugin-core-server.statusservicesetup.derivedstatus_.md)
+
+## StatusServiceSetup.derivedStatus$ property
+
+The status of this plugin as derived from its dependencies.
+
+<b>Signature:</b>
+
+```typescript
+derivedStatus$: Observable<ServiceStatus>;
+```
+
+## Remarks
+
+By default, plugins inherit this derived status from their dependencies. Calling  overrides this default status.
+
+This may emit multliple times for a single status change event as propagates through the dependency tree
+

docs/development/core/server/kibana-plugin-core-server.statusservicesetup.md

@@ -12,10 +12,73 @@ API for accessing status of Core and this plugin's dependencies as well as for c
 export interface StatusServiceSetup 
 ```
 
+## Remarks
+
+By default, a plugin inherits it's current status from the most severe status level of any Core services and any plugins that it depends on. This default status is available on the  API.
+
+Plugins may customize their status calculation by calling the  API with an Observable. Within this Observable, a plugin may choose to only depend on the status of some of its dependencies, to ignore severe status levels of particular Core services they are not concerned with, or to make its status dependent on other external services.
+
+## Example 1
+
+Customize a plugin's status to only depend on the status of SavedObjects:
+
+```ts
+core.status.set(
+  core.status.core$.pipe(
+.   map((coreStatus) => {
+      return coreStatus.savedObjects;
+    }) ;
+  );
+);
+
+```
+
+## Example 2
+
+Customize a plugin's status to include an external service:
+
+```ts
+const externalStatus$ = interval(1000).pipe(
+  switchMap(async () => {
+    const resp = await fetch(`https://myexternaldep.com/_healthz`);
+    const body = await resp.json();
+    if (body.ok) {
+      return of({ level: ServiceStatusLevels.available, summary: 'External Service is up'});
+    } else {
+      return of({ level: ServiceStatusLevels.available, summary: 'External Service is unavailable'});
+    }
+  }),
+  catchError((error) => {
+    of({ level: ServiceStatusLevels.unavailable, summary: `External Service is down`, meta: { error }})
+  })
+);
+
+core.status.set(
+  combineLatest([core.status.derivedStatus$, externalStatus$]).pipe(
+    map(([derivedStatus, externalStatus]) => {
+      if (externalStatus.level > derivedStatus) {
+        return externalStatus;
+      } else {
+        return derivedStatus;
+      }
+    })
+  )
+);
+
+```
+
 ## Properties
 
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [core$](./kibana-plugin-core-server.statusservicesetup.core_.md) | <code>Observable&lt;CoreStatus&gt;</code> | Current status for all Core services. |
+|  [dependencies$](./kibana-plugin-core-server.statusservicesetup.dependencies_.md) | <code>Observable&lt;Record&lt;string, ServiceStatus&gt;&gt;</code> | Current status for all plugins this plugin depends on. Each key of the <code>Record</code> is a plugin id. |
+|  [derivedStatus$](./kibana-plugin-core-server.statusservicesetup.derivedstatus_.md) | <code>Observable&lt;ServiceStatus&gt;</code> | The status of this plugin as derived from its dependencies. |
 |  [overall$](./kibana-plugin-core-server.statusservicesetup.overall_.md) | <code>Observable&lt;ServiceStatus&gt;</code> | Overall system status for all of Kibana. |
 
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [set(status$)](./kibana-plugin-core-server.statusservicesetup.set.md) | Allows a plugin to specify a custom status dependent on its own criteria. Completely overrides the default inherited status. |
+

docs/development/core/server/kibana-plugin-core-server.statusservicesetup.set.md

@@ -0,0 +1,28 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [StatusServiceSetup](./kibana-plugin-core-server.statusservicesetup.md) &gt; [set](./kibana-plugin-core-server.statusservicesetup.set.md)
+
+## StatusServiceSetup.set() method
+
+Allows a plugin to specify a custom status dependent on its own criteria. Completely overrides the default inherited status.
+
+<b>Signature:</b>
+
+```typescript
+set(status$: Observable<ServiceStatus>): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  status$ | <code>Observable&lt;ServiceStatus&gt;</code> |  |
+
+<b>Returns:</b>
+
+`void`
+
+## Remarks
+
+See the [StatusServiceSetup.derivedStatus$](./kibana-plugin-core-server.statusservicesetup.derivedstatus_.md) API for leveraging the default status calculation that is provided by Core.
+

rfcs/text/0010_service_status.md

@@ -137,7 +137,7 @@ interface StatusSetup {
    * Current status for all dependencies of the current plugin.
    * Each key of the `Record` is a plugin id.
    */
-  plugins$: Observable<Record<string, ServiceStatus>>;
+  dependencies$: Observable<Record<string, ServiceStatus>>;
 
   /**
    * The status of this plugin as derived from its dependencies.

src/core/server/legacy/legacy_service.ts

@@ -323,6 +323,9 @@ export class LegacyService implements CoreService {
       status: {
         core$: setupDeps.core.status.core$,
         overall$: setupDeps.core.status.overall$,
+        set: setupDeps.core.status.plugins.set.bind(null, 'legacy'),
+        dependencies$: setupDeps.core.status.plugins.getDependenciesStatus$('legacy'),
+        derivedStatus$: setupDeps.core.status.plugins.getDerivedStatus$('legacy'),
       },
       uiSettings: {
         register: setupDeps.core.uiSettings.register,

src/core/server/plugins/plugin_context.ts

@@ -185,6 +185,9 @@ export function createPluginSetupContext<TPlugin, TPluginDependencies>(
     status: {
       core$: deps.status.core$,
       overall$: deps.status.overall$,
+      set: deps.status.plugins.set.bind(null, plugin.name),
+      dependencies$: deps.status.plugins.getDependenciesStatus$(plugin.name),
+      derivedStatus$: deps.status.plugins.getDerivedStatus$(plugin.name),
     },
     uiSettings: {
       register: deps.uiSettings.register,

src/core/server/plugins/plugins_system.test.ts

@@ -100,15 +100,27 @@ test('getPluginDependencies returns dependency tree of symbols', () => {
   pluginsSystem.addPlugin(createPlugin('no-dep'));
 
   expect(pluginsSystem.getPluginDependencies()).toMatchInlineSnapshot(`
-    Map {
-      Symbol(plugin-a) => Array [
-        Symbol(no-dep),
-      ],
-      Symbol(plugin-b) => Array [
-        Symbol(plugin-a),
-        Symbol(no-dep),
-      ],
-      Symbol(no-dep) => Array [],
+    Object {
+      "asNames": Map {
+        "plugin-a" => Array [
+          "no-dep",
+        ],
+        "plugin-b" => Array [
+          "plugin-a",
+          "no-dep",
+        ],
+        "no-dep" => Array [],
+      },
+      "asOpaqueIds": Map {
+        Symbol(plugin-a) => Array [
+          Symbol(no-dep),
+        ],
+        Symbol(plugin-b) => Array [
+          Symbol(plugin-a),
+          Symbol(no-dep),
+        ],
+        Symbol(no-dep) => Array [],
+      },
     }
   `);
 });

src/core/server/plugins/plugins_system.ts

@@ -20,10 +20,11 @@
 import { CoreContext } from '../core_context';
 import { Logger } from '../logging';
 import { PluginWrapper } from './plugin';
-import { DiscoveredPlugin, PluginName, PluginOpaqueId } from './types';
+import { DiscoveredPlugin, PluginName } from './types';
 import { createPluginSetupContext, createPluginStartContext } from './plugin_context';
 import { PluginsServiceSetupDeps, PluginsServiceStartDeps } from './plugins_service';
 import { withTimeout } from '../../utils';
+import { PluginDependencies } from '.';
 
 const Sec = 1000;
 /** @internal */
@@ -45,9 +46,19 @@ export class PluginsSystem {
    * @returns a ReadonlyMap of each plugin and an Array of its available dependencies
    * @internal
    */
-  public getPluginDependencies(): ReadonlyMap<PluginOpaqueId, PluginOpaqueId[]> {
-    // Return dependency map of opaque ids
-    return new Map(
+  public getPluginDependencies(): PluginDependencies {
+    const asNames = new Map(
+      [...this.plugins].map(([name, plugin]) => [
+        plugin.name,
+        [
+          ...new Set([
+            ...plugin.requiredPlugins,
+            ...plugin.optionalPlugins.filter((optPlugin) => this.plugins.has(optPlugin)),
+          ]),
+        ].map((depId) => this.plugins.get(depId)!.name),
+      ])
+    );
+    const asOpaqueIds = new Map(
       [...this.plugins].map(([name, plugin]) => [
         plugin.opaqueId,
         [
@@ -58,6 +69,8 @@ export class PluginsSystem {
         ].map((depId) => this.plugins.get(depId)!.opaqueId),
       ])
     );
+
+    return { asNames, asOpaqueIds };
   }
 
   public async setupPlugins(deps: PluginsServiceSetupDeps) {

src/core/server/plugins/types.ts

@@ -93,6 +93,12 @@ export type PluginName = string;
 /** @public */
 export type PluginOpaqueId = symbol;
 
+/** @internal */
+export interface PluginDependencies {
+  asNames: ReadonlyMap<PluginName, PluginName[]>;
+  asOpaqueIds: ReadonlyMap<PluginOpaqueId, PluginOpaqueId[]>;
+}
+
 /**
  * Describes the set of required and optional properties plugin can define in its
  * mandatory JSON manifest file.