Merge pull request #30969 from drodil/processor_priority

feat(catalog): processor priority

.changeset/curvy-terms-jam.md

@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-node': patch
+---
+
+Order catalog processors by priority.
+
+This change enables the ordering of catalog processors by their priority,
+allowing for more control over the catalog processing sequence.
+The default priority is set to 20, and processors can be assigned a custom
+priority to influence their execution order. Lower number indicates higher priority.
+The priority can be set by implementing the `getPriority` method in the processor class
+or by adding a `catalog.processors.<processorName>.priority` configuration
+in the `app-config.yaml` file. The configuration takes precedence over the method.

docs/features/software-catalog/life-of-an-entity.md

@@ -132,6 +132,10 @@ in the registration order, but this does not apply over multiple catalog modules
 the order of registration depends on the order in which the modules are loaded
 by the framework.
 
+It's possible to customize the order of the processors by modifying the
+`catalog.processors.<processorName>.priority` configuration option.
+The default priority is `20`, and lower value means that the processor runs earlier.
+
 :::
 
 Each step has the opportunity to optionally modify the entity, and to optionally

plugins/catalog-backend/config.d.ts

@@ -251,6 +251,12 @@ export interface Config {
          * Whether the processor is enabled or not. Defaults to true.
          */
         enabled?: boolean;
+        /**
+         * The priority of the processor, which is used to determine the order in which
+         * processors are run. The default priority is 20, and lower value means
+         * that the processor runs earlier.
+         */
+        priority?: number;
       };
     };
   };

plugins/catalog-backend/src/service/CatalogBuilder.ts

@@ -727,7 +727,32 @@ export class CatalogBuilder {
 
     this.checkMissingExternalProcessors(processors);
 
-    return this.filterProcessors(processors);
+    const filteredProcessors = this.filterProcessors(processors);
+
+    // Lastly sort the processors by priority. Config can override the
+    // priority of a processor to allow control of 3rd party processors.
+    filteredProcessors.sort((a, b) => {
+      const getProcessorPriority = (processor: CatalogProcessor) => {
+        try {
+          return (
+            config.getOptionalNumber(
+              `catalog.processors.${processor.getProcessorName()}.priority`,
+            ) ??
+            processor.getPriority?.() ??
+            20
+          );
+        } catch (_) {
+          // In case the processor config is not an object, just return default priority
+          return 20;
+        }
+      };
+
+      const aPriority = getProcessorPriority(a);
+      const bPriority = getProcessorPriority(b);
+      return aPriority - bPriority;
+    });
+
+    return filteredProcessors;
   }
 
   private filterProcessors(processors: CatalogProcessor[]) {

plugins/catalog-node/report.api.md

@@ -60,6 +60,7 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+  getPriority?(): number;
 };
 
 // @public

plugins/catalog-node/src/api/processor.ts

@@ -100,6 +100,14 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+
+  /**
+   * Returns a processor priority, which is used to determine the order in which
+   * processors are run. The default priority is 20, and lower value means
+   * that the processor runs earlier.
+   * @returns A number representing the priority of the processor.
+   */
+  getPriority?(): number;
 };
 
 /**