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