@backstage/plugin-catalog-backend 1.1.0-next.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @backstage/plugin-catalog-backend
 
+## 1.1.0
+
+### Minor Changes
+
+- 8012ac46a0: **BREAKING (alpha api):** Replace `createCatalogPolicyDecision` export with `createCatalogConditionalDecision`, which accepts a permission parameter of type `ResourcePermission<'catalog-entity'>` along with conditions. The permission passed is expected to be the handled permission in `PermissionPolicy#handle`, whose type must first be narrowed using methods like `isPermission` and `isResourcePermission`:
+
+  ```typescript
+  class TestPermissionPolicy implements PermissionPolicy {
+    async handle(
+      request: PolicyQuery<Permission>,
+      _user?: BackstageIdentityResponse,
+    ): Promise<PolicyDecision> {
+      if (
+        // Narrow type of `request.permission` to `ResourcePermission<'catalog-entity'>
+        isResourcePermission(request.permission, RESOURCE_TYPE_CATALOG_ENTITY)
+      ) {
+        return createCatalogConditionalDecision(
+          request.permission,
+          catalogConditions.isEntityOwner(
+            _user?.identity.ownershipEntityRefs ?? [],
+          ),
+        );
+      }
+
+      return {
+        result: AuthorizeResult.ALLOW,
+      };
+  ```
+
+- 8012ac46a0: **BREAKING:** Mark CatalogBuilder#addPermissionRules as @alpha.
+- fb02d2d94d: export `locationSpecToLocationEntity`
+- bf82edf4c9: Added `/validate-entity` endpoint
+
+### Patch Changes
+
+- ada4446733: Specify type of `visibilityPermission` property on collators and collator factories.
+- 1691c6c5c2: Clarify that config locations that emit User and Group kinds now need to declare so in the `catalog.locations.[].rules`
+- 8592cacfd3: Fixed an issue where sometimes entities would have stale relations "stuck" and
+  not getting removed as expected, after the other end of the relation had stopped
+  referring to them.
+- 23646e51a5: Use new `PermissionEvaluator#authorizeConditional` method when retrieving permission conditions.
+- 9fe24b0fc8: Adjust the error messages when entities fail validation, to clearly state what entity that failed it
+- 48405ed232: Added `spec.profile.displayName` to search index for Group kinds
+- 95408dbe99: Enable internal batching of very large deletions, to not run into SQL binding limits
+- 8012ac46a0: Handle changes to @alpha permission-related types.
+
+  - All exported permission rules and conditions now have a `resourceType`.
+  - `createCatalogConditionalDecision` now expects supplied conditions to have the appropriate `resourceType`.
+  - `createCatalogPermissionRule` now expects `resourceType` as part of the supplied rule object.
+  - Introduce new `CatalogPermissionRule` convenience type.
+
+- ffec894ed0: add gitlab to AnnotateScmSlugEntityProcessor
+- Updated dependencies
+  - @backstage/integration@1.1.0
+  - @backstage/plugin-permission-common@0.6.0
+  - @backstage/plugin-permission-node@0.6.0
+  - @backstage/catalog-model@1.0.1
+  - @backstage/plugin-search-common@0.3.3
+  - @backstage/backend-common@0.13.2
+  - @backstage/plugin-catalog-common@1.0.1
+  - @backstage/catalog-client@1.0.1
+  - @backstage/plugin-scaffolder-common@1.0.1
+
+## 1.1.0-next.3
+
+### Patch Changes
+
+- 23646e51a5: Use new `PermissionEvaluator#authorizeConditional` method when retrieving permission conditions.
+- 48405ed232: Added `spec.profile.displayName` to search index for Group kinds
+- Updated dependencies
+  - @backstage/plugin-permission-common@0.6.0-next.1
+  - @backstage/plugin-permission-node@0.6.0-next.2
+  - @backstage/backend-common@0.13.2-next.2
+  - @backstage/integration@1.1.0-next.2
+
+## 1.1.0-next.2
+
+### Minor Changes
+
+- bf82edf4c9: Added `/validate-entity` endpoint
+
+### Patch Changes
+
+- 8592cacfd3: Fixed an issue where sometimes entities would have stale relations "stuck" and
+  not getting removed as expected, after the other end of the relation had stopped
+  referring to them.
+- Updated dependencies
+  - @backstage/catalog-model@1.0.1-next.1
+
 ## 1.1.0-next.1
 
 ### Minor Changes

package/README.md

