From e31e86b2c3119ecf331ed137dddad0fe025d049c Mon Sep 17 00:00:00 2001 From: Bamieh Date: Sun, 10 Nov 2024 15:42:54 +0100 Subject: [PATCH] finalize copy --- .../routes/deprecated_routes/internal.ts | 3 +- .../{ => access}/access_deprecations.ts | 20 ++-- .../api_deprecations/access/i18n_texts.ts | 101 ++++++++++++++++++ .../api_deprecations/access/index.ts | 10 ++ .../register_api_depercation_info.test.ts | 2 +- .../register_api_depercation_info.ts | 47 ++++---- .../{ => route}/i18n_texts.ts | 59 +++++----- .../api_deprecations/route/index.ts | 10 ++ .../{ => route}/route_deprecations.ts | 20 ++-- .../deprecations/api_deprecations/types.ts | 2 +- packages/core/http/core-http-server/index.ts | 2 + .../http/core-http-server/src/router/index.ts | 9 +- .../core-http-server/src/router/router.ts | 14 ++- x-pack/plugins/upgrade_assistant/README.md | 18 ++-- 14 files changed, 238 insertions(+), 79 deletions(-) rename packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/{ => access}/access_deprecations.ts (67%) create mode 100644 packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts create mode 100644 packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/index.ts rename packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/{ => route}/i18n_texts.ts (70%) create mode 100644 packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/index.ts rename packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/{ => route}/route_deprecations.ts (73%) diff --git a/examples/routing_example/server/routes/deprecated_routes/internal.ts b/examples/routing_example/server/routes/deprecated_routes/internal.ts index 983d1ab444979..033a6c713292b 100644 --- a/examples/routing_example/server/routes/deprecated_routes/internal.ts +++ b/examples/routing_example/server/routes/deprecated_routes/internal.ts @@ -20,7 +20,8 @@ export const registerInternalDeprecatedRoute = (router: IRouter) => { deprecated: { documentationUrl: 'https://elastic.co/', severity: 'critical', - reason: { type: 'remove' }, + message: 'Additonal message for internal deprecated api', + reason: { type: 'deprecate' }, }, }, }, diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access_deprecations.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts similarity index 67% rename from packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access_deprecations.ts rename to packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts index 5cd574cf9f702..6e264e05e8164 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access_deprecations.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts @@ -11,34 +11,30 @@ import type { ApiDeprecationDetails, DomainDeprecationDetails, } from '@kbn/core-deprecations-common'; -import type { BuildApiDeprecationDetailsParams } from './types'; +import type { BuildApiDeprecationDetailsParams } from '../types'; import { getApiDeprecationMessage, getApiDeprecationsManualSteps, getApiDeprecationTitle, } from './i18n_texts'; -import { buildApiDeprecationId } from './api_deprecation_id'; export const buildApiAccessDeprecationDetails = ({ apiUsageStats, - deprecatedApis, + deprecatedApiDetails, }: BuildApiDeprecationDetailsParams): DomainDeprecationDetails => { const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats; - const routeDeprecationDetails = deprecatedApis.find( - (routeDetails) => buildApiDeprecationId(routeDetails) === apiId - )!; - const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = routeDeprecationDetails; + const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = deprecatedApiDetails; - const deprecationLevel = routeDeprecationOptions.severity || 'warning'; + const deprecationLevel = routeDeprecationOptions?.severity || 'warning'; return { apiId, - title: getApiDeprecationTitle(routeDeprecationDetails), + title: getApiDeprecationTitle(deprecatedApiDetails), level: deprecationLevel, - message: getApiDeprecationMessage(routeDeprecationDetails, apiUsageStats), - documentationUrl: routeDeprecationOptions.documentationUrl, + message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats), + documentationUrl: routeDeprecationOptions?.documentationUrl, correctiveActions: { - manualSteps: getApiDeprecationsManualSteps(routeDeprecationDetails), + manualSteps: getApiDeprecationsManualSteps(), mark_as_resolved_api: { routePath, routeMethod, diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts new file mode 100644 index 0000000000000..bd1f92cf368fe --- /dev/null +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts @@ -0,0 +1,101 @@ +/* + * 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 { RouterDeprecatedApiDetails } from '@kbn/core-http-server'; +import { CoreDeprecatedApiUsageStats } from '@kbn/core-usage-data-server'; +import { i18n } from '@kbn/i18n'; +import moment from 'moment'; + +export const getApiDeprecationTitle = ( + details: Pick +) => { + const { routePath, routeMethod } = details; + const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`; + + return i18n.translate('core.deprecations.apiAccessDeprecation.infoTitle', { + defaultMessage: 'The "{routeWithMethod}" API is internal to Elastic', + values: { + routeWithMethod, + }, + }); +}; + +export const getApiDeprecationMessage = ( + details: Pick< + RouterDeprecatedApiDetails, + 'routePath' | 'routeMethod' | 'routeDeprecationOptions' + >, + apiUsageStats: CoreDeprecatedApiUsageStats +): string[] => { + const { routePath, routeMethod, routeDeprecationOptions } = details; + const { apiLastCalledAt, apiTotalCalls, markedAsResolvedLastCalledAt, totalMarkedAsResolved } = + apiUsageStats; + + const diff = apiTotalCalls - totalMarkedAsResolved; + const wasResolvedBefore = totalMarkedAsResolved > 0; + const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`; + + const messages = [ + i18n.translate('core.deprecations.apiAccessDeprecation.apiCallsDetailsMessage', { + defaultMessage: + 'The API "{routeWithMethod}" has been called {apiTotalCalls} times. The last call was on {apiLastCalledAt}.', + values: { + routeWithMethod, + apiTotalCalls, + apiLastCalledAt: moment(apiLastCalledAt).format('LLLL Z'), + }, + }), + ]; + + if (wasResolvedBefore) { + messages.push( + i18n.translate('core.deprecations.apiAccessDeprecation.previouslyMarkedAsResolvedMessage', { + defaultMessage: + 'This issue has been marked as resolved on {markedAsResolvedLastCalledAt} but the API has been called {timeSinceLastResolved, plural, one {# time} other {# times}} since.', + values: { + timeSinceLastResolved: diff, + markedAsResolvedLastCalledAt: moment(markedAsResolvedLastCalledAt).format('LLLL Z'), + }, + }) + ); + } + + messages.push( + i18n.translate('core.deprecations.apiAccessDeprecation.internalApiExplanationMessage', { + defaultMessage: + 'Internal APIs are meant to be used by Elastic services only. You should not use them. External access to these APIs will be restricted.', + }) + ); + + if (routeDeprecationOptions?.message) { + // Surfaces additional deprecation messages passed into the route in UA + messages.push(routeDeprecationOptions.message); + } + + return messages; +}; + +export const getApiDeprecationsManualSteps = (): string[] => { + return [ + i18n.translate('core.deprecations.apiAccessDeprecation.manualSteps.identifyCallsOriginStep', { + defaultMessage: 'Identify the origin of these API calls.', + }), + i18n.translate('core.deprecations.apiAccessDeprecation.manualSteps.deleteRequestsStep', { + defaultMessage: + 'Delete any requests you have that use this API. Check the learn more link for possible alternatives.', + }), + i18n.translate( + 'core.deprecations.apiAccessDeprecation.manualSteps.accessDepractionMarkAsResolvedStep', + { + defaultMessage: + 'Once you have successfully stopped using this API, mark this issue as resolved. It will no longer appear in the Upgrade Assistant unless another call using this API is detected.', + } + ), + ]; +}; diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/index.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/index.ts new file mode 100644 index 0000000000000..8bf195a8360f1 --- /dev/null +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/index.ts @@ -0,0 +1,10 @@ +/* + * 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". + */ + +export { buildApiAccessDeprecationDetails } from './access_deprecations'; diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts index 1df0956ce543d..77d6f089ffb40 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts @@ -260,7 +260,7 @@ describe('#registerApiDeprecationsInfo', () => { }, "deprecationType": "api", "documentationUrl": "https://fake-url", - "domainId": "core.routes-deprecations", + "domainId": "core.http.routes-deprecations", "level": "critical", "message": Array [ "The API \\"GET /api/test_deprecated/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.", diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts index 47fbd123b5594..535db90577106 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts @@ -9,12 +9,10 @@ import { DeprecationsDetails } from '@kbn/core-deprecations-common'; -import _ from 'lodash'; -import { buildApiRouteDeprecationDetails } from './route_deprecations'; -import { buildApiAccessDeprecationDetails } from './access_deprecations'; - -import { ApiDeprecationsServiceDeps } from './types'; +import { buildApiRouteDeprecationDetails } from './route/route_deprecations'; +import { buildApiAccessDeprecationDetails } from './access/access_deprecations'; import { buildApiDeprecationId } from './api_deprecation_id'; +import type { ApiDeprecationsServiceDeps } from './types'; export const createGetApiDeprecations = ({ http, coreUsageData }: Pick) => @@ -31,23 +29,32 @@ export const createGetApiDeprecations = deprecatedApis.some((routeDetails) => buildApiDeprecationId(routeDetails) === apiId) ) .map((apiUsageStats) => { - const { internal: internalApiDeprecationedRoutes, ...deprecatedRoutes } = _.groupBy( - deprecatedApis, - 'routeAccess' + const { apiId } = apiUsageStats; + const deprecatedApiDetails = deprecatedApis.find( + (routeDetails) => buildApiDeprecationId(routeDetails) === apiId ); + if (!deprecatedApiDetails) { + throw new Error(`Unable to find deprecation details for "${apiId}"`); + } - return [ - buildApiRouteDeprecationDetails({ - apiUsageStats, - deprecatedApis: Object.values(deprecatedRoutes).flat(), - }), - buildApiAccessDeprecationDetails({ - apiUsageStats, - deprecatedApis: Object.values(internalApiDeprecationedRoutes), - }), - ]; - }) - .flat(); + const { routeAccess } = deprecatedApiDetails; + + switch (routeAccess) { + case 'internal': { + return buildApiAccessDeprecationDetails({ + apiUsageStats, + deprecatedApiDetails, + }); + } + case 'public': + default: { + return buildApiRouteDeprecationDetails({ + apiUsageStats, + deprecatedApiDetails, + }); + } + } + }); }; export const registerApiDeprecationsInfo = ({ diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/i18n_texts.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/i18n_texts.ts similarity index 70% rename from packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/i18n_texts.ts rename to packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/i18n_texts.ts index 41d35c1f1494c..8cbade658bb2e 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/i18n_texts.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/i18n_texts.ts @@ -14,15 +14,19 @@ import moment from 'moment'; export const getApiDeprecationTitle = (details: RouterDeprecatedApiDetails) => { const { routePath, routeMethod, routeDeprecationOptions } = details; + if (!routeDeprecationOptions) { + throw new Error(`Router "deprecated" param is missing for path "${routePath}".`); + } + const deprecationType = routeDeprecationOptions.reason.type; const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`; - const deprecationTypeText = i18n.translate('core.deprecations.deprecations.apiDeprecationType', { + const deprecationTypeText = i18n.translate('core.deprecations.apiRouteDeprecation.type', { defaultMessage: '{deprecationType, select, remove {is removed} bump {has a newer version available} migrate {is migrated to a different API} other {is deprecated}}', values: { deprecationType }, }); - return i18n.translate('core.deprecations.deprecations.apiDeprecationInfoTitle', { + return i18n.translate('core.deprecations.apiRouteDeprecation.infoTitle', { defaultMessage: 'The "{routeWithMethod}" route {deprecationTypeText}', values: { routeWithMethod, @@ -36,6 +40,9 @@ export const getApiDeprecationMessage = ( apiUsageStats: CoreDeprecatedApiUsageStats ): string[] => { const { routePath, routeMethod, routeDeprecationOptions } = details; + if (!routeDeprecationOptions) { + throw new Error(`Router "deprecated" param is missing for path "${routePath}".`); + } const { apiLastCalledAt, apiTotalCalls, markedAsResolvedLastCalledAt, totalMarkedAsResolved } = apiUsageStats; @@ -44,7 +51,7 @@ export const getApiDeprecationMessage = ( const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`; const messages = [ - i18n.translate('core.deprecations.deprecations.apiDeprecationApiCallsDetailsMessage', { + i18n.translate('core.deprecations.apiRouteDeprecation.apiCallsDetailsMessage', { defaultMessage: 'The API "{routeWithMethod}" has been called {apiTotalCalls} times. The last call was on {apiLastCalledAt}.', values: { @@ -57,17 +64,14 @@ export const getApiDeprecationMessage = ( if (wasResolvedBefore) { messages.push( - i18n.translate( - 'core.deprecations.deprecations.apiDeprecationPreviouslyMarkedAsResolvedMessage', - { - defaultMessage: - 'This issue has been marked as resolved on {markedAsResolvedLastCalledAt} but the API has been called {timeSinceLastResolved, plural, one {# time} other {# times}} since.', - values: { - timeSinceLastResolved: diff, - markedAsResolvedLastCalledAt: moment(markedAsResolvedLastCalledAt).format('LLLL Z'), - }, - } - ) + i18n.translate('core.deprecations.apiRouteDeprecation.previouslyMarkedAsResolvedMessage', { + defaultMessage: + 'This issue has been marked as resolved on {markedAsResolvedLastCalledAt} but the API has been called {timeSinceLastResolved, plural, one {# time} other {# times}} since.', + values: { + timeSinceLastResolved: diff, + markedAsResolvedLastCalledAt: moment(markedAsResolvedLastCalledAt).format('LLLL Z'), + }, + }) ); } @@ -80,11 +84,15 @@ export const getApiDeprecationMessage = ( }; export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetails): string[] => { - const { routeDeprecationOptions } = details; + const { routePath, routeDeprecationOptions } = details; + if (!routeDeprecationOptions) { + throw new Error(`Router "deprecated" param is missing for path "${routePath}".`); + } + const deprecationType = routeDeprecationOptions.reason.type; const manualSteps = [ - i18n.translate('core.deprecations.deprecations.manualSteps.apiIseprecatedStep', { + i18n.translate('core.deprecations.apiRouteDeprecation.manualSteps.identifyCallsOriginStep', { defaultMessage: 'Identify the origin of these API calls.', }), ]; @@ -93,7 +101,7 @@ export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetail case 'bump': { const { newApiVersion } = routeDeprecationOptions.reason; manualSteps.push( - i18n.translate('core.deprecations.deprecations.manualSteps.bumpDetailsStep', { + i18n.translate('core.deprecations.apiRouteDeprecation.manualSteps.bumpTypeStep', { defaultMessage: 'Update the requests to use the following new version of the API instead: "{newApiVersion}".', values: { newApiVersion }, @@ -104,7 +112,7 @@ export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetail case 'remove': { manualSteps.push( - i18n.translate('core.deprecations.deprecations.manualSteps.removeTypeExplainationStep', { + i18n.translate('core.deprecations.apiRouteDeprecation.manualSteps.removeTypeStep', { defaultMessage: 'This API no longer exists and no replacement is available. Delete any requests you have that use this API.', }) @@ -113,7 +121,7 @@ export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetail } case 'deprecate': { manualSteps.push( - i18n.translate('core.deprecations.deprecations.manualSteps.removeTypeExplainationStep', { + i18n.translate('core.deprecations.apiRouteDeprecation.manualSteps.deprecateTypeStep', { defaultMessage: 'For now, the API will still work, but will be moved or removed in a future version. Check the Learn more link for more information. If you are no longer using the API, you can mark this issue as resolved. It will no longer appear in the Upgrade Assistant unless another call using this API is detected.', }) @@ -125,7 +133,7 @@ export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetail const newRouteWithMethod = `${newApiMethod.toUpperCase()} ${newApiPath}`; manualSteps.push( - i18n.translate('core.deprecations.deprecations.manualSteps.migrateDetailsStep', { + i18n.translate('core.deprecations.apiRouteDeprecation.manualSteps.migrateTypeStep', { defaultMessage: 'Update the requests to use the following new API instead: "{newRouteWithMethod}".', values: { newRouteWithMethod }, @@ -137,10 +145,13 @@ export const getApiDeprecationsManualSteps = (details: RouterDeprecatedApiDetail if (deprecationType !== 'deprecate') { manualSteps.push( - i18n.translate('core.deprecations.deprecations.manualSteps.markAsResolvedStep', { - defaultMessage: - 'Check that you are no longer using the old API in any requests, and mark this issue as resolved. It will no longer appear in the Upgrade Assistant unless another call using this API is detected.', - }) + i18n.translate( + 'core.deprecations.apiRouteDeprecation.manualSteps.routeDepractionMarkAsResolvedStep', + { + defaultMessage: + 'Check that you are no longer using the old API in any requests, and mark this issue as resolved. It will no longer appear in the Upgrade Assistant unless another call using this API is detected.', + } + ) ); } diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/index.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/index.ts new file mode 100644 index 0000000000000..2e28928c9c065 --- /dev/null +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/index.ts @@ -0,0 +1,10 @@ +/* + * 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". + */ + +export { buildApiRouteDeprecationDetails } from './route_deprecations'; diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route_deprecations.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/route_deprecations.ts similarity index 73% rename from packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route_deprecations.ts rename to packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/route_deprecations.ts index 6d6f59f8a4882..cbddb117c1620 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route_deprecations.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/route_deprecations.ts @@ -11,35 +11,33 @@ import type { ApiDeprecationDetails, DomainDeprecationDetails, } from '@kbn/core-deprecations-common'; -import type { BuildApiDeprecationDetailsParams } from './types'; +import type { BuildApiDeprecationDetailsParams } from '../types'; import { getApiDeprecationMessage, getApiDeprecationsManualSteps, getApiDeprecationTitle, } from './i18n_texts'; -import { buildApiDeprecationId } from './api_deprecation_id'; - export const buildApiRouteDeprecationDetails = ({ apiUsageStats, - deprecatedApis, + deprecatedApiDetails, }: BuildApiDeprecationDetailsParams): DomainDeprecationDetails => { const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats; - const routeDeprecationDetails = deprecatedApis.find( - (routeDetails) => buildApiDeprecationId(routeDetails) === apiId - )!; - const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = routeDeprecationDetails; + const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = deprecatedApiDetails; + if (!routeDeprecationOptions) { + throw new Error(`Expecing deprecated to be defined for route ${apiId}`); + } const deprecationLevel = routeDeprecationOptions.severity || 'warning'; return { apiId, - title: getApiDeprecationTitle(routeDeprecationDetails), + title: getApiDeprecationTitle(deprecatedApiDetails), level: deprecationLevel, - message: getApiDeprecationMessage(routeDeprecationDetails, apiUsageStats), + message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats), documentationUrl: routeDeprecationOptions.documentationUrl, correctiveActions: { - manualSteps: getApiDeprecationsManualSteps(routeDeprecationDetails), + manualSteps: getApiDeprecationsManualSteps(deprecatedApiDetails), mark_as_resolved_api: { routePath, routeMethod, diff --git a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/types.ts b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/types.ts index 4b3b34e9ee76d..ad6436b70c55f 100644 --- a/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/types.ts +++ b/packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/types.ts @@ -21,5 +21,5 @@ export interface ApiDeprecationsServiceDeps { export interface BuildApiDeprecationDetailsParams { apiUsageStats: CoreDeprecatedApiUsageStats; - deprecatedApis: RouterDeprecatedApiDetails[]; + deprecatedApiDetails: RouterDeprecatedApiDetails; } diff --git a/packages/core/http/core-http-server/index.ts b/packages/core/http/core-http-server/index.ts index 15c7ff2f7dfe2..af3c566f6a8d2 100644 --- a/packages/core/http/core-http-server/index.ts +++ b/packages/core/http/core-http-server/index.ts @@ -94,6 +94,8 @@ export type { RouteRegistrar, RouterRoute, RouterDeprecatedApiDetails, + RouterAccessDeprecatedApiDetails, + RouterRouteDeprecatedApiDetails, IKibanaSocket, KibanaErrorResponseFactory, KibanaRedirectionResponseFactory, diff --git a/packages/core/http/core-http-server/src/router/index.ts b/packages/core/http/core-http-server/src/router/index.ts index 67423a93f849a..2c7a83469ebb1 100644 --- a/packages/core/http/core-http-server/src/router/index.ts +++ b/packages/core/http/core-http-server/src/router/index.ts @@ -81,7 +81,14 @@ export type { LazyValidator, } from './route_validator'; export { RouteValidationError } from './route_validator'; -export type { IRouter, RouteRegistrar, RouterRoute, RouterDeprecatedApiDetails } from './router'; +export type { + IRouter, + RouteRegistrar, + RouterRoute, + RouterDeprecatedApiDetails, + RouterAccessDeprecatedApiDetails, + RouterRouteDeprecatedApiDetails, +} from './router'; export type { IKibanaSocket } from './socket'; export type { KibanaErrorResponseFactory, diff --git a/packages/core/http/core-http-server/src/router/router.ts b/packages/core/http/core-http-server/src/router/router.ts index b8c03380a500a..f770cfcc45e4b 100644 --- a/packages/core/http/core-http-server/src/router/router.ts +++ b/packages/core/http/core-http-server/src/router/router.ts @@ -144,9 +144,21 @@ export interface RouterRoute { /** @public */ export interface RouterDeprecatedApiDetails { - routeDeprecationOptions: RouteDeprecationInfo; + routeDeprecationOptions?: RouteDeprecationInfo; routeMethod: RouteMethod; routePath: string; routeVersion?: string; routeAccess?: RouteAccess; } + +/** @public */ +export interface RouterRouteDeprecatedApiDetails extends RouterDeprecatedApiDetails { + routeAccess: 'public'; + routeDeprecationOptions: RouteDeprecationInfo; +} + +/** @public */ +export interface RouterAccessDeprecatedApiDetails extends RouterDeprecatedApiDetails { + routeAccess: 'internal'; + routeDeprecationOptions?: RouteDeprecationInfo; +} diff --git a/x-pack/plugins/upgrade_assistant/README.md b/x-pack/plugins/upgrade_assistant/README.md index 9e2cf1b47e60a..e1cadeb0404f9 100644 --- a/x-pack/plugins/upgrade_assistant/README.md +++ b/x-pack/plugins/upgrade_assistant/README.md @@ -21,14 +21,14 @@ When we want to enable ML model snapshot deprecation warnings again we need to c There are three sources of deprecation information: -* [**Elasticsearch Deprecation Info API.**](https://www.elastic.co/guide/en/elasticsearch/reference/master/migration-api-deprecation.html) +* [**Elasticsearch Deprecation Info API.**](https://www.elastic.co/guide/en/elasticsearch/reference/main/migration-api-deprecation.html) This is information about Elasticsearch cluster, node, Machine Learning, and index-level settings that use deprecated features that will be removed or changed in the next major version. ES server engineers are responsible for adding deprecations to the Deprecation Info API. * [**Elasticsearch deprecation logs.**](https://www.elastic.co/guide/en/elasticsearch/reference/current/logging.html#deprecation-logging) These surface runtime deprecations, e.g. a Painless script that uses a deprecated accessor or a request to a deprecated API. These are also generally surfaced as deprecation headers within the response. Even if the cluster state is good, app maintainers need to watch the logs in case deprecations are discovered as data is migrated. Starting in 7.x, deprecation logs can be written to a file or a data stream ([#58924](https://github.com/elastic/elasticsearch/pull/58924)). When the data stream exists, the Upgrade Assistant provides a way to analyze the logs through Observability or Discover ([#106521](https://github.com/elastic/kibana/pull/106521)). -* [**Kibana deprecations API.**](https://github.com/elastic/kibana/blob/master/src/core/server/deprecations/README.mdx) This is information about deprecated features and configs in Kibana. These deprecations are only communicated to the user if the deployment is using these features. Kibana engineers are responsible for adding deprecations to the deprecations API for their respective team. +* [**Kibana deprecations API.**](https://github.com/elastic/kibana/blob/main/src/core/server/deprecations/README.mdx) This is information about deprecated features and configs in Kibana. These deprecations are only communicated to the user if the deployment is using these features. Kibana engineers are responsible for adding deprecations to the deprecations API for their respective team. ### Fixing problems @@ -286,15 +286,19 @@ The following comprehensive deprecated routes examples are registered inside the Run them in the console to trigger the deprecation condition so they show up in the UA: ``` -# Versioned routes: Version 1 is deprecated +# Route deprecations for Versioned routes: Version 1 is deprecated GET kbn:/api/routing_example/d/versioned?apiVersion=1 GET kbn:/api/routing_example/d/versioned?apiVersion=2 -# Non-versioned routes +# Route deprecations for Non-versioned routes GET kbn:/api/routing_example/d/removed_route GET kbn:/api/routing_example/d/deprecated_route POST kbn:/api/routing_example/d/migrated_route {} + +# Access deprecations +GET kbn:/api/routing_example/d/internal_deprecated_route +GET kbn:/internal/routing_example/d/internal_only_route ``` 1. You can also mark as deprecated in the UA to remove the deprecation from the list. @@ -331,7 +335,7 @@ This is a non-exhaustive list of different error scenarios in Upgrade Assistant. ### Telemetry -The Upgrade Assistant tracks several triggered events in the UI, using Kibana Usage Collection service's [UI counters](https://github.com/elastic/kibana/blob/master/src/plugins/usage_collection/README.mdx#ui-counters). +The Upgrade Assistant tracks several triggered events in the UI, using Kibana Usage Collection service's [UI counters](https://github.com/elastic/kibana/blob/main/src/plugins/usage_collection/README.mdx#ui-counters). **Overview page** - Component loaded @@ -350,6 +354,6 @@ The Upgrade Assistant tracks several triggered events in the UI, using Kibana Us - Component loaded - Click event for "Quick resolve" button -In addition to UI counters, the Upgrade Assistant has a [custom usage collector](https://github.com/elastic/kibana/blob/master/src/plugins/usage_collection/README.mdx#custom-collector). It currently is only responsible for tracking whether the user has deprecation logging enabled or not. +In addition to UI counters, the Upgrade Assistant has a [custom usage collector](https://github.com/elastic/kibana/blob/main/src/plugins/usage_collection/README.mdx#custom-collector). It currently is only responsible for tracking whether the user has deprecation logging enabled or not. -For testing instructions, refer to the [Kibana Usage Collection service README](https://github.com/elastic/kibana/blob/master/src/plugins/usage_collection/README.mdx#testing). \ No newline at end of file +For testing instructions, refer to the [Kibana Usage Collection service README](https://github.com/elastic/kibana/blob/main/src/plugins/usage_collection/README.mdx#testing). \ No newline at end of file