@backstage/plugin-catalog-backend 1.5.1-next.1 → 1.6.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @backstage/plugin-catalog-backend
 
+## 1.6.0-next.0
+
+### Minor Changes
+
+- 16891a212c: Added new `POST /entities/by-refs` endpoint, which allows you to efficiently
+  batch-fetch entities by their entity ref. This can be useful e.g. in graphql
+  resolvers or similar contexts where you need to fetch many entities at the same
+  time.
+
+### Patch Changes
+
+- d8593ce0e6: Do not use deprecated `LocationSpec` from the `@backstage/plugin-catalog-node` package
+- 3280711113: Updated dependency `msw` to `^0.49.0`.
+- e982f77fe3: Registered shutdown hook in experimental catalog plugin.
+- Updated dependencies
+  - @backstage/catalog-client@1.2.0-next.0
+  - @backstage/backend-common@0.16.1-next.0
+  - @backstage/integration@1.4.1-next.0
+  - @backstage/plugin-permission-common@0.7.2-next.0
+  - @backstage/plugin-permission-node@0.7.2-next.0
+  - @backstage/types@1.0.2-next.0
+  - @backstage/backend-plugin-api@0.1.5-next.0
+  - @backstage/plugin-catalog-node@1.2.2-next.0
+  - @backstage/catalog-model@1.1.4-next.0
+  - @backstage/config@1.0.5-next.0
+  - @backstage/errors@1.1.4-next.0
+  - @backstage/plugin-catalog-common@1.0.9-next.0
+  - @backstage/plugin-scaffolder-common@1.2.3-next.0
+  - @backstage/plugin-search-common@1.1.2-next.0
+
+## 1.5.1
+
+### Patch Changes
+
+- c1a4addda3: Improve processing error logging.
+
+  Adds `location` and `owner` to the logging meta if they are available.
+
+- a7607b5413: Replace usage of deprecataed `UrlReader.read` with `UrlReader.readUrl`.
+- Updated dependencies
+  - @backstage/backend-common@0.16.0
+  - @backstage/integration@1.4.0
+  - @backstage/catalog-model@1.1.3
+  - @backstage/plugin-permission-common@0.7.1
+  - @backstage/types@1.0.1
+  - @backstage/backend-plugin-api@0.1.4
+  - @backstage/plugin-catalog-node@1.2.1
+  - @backstage/plugin-permission-node@0.7.1
+  - @backstage/catalog-client@1.1.2
+  - @backstage/config@1.0.4
+  - @backstage/errors@1.1.3
+  - @backstage/plugin-catalog-common@1.0.8
+  - @backstage/plugin-scaffolder-common@1.2.2
+  - @backstage/plugin-search-common@1.1.1
+
 ## 1.5.1-next.1
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-backend",
-  "version": "1.5.1-next.1",
+  "version": "1.6.0-next.0",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -38,7 +38,7 @@ import { EntityRelationSpec } from '@backstage/plugin-catalog-node';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
 import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
-import { LocationSpec } from '@backstage/plugin-catalog-node';
+import { LocationSpec as LocationSpec_2 } from '@backstage/plugin-catalog-common';
 import { Logger } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
@@ -114,7 +114,7 @@ export declare class AnnotateLocationEntityProcessor implements CatalogProcessor
         integrations: ScmIntegrationRegistry;
     });
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec, _: CatalogProcessorEmit, originLocation: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2, _: CatalogProcessorEmit, originLocation: LocationSpec_2): Promise<Entity>;
 }
 
 /** @public */
@@ -125,7 +125,7 @@ export declare class AnnotateScmSlugEntityProcessor implements CatalogProcessor
     });
     getProcessorName(): string;
     static fromConfig(config: Config): AnnotateScmSlugEntityProcessor;
-    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2): Promise<Entity>;
 }
 
 /** @public */