@@ -27,8 +27,7 @@ restoring the plugin, if you previously removed it.
 
 ```bash
 # From your Backstage root directory
-cd packages/backend
-yarn add @backstage/plugin-catalog-backend
+yarn add --cwd packages/backend @backstage/plugin-catalog-backend
 ```
 
 ### Adding the plugin to your `packages/backend`

package/alpha/package.json

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

package/dist/index.alpha.d.ts

@@ -23,6 +23,7 @@ import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionCondition } from '@backstage/plugin-permission-common';
 import { PermissionCriteria } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -308,7 +309,7 @@ export declare type CatalogEnvironment = {
     database: PluginDatabaseManager;
     config: Config;
     reader: UrlReader;
-    permissions: PermissionAuthorizer;
+    permissions: PermissionEvaluator | PermissionAuthorizer;
 };
 
 /**
@@ -572,8 +573,6 @@ export declare class DefaultCatalogCollatorFactory implements DocumentCollatorFa
     private constructor();
     getCollator(): Promise<Readable>;
     private applyArgsToFormat;
-    private isUserEntity;
-    private getDocumentText;
     private execute;
 }
 

package/dist/index.beta.d.ts

@@ -23,6 +23,7 @@ import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionCondition } from '@backstage/plugin-permission-common';
 import { PermissionCriteria } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -287,7 +288,7 @@ export declare type CatalogEnvironment = {
     database: PluginDatabaseManager;
     config: Config;
     reader: UrlReader;
-    permissions: PermissionAuthorizer;
+    permissions: PermissionEvaluator | PermissionAuthorizer;
 };
 
 /* Excluded from this release type: CatalogPermissionRule */
@@ -506,8 +507,6 @@ export declare class DefaultCatalogCollatorFactory implements DocumentCollatorFa
     private constructor();
     getCollator(): Promise<Readable>;
     private applyArgsToFormat;
-    private isUserEntity;
-    private getDocumentText;
     private execute;
 }
 

package/dist/index.cjs.js

@@ -781,6 +781,24 @@ function createRandomProcessingInterval(options) {
   };
 }
 
+function isUserEntity(entity) {
+  return entity.kind.toLocaleUpperCase("en-US") === "USER";
+}
+function isGroupEntity(entity) {
+  return entity.kind.toLocaleUpperCase("en-US") === "GROUP";
+}
+function getDocumentText(entity) {
+  var _a, _b;
+  const documentTexts = [];
+  documentTexts.push(entity.metadata.description || "");
+  if (isUserEntity(entity) || isGroupEntity(entity)) {
+    if ((_b = (_a = entity.spec) == null ? void 0 : _a.profile) == null ? void 0 : _b.displayName) {
+      documentTexts.push(entity.spec.profile.displayName);
+    }
+  }
+  return documentTexts.join(" : ");
+}
+
 class DefaultCatalogCollatorFactory {
   constructor(options) {
     this.type = "software-catalog";
@@ -812,22 +830,6 @@ class DefaultCatalogCollatorFactory {
     }
     return formatted.toLowerCase();
   }
-  isUserEntity(entity) {
-    return entity.kind.toLocaleUpperCase("en-US") === "USER";
-  }
-  getDocumentText(entity) {
-    var _a, _b, _c, _d, _e, _f;
-    let documentText = entity.metadata.description || "";
-    if (this.isUserEntity(entity)) {
-      if (((_b = (_a = entity.spec) == null ? void 0 : _a.profile) == null ? void 0 : _b.displayName) && documentText) {
-        const displayName = (_d = (_c = entity.spec) == null ? void 0 : _c.profile) == null ? void 0 : _d.displayName;
-        documentText = displayName.concat(" : ", documentText);
-      } else {
-        documentText = ((_f = (_e = entity.spec) == null ? void 0 : _e.profile) == null ? void 0 : _f.displayName) || documentText;
-      }
-    }
-    return documentText;
-  }
   async *execute() {
     var _a, _b, _c, _d, _e, _f, _g;
     const { token } = await this.tokenManager.getToken();
@@ -849,7 +851,7 @@ class DefaultCatalogCollatorFactory {
             kind: entity.kind,
             name: entity.metadata.name
           }),
-          text: this.getDocumentText(entity),
+          text: getDocumentText(entity),
           componentType: ((_c = (_b = entity.spec) == null ? void 0 : _b.type) == null ? void 0 : _c.toString()) || "other",
           type: ((_e = (_d = entity.spec) == null ? void 0 : _d.type) == null ? void 0 : _e.toString()) || "other",
           namespace: entity.metadata.namespace || "default",
@@ -1318,7 +1320,13 @@ class DefaultProcessingDatabase {
       entities: deferredEntities,
       sourceEntityRef: catalogModel.stringifyEntityRef(processedEntity)
     });
