From 17a9550f136173f633214cccc059bab683bc2405 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Mon, 18 May 2026 14:11:11 +0200
Subject: [PATCH] catalog-backend: deprecate immediate mode stitching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mark immediate mode stitching as deprecated in config.d.ts, the
StitchingStrategy type, and log a warning on startup when it is
detected. This is a precursor to removing immediate mode entirely
in the next release.

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 .changeset/deprecate-immediate-stitching.md      |  5 +++++
 plugins/catalog-backend/config.d.ts              |  6 +++++-
 .../processing/DefaultCatalogProcessingEngine.ts |  4 +++-
 .../src/stitching/DefaultStitcher.ts             |  4 +++-
 plugins/catalog-backend/src/stitching/types.ts   | 16 +++++++++++++++-
 5 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/deprecate-immediate-stitching.md

diff --git a/.changeset/deprecate-immediate-stitching.md b/.changeset/deprecate-immediate-stitching.md
new file mode 100644
index 0000000000..e921995912
--- /dev/null
+++ b/.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'`.
diff --git a/plugins/catalog-backend/config.d.ts b/plugins/catalog-backend/config.d.ts
index 433d8c494c..41be62feb4 100644
--- a/plugins/catalog-backend/config.d.ts
+++ b/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';
         }
       | {
diff --git a/plugins/catalog-backend/src/processing/DefaultCatalogProcessingEngine.ts b/plugins/catalog-backend/src/processing/DefaultCatalogProcessingEngine.ts
index a8dad983b2..a8cca7fa0d 100644
--- a/plugins/catalog-backend/src/processing/DefaultCatalogProcessingEngine.ts
+++ b/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 {
diff --git a/plugins/catalog-backend/src/stitching/DefaultStitcher.ts b/plugins/catalog-backend/src/stitching/DefaultStitcher.ts
index e7848961a6..f67adf7942 100644
--- a/plugins/catalog-backend/src/stitching/DefaultStitcher.ts
+++ b/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,
+      }),
     });
   }
 
diff --git a/plugins/catalog-backend/src/stitching/types.ts b/plugins/catalog-backend/src/stitching/types.ts
index 7c8a5c7d65..7dc8ee1ac0 100644
--- a/plugins/catalog-backend/src/stitching/types.ts
+++ b/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',
     };