entity provider delta remove with refs

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

.changeset/fifty-news-stare.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-node': minor
+---
+
+Make it possible for entity providers to supply only entity refs, instead of full entities, in `delta` mutation deletions.

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

@@ -991,13 +991,7 @@ describe('Default Processing Database', () => {
             added: [],
             removed: [
               {
-                entity: {
-                  apiVersion: '1.0.0',
-                  metadata: {
-                    name: 'new-root',
-                  },
-                  kind: 'Location',
-                } as Entity,
+                entityRef: 'location:default/new-root',
                 locationKey: 'file:/tmp/foobar',
               },
             ],

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

@@ -737,7 +737,7 @@ export class DefaultProcessingDatabase implements ProcessingDatabase {
           deferred: e,
           hash: generateStableHash(e.entity),
         })),
-        toRemove: options.removed.map(e => stringifyEntityRef(e.entity)),
+        toRemove: options.removed.map(e => e.entityRef),
       };
     }
 

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

@@ -81,7 +81,7 @@ export type ReplaceUnprocessedEntitiesOptions =
   | {
       sourceKey: string;
       added: DeferredEntity[];
-      removed: DeferredEntity[];
+      removed: { entityRef: string; locationKey?: string }[];
       type: 'delta';
     };
 

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

@@ -17,6 +17,7 @@
 import {
   Entity,
   entityEnvelopeSchemaValidator,
+  stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { ProcessingDatabase } from '../database/types';
 import {
@@ -50,13 +51,24 @@ class Connection implements EntityProviderConnection {
       });
     } else if (mutation.type === 'delta') {
       this.check(mutation.added.map(e => e.entity));
-      this.check(mutation.removed.map(e => e.entity));
+      this.check(
+        mutation.removed
+          .map(e => ('entity' in e ? e.entity : undefined))
+          .filter((e): e is Entity => Boolean(e)),
+      );
       await db.transaction(async tx => {
         await db.replaceUnprocessedEntities(tx, {
           sourceKey: this.config.id,
           type: 'delta',
           added: mutation.added,
-          removed: mutation.removed,
+          removed: mutation.removed.map(r =>
+            'entityRef' in r
+              ? r
+              : {
+                  entityRef: stringifyEntityRef(r.entity),
+                  locationKey: r.locationKey,
+                },
+          ),
         });
       });
     }

plugins/catalog-node/api-report.md

@@ -139,10 +139,16 @@ export type EntityProviderMutation =
   | {
       type: 'delta';
       added: DeferredEntity[];
-      removed: DeferredEntity[];
+      removed: (
+        | DeferredEntity
+        | {
+            entityRef: string;
+            locationKey?: string;
+          }
+      )[];
     };
 
-// @public (undocumented)
+// @public
 export type EntityProviderRefreshOptions = {
   keys: string[];
 };

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

@@ -17,16 +17,26 @@
 import { DeferredEntity } from '../processing';
 
 /**
- * @public
  * A 'full' mutation replaces all existing entities created by this entity provider with new ones.
  * A 'delta' mutation can both add and remove entities provided by this provider. Previously provided
  * entities from a 'full' mutation are not removed.
+ *
+ * @public
  */
 export type EntityProviderMutation =
-  | { type: 'full'; entities: DeferredEntity[] }
-  | { type: 'delta'; added: DeferredEntity[]; removed: DeferredEntity[] };
+  | {
+      type: 'full';
+      entities: DeferredEntity[];
+    }
+  | {
+      type: 'delta';
+      added: DeferredEntity[];
+      removed: (DeferredEntity | { entityRef: string; locationKey?: string })[];
+    };
 
 /**
+ * The options given to an entity refresh operation.
+ *
  * @public
  */
 export type EntityProviderRefreshOptions = {
@@ -34,30 +44,38 @@ export type EntityProviderRefreshOptions = {
 };
 
 /**
- * The EntityProviderConnection is the connection between the catalog and the entity provider.
- * The EntityProvider use this connection to add and remove entities from the catalog.
+ * The connection between the catalog and the entity provider.
+ * Entity providers use this connection to add and remove entities from the catalog.
+ *
  * @public
  */
 export interface EntityProviderConnection {
   /**
-   * Applies either a full or delta update to the catalog engine.
+   * Applies either a full or a delta update to the catalog engine.
    */
   applyMutation(mutation: EntityProviderMutation): Promise<void>;
 
   /**
-   * Schedules a refresh on all of the entities that has a matching refresh key associated with the provided keys.
+   * Schedules a refresh on all of the entities that have a matching refresh key associated with the provided keys.
    */
   refresh(options: EntityProviderRefreshOptions): Promise<void>;
 }
 
 /**
- * An EntityProvider is able to provide entities to the catalog.
+ * An entity provider is able to provide entities to the catalog.
  * See https://backstage.io/docs/features/software-catalog/life-of-an-entity for more details.
+ *
  * @public
  */
 export interface EntityProvider {
-  /** Unique provider name used internally for caching. */
+  /**
+   * The name of the provider, which must be unique for all providers that are
+   * active in a catalog, and stable over time since emitted entities are
+   * related to the provider by this name.
+   */
   getProviderName(): string;
-  /** Connect is called upon initialization by the catalog engine. */
+  /**
+   * Called upon initialization by the catalog engine.
+   */
   connect(connection: EntityProviderConnection): Promise<void>;
 }