@@ -133,7 +133,7 @@ export declare class BuiltinKindsEntityProcessor implements CatalogProcessor {
     private readonly validators;
     getProcessorName(): string;
     validateEntityKind(entity: Entity): Promise<boolean>;
-    postProcessEntity(entity: Entity, _location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    postProcessEntity(entity: Entity, _location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /**
@@ -427,7 +427,7 @@ export declare class CodeOwnersProcessor implements CatalogProcessor {
         reader: UrlReader;
     });
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2): Promise<Entity>;
 }
 
 /**
@@ -586,7 +586,7 @@ export { EntityRelationSpec }
 /** @public */
 export declare class FileReaderProcessor implements CatalogProcessor {
     getProcessorName(): string;
-    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
+    readLocation(location: LocationSpec_2, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
 }
 
 /** @public */
@@ -605,7 +605,7 @@ export declare class LocationEntityProcessor implements CatalogProcessor {
     private readonly options;
     constructor(options: LocationEntityProcessorOptions);
     getProcessorName(): string;
-    postProcessEntity(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    postProcessEntity(entity: Entity, location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /** @public */
@@ -613,16 +613,28 @@ export declare type LocationEntityProcessorOptions = {
     integrations: ScmIntegrationRegistry;
 };
 
-export { LocationSpec }
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ * @deprecated use the same type from `@backstage/plugin-catalog-common` instead
+ */
+export declare type LocationSpec = LocationSpec_2;
 
 /** @public */
 export declare function locationSpecToLocationEntity(opts: {
-    location: LocationSpec;
+    location: LocationSpec_2;
     parentEntity?: Entity;
 }): LocationEntityV1alpha1;
 
 /** @public */
-export declare function parseEntityYaml(data: Buffer, location: LocationSpec): Iterable<CatalogProcessorResult>;
+export declare function parseEntityYaml(data: Buffer, location: LocationSpec_2): Iterable<CatalogProcessorResult>;
 
 /**
  * These permission rules can be used to conditionally filter catalog entities
@@ -663,7 +675,7 @@ export declare class PlaceholderProcessor implements CatalogProcessor {
     private readonly options;
     constructor(options: PlaceholderProcessorOptions);
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /** @public */
@@ -719,7 +731,7 @@ export declare class UrlReaderProcessor implements CatalogProcessor {
         logger: Logger;
     });
     getProcessorName(): string;
-    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    readLocation(location: LocationSpec_2, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
     private doRead;
 }
 

package/dist/index.beta.d.ts

@@ -38,7 +38,7 @@ import { EntityRelationSpec } from '@backstage/plugin-catalog-node';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
 import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
-import { LocationSpec } from '@backstage/plugin-catalog-node';
+import { LocationSpec as LocationSpec_2 } from '@backstage/plugin-catalog-common';
 import { Logger } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
@@ -114,7 +114,7 @@ export declare class AnnotateLocationEntityProcessor implements CatalogProcessor
         integrations: ScmIntegrationRegistry;
     });
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec, _: CatalogProcessorEmit, originLocation: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2, _: CatalogProcessorEmit, originLocation: LocationSpec_2): Promise<Entity>;
 }
 
 /** @public */
@@ -125,7 +125,7 @@ export declare class AnnotateScmSlugEntityProcessor implements CatalogProcessor
     });
     getProcessorName(): string;
     static fromConfig(config: Config): AnnotateScmSlugEntityProcessor;
-    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2): Promise<Entity>;
 }
 
 /** @public */
