[Core] [UA] Support API Deprecations

packages/core/deprecations/core-deprecations-browser-internal/src/deprecations_client.ts

@@ -8,7 +8,7 @@
  */
 
 import { i18n } from '@kbn/i18n';
-import type { HttpStart } from '@kbn/core-http-browser';
+import type { HttpFetchOptionsWithPath, HttpStart } from '@kbn/core-http-browser';
 import type {
   DomainDeprecationDetails,
   DeprecationsGetResponse,
@@ -47,31 +47,70 @@ export class DeprecationsClient {
     return typeof details.correctiveActions.api === 'object';
   };
 
-  public resolveDeprecation = async (
+  private getResolveFetchDetails = (
     details: DomainDeprecationDetails
-  ): Promise<ResolveDeprecationResponse> => {
+  ): HttpFetchOptionsWithPath | undefined => {
     const { domainId, correctiveActions } = details;
-    // explicit check required for TS type guard
-    if (typeof correctiveActions.api !== 'object') {
-      return {
-        status: 'fail',
-        reason: i18n.translate('core.deprecations.noCorrectiveAction', {
-          defaultMessage: 'This deprecation cannot be resolved automatically.',
-        }),
-      };
-    }
 
-    const { body, method, path, omitContextFromBody = false } = correctiveActions.api;
-    try {
-      await this.http.fetch<void>({
+    if (correctiveActions.api) {
+      const { body, method, path, omitContextFromBody = false } = correctiveActions.api;
+
+      return {
         path,
         method,
         asSystemRequest: true,
         body: JSON.stringify({
           ...body,
           ...(omitContextFromBody ? {} : { deprecationDetails: { domainId } }),
         }),
-      });
+      };
+    }
+
+    if (correctiveActions.mark_as_resolved_api) {
+      const { routeMethod, routePath, routeVersion, apiTotalCalls, totalMarkedAsResolved } =
+        correctiveActions.mark_as_resolved_api;
+      const incrementBy = apiTotalCalls - totalMarkedAsResolved;
+
+      return {
+        path: '/api/deprecations/mark_as_resolved/',
+        method: 'POST',
+        asSystemRequest: true,
+        body: JSON.stringify({
+          domainId,
+          routeMethod,
+          routePath,
+          routeVersion,
+          incrementBy,
+        }),
+      };
+    }
+  };
+
+  public resolveDeprecation = async (
+    details: DomainDeprecationDetails
+  ): Promise<ResolveDeprecationResponse> => {
+    const { correctiveActions } = details;
+    const noCorrectiveActionFail = {
+      status: 'fail' as const,
+      reason: i18n.translate('core.deprecations.noCorrectiveAction', {
+        defaultMessage: 'This deprecation cannot be resolved automatically or marked as resolved.',
+      }),
+    };
+
+    if (
+      typeof correctiveActions.api !== 'object' &&
+      typeof correctiveActions.mark_as_resolved_api !== 'object'
+    ) {
+      return noCorrectiveActionFail;
+    }
+
+    try {
+      const fetchParams = this.getResolveFetchDetails(details);
+      if (!fetchParams) {
+        return noCorrectiveActionFail;
+      }
+
+      await this.http.fetch<void>(fetchParams);
       return { status: 'ok' };
     } catch (err) {
       return {

packages/core/deprecations/core-deprecations-common/src/types.ts

@@ -39,7 +39,7 @@ export interface BaseDeprecationDetails {
    * Predefined types are necessary to reduce having similar definitions with different keywords
    * across kibana deprecations.
    */
-  deprecationType?: 'config' | 'feature';
+  deprecationType?: 'config' | 'api' | 'feature';
   /** (optional) link to the documentation for more details on the deprecation. */
   documentationUrl?: string;
   /** (optional) specify the fix for this deprecation requires a full kibana restart. */
@@ -70,9 +70,31 @@ export interface BaseDeprecationDetails {
      * Check the README for writing deprecations in `src/core/server/deprecations/README.mdx`
      */
     manualSteps: string[];
+    /**
+     * (optional) The api to be called to mark the deprecation as resolved
+     * This corrective action when called should not resolve the deprecation
+     * instead it helps users track manually deprecated apis
+     * If the API used does resolve the deprecation use `correctiveActions.api`
+     */
+    mark_as_resolved_api?: {
+      apiTotalCalls: number;
+      totalMarkedAsResolved: number;
+      timestamp: Date | number | string;
+      routePath: string;
+      routeMethod: string;
+      routeVersion?: string;
+    };
   };
 }
 
+/**
+ * @public
+ */
+export interface ApiDeprecationDetails extends BaseDeprecationDetails {
+  apiId: string;
+  deprecationType: 'api';
+}
+
 /**
  * @public
  */
@@ -91,7 +113,10 @@ export interface FeatureDeprecationDetails extends BaseDeprecationDetails {
 /**
  * @public
  */
-export type DeprecationsDetails = ConfigDeprecationDetails | FeatureDeprecationDetails;
+export type DeprecationsDetails =
+  | ConfigDeprecationDetails
+  | ApiDeprecationDetails
+  | FeatureDeprecationDetails;
 
 /**
  * @public

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { Logger } from '@kbn/logging';
+import type { InternalHttpServiceSetup } from '@kbn/core-http-server-internal';
+import type { InternalCoreUsageDataSetup } from '@kbn/core-usage-data-base-server-internal';
+import type { RouterDeprecatedRouteDetails } from '@kbn/core-http-server';
+import type { DeprecationsFactory } from '../deprecations_factory';
+import {
+  getApiDeprecationMessage,
+  getApiDeprecationsManualSteps,
+  getApiDeprecationTitle,
+} from './i18n_texts';
+interface ApiDeprecationsServiceDeps {
+  logger: Logger;
+  deprecationsFactory: DeprecationsFactory;
+  http: InternalHttpServiceSetup;
+  coreUsageData: InternalCoreUsageDataSetup;
+}
+
+export const buildApiDeprecationId = ({
+  routePath,
+  routeMethod,
+  routeVersion,
+}: Pick<RouterDeprecatedRouteDetails, 'routeMethod' | 'routePath' | 'routeVersion'>): string => {
+  return [routeVersion || 'unversioned', routeMethod, routePath].join('|');
+};
+
+export const registerApiDeprecationsInfo = ({
+  deprecationsFactory,
+  http,
+  coreUsageData,
+}: ApiDeprecationsServiceDeps): void => {
+  const deprecationsRegistery = deprecationsFactory.getRegistry('core.api_deprecations');
+
+  deprecationsRegistery.registerDeprecations({
+    getDeprecations: async () => {
+      const deprecatedRoutes = http.getRegisteredDeprecatedApis();
+      const usageClient = coreUsageData.getClient();
+      const deprecatedApiUsageStats = await usageClient.getDeprecatedApiUsageStats();
+
+      return deprecatedApiUsageStats
+        .filter(({ apiTotalCalls, totalMarkedAsResolved }) => {
+          return apiTotalCalls > totalMarkedAsResolved;
+        })
+        .filter(({ apiId }) =>
+          deprecatedRoutes.some((routeDetails) => buildApiDeprecationId(routeDetails) === apiId)
+        )
+        .map((apiUsageStats) => {
+          const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats;
+          const routeDeprecationDetails = deprecatedRoutes.find(
+            (routeDetails) => buildApiDeprecationId(routeDetails) === apiId
+          )!;
+          const { routeVersion, routePath, routeDeprecationOptions, routeMethod } =
+            routeDeprecationDetails;
+          const defaultLevel =
+            routeDeprecationOptions.reason.type === 'remove' ? 'critical' : 'warning';
+          const deprecationLevel = routeDeprecationOptions.severity || defaultLevel;
+
+          return {
+            apiId,
+            title: getApiDeprecationTitle(routeDeprecationDetails),
+            level: deprecationLevel,
+            message: getApiDeprecationMessage(routeDeprecationDetails, apiUsageStats),
+            documentationUrl: routeDeprecationOptions.documentationUrl,
+            correctiveActions: {
+              manualSteps: getApiDeprecationsManualSteps(routeDeprecationDetails),
+              mark_as_resolved_api: {
+                routePath,
+                routeMethod,
+                routeVersion,
+                apiTotalCalls,
+                totalMarkedAsResolved,
+                timestamp: new Date(),
+              },
+            },
+            deprecationType: 'api',
+            domainId: 'core.routes-deprecations',
+          };
+        });
+    },
+  });
+};

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/config_deprecations.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { IConfigService } from '@kbn/config';
+import { DeprecationsFactory } from '../deprecations_factory';
+
+interface RegisterConfigDeprecationsInfo {
+  deprecationsFactory: DeprecationsFactory;
+  configService: IConfigService;
+}
+
+export const registerConfigDeprecationsInfo = ({
+  deprecationsFactory,
+  configService,
+}: RegisterConfigDeprecationsInfo) => {
+  const handledDeprecatedConfigs = configService.getHandledDeprecatedConfigs();
+
+  for (const [domainId, deprecationsContexts] of handledDeprecatedConfigs) {
+    const deprecationsRegistry = deprecationsFactory.getRegistry(domainId);
+    deprecationsRegistry.registerDeprecations({
+      getDeprecations: () => {
+        return deprecationsContexts.map(
+          ({
+            configPath,
+            title = `${domainId} has a deprecated setting`,
+            level,
+            message,
+            correctiveActions,
+            documentationUrl,
+          }) => ({
+            configPath,
+            title,
+            level,
+            message,
+            correctiveActions,
+            documentationUrl,
+            deprecationType: 'config',
+            requireRestart: true,
+          })
+        );
+      },
+    });
+  }
+};