permission-node: refactor PermissionRuleAccessor to PermissionRuleset

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/gold-rabbits-change.md

@@ -2,4 +2,4 @@
 '@backstage/plugin-permission-node': patch
 ---
 
-Added a new `PermissionRuleAccessor` type that encapsulates a lookup function for permission rules, which can be created by the new `PermissionsRegistryService` via the `getRuleAccessor` method. The `createConditionTransformer` and `createConditionAuthorizer` functions have been adapted to receive these accessors as arguments, with their older counterparts being deprecated.
+Added a new `PermissionRuleset` type that encapsulates a lookup function for permission rules, which can be created by the new `PermissionsRegistryService` via the `getPermissionRuleset` method. The `createConditionTransformer` and `createConditionAuthorizer` functions have been adapted to receive these accessors as arguments, with their older counterparts being deprecated.

.changeset/gorgeous-shoes-stare.md

@@ -2,4 +2,4 @@
 '@backstage/backend-test-utils': patch
 ---
 
-Added the new `getRuleAccessor` method to `mockServices.permissionsRegistry`.
+Added the new `getPermissionRuleset` method to `mockServices.permissionsRegistry`.

.changeset/witty-ducks-cross.md

@@ -3,4 +3,4 @@
 '@backstage/backend-defaults': patch
 ---
 
-Updated `PermissionsRegistryService` to use `PermissionResourceRef`s and added the `getRuleAccessor` method.
+Updated `PermissionsRegistryService` to use `PermissionResourceRef`s and added the `getPermissionRuleset` method.

docs/permissions/plugin-authors/04-authorizing-access-to-paginated-data.md

@@ -142,7 +142,7 @@ import {
 
 /* highlight-add-start */
 const transformConditions = createConditionTransformer(
-  permissionsRegistry.getRuleAccessor(todoListPermissionResourceRef)
+  permissionsRegistry.getPermissionRuleset(todoListPermissionResourceRef)
 );
 /* highlight-add-end */
 

packages/backend-defaults/src/entrypoints/permissionsRegistry/permissionsRegistryServiceFactory.ts

@@ -74,8 +74,8 @@ export const permissionsRegistryServiceFactory = createServiceFactory({
         }
         router.addPermissionRules(rules);
       },
-      getRuleAccessor(resourceRef) {
-        return router.getRuleAccessor(resourceRef);
+      getPermissionRuleset(resourceRef) {
+        return router.getPermissionRuleset(resourceRef);
       },
     } satisfies PermissionsRegistryService;
   },

packages/backend-plugin-api/report.api.md

@@ -21,7 +21,7 @@ import { PermissionAttributes } from '@backstage/plugin-permission-common';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionResourceRef } from '@backstage/plugin-permission-node';
 import { PermissionRule } from '@backstage/plugin-permission-node';
-import { PermissionRuleAccessor } from '@backstage/plugin-permission-node';
+import { PermissionRuleset } from '@backstage/plugin-permission-node';
 import { QueryPermissionRequest } from '@backstage/plugin-permission-common';
 import { QueryPermissionResponse } from '@backstage/plugin-permission-common';
 import { Readable } from 'stream';
@@ -475,9 +475,9 @@ export interface PermissionsRegistryService {
       TQuery
     >,
   ): void;
-  getRuleAccessor<TResourceType extends string, TResource, TQuery>(
+  getPermissionRuleset<TResourceType extends string, TResource, TQuery>(
     resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
-  ): PermissionRuleAccessor<TResource, TQuery, TResourceType>;
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 }
 
 // @public

packages/backend-plugin-api/src/services/definitions/PermissionsRegistryService.ts

@@ -18,7 +18,7 @@ import { Permission } from '@backstage/plugin-permission-common';
 import {
   PermissionResourceRef,
   PermissionRule,
-  PermissionRuleAccessor,
+  PermissionRuleset,
 } from '@backstage/plugin-permission-node';
 
 /**
@@ -148,7 +148,7 @@ export interface PermissionsRegistryService {
    *
    * Primarily intended for use with {@link @backstage/plugin-permission-node#createConditionAuthorizer} and {@link @backstage/plugin-permission-node#createConditionTransformer}.
    */
