Merge pull request #34278 from backstage/freben/deprecate-immediate-stitching

catalog-backend: deprecate immediate mode stitching

.changeset/deprecate-immediate-stitching.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Deprecated immediate mode stitching (`catalog.stitchingStrategy.mode: 'immediate'`). A warning is now logged on startup when immediate mode is configured. Immediate mode will be removed in the next Backstage release. Migrate to deferred mode (the default) by removing the `stitchingStrategy` configuration or setting `mode: 'deferred'`.

plugins/catalog-backend/config.d.ts

@@ -179,7 +179,11 @@ export interface Config {
      */
     stitchingStrategy?:
       | {
-          /** Perform stitching in-band immediately when needed */
+          /**
+           * Perform stitching in-band immediately when needed.
+           *
+           * @deprecated Immediate mode stitching has been deprecated and will be removed in a future release. Migrate to deferred mode (the default).
+           */
           mode: 'immediate';
         }
       | {

plugins/catalog-backend/src/processing/DefaultCatalogProcessingEngine.ts

@@ -358,7 +358,9 @@ export class DefaultCatalogProcessingEngine {
       return () => {};
     }
 
-    const stitchingStrategy = stitchingStrategyFromConfig(this.config);
+    const stitchingStrategy = stitchingStrategyFromConfig(this.config, {
+      logger: this.logger,
+    });
 
     const runOnce = async () => {
       try {

plugins/catalog-backend/src/stitching/DefaultStitcher.ts

@@ -63,7 +63,9 @@ export class DefaultStitcher implements Stitcher {
       knex: options.knex,
       logger: options.logger,
       metrics: options.metrics,
-      strategy: stitchingStrategyFromConfig(config),
+      strategy: stitchingStrategyFromConfig(config, {
+        logger: options.logger,
+      }),
     });
   }
 

plugins/catalog-backend/src/stitching/types.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { LoggerService } from '@backstage/backend-plugin-api';
 import { Config, readDurationFromConfig } from '@backstage/config';
 import { HumanDuration } from '@backstage/types';
 
@@ -45,6 +46,8 @@ export interface Stitcher {
  * over-stitching of hot spot entities when fan-out/fan-in in terms of relations
  * is very large. It does however also come with some performance cost due to
  * the queuing with how much wall-clock time some types of task take.
+ *
+ * Note: Immediate mode is deprecated and will be removed in a future release.
  */
 export type StitchingStrategy =
   | {
@@ -56,12 +59,23 @@ export type StitchingStrategy =
       stitchTimeout: HumanDuration;
     };
 
-export function stitchingStrategyFromConfig(config: Config): StitchingStrategy {
+let immediateDeprecationLogged = false;
+
+export function stitchingStrategyFromConfig(
+  config: Config,
+  options: { logger: LoggerService },
+): StitchingStrategy {
   const strategyMode = config.getOptionalString(
     'catalog.stitchingStrategy.mode',
   );
 
   if (strategyMode === 'immediate') {
+    if (!immediateDeprecationLogged) {
+      immediateDeprecationLogged = true;
+      options.logger.warn(
+        'DEPRECATED: Immediate mode stitching has been deprecated, and will be removed in the next Backstage release.',
+      );
+    }
     return {
       mode: 'immediate',
     };