Merge pull request #9934 from backstage/blam/some-alpha-stuff

🧹 `setRefreshInterval` -> `setProcessingInterval`

.changeset/wild-dolphins-lick.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+**DEPRECATION**: Deprecated the `RefreshIntervalFunction` and `createRandomRefreshInterval` in favour of the `ProcessingIntervalFunction` and `createRandomProcessingInterval` type and method respectively. Please migrate to use the new names.
+
+**DEPRECATION**: Deprecated the `setRefreshInterval` and `setRefreshIntervalSeconds` methods on the `CatalogBuilder` for the new `setProcessingInterval` and `setProcessingIntervalSeconds` methods. Please migrate to use the new names.

plugins/catalog-backend/api-report.md

@@ -218,7 +218,13 @@ export class CatalogBuilder {
     key: string,
     resolver: PlaceholderResolver,
   ): CatalogBuilder;
+  setProcessingInterval(
+    processingInterval: ProcessingIntervalFunction,
+  ): CatalogBuilder;
+  setProcessingIntervalSeconds(seconds: number): CatalogBuilder;
+  // @deprecated
   setRefreshInterval(refreshInterval: RefreshIntervalFunction): CatalogBuilder;
+  // @deprecated
   setRefreshIntervalSeconds(seconds: number): CatalogBuilder;
 }
 
@@ -408,6 +414,12 @@ export const createCatalogPolicyDecision: (
 ) => ConditionalPolicyDecision;
 
 // @public
