Merge pull request #12484 from backstage/mob/backend-system

Alpha Backend Framework 🚀

plugins/catalog-backend/api-report.md

@@ -5,6 +5,7 @@
 ```ts
 /// <reference types="node" />
 
+import { BackendRegistrable } from '@backstage/backend-plugin-api';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntityDocument } from '@backstage/plugin-catalog-common';
 import { CatalogProcessor } from '@backstage/plugin-catalog-node';
@@ -222,6 +223,9 @@ export type CatalogEnvironment = {
 export type CatalogPermissionRule<TParams extends unknown[] = unknown[]> =
   PermissionRule<Entity, EntitiesSearchFilter, 'catalog-entity', TParams>;
 
+// @alpha
+export const catalogPlugin: (option: unknown) => BackendRegistrable;
+
 // @public (undocumented)
 export interface CatalogProcessingEngine {
   // (undocumented)

plugins/catalog-backend/package.json

@@ -34,6 +34,7 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
+    "@backstage/backend-plugin-api": "^0.0.0",
     "@backstage/plugin-catalog-node": "^0.0.0",
     "@backstage/backend-common": "^0.14.1-next.2",
     "@backstage/catalog-client": "^1.0.4-next.1",

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

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {
+  configServiceRef,
+  createBackendPlugin,
+  databaseServiceRef,
+  loggerServiceRef,
+  loggerToWinstonLogger,
+  permissionsServiceRef,
+  urlReaderServiceRef,
+  httpRouterServiceRef,
+} from '@backstage/backend-plugin-api';
+import { CatalogBuilder } from './CatalogBuilder';
+import {
+  CatalogProcessor,
+  CatalogProcessingExtensionPoint,
+  catalogProcessingExtentionPoint,
+  EntityProvider,
+} from '@backstage/plugin-catalog-node';
+
+class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
+  #processors = new Array<CatalogProcessor>();
+  #entityProviders = new Array<EntityProvider>();
+
+  addProcessor(processor: CatalogProcessor): void {
+    this.#processors.push(processor);
+  }
+
+  addEntityProvider(provider: EntityProvider): void {
+    this.#entityProviders.push(provider);
+  }
+
+  get processors() {
+    return this.#processors;
+  }
+
+  get entityProviders() {
+    return this.#entityProviders;
+  }
+}
+
+/**
+ * Catalog plugin
+ * @alpha
+ */
+export const catalogPlugin = createBackendPlugin({
+  id: 'catalog',
+  register(env) {
+    const processingExtensions = new CatalogExtensionPointImpl();
+    // plugins depending on this API will be initialized before this plugins init method is executed.
+    env.registerExtensionPoint(
+      catalogProcessingExtentionPoint,
+      processingExtensions,
+    );
+
+    env.registerInit({
+      deps: {
+        logger: loggerServiceRef,
+        config: configServiceRef,
+        reader: urlReaderServiceRef,
+        permissions: permissionsServiceRef,
+        database: databaseServiceRef,
+        httpRouter: httpRouterServiceRef,
+      },
+      async init({
+        logger,
+        config,
+        reader,
+        database,
+        permissions,
+        httpRouter,
+      }) {
+        const winstonLogger = loggerToWinstonLogger(logger);
+        const builder = await CatalogBuilder.create({
+          config,
+          reader,
+          permissions,
+          database,
+          logger: winstonLogger,
+        });
+        builder.addProcessor(...processingExtensions.processors);
+        builder.addEntityProvider(...processingExtensions.entityProviders);
+        const { processingEngine, router } = await builder.build();
+
+        await processingEngine.start();
+
+        httpRouter.use(router);
+      },
+    });
+  },
+});

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

@@ -16,3 +16,4 @@
 
 export type { CatalogEnvironment } from './CatalogBuilder';
 export { CatalogBuilder } from './CatalogBuilder';
+export { catalogPlugin } from './CatalogPlugin';

plugins/catalog-node/api-report.md

@@ -8,6 +8,18 @@
 import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
+import { ServiceRef } from '@backstage/backend-plugin-api';
+
+// @alpha (undocumented)
+export interface CatalogProcessingExtensionPoint {
+  // (undocumented)
+  addEntityProvider(provider: EntityProvider): void;
+  // (undocumented)
+  addProcessor(processor: CatalogProcessor): void;
+}
+
+// @alpha (undocumented)
+export const catalogProcessingExtentionPoint: ServiceRef<CatalogProcessingExtensionPoint>;
 
 // @public (undocumented)
 export type CatalogProcessor = {

plugins/catalog-node/package.json

@@ -25,6 +25,7 @@
     "postpack": "backstage-cli package postpack"
   },
   "dependencies": {
+    "@backstage/backend-plugin-api": "^0.0.0",
     "@backstage/catalog-model": "^1.1.0-next.2",
     "@backstage/errors": "1.1.0-next.0",
     "@backstage/types": "^1.0.0"

plugins/catalog-node/src/extensions.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createServiceRef } from '@backstage/backend-plugin-api';
+import { EntityProvider } from './api';
+import { CatalogProcessor } from './api/processor';
+
+/**
+ * @alpha
+ */
+export interface CatalogProcessingExtensionPoint {
+  addProcessor(processor: CatalogProcessor): void;
+  addEntityProvider(provider: EntityProvider): void;
+}
+
+/**
+ * @alpha
+ */
+export const catalogProcessingExtentionPoint =
+  createServiceRef<CatalogProcessingExtensionPoint>({
+    id: 'catalog.processing',
+  });

plugins/catalog-node/src/index.ts

@@ -20,5 +20,7 @@
  * @packageDocumentation
  */
 
+export type { CatalogProcessingExtensionPoint } from './extensions';
+export { catalogProcessingExtentionPoint } from './extensions';
 export * from './api';
 export * from './processing';

plugins/scaffolder-backend/api-report.md

@@ -5,6 +5,7 @@
 ```ts
 /// <reference types="node" />
 