-  getRuleAccessor<TResourceType extends string, TResource, TQuery>(
+  getPermissionRuleset<TResourceType extends string, TResource, TQuery>(
     resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
-  ): PermissionRuleAccessor<TResource, TQuery, TResourceType>;
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 }

packages/backend-test-utils/src/next/services/mockServices.ts

@@ -489,7 +489,7 @@ export namespace mockServices {
       addPermissionRules: jest.fn(),
       addPermissions: jest.fn(),
       addResourceType: jest.fn(),
-      getRuleAccessor: jest.fn(),
+      getPermissionRuleset: jest.fn(),
     }));
   }
 

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

@@ -561,7 +561,7 @@ export class CatalogBuilder {
       permissionsService,
       permissionsRegistry
         ? createConditionTransformer(
-            permissionsRegistry.getRuleAccessor(
+            permissionsRegistry.getPermissionRuleset(
               catalogEntityPermissionResourceRef,
             ),
           )

plugins/permission-node/report.api.md

@@ -79,7 +79,7 @@ export type ConditionTransformer<TQuery> = (
 
 // @public
 export function createConditionAuthorizer<TResource>(
-  permissionRuleAccessor: PermissionRuleAccessor<TResource>,
+  permissionRuleset: PermissionRuleset<TResource>,
 ): (decision: PolicyDecision, resource: TResource | undefined) => boolean;
 
 // @public @deprecated (undocumented)
@@ -130,7 +130,7 @@ export const createConditionFactory: <
 
 // @public
 export function createConditionTransformer<TQuery>(
-  permissionRuleAccessor: PermissionRuleAccessor<any, TQuery>,
+  permissionRuleset: PermissionRuleset<any, TQuery>,
 ): ConditionTransformer<TQuery>;
 
 // @public @deprecated (undocumented)
@@ -173,9 +173,9 @@ export function createPermissionIntegrationRouter<
       TResource
     >,
   ): void;
-  getRuleAccessor<TResource, TQuery, TResourceType extends string>(
+  getPermissionRuleset<TResource, TQuery, TResourceType extends string>(
     resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
-  ): PermissionRuleAccessor<TResource, TQuery, TResourceType>;
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 };
 
 // @public
@@ -351,11 +351,13 @@ export type PermissionRule<
 };
 
 // @public
-export type PermissionRuleAccessor<
+export type PermissionRuleset<
   TResource = unknown,
   TQuery = unknown,
   TResourceType extends string = string,
-> = (name: string) => PermissionRule<TResource, TQuery, TResourceType>;
+> = {
+  getRuleByName(name: string): PermissionRule<TResource, TQuery, TResourceType>;
+};
 
 // @public
 export type PolicyQuery = {

plugins/permission-node/src/integration/createConditionTransformer.ts

@@ -20,7 +20,7 @@ import {
   PermissionCondition,
   PermissionCriteria,
 } from '@backstage/plugin-permission-common';
-import { PermissionRule, PermissionRuleAccessor } from '../types';
+import { PermissionRule, PermissionRuleset } from '../types';
 import {
   createGetRule,
   isAndCriteria,
@@ -77,11 +77,11 @@ export type ConditionTransformer<TQuery> = (
  * @public
  */
 export function createConditionTransformer<TQuery>(
-  permissionRuleAccessor: PermissionRuleAccessor<any, TQuery>,
+  permissionRuleset: PermissionRuleset<any, TQuery>,
 ): ConditionTransformer<TQuery>;
 /**
  * @public
- * @deprecated Use the version of `createConditionTransformer` that accepts a `PermissionRuleAccessor` instead.
+ * @deprecated Use the version of `createConditionTransformer` that accepts a `PermissionRuleset` instead.
  */
 export function createConditionTransformer<
   TQuery,
@@ -90,11 +90,11 @@ export function createConditionTransformer<
 export function createConditionTransformer<TQuery>(
   permissionRules:
     | PermissionRule<any, TQuery, string>[]
-    | PermissionRuleAccessor<any, TQuery>,
+    | PermissionRuleset<any, TQuery>,
 ): ConditionTransformer<TQuery> {
   const getRule =
-    typeof permissionRules === 'function'
-      ? permissionRules
+    'getRuleByName' in permissionRules
+      ? (n: string) => permissionRules.getRuleByName(n)
       : createGetRule(permissionRules);
 
   return conditions => mapConditions(conditions, getRule);

plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts

@@ -30,7 +30,7 @@ import {
   PermissionCriteria,
   PolicyDecision,
 } from '@backstage/plugin-permission-common';
-import { PermissionRule, PermissionRuleAccessor } from '../types';
+import { PermissionRule, PermissionRuleset } from '../types';
 import {
   NoInfer,
   createGetRule,
@@ -165,11 +165,11 @@ const applyConditions = <TResourceType extends string, TResource>(
  * @public
  */
 export function createConditionAuthorizer<TResource>(
-  permissionRuleAccessor: PermissionRuleAccessor<TResource>,
+  permissionRuleset: PermissionRuleset<TResource>,
 ): (decision: PolicyDecision, resource: TResource | undefined) => boolean;
 /**
  * @public
- * @deprecated Use the version of `createConditionAuthorizer` that accepts a `PermissionRuleAccessor` instead.
+ * @deprecated Use the version of `createConditionAuthorizer` that accepts a `PermissionRuleset` instead.
  */
 export function createConditionAuthorizer<TResource, TQuery>(
   rules: PermissionRule<TResource, TQuery, string>[],
@@ -177,9 +177,12 @@ export function createConditionAuthorizer<TResource, TQuery>(
 export function createConditionAuthorizer<TResource, TQuery>(
   rules:
     | PermissionRule<TResource, TQuery, string>[]
-    | PermissionRuleAccessor<TResource>,
+    | PermissionRuleset<TResource>,
 ): (decision: PolicyDecision, resource: TResource | undefined) => boolean {
-  const getRule = typeof rules === 'function' ? rules : createGetRule(rules);
+  const getRule =
+    'getRuleByName' in rules
+      ? (n: string) => rules.getRuleByName(n)
+      : createGetRule(rules);
 
   return (
     decision: PolicyDecision,
@@ -439,9 +442,9 @@ export function createPermissionIntegrationRouter<
       TResource
     >,
   ): void;
-  getRuleAccessor<TResource, TQuery, TResourceType extends string>(
+  getPermissionRuleset<TResource, TQuery, TResourceType extends string>(
     resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
-  ): PermissionRuleAccessor<TResource, TQuery, TResourceType>;
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 } {
   const store = new PermissionIntegrationMetadataStore();
 
@@ -531,12 +534,12 @@ export function createPermissionIntegrationRouter<
     ) {
       store.addResourceType(resource);
     },
-    getRuleAccessor<TResource, TQuery, TResourceType extends string>(
+    getPermissionRuleset<TResource, TQuery, TResourceType extends string>(
       resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
-    ): PermissionRuleAccessor<TResource, TQuery, TResourceType> {
-      return store.getRuleMapper(
-        resourceRef.resourceType,
-      ) as PermissionRuleAccessor<TResource, TQuery, TResourceType>;
+    ): PermissionRuleset<TResource, TQuery, TResourceType> {
+      return {
+        getRuleByName: store.getRuleMapper(resourceRef.resourceType),
+      } as PermissionRuleset<TResource, TQuery, TResourceType>;
     },
   });
 }

plugins/permission-node/src/types.ts

@@ -72,14 +72,16 @@ export type PermissionRule<
  *
  * @remarks
  *
- * Accessed via {@link @backstage/backend-plugin-api#PermissionsRegistryService.getRuleAccessor}.
+ * Accessed via {@link @backstage/backend-plugin-api#PermissionsRegistryService.getPermissionRuleset}.
  *
  * Will throw an error if a rule with the provided name does not exist.
  *
  * @public
  */
-export type PermissionRuleAccessor<
+export type PermissionRuleset<
   TResource = unknown,
   TQuery = unknown,
   TResourceType extends string = string,
-> = (name: string) => PermissionRule<TResource, TQuery, TResourceType>;
+> = {
+  getRuleByName(name: string): PermissionRule<TResource, TQuery, TResourceType>;
+};