-    await tx("relations").where({ originating_entity_id: id }).delete();
+    let previousRelationRows;
+    if (tx.client.config.client.includes("sqlite3")) {
+      previousRelationRows = await tx("relations").select("*").where({ originating_entity_id: id });
+      await tx("relations").where({ originating_entity_id: id }).delete();
+    } else {
+      previousRelationRows = await tx("relations").where({ originating_entity_id: id }).delete().returning("*");
+    }
     const relationRows = relations.map(({ source, target, type }) => ({
       originating_entity_id: id,
       source_entity_ref: catalogModel.stringifyEntityRef(source),
@@ -1326,6 +1334,11 @@ class DefaultProcessingDatabase {
       type
     }));
     await tx.batchInsert("relations", this.deduplicateRelations(relationRows), BATCH_SIZE$1);
+    return {
+      previous: {
+        relations: previousRelationRows
+      }
+    };
   }
   async updateProcessedEntityErrors(txOpaque, options) {
     const tx = txOpaque;
@@ -1802,8 +1815,9 @@ class DefaultCatalogProcessingEngine {
             return;
           }
           result.completedEntity.metadata.uid = id;
+          let oldRelationSources;
           await this.processingDatabase.transaction(async (tx) => {
-            await this.processingDatabase.updateProcessedEntity(tx, {
+            const { previous } = await this.processingDatabase.updateProcessedEntity(tx, {
               id,
               processedEntity: result.completedEntity,
               resultHash,
@@ -1812,11 +1826,22 @@ class DefaultCatalogProcessingEngine {
               deferredEntities: result.deferredEntities,
               locationKey
             });
+            oldRelationSources = new Set(previous.relations.map((r) => r.source_entity_ref));
           });
+          const newRelationSources = new Set(result.relations.map((relation) => catalogModel.stringifyEntityRef(relation.source)));
           const setOfThingsToStitch = /* @__PURE__ */ new Set([
-            catalogModel.stringifyEntityRef(result.completedEntity),
-            ...result.relations.map((relation) => catalogModel.stringifyEntityRef(relation.source))
+            catalogModel.stringifyEntityRef(result.completedEntity)
           ]);
+          newRelationSources.forEach((r) => {
+            if (!oldRelationSources.has(r)) {
+              setOfThingsToStitch.add(r);
+            }
+          });
+          oldRelationSources.forEach((r) => {
+            if (!newRelationSources.has(r)) {
+              setOfThingsToStitch.add(r);
+            }
+          });
           await this.stitcher.stitch(setOfThingsToStitch);
           track.markSuccessfulWithChanges(setOfThingsToStitch.size);
         } catch (error) {
@@ -2866,6 +2891,7 @@ async function createRouter(options) {
     entitiesCatalog,
     locationAnalyzer,
     locationService,
+    orchestrator,
     refreshService,
     config,
     logger,
@@ -2988,6 +3014,46 @@ async function createRouter(options) {
       res.status(200).json(output);
     });
   }
+  if (orchestrator) {
+    router.post("/validate-entity", async (req, res) => {
+      const bodySchema = zod.z.object({
+        entity: zod.z.unknown(),
+        location: zod.z.string()
+      });
+      let body;
+      let entity;
+      let location;
+      try {
+        body = await validateRequestBody(req, bodySchema);
+        entity = validateEntityEnvelope(body.entity);
+        location = catalogModel.parseLocationRef(body.location);
+        if (location.type !== "url")
+          throw new TypeError(`Invalid location ref ${body.location}, only 'url:<target>' is supported, e.g. url:https://host/path`);
+      } catch (err) {
+        return res.status(400).json({
+          errors: [errors.serializeError(err)]
+        });
+      }
+      const processingResult = await orchestrator.process({
+        entity: {
+          ...entity,
+          metadata: {
+            ...entity.metadata,
+            annotations: {
+              [catalogModel.ANNOTATION_LOCATION]: body.location,
+              [catalogModel.ANNOTATION_ORIGIN_LOCATION]: body.location,
+              ...entity.metadata.annotations
+            }
+          }
+        }
+      });
+      if (!processingResult.ok)
+        res.status(400).json({
+          errors: processingResult.errors.map((e) => errors.serializeError(e))
+        });
+      return res.status(200).end();
+    });
+  }
   router.use(backendCommon.errorHandler());
   return router;
 }
@@ -3179,7 +3245,7 @@ class AuthorizedEntitiesCatalog {
     this.transformConditions = transformConditions;
   }
   async entities(request) {
-    const authorizeDecision = (await this.permissionApi.authorize([{ permission: pluginCatalogCommon.catalogEntityReadPermission }], { token: request == null ? void 0 : request.authorizationToken }))[0];
+    const authorizeDecision = (await this.permissionApi.authorizeConditional([{ permission: pluginCatalogCommon.catalogEntityReadPermission }], { token: request == null ? void 0 : request.authorizationToken }))[0];
     if (authorizeDecision.result === pluginPermissionCommon.AuthorizeResult.DENY) {
       return {
         entities: [],
@@ -3196,7 +3262,7 @@ class AuthorizedEntitiesCatalog {
     return this.entitiesCatalog.entities(request);
   }
   async removeEntityByUid(uid, options) {
-    const authorizeResponse = (await this.permissionApi.authorize([{ permission: pluginCatalogCommon.catalogEntityDeletePermission }], { token: options == null ? void 0 : options.authorizationToken }))[0];
+    const authorizeResponse = (await this.permissionApi.authorizeConditional([{ permission: pluginCatalogCommon.catalogEntityDeletePermission }], { token: options == null ? void 0 : options.authorizationToken }))[0];
     if (authorizeResponse.result === pluginPermissionCommon.AuthorizeResult.DENY) {
       throw new errors.NotAllowedError();
     }
@@ -3235,7 +3301,7 @@ class AuthorizedEntitiesCatalog {
     };
   }
   async facets(request) {
-    const authorizeDecision = (await this.permissionApi.authorize([{ permission: pluginCatalogCommon.catalogEntityReadPermission }], { token: request == null ? void 0 : request.authorizationToken }))[0];
+    const authorizeDecision = (await this.permissionApi.authorizeConditional([{ permission: pluginCatalogCommon.catalogEntityReadPermission }], { token: request == null ? void 0 : request.authorizationToken }))[0];
     if (authorizeDecision.result === pluginPermissionCommon.AuthorizeResult.DENY) {
       return {
         facets: Object.fromEntries(request.facets.map((f) => [f, []]))
@@ -3408,7 +3474,14 @@ class CatalogBuilder {
       policy
     });
     const unauthorizedEntitiesCatalog = new DefaultEntitiesCatalog(dbClient);
-    const entitiesCatalog = new AuthorizedEntitiesCatalog(unauthorizedEntitiesCatalog, permissions, pluginPermissionNode.createConditionTransformer(this.permissionRules));
+    let permissionEvaluator;
+    if ("query" in permissions) {
+      permissionEvaluator = permissions;
+    } else {
+      logger.warn("PermissionAuthorizer is deprecated. Please use an instance of PermissionEvaluator instead of PermissionAuthorizer in PluginEnvironment#permissions");
+      permissionEvaluator = pluginPermissionCommon.toPermissionEvaluator(permissions);
+    }
+    const entitiesCatalog = new AuthorizedEntitiesCatalog(unauthorizedEntitiesCatalog, permissionEvaluator, pluginPermissionNode.createConditionTransformer(this.permissionRules));
     const permissionIntegrationRouter = pluginPermissionNode.createPermissionIntegrationRouter({
       resourceType: pluginCatalogCommon.RESOURCE_TYPE_CATALOG_ENTITY,
       getResources: async (resourceRefs) => {
@@ -3435,12 +3508,13 @@ class CatalogBuilder {
     const entityProviders = lodash__default["default"].uniqBy([...this.entityProviders, locationStore, configLocationProvider], (provider) => provider.getProviderName());
     const processingEngine = new DefaultCatalogProcessingEngine(logger, processingDatabase, orchestrator, stitcher, () => crypto.createHash("sha1"));
     const locationAnalyzer = (_b = this.locationAnalyzer) != null ? _b : new RepoLocationAnalyzer(logger, integrations);
-    const locationService = new AuthorizedLocationService(new DefaultLocationService(locationStore, orchestrator), permissions);
-    const refreshService = new AuthorizedRefreshService(new DefaultRefreshService({ database: processingDatabase }), permissions);
+    const locationService = new AuthorizedLocationService(new DefaultLocationService(locationStore, orchestrator), permissionEvaluator);
+    const refreshService = new AuthorizedRefreshService(new DefaultRefreshService({ database: processingDatabase }), permissionEvaluator);
     const router = await createRouter({
       entitiesCatalog,
       locationAnalyzer,
       locationService,
+      orchestrator,
       refreshService,
       logger,
       config,