@@ -133,7 +133,7 @@ export declare class BuiltinKindsEntityProcessor implements CatalogProcessor {
     private readonly validators;
     getProcessorName(): string;
     validateEntityKind(entity: Entity): Promise<boolean>;
-    postProcessEntity(entity: Entity, _location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    postProcessEntity(entity: Entity, _location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /**
@@ -380,7 +380,7 @@ export declare class CodeOwnersProcessor implements CatalogProcessor {
         reader: UrlReader;
     });
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2): Promise<Entity>;
 }
 
 /* Excluded from this release type: createCatalogConditionalDecision */
@@ -501,7 +501,7 @@ export { EntityRelationSpec }
 /** @public */
 export declare class FileReaderProcessor implements CatalogProcessor {
     getProcessorName(): string;
-    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
+    readLocation(location: LocationSpec_2, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser): Promise<boolean>;
 }
 
 /** @public */
@@ -520,7 +520,7 @@ export declare class LocationEntityProcessor implements CatalogProcessor {
     private readonly options;
     constructor(options: LocationEntityProcessorOptions);
     getProcessorName(): string;
-    postProcessEntity(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    postProcessEntity(entity: Entity, location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /** @public */
@@ -528,16 +528,28 @@ export declare type LocationEntityProcessorOptions = {
     integrations: ScmIntegrationRegistry;
 };
 
-export { LocationSpec }
+/**
+ * Holds the entity location information.
+ *
+ * @remarks
+ *
+ *  `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch.
+ *  This flag is then set to indicate that the file can be not present.
+ *  default value: 'required'.
+ *
+ * @public
+ * @deprecated use the same type from `@backstage/plugin-catalog-common` instead
+ */
+export declare type LocationSpec = LocationSpec_2;
 
 /** @public */
 export declare function locationSpecToLocationEntity(opts: {
-    location: LocationSpec;
+    location: LocationSpec_2;
     parentEntity?: Entity;
 }): LocationEntityV1alpha1;
 
 /** @public */
-export declare function parseEntityYaml(data: Buffer, location: LocationSpec): Iterable<CatalogProcessorResult>;
+export declare function parseEntityYaml(data: Buffer, location: LocationSpec_2): Iterable<CatalogProcessorResult>;
 
 /* Excluded from this release type: permissionRules */
 
@@ -550,7 +562,7 @@ export declare class PlaceholderProcessor implements CatalogProcessor {
     private readonly options;
     constructor(options: PlaceholderProcessorOptions);
     getProcessorName(): string;
-    preProcessEntity(entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    preProcessEntity(entity: Entity, location: LocationSpec_2, emit: CatalogProcessorEmit): Promise<Entity>;
 }
 
 /** @public */
@@ -606,7 +618,7 @@ export declare class UrlReaderProcessor implements CatalogProcessor {
         logger: Logger;
     });
     getProcessorName(): string;
-    readLocation(location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
+    readLocation(location: LocationSpec_2, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, cache: CatalogProcessorCache): Promise<boolean>;
     private doRead;
 }
 

package/dist/index.cjs.js

@@ -2093,6 +2093,7 @@ class DefaultCatalogProcessingEngine {
         }
       },
       processTask: async (item) => {
+        var _a, _b;
         const track = this.tracker.processStart(item, this.logger);
         try {
           const {
@@ -2130,9 +2131,11 @@ class DefaultCatalogProcessingEngine {
               });
             });
           }
+          const location = (_b = (_a = unprocessedEntity == null ? void 0 : unprocessedEntity.metadata) == null ? void 0 : _a.annotations) == null ? void 0 : _b[catalogModel.ANNOTATION_LOCATION];
           for (const error of result.errors) {
             this.logger.warn(error.message, {
-              entity: entityRef
+              entity: entityRef,
+              location
             });
           }
           const errorsString = JSON.stringify(
@@ -2155,8 +2158,8 @@ class DefaultCatalogProcessingEngine {
           if (!result.ok) {
             Promise.resolve(void 0).then(
               () => {
-                var _a;
-                return (_a = this.onProcessingError) == null ? void 0 : _a.call(this, {
+                var _a2;
+                return (_a2 = this.onProcessingError) == null ? void 0 : _a2.call(this, {
                   unprocessedEntity,
                   errors: result.errors
                 });
@@ -2522,6 +2525,31 @@ class DefaultEntitiesCatalog {
       pageInfo
     };
   }
+  async entitiesBatch(request) {
+    const lookup = /* @__PURE__ */ new Map();
+    for (const chunk of lodash__default["default"].chunk(request.entityRefs, 200)) {
+      let query = this.database("final_entities").innerJoin("refresh_state", {
+        "refresh_state.entity_id": "final_entities.entity_id"
+      }).select({
+        entityRef: "refresh_state.entity_ref",
+        entity: "final_entities.final_entity"
+      }).whereIn("refresh_state.entity_ref", chunk);
+      if (request == null ? void 0 : request.filter) {
+        query = parseFilter(request.filter, query, this.database);
+      }
+      for (const row of await query) {
+        lookup.set(row.entityRef, row.entity ? JSON.parse(row.entity) : null);
+      }
+    }
+    let items = request.entityRefs.map((ref) => {
+      var _a;
+      return (_a = lookup.get(ref)) != null ? _a : null;
+    });
+    if (request.fields) {
+      items = items.map((e) => e && request.fields(e));
+    }
+    return { items };
+  }
   async removeEntityByUid(uid) {
     await this.database("refresh_state").update({
       result_hash: "child-was-deleted",
@@ -3227,6 +3255,19 @@ class Stitcher {
   }
 }
 
+const schema = zod.z.object({
+  entityRefs: zod.z.array(zod.z.string())
+});
+function entitiesBatchRequest(req) {
+  try {
+    return schema.parse(req.body);
+  } catch (error) {
+    throw new errors.InputError(
+      `Malformed request body (did you remember to specify an application/json content type?), ${error.message}`
+    );
+  }
+}
+
 function basicEntityFilter(items) {
   const filtersByKey = {};
   for (const [key, value] of Object.entries(items)) {
@@ -3366,6 +3407,17 @@ function parseEntityTransformParams(params) {
   };
 }
 
+function parseEntityFacetParams(params) {
+  const facetStrings = parseStringsParam(params.facet, "facet");
+  if (facetStrings) {
+    const filtered = facetStrings.filter(Boolean);
+    if (filtered.length) {
+      return filtered;
+    }
+  }
+  throw new errors.InputError("Missing facet parameter");
+}
+
 async function requireRequestBody(req) {
   const contentType = req.header("content-type");
   if (!contentType) {
@@ -3402,17 +3454,6 @@ function disallowReadonlyMode(readonly) {
   }
 }
 
-function parseEntityFacetParams(params) {
-  const facetStrings = parseStringsParam(params.facet, "facet");
-  if (facetStrings) {
-    const filtered = facetStrings.filter(Boolean);
-    if (filtered.length) {
-      return filtered;
-    }
-  }
-  throw new errors.InputError("Missing facet parameter");
-}
-
 async function createRouter(options) {
   const {
     entitiesCatalog,
@@ -3500,7 +3541,16 @@ async function createRouter(options) {
         });
         res.status(200).json(response);
       }
-    ).get("/entity-facets", async (req, res) => {
+    ).post("/entities/by-refs", async (req, res) => {
+      const request = entitiesBatchRequest(req);
+      const token = getBearerToken(req.header("authorization"));
+      const response = await entitiesCatalog.entitiesBatch({
+        entityRefs: request.entityRefs,
+        fields: parseEntityTransformParams(req.query),
+        authorizationToken: token
+      });
+      res.status(200).json(response);
+    }).get("/entity-facets", async (req, res) => {
       const response = await entitiesCatalog.facets({
         filter: parseEntityFilterParams(req.query),
         facets: parseEntityFacetParams(req.query),
@@ -3826,6 +3876,27 @@ class AuthorizedEntitiesCatalog {
     }
     return this.entitiesCatalog.entities(request);
   }
+  async entitiesBatch(request) {
+    const authorizeDecision = (await this.permissionApi.authorizeConditional(
+      [{ permission: pluginCatalogCommon.catalogEntityReadPermission }],
+      { token: request == null ? void 0 : request.authorizationToken }
+    ))[0];
+    if (authorizeDecision.result === pluginPermissionCommon.AuthorizeResult.DENY) {
+      return {
+        items: new Array(request.entityRefs.length).fill(null)
+      };
+    }
+    if (authorizeDecision.result === pluginPermissionCommon.AuthorizeResult.CONDITIONAL) {
+      const permissionFilter = this.transformConditions(
+        authorizeDecision.conditions
+      );
+      return this.entitiesCatalog.entitiesBatch({
+        ...request,
+        filter: (request == null ? void 0 : request.filter) ? { allOf: [permissionFilter, request.filter] } : permissionFilter
+      });
+    }
+    return this.entitiesCatalog.entitiesBatch(request);
+  }
   async removeEntityByUid(uid, options) {
     const authorizeResponse = (await this.permissionApi.authorizeConditional(
       [{ permission: pluginCatalogCommon.catalogEntityDeletePermission }],
@@ -4370,7 +4441,8 @@ const catalogPlugin = backendPluginApi.createBackendPlugin({
         reader: backendPluginApi.urlReaderServiceRef,
         permissions: backendPluginApi.permissionsServiceRef,
         database: backendPluginApi.databaseServiceRef,
-        httpRouter: backendPluginApi.httpRouterServiceRef
+        httpRouter: backendPluginApi.httpRouterServiceRef,
+        lifecycle: backendPluginApi.lifecycleServiceRef
       },
       async init({
         logger,
@@ -4378,7 +4450,8 @@ const catalogPlugin = backendPluginApi.createBackendPlugin({
         reader,
         database,
         permissions,
-        httpRouter
+        httpRouter,
+        lifecycle
       }) {
         const winstonLogger = backendPluginApi.loggerToWinstonLogger(logger);
         const builder = await CatalogBuilder.create({
@@ -4392,6 +4465,11 @@ const catalogPlugin = backendPluginApi.createBackendPlugin({
         builder.addEntityProvider(...processingExtensions.entityProviders);
         const { processingEngine, router } = await builder.build();
         await processingEngine.start();
+        lifecycle.addShutdownHook({
+          fn: async () => {
+            await processingEngine.stop();
+          }
+        });
         httpRouter.use(router);
       }
     });