+import { BackendRegistrable } from '@backstage/backend-plugin-api';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
@@ -543,6 +544,9 @@ export type RunCommandOptions = {
   logStream?: Writable;
 };
 
+// @alpha
+export const scaffolderCatalogModule: (option: unknown) => BackendRegistrable;
+
 // @public (undocumented)
 export class ScaffolderEntitiesProcessor implements CatalogProcessor {
   // (undocumented)

plugins/scaffolder-backend/package.json

@@ -9,7 +9,8 @@
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
-    "types": "dist/index.d.ts"
+    "types": "dist/index.d.ts",
+    "alphaTypes": "dist/index.alpha.d.ts"
   },
   "backstage": {
     "role": "backend-plugin"
@@ -25,7 +26,7 @@
   ],
   "scripts": {
     "start": "backstage-cli package start",
-    "build": "backstage-cli package build",
+    "build": "backstage-cli package build --experimental-type-build",
     "lint": "backstage-cli package lint",
     "test": "backstage-cli package test",
     "prepack": "backstage-cli package prepack",
@@ -42,6 +43,8 @@
     "@backstage/integration": "^1.2.2-next.2",
     "@backstage/plugin-catalog-backend": "^1.2.1-next.2",
     "@backstage/plugin-scaffolder-common": "^1.1.2-next.0",
+    "@backstage/backend-plugin-api": "^0.0.0",
+    "@backstage/plugin-catalog-node": "^0.0.0",
     "@backstage/types": "^1.0.0",
     "@gitbeaker/core": "^35.6.0",
     "@gitbeaker/node": "^35.1.0",
@@ -93,6 +96,7 @@
     "yaml": "^2.0.0"
   },
   "files": [
+    "alpha",
     "dist",
     "migrations",
     "config.d.ts",

plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.test.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { BackendInitRegistry } from '@backstage/backend-plugin-api';
+import { ScaffolderEntitiesProcessor } from '../processor';
+import { scaffolderCatalogModule } from './ScaffolderCatalogModule';
+
+describe('ScaffolderCatalogModule', () => {
+  it('should register the extension point', () => {
+    // TODO(jhaals): clean this up and add test helpers for backend system.
+    const ext = scaffolderCatalogModule({});
+    expect(ext.id).toBe('catalog.scaffolder.module');
+    const registry: jest.Mocked<BackendInitRegistry> = {
+      registerInit: jest.fn(),
+    } as any;
+    ext.register(registry);
+
+    const extensionPoint = {
+      addProcessor: jest.fn(),
+    };
+
+    registry.registerInit.mock.calls[0][0].init({
+      catalogProcessingExtensionPoint: extensionPoint,
+    });
+    expect(extensionPoint.addProcessor).toHaveBeenCalledWith(
+      new ScaffolderEntitiesProcessor(),
+    );
+  });
+});

plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { catalogProcessingExtentionPoint } from '@backstage/plugin-catalog-node';
+import { ScaffolderEntitiesProcessor } from '../processor';
+
+/**
+ * @alpha
+ * Registers the ScaffolderEntitiesProcessor with the catalog processing extension point.
+ */
+export const scaffolderCatalogModule = createBackendModule({
+  moduleId: 'scaffolder.module',
+  pluginId: 'catalog',
+  register(env) {
+    env.registerInit({
+      deps: {
+        catalogProcessingExtensionPoint: catalogProcessingExtentionPoint,
+      },
+      async init({ catalogProcessingExtensionPoint }) {
+        catalogProcessingExtensionPoint.addProcessor(
+          new ScaffolderEntitiesProcessor(),
+        );
+      },
+    });
+  },
+});

plugins/scaffolder-backend/src/extension/index.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { scaffolderCatalogModule } from './ScaffolderCatalogModule';

plugins/scaffolder-backend/src/index.ts

@@ -24,3 +24,4 @@ export * from './scaffolder';
 export * from './service/router';
 export * from './lib';
 export * from './processor';
+export * from './extension';