From f06f0e46ba882fec8e575d8908d5561edbb5a41a Mon Sep 17 00:00:00 2001 From: Aramis Date: Sun, 4 Jun 2023 16:33:32 -0400 Subject: [PATCH] feat(catalog-plugin): Add support for setting placeholder resolvers. Signed-off-by: Aramis --- .changeset/sour-humans-begin.md | 6 +++++ plugins/catalog-backend/api-report.md | 8 +++--- .../src/modules/core/PlaceholderProcessor.ts | 20 +++++++++++--- .../src/service/CatalogPlugin.ts | 18 +++++++++++++ plugins/catalog-node/alpha-api-report.md | 3 +++ plugins/catalog-node/api-report.md | 24 +++++++++++++++++ plugins/catalog-node/src/extensions.ts | 2 ++ plugins/catalog-node/src/processing/index.ts | 8 +++++- plugins/catalog-node/src/processing/types.ts | 26 +++++++++++++++++++ 9 files changed, 106 insertions(+), 9 deletions(-) create mode 100644 .changeset/sour-humans-begin.md diff --git a/.changeset/sour-humans-begin.md b/.changeset/sour-humans-begin.md new file mode 100644 index 0000000000..1f090f1c89 --- /dev/null +++ b/.changeset/sour-humans-begin.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-catalog-backend': minor +'@backstage/plugin-catalog-node': minor +--- + +Support placeholder resolvers in the CatalogPlugin, also moves `PlaceholderResolver` and related types from `@backstage/plugin-catalog-backend` to `@backstage/plugin-catalog-node`. diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 3e97442dd4..84d8de4753 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -410,12 +410,12 @@ export type PlaceholderProcessorOptions = { integrations: ScmIntegrationRegistry; }; -// @public (undocumented) +// @public @deprecated (undocumented) export type PlaceholderResolver = ( params: PlaceholderResolverParams, ) => Promise; -// @public (undocumented) +// @public @deprecated (undocumented) export type PlaceholderResolverParams = { key: string; value: JsonValue; @@ -425,10 +425,10 @@ export type PlaceholderResolverParams = { emit: CatalogProcessorEmit_2; }; -// @public (undocumented) +// @public @deprecated (undocumented) export type PlaceholderResolverRead = (url: string) => Promise; -// @public (undocumented) +// @public @deprecated (undocumented) export type PlaceholderResolverResolveUrl = ( url: string, base: string, diff --git a/plugins/catalog-backend/src/modules/core/PlaceholderProcessor.ts b/plugins/catalog-backend/src/modules/core/PlaceholderProcessor.ts index 79fcee960c..ee61e931e3 100644 --- a/plugins/catalog-backend/src/modules/core/PlaceholderProcessor.ts +++ b/plugins/catalog-backend/src/modules/core/PlaceholderProcessor.ts @@ -26,16 +26,25 @@ import { processingResult, } from '@backstage/plugin-catalog-node'; -/** @public */ +/** + * @public + * @deprecated Use the exported value from `@backstage/plugin-catalog-node` instead. + */ export type PlaceholderResolverRead = (url: string) => Promise; -/** @public */ +/** + * @public + * @deprecated Use the exported value from `@backstage/plugin-catalog-node` instead. + */ export type PlaceholderResolverResolveUrl = ( url: string, base: string, ) => string; -/** @public */ +/** + * @public + * @deprecated Use the exported value from `@backstage/plugin-catalog-node` instead. + */ export type PlaceholderResolverParams = { key: string; value: JsonValue; @@ -45,7 +54,10 @@ export type PlaceholderResolverParams = { emit: CatalogProcessorEmit; }; -/** @public */ +/** + * @public + * @deprecated Use the exported value from `@backstage/plugin-catalog-node` instead. + */ export type PlaceholderResolver = ( params: PlaceholderResolverParams, ) => Promise; diff --git a/plugins/catalog-backend/src/service/CatalogPlugin.ts b/plugins/catalog-backend/src/service/CatalogPlugin.ts index e0399c1683..d77b034517 100644 --- a/plugins/catalog-backend/src/service/CatalogPlugin.ts +++ b/plugins/catalog-backend/src/service/CatalogPlugin.ts @@ -27,10 +27,12 @@ import { EntityProvider, } from '@backstage/plugin-catalog-node'; import { loggerToWinstonLogger } from '@backstage/backend-common'; +import { PlaceholderResolver } from '../modules'; class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint { #processors = new Array(); #entityProviders = new Array(); + #placeholderResolvers: Record = {}; addProcessor( ...processors: Array> @@ -44,6 +46,14 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint { this.#entityProviders.push(...providers.flat()); } + addPlaceholderResolver(key: string, resolver: PlaceholderResolver) { + if (key in this.#placeholderResolvers) + throw new Error( + `A placeholder resolver for '${key}' has already been set up, please check your config.`, + ); + this.#placeholderResolvers[key] = resolver; + } + get processors() { return this.#processors; } @@ -51,6 +61,10 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint { get entityProviders() { return this.#entityProviders; } + + get placeholderResolvers() { + return this.#placeholderResolvers; + } } /** @@ -99,6 +113,10 @@ export const catalogPlugin = createBackendPlugin({ }); builder.addProcessor(...processingExtensions.processors); builder.addEntityProvider(...processingExtensions.entityProviders); + Object.entries(processingExtensions.placeholderResolvers).forEach( + ([key, resolver]) => builder.setPlaceholderResolver(key, resolver), + ); + const { processingEngine, router } = await builder.build(); await processingEngine.start(); diff --git a/plugins/catalog-node/alpha-api-report.md b/plugins/catalog-node/alpha-api-report.md index ba1bcd47b2..082228a58e 100644 --- a/plugins/catalog-node/alpha-api-report.md +++ b/plugins/catalog-node/alpha-api-report.md @@ -7,6 +7,7 @@ import { CatalogApi } from '@backstage/catalog-client'; import { CatalogProcessor } from '@backstage/plugin-catalog-node'; import { EntityProvider } from '@backstage/plugin-catalog-node'; import { ExtensionPoint } from '@backstage/backend-plugin-api'; +import { PlaceholderResolver } from '@backstage/plugin-catalog-node'; import { ServiceRef } from '@backstage/backend-plugin-api'; // @alpha (undocumented) @@ -16,6 +17,8 @@ export interface CatalogProcessingExtensionPoint { ...providers: Array> ): void; // (undocumented) + addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void; + // (undocumented) addProcessor( ...processors: Array> ): void; diff --git a/plugins/catalog-node/api-report.md b/plugins/catalog-node/api-report.md index 47a8e66ca9..34d7a4bc9b 100644 --- a/plugins/catalog-node/api-report.md +++ b/plugins/catalog-node/api-report.md @@ -152,6 +152,30 @@ export function locationSpecToLocationEntity(opts: { // @public export function locationSpecToMetadataName(location: LocationSpec_2): string; +// @public (undocumented) +export type PlaceholderResolver = ( + params: PlaceholderResolverParams, +) => Promise; + +// @public (undocumented) +export type PlaceholderResolverParams = { + key: string; + value: JsonValue; + baseUrl: string; + read: PlaceholderResolverRead; + resolveUrl: PlaceholderResolverResolveUrl; + emit: CatalogProcessorEmit; +}; + +// @public (undocumented) +export type PlaceholderResolverRead = (url: string) => Promise; + +// @public (undocumented) +export type PlaceholderResolverResolveUrl = ( + url: string, + base: string, +) => string; + // @public export const processingResult: Readonly<{ readonly notFoundError: ( diff --git a/plugins/catalog-node/src/extensions.ts b/plugins/catalog-node/src/extensions.ts index 0466af36b0..5225ad7545 100644 --- a/plugins/catalog-node/src/extensions.ts +++ b/plugins/catalog-node/src/extensions.ts @@ -17,6 +17,7 @@ import { createExtensionPoint } from '@backstage/backend-plugin-api'; import { EntityProvider, CatalogProcessor, + PlaceholderResolver, } from '@backstage/plugin-catalog-node'; /** @@ -29,6 +30,7 @@ export interface CatalogProcessingExtensionPoint { addEntityProvider( ...providers: Array> ): void; + addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void; } /** diff --git a/plugins/catalog-node/src/processing/index.ts b/plugins/catalog-node/src/processing/index.ts index 90b87aa850..40cee63e25 100644 --- a/plugins/catalog-node/src/processing/index.ts +++ b/plugins/catalog-node/src/processing/index.ts @@ -14,4 +14,10 @@ * limitations under the License. */ -export type { DeferredEntity } from './types'; +export type { + DeferredEntity, + PlaceholderResolver, + PlaceholderResolverParams, + PlaceholderResolverRead, + PlaceholderResolverResolveUrl, +} from './types'; diff --git a/plugins/catalog-node/src/processing/types.ts b/plugins/catalog-node/src/processing/types.ts index 25e76faea3..b98e2da1b7 100644 --- a/plugins/catalog-node/src/processing/types.ts +++ b/plugins/catalog-node/src/processing/types.ts @@ -15,6 +15,8 @@ */ import { Entity } from '@backstage/catalog-model'; +import { JsonValue } from '@backstage/types'; +import { CatalogProcessorEmit } from '../api'; /** * Entities that are not yet processed. @@ -24,3 +26,27 @@ export type DeferredEntity = { entity: Entity; locationKey?: string; }; + +/** @public */ +export type PlaceholderResolverRead = (url: string) => Promise; + +/** @public */ +export type PlaceholderResolverResolveUrl = ( + url: string, + base: string, +) => string; + +/** @public */ +export type PlaceholderResolverParams = { + key: string; + value: JsonValue; + baseUrl: string; + read: PlaceholderResolverRead; + resolveUrl: PlaceholderResolverResolveUrl; + emit: CatalogProcessorEmit; +}; + +/** @public */ +export type PlaceholderResolver = ( + params: PlaceholderResolverParams, +) => Promise;