+export function createRandomProcessingInterval(options: {
+  minSeconds: number;
+  maxSeconds: number;
+}): ProcessingIntervalFunction;
+
+// @public @deprecated
 export function createRandomRefreshInterval(options: {
   minSeconds: number;
   maxSeconds: number;
@@ -989,6 +1001,9 @@ export type PlaceholderResolverResolveUrl = (
   base: string,
 ) => string;
 
+// @public
+export type ProcessingIntervalFunction = () => number;
+
 // @public
 export const processingResult: Readonly<{
   readonly notFoundError: (
@@ -1023,7 +1038,7 @@ export type RecursivePartial<T> = {
     : T[P];
 };
 
-// @public
+// @public @deprecated
 export type RefreshIntervalFunction = () => number;
 
 // @public

plugins/catalog-backend/src/database/DefaultProcessingDatabase.test.ts

@@ -28,7 +28,7 @@ import {
   DbRefreshStateRow,
   DbRelationsRow,
 } from './tables';
-import { createRandomRefreshInterval } from '../processing/refresh';
+import { createRandomProcessingInterval } from '../processing/refresh';
 import { timestampToDateTime } from './conversion';
 import { generateStableHash } from './util';
 
@@ -49,7 +49,7 @@ describe('Default Processing Database', () => {
       db: new DefaultProcessingDatabase({
         database: knex,
         logger,
-        refreshInterval: createRandomRefreshInterval({
+        refreshInterval: createRandomProcessingInterval({
           minSeconds: 100,
           maxSeconds: 150,
         }),

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

@@ -23,5 +23,11 @@ export type {
 } from './types';
 export { DefaultCatalogProcessingOrchestrator } from './DefaultCatalogProcessingOrchestrator';
 
-export { createRandomRefreshInterval } from './refresh';
-export type { RefreshIntervalFunction } from './refresh';
+export {
+  createRandomRefreshInterval,
+  createRandomProcessingInterval,
+} from './refresh';
+export type {
+  RefreshIntervalFunction,
+  ProcessingIntervalFunction,
+} from './refresh';

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

@@ -16,13 +16,21 @@
 
 /**
  * Function that returns the catalog refresh interval in seconds.
+ * @deprecated use {@link ProcessingIntervalFunction} instead
  * @public
  */
 export type RefreshIntervalFunction = () => number;
 
+/**
+ * Function that returns the catalog processing interval in seconds.
+ * @public
+ */
+export type ProcessingIntervalFunction = () => number;
+
 /**
  * Creates a function that returns a random refresh interval between minSeconds and maxSeconds.
  * @returns A {@link RefreshIntervalFunction} that provides the next refresh interval
+ * @deprecated use {@link createRandomProcessingInterval} instead
  * @public
  */
 export function createRandomRefreshInterval(options: {
@@ -34,3 +42,18 @@ export function createRandomRefreshInterval(options: {
     return Math.random() * (maxSeconds - minSeconds) + minSeconds;
   };
 }
+
+/**
+ * Creates a function that returns a random processing interval between minSeconds and maxSeconds.
+ * @returns A {@link ProcessingIntervalFunction} that provides the next processing interval
+ * @public
+ */
+export function createRandomProcessingInterval(options: {
+  minSeconds: number;
+  maxSeconds: number;
+}): ProcessingIntervalFunction {
+  const { minSeconds, maxSeconds } = options;
+  return () => {
+    return Math.random() * (maxSeconds - minSeconds) + minSeconds;
+  };
+}

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

@@ -76,8 +76,9 @@ import { DefaultEntitiesCatalog } from './DefaultEntitiesCatalog';
 import { DefaultCatalogProcessingOrchestrator } from '../processing/DefaultCatalogProcessingOrchestrator';
 import { Stitcher } from '../stitching/Stitcher';
 import {
-  createRandomRefreshInterval,
+  createRandomProcessingInterval,
   RefreshIntervalFunction,
+  ProcessingIntervalFunction,
 } from '../processing/refresh';
 import { createRouter } from './createRouter';
 import { DefaultRefreshService } from './DefaultRefreshService';
@@ -139,8 +140,8 @@ export class CatalogBuilder {
   private processors: CatalogProcessor[];
   private processorsReplace: boolean;
   private parser: CatalogProcessorParser | undefined;
-  private refreshInterval: RefreshIntervalFunction =
-    createRandomRefreshInterval({
+  private processingInterval: ProcessingIntervalFunction =
+    createRandomProcessingInterval({
       minSeconds: 100,
       maxSeconds: 150,
     });
@@ -192,9 +193,28 @@ export class CatalogBuilder {
    * Seconds provided will be multiplied by 1.5
    * The default refresh duration is 100-150 seconds.
    * setting this too low will potentially deplete request quotas to upstream services.
+   *
+   * @deprecated use {@link CatalogBuilder#setProcessingIntervalSeconds} instead
    */
   setRefreshIntervalSeconds(seconds: number): CatalogBuilder {
-    this.refreshInterval = createRandomRefreshInterval({
+    this.env.logger.warn(
+      '[DEPRECATION] - CatalogBuilder.setRefreshIntervalSeconds is deprecated. Use CatalogBuilder.setProcessingIntervalSeconds instead.',
+    );
+    this.processingInterval = createRandomProcessingInterval({
+      minSeconds: seconds,
+      maxSeconds: seconds * 1.5,
+    });
+    return this;
+  }
+
+  /**
+   * Processing interval determines how often entities should be processed.
+   * Seconds provided will be multiplied by 1.5
+   * The default processing interval is 100-150 seconds.
+   * setting this too low will potentially deplete request quotas to upstream services.
+   */
+  setProcessingIntervalSeconds(seconds: number): CatalogBuilder {
+    this.processingInterval = createRandomProcessingInterval({
       minSeconds: seconds,
       maxSeconds: seconds * 1.5,
     });
@@ -204,9 +224,25 @@ export class CatalogBuilder {
   /**
    * Overwrites the default refresh interval function used to spread
    * entity updates in the catalog.
+   *
+   * @deprecated use {@link CatalogBuilder#setProcessingInterval} instead
    */
   setRefreshInterval(refreshInterval: RefreshIntervalFunction): CatalogBuilder {
-    this.refreshInterval = refreshInterval;
+    this.env.logger.warn(
+      '[DEPRECATION] - CatalogBuilder.setRefreshInterval is deprecated. Use CatalogBuilder.setProcessingInterval instead.',
+    );
+    this.processingInterval = refreshInterval;
+    return this;
+  }
+
+  /**
+   * Overwrites the default processing interval function used to spread
+   * entity updates in the catalog.
+   */
+  setProcessingInterval(
+    processingInterval: ProcessingIntervalFunction,
+  ): CatalogBuilder {
+    this.processingInterval = processingInterval;
     return this;
   }
 
@@ -396,7 +432,7 @@ export class CatalogBuilder {
     const processingDatabase = new DefaultProcessingDatabase({
       database: dbClient,
       logger,
-      refreshInterval: this.refreshInterval,
+      refreshInterval: this.processingInterval,
     });
     const integrations = ScmIntegrations.fromConfig(config);
     const rulesEnforcer = DefaultCatalogRulesEnforcer.fromConfig(config);