feat(catalog-plugin): Add support for setting placeholder resolvers.

Signed-off-by: Aramis <sennyeyaramis@gmail.com>

.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`.

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<JsonValue>;
 
-// @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<Buffer>;
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export type PlaceholderResolverResolveUrl = (
   url: string,
   base: string,

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<Buffer>;
 
-/** @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<JsonValue>;

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<CatalogProcessor>();
   #entityProviders = new Array<EntityProvider>();
+  #placeholderResolvers: Record<string, PlaceholderResolver> = {};
 
   addProcessor(
     ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
@@ -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();

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<EntityProvider | Array<EntityProvider>>
   ): void;
   // (undocumented)
+  addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
+  // (undocumented)
   addProcessor(
     ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
   ): void;

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<JsonValue>;
+
+// @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<Buffer>;
+
+// @public (undocumented)
+export type PlaceholderResolverResolveUrl = (
+  url: string,
+  base: string,
+) => string;
+
 // @public
 export const processingResult: Readonly<{
   readonly notFoundError: (

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<EntityProvider | Array<EntityProvider>>
   ): void;
+  addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
 }
 
 /**

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';

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<Buffer>;
+
+/** @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<JsonValue>;