Merge pull request #13197 from backstage/mob/services

backend-system: add default service factories

.changeset/gorgeous-swans-kiss.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-github': patch
+---
+
+New experimental alpha exports for use with the upcoming backend system.

.changeset/old-tables-joke.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': patch
+---
+
+Simplified the `ServiceFactory` type and removed `AnyServiceFactory`.

.changeset/spicy-cherries-remember.md

@@ -0,0 +1,7 @@
+---
+'@backstage/backend-app-api': patch
+'@backstage/backend-defaults': patch
+'@backstage/backend-test-utils': patch
+---
+
+Updated usages of `ServiceFactory`.

.changeset/strong-games-kiss.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-node': patch
+---
+
+The experimental `CatalogProcessingExtensionPoint` now accepts multiple providers and processors at once.

.changeset/tame-papayas-protect.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': patch
+---
+
+When defining a new `ServiceRef` you can now also include a `defaultFactory`, which will be used to construct instances of the service in case there is no explicit factory defined.

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

@@ -3,7 +3,6 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyServiceFactory } from '@backstage/backend-plugin-api';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { Config } from '@backstage/config';
 import { ExtensionPoint } from '@backstage/backend-plugin-api';
@@ -29,14 +28,10 @@ export interface Backend {
 }
 
 // @public (undocumented)
-export const cacheFactory: ServiceFactory<
-  PluginCacheManager,
-  PluginCacheManager,
-  {}
->;
+export const cacheFactory: ServiceFactory<PluginCacheManager>;
 
 // @public (undocumented)
-export const configFactory: ServiceFactory<Config, Config, {}>;
+export const configFactory: ServiceFactory<Config>;
 
 // @public (undocumented)
 export function createSpecializedBackend(
@@ -46,46 +41,28 @@ export function createSpecializedBackend(
 // @public (undocumented)
 export interface CreateSpecializedBackendOptions {
   // (undocumented)
-  services: AnyServiceFactory[];
+  services: ServiceFactory[];
 }
 
 // @public (undocumented)
-export const databaseFactory: ServiceFactory<
-  PluginDatabaseManager,
-  PluginDatabaseManager,
-  {}
->;
+export const databaseFactory: ServiceFactory<PluginDatabaseManager>;
 
 // @public (undocumented)
-export const discoveryFactory: ServiceFactory<
-  PluginEndpointDiscovery,
-  PluginEndpointDiscovery,
-  {}
->;
+export const discoveryFactory: ServiceFactory<PluginEndpointDiscovery>;
 
 // @public (undocumented)
-export const httpRouterFactory: ServiceFactory<
-  HttpRouterService,
-  HttpRouterService,
-  {}
->;
+export const httpRouterFactory: ServiceFactory<HttpRouterService>;
 
 // @public (undocumented)
-export const loggerFactory: ServiceFactory<Logger, Logger, {}>;
+export const loggerFactory: ServiceFactory<Logger>;
 
 // @public (undocumented)
 export const permissionsFactory: ServiceFactory<
-  PermissionAuthorizer | PermissionEvaluator,
-  PermissionAuthorizer | PermissionEvaluator,
-  {}
+  PermissionAuthorizer | PermissionEvaluator
 >;
 
 // @public (undocumented)
-export const schedulerFactory: ServiceFactory<
-  PluginTaskScheduler,
-  PluginTaskScheduler,
-  {}
->;
+export const schedulerFactory: ServiceFactory<PluginTaskScheduler>;
 
 // @public (undocumented)
 export type ServiceOrExtensionPoint<T = unknown> =
@@ -93,12 +70,8 @@ export type ServiceOrExtensionPoint<T = unknown> =
   | ServiceRef<T>;
 
 // @public (undocumented)
-export const tokenManagerFactory: ServiceFactory<
-  TokenManager,
-  TokenManager,
-  {}
->;
+export const tokenManagerFactory: ServiceFactory<TokenManager>;
 
 // @public (undocumented)
-export const urlReaderFactory: ServiceFactory<UrlReader, UrlReader, {}>;
+export const urlReaderFactory: ServiceFactory<UrlReader>;
 ```

packages/backend-app-api/src/wiring/BackendInitializer.ts

@@ -108,7 +108,9 @@ export class BackendInitializer {
             id: feature.id,
             provides,
             consumes: new Set(Object.values(registerOptions.deps)),
-            deps: registerOptions.deps,
+            deps: registerOptions.deps as {
+              [name: string]: ServiceOrExtensionPoint;
+            },
             init: registerOptions.init as BackendRegisterInit['init'],
           };
         },

packages/backend-app-api/src/wiring/BackstageBackend.ts

@@ -14,10 +14,7 @@
  * limitations under the License.
  */
 
-import {
-  AnyServiceFactory,
-  BackendFeature,
-} from '@backstage/backend-plugin-api';
+import { ServiceFactory, BackendFeature } from '@backstage/backend-plugin-api';
 import { BackendInitializer } from './BackendInitializer';
 import { ServiceRegistry } from './ServiceRegistry';
 import { Backend } from './types';
@@ -26,7 +23,7 @@ export class BackstageBackend implements Backend {
   #services: ServiceRegistry;
   #initializer: BackendInitializer;
 
-  constructor(apiFactories: AnyServiceFactory[]) {
+  constructor(apiFactories: ServiceFactory[]) {
     this.#services = new ServiceRegistry(apiFactories);
     this.#initializer = new BackendInitializer(this.#services);
   }

packages/backend-app-api/src/wiring/ServiceRegistry.test.ts

@@ -0,0 +1,173 @@
+/*
+ * 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,
+  createServiceFactory,
+} from '@backstage/backend-plugin-api';
+import { ServiceRegistry } from './ServiceRegistry';
+
+const ref1 = createServiceRef<{ x: number; pluginId: string }>({
+  id: '1',
+});
+const sf1 = createServiceFactory({
+  service: ref1,
+  deps: {},
+  factory: async () => {
+    return async pluginId => {
+      return { x: 1, pluginId };
+    };
+  },
+});
+
+const ref2 = createServiceRef<{ x: number; pluginId: string }>({
+  id: '2',
+});
+const sf2 = createServiceFactory({
+  service: ref2,
+  deps: {},
+  factory: async () => {
+    return async pluginId => {
+      return { x: 2, pluginId };
+    };
+  },
+});
+const sf2b = createServiceFactory({
+  service: ref2,
+  deps: {},
+  factory: async () => {
+    return async pluginId => {
+      return { x: 22, pluginId };
+    };
+  },
+});
+
+const refDefault1 = createServiceRef<{ x: number; pluginId: string }>({
+  id: '1',
+  defaultFactory: async service =>
+    createServiceFactory({
+      service,
+      deps: {},
+      factory: async () => async pluginId => ({ x: 10, pluginId }),
+    }),
+});
+
+const refDefault2a = createServiceRef<{ x: number; pluginId: string }>({
+  id: '2a',
+  defaultFactory: async service =>
+    createServiceFactory({
+      service,
+      deps: {},
+      factory: async () => async pluginId => ({ x: 20, pluginId }),
+    }),
+});
+
+const refDefault2b = createServiceRef<{ x: number; pluginId: string }>({
+  id: '2b',
+  defaultFactory: async service =>
+    createServiceFactory({
+      service,
+      deps: {},
+      factory: async () => async pluginId => ({ x: 220, pluginId }),
+    }),
+});
+
+describe('ServiceRegistry', () => {
+  it('should return undefined if there is no factory defined', async () => {
+    const registry = new ServiceRegistry([]);
+    expect(registry.get(ref1)).toBe(undefined);
+  });
+
+  it('should return a factory for a registered ref', async () => {
+    const registry = new ServiceRegistry([sf1]);
+    const factory = registry.get(ref1)!;
+    expect(factory).toEqual(expect.any(Function));
+    await expect(factory('catalog')).resolves.toEqual({
+      x: 1,
+      pluginId: 'catalog',
+    });
+    await expect(factory('scaffolder')).resolves.toEqual({
+      x: 1,
+      pluginId: 'scaffolder',
+    });
+    expect(await factory('catalog')).toBe(await factory('catalog'));
+  });
+
+  it('should handle multiple factories with different serviceRefs', async () => {
+    const registry = new ServiceRegistry([sf1, sf2]);
+    const factory1 = registry.get(ref1)!;
+    const factory2 = registry.get(ref2)!;
+    expect(factory1).toEqual(expect.any(Function));
+    expect(factory2).toEqual(expect.any(Function));
+    await expect(factory1('catalog')).resolves.toEqual({
+      x: 1,
+      pluginId: 'catalog',
+    });
+    await expect(factory2('catalog')).resolves.toEqual({
+      x: 2,
+      pluginId: 'catalog',
+    });
+    expect(await factory1('catalog')).not.toBe(await factory2('catalog'));
+  });
+
+  it('should use the last factory for each ref', async () => {
+    const registry = new ServiceRegistry([sf2, sf2b]);
+    const factory2 = registry.get(ref2)!;
+    await expect(factory2('catalog')).resolves.toEqual({
+      x: 22,
+      pluginId: 'catalog',
+    });
+  });
+
+  it('should return the defaultFactory from the ref if not provided to the registry', async () => {
+    const registry = new ServiceRegistry([]);
+    const factory = registry.get(refDefault1)!;
+    expect(factory).toEqual(expect.any(Function));
+    await expect(factory('catalog')).resolves.toEqual({
+      x: 10,
+      pluginId: 'catalog',
+    });
+  });
+
+  it('should not return the defaultFactory from the ref if provided to the registry', async () => {
+    const registry = new ServiceRegistry([sf1]);
+    const factory = registry.get(refDefault1)!;
+    expect(factory).toEqual(expect.any(Function));
+    await expect(factory('catalog')).resolves.toEqual({
+      x: 1,
+      pluginId: 'catalog',
+    });
+  });
+
+  it('should handle duplicate defaultFactories by duplicating the implementations', async () => {
+    const registry = new ServiceRegistry([]);
+    const factoryA = registry.get(refDefault2a)!;
+    const factoryB = registry.get(refDefault2b)!;
+    expect(factoryA).toEqual(expect.any(Function));
+    expect(factoryB).toEqual(expect.any(Function));
+    await expect(factoryA('catalog')).resolves.toEqual({
+      x: 20,
+      pluginId: 'catalog',
+    });
+    await expect(factoryB('catalog')).resolves.toEqual({
+      x: 220,
+      pluginId: 'catalog',
+    });
+    expect(await factoryA('catalog')).toBe(await factoryA('catalog'));
+    expect(await factoryB('catalog')).toBe(await factoryB('catalog'));
+    expect(await factoryA('catalog')).not.toBe(await factoryB('catalog'));
+  });
+});

packages/backend-app-api/src/wiring/ServiceRegistry.ts

@@ -14,35 +14,47 @@
  * limitations under the License.
  */
 import {
-  AnyServiceFactory,
+  ServiceFactory,
   FactoryFunc,
   ServiceRef,
 } from '@backstage/backend-plugin-api';
 
 export class ServiceRegistry {
-  readonly #implementations: Map<string, Map<string, unknown>>;
-  readonly #factories: Map<string, AnyServiceFactory>;
+  readonly #providedFactories: Map<string, ServiceFactory>;
+  readonly #loadedDefaultFactories: Map<Function, ServiceFactory>;
+  readonly #implementations: Map<ServiceFactory, Map<string, unknown>>;
 
-  constructor(factories: AnyServiceFactory[]) {
-    this.#factories = new Map(factories.map(f => [f.service.id, f]));
+  constructor(factories: ServiceFactory<any>[]) {
+    this.#providedFactories = new Map(factories.map(f => [f.service.id, f]));
+    this.#loadedDefaultFactories = new Map();
     this.#implementations = new Map();
   }
 
   get<T>(ref: ServiceRef<T>): FactoryFunc<T> | undefined {
-    const factory = this.#factories.get(ref.id);
-    if (!factory) {
+    let factory = this.#providedFactories.get(ref.id);
+    const { defaultFactory } = ref;
+    if (!factory && !defaultFactory) {
       return undefined;
     }
 
     return async (pluginId: string): Promise<T> => {
-      let implementations = this.#implementations.get(ref.id);
+      if (!factory) {
+        let loadedFactory = this.#loadedDefaultFactories.get(defaultFactory!);
+        if (!loadedFactory) {
+          loadedFactory = (await defaultFactory!(ref)) as ServiceFactory;
+          this.#loadedDefaultFactories.set(defaultFactory!, loadedFactory);
+        }
+        factory = loadedFactory;
+      }
+
+      let implementations = this.#implementations.get(factory);
       if (implementations) {
         if (implementations.has(pluginId)) {
           return implementations.get(pluginId) as T;
         }
       } else {
         implementations = new Map();
-        this.#implementations.set(ref.id, implementations);
+        this.#implementations.set(factory, implementations);
       }
 
       const factoryDeps = Object.fromEntries(

packages/backend-app-api/src/wiring/types.ts

@@ -15,7 +15,7 @@
  */
 
 import {
-  AnyServiceFactory,
+  ServiceFactory,
   BackendFeature,
   ExtensionPoint,
   FactoryFunc,
@@ -43,7 +43,7 @@ export interface BackendRegisterInit {
  * @public
  */
 export interface CreateSpecializedBackendOptions {
-  services: AnyServiceFactory[];
+  services: ServiceFactory[];
 }
 
 export type ServiceHolder = {

packages/backend-defaults/api-report.md

@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyServiceFactory } from '@backstage/backend-plugin-api';
 import { Backend } from '@backstage/backend-app-api';
+import { ServiceFactory } from '@backstage/backend-plugin-api';
 
 // @public (undocumented)
 export function createBackend(options?: CreateBackendOptions): Backend;
@@ -12,6 +12,6 @@ export function createBackend(options?: CreateBackendOptions): Backend;
 // @public (undocumented)
 export interface CreateBackendOptions {
   // (undocumented)
-  services?: AnyServiceFactory[];
+  services?: ServiceFactory[];
 }
 ```

packages/backend-defaults/src/CreateBackend.ts

@@ -28,7 +28,7 @@ import {
   tokenManagerFactory,
   urlReaderFactory,
 } from '@backstage/backend-app-api';
-import { AnyServiceFactory } from '@backstage/backend-plugin-api';
+import { ServiceFactory } from '@backstage/backend-plugin-api';
 
 export const defaultServiceFactories = [
   cacheFactory,
@@ -47,15 +47,15 @@ export const defaultServiceFactories = [
  * @public
  */
 export interface CreateBackendOptions {
-  services?: AnyServiceFactory[];
+  services?: ServiceFactory[];
 }
 
 /**
  * @public
  */
 export function createBackend(options?: CreateBackendOptions): Backend {
-  const services = new Map<string, AnyServiceFactory>(
-    defaultServiceFactories.map(sf => [sf.service.id, sf]),
+  const services = new Map<string, ServiceFactory>(
+    defaultServiceFactories.map(sf => [sf.service.id, sf as ServiceFactory]),
   );
 
   if (options?.services) {

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

@@ -16,15 +16,6 @@ import { TokenManager } from '@backstage/backend-common';
 import { TransportStreamOptions } from 'winston-transport';
 import { UrlReader } from '@backstage/backend-common';
 
-// @public (undocumented)
-export type AnyServiceFactory = ServiceFactory<
-  unknown,
-  unknown,
-  {
-    [key in string]: unknown;
-  }
->;
-
 // @public (undocumented)
 export interface BackendFeature {
   // (undocumented)
@@ -101,15 +92,22 @@ export function createExtensionPoint<T>(options: {
 
 // @public (undocumented)
 export function createServiceFactory<
-  Api,
-  Impl extends Api,
-  Deps extends {
+  TService,
+  TImpl extends TService,
+  TDeps extends {
     [name in string]: unknown;
   },
->(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}>;
+>(factory: {
+  service: ServiceRef<TService>;
+  deps: TypesToServiceRef<TDeps>;
+  factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+}): ServiceFactory<TService>;
 
 // @public (undocumented)
-export function createServiceRef<T>(options: { id: string }): ServiceRef<T>;
+export function createServiceRef<T>(options: {
+  id: string;
+  defaultFactory?: (service: ServiceRef<T>) => Promise<ServiceFactory<T>>;
+}): ServiceRef<T>;
 
 // @public (undocumented)
 export const databaseServiceRef: ServiceRef<PluginDatabaseManager>;
@@ -168,22 +166,21 @@ export const permissionsServiceRef: ServiceRef<
 export const schedulerServiceRef: ServiceRef<PluginTaskScheduler>;
 
 // @public (undocumented)
-export type ServiceFactory<
-  TApi,
-  TImpl extends TApi,
-  TDeps extends {
-    [name in string]: unknown;
-  },
-> = {
-  service: ServiceRef<TApi>;
-  deps: TypesToServiceRef<TDeps>;
-  factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+export type ServiceFactory<TService = unknown> = {
+  service: ServiceRef<TService>;
+  deps: {
+    [key in string]: ServiceRef<unknown>;
+  };
+  factory(deps: {
+    [key in string]: unknown;
+  }): Promise<FactoryFunc<TService>>;
 };
 
 // @public
 export type ServiceRef<T> = {
   id: string;
   T: T;
+  defaultFactory?: (service: ServiceRef<T>) => Promise<ServiceFactory<T>>;
   toString(): string;
   $$ref: 'service';
 };

packages/backend-plugin-api/src/services/system/index.ts

@@ -20,6 +20,5 @@ export type {
   DepsToDepFactories,
   FactoryFunc,
   ServiceFactory,
-  AnyServiceFactory,
 } from './types';
 export { createServiceRef, createServiceFactory } from './types';

packages/backend-plugin-api/src/services/system/types.ts

@@ -28,6 +28,12 @@ export type ServiceRef<T> = {
    */
   T: T;
 
+  /**
+   * The default factory that will be used to create service
+   * instances if no other factory is provided.
+   */
+  defaultFactory?: (service: ServiceRef<T>) => Promise<ServiceFactory<T>>;
+
   toString(): string;
 
   $$ref: 'service';
@@ -45,32 +51,26 @@ export type DepsToDepFactories<T> = {
 export type FactoryFunc<Impl> = (pluginId: string) => Promise<Impl>;
 
 /** @public */
-export type ServiceFactory<
-  TApi,
-  TImpl extends TApi,
-  TDeps extends { [name in string]: unknown },
-> = {
-  service: ServiceRef<TApi>;
-  deps: TypesToServiceRef<TDeps>;
-  factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+export type ServiceFactory<TService = unknown> = {
+  service: ServiceRef<TService>;
+  deps: { [key in string]: ServiceRef<unknown> };
+  factory(deps: { [key in string]: unknown }): Promise<FactoryFunc<TService>>;
 };
 
-/** @public */
-export type AnyServiceFactory = ServiceFactory<
-  unknown,
-  unknown,
-  { [key in string]: unknown }
->;
-
 /**
  * @public
  */
-export function createServiceRef<T>(options: { id: string }): ServiceRef<T> {
+export function createServiceRef<T>(options: {
+  id: string;
+  defaultFactory?: (service: ServiceRef<T>) => Promise<ServiceFactory<T>>;
+}): ServiceRef<T> {
+  const { id, defaultFactory } = options;
   return {
-    id: options.id,
+    id,
     get T(): T {
       throw new Error(`tried to read ServiceRef.T of ${this}`);
     },
+    defaultFactory,
     toString() {
       return `serviceRef{${options.id}}`;
     },
@@ -82,9 +82,13 @@ export function createServiceRef<T>(options: { id: string }): ServiceRef<T> {
  * @public
  */
 export function createServiceFactory<
-  Api,
-  Impl extends Api,
-  Deps extends { [name in string]: unknown },
->(factory: ServiceFactory<Api, Impl, Deps>): ServiceFactory<Api, Api, {}> {
-  return factory;
+  TService,
+  TImpl extends TService,
+  TDeps extends { [name in string]: unknown },
+>(factory: {
+  service: ServiceRef<TService>;
+  deps: TypesToServiceRef<TDeps>;
+  factory(deps: DepsToDepFactories<TDeps>): Promise<FactoryFunc<TImpl>>;
+}): ServiceFactory<TService> {
+  return factory as ServiceFactory<TService>;
 }

packages/backend-test-utils/api-report.md

@@ -3,10 +3,10 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
-import { AnyServiceFactory } from '@backstage/backend-plugin-api';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { ExtensionPoint } from '@backstage/backend-plugin-api';
 import { Knex } from 'knex';
+import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 
 // @public (undocumented)
@@ -45,7 +45,7 @@ export interface TestBackendOptions<
   services?: readonly [
     ...{
       [index in keyof TServices]:
-        | AnyServiceFactory
+        | ServiceFactory<TServices[index]>
         | [ServiceRef<TServices[index]>, Partial<TServices[index]>];
     },
   ];

packages/backend-test-utils/src/next/wiring/TestBackend.ts

@@ -16,7 +16,7 @@
 
 import { createSpecializedBackend } from '@backstage/backend-app-api';
 import {
-  AnyServiceFactory,
+  ServiceFactory,
   ServiceRef,
   createServiceFactory,
   BackendFeature,
@@ -31,7 +31,7 @@ export interface TestBackendOptions<
   services?: readonly [
     ...{
       [index in keyof TServices]:
-        | AnyServiceFactory
+        | ServiceFactory<TServices[index]>
         | [ServiceRef<TServices[index]>, Partial<TServices[index]>];
     },
   ];
@@ -68,7 +68,7 @@ export async function startTestBackend<
         factory: async () => async () => serviceDef[1],
       });
     }
-    return serviceDef as AnyServiceFactory;
+    return serviceDef as ServiceFactory;
   });
 
   const backend = createSpecializedBackend({

plugins/catalog-backend-module-github/api-report.md

@@ -3,6 +3,7 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
 import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 import { Config } from '@backstage/config';
@@ -14,6 +15,7 @@ import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { TaskRunner } from '@backstage/backend-tasks';
+import { TaskScheduleDefinition } from '@backstage/backend-tasks';
 
 // @public
 export class GithubDiscoveryProcessor implements CatalogProcessor {
@@ -58,6 +60,16 @@ export class GitHubEntityProvider implements EntityProvider {
   refresh(logger: Logger): Promise<void>;
 }
 
+// @alpha
+export const githubEntityProviderCatalogModule: (
+  options?: GithubEntityProviderCatalogModuleOptions | undefined,
+) => BackendFeature;
+
+// @alpha
+export type GithubEntityProviderCatalogModuleOptions = {
+  schedule?: TaskScheduleDefinition;
+};
+
 // @public
 export type GithubMultiOrgConfig = Array<{
   name: string;

plugins/catalog-backend-module-github/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-module"
@@ -24,7 +25,7 @@
     "backstage"
   ],
   "scripts": {
-    "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",
@@ -35,11 +36,13 @@
   "dependencies": {
     "@backstage/backend-common": "^0.15.0",
     "@backstage/backend-tasks": "^0.3.4",
+    "@backstage/backend-plugin-api": "^0.1.1",
     "@backstage/catalog-model": "^1.1.0",
     "@backstage/config": "^1.0.1",
     "@backstage/errors": "^1.1.0",
     "@backstage/integration": "^1.3.0",
     "@backstage/plugin-catalog-backend": "^1.3.1",
+    "@backstage/plugin-catalog-node": "^1.0.1",
     "@backstage/types": "^1.0.0",
     "@octokit/graphql": "^5.0.0",
     "lodash": "^4.17.21",
@@ -55,6 +58,7 @@
   },
   "files": [
     "dist",
+    "alpha",
     "config.d.ts"
   ],
   "configSchema": "config.d.ts"

plugins/catalog-backend-module-github/src/index.ts

@@ -27,3 +27,5 @@ export { GitHubEntityProvider } from './providers/GitHubEntityProvider';
 export { GitHubOrgEntityProvider } from './providers/GitHubOrgEntityProvider';
 export type { GitHubOrgEntityProviderOptions } from './providers/GitHubOrgEntityProvider';
 export type { GithubMultiOrgConfig } from './lib';
+export { githubEntityProviderCatalogModule } from './module';
+export type { GithubEntityProviderCatalogModuleOptions } from './module';

plugins/catalog-backend-module-github/src/module.ts

@@ -0,0 +1,69 @@
+/*
+ * 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,
+  loggerToWinstonLogger,
+  configServiceRef,
+  loggerServiceRef,
+  schedulerServiceRef,
+} from '@backstage/backend-plugin-api';
+import { TaskScheduleDefinition } from '@backstage/backend-tasks';
+import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node';
+import { GitHubEntityProvider } from './providers/GitHubEntityProvider';
+
+/**
+ * Options for {@link githubEntityProviderCatalogModule}.
+ *
+ * @alpha
+ */
+export type GithubEntityProviderCatalogModuleOptions = {
+  schedule?: TaskScheduleDefinition;
+};
+
+/**
+ * Registers the GitHubEntityProvider with the catalog processing extension point.
+ *
+ * @alpha
+ */
+export const githubEntityProviderCatalogModule = createBackendModule({
+  pluginId: 'catalog',
+  moduleId: 'github-entity-provider',
+  register(env, options?: GithubEntityProviderCatalogModuleOptions) {
+    env.registerInit({
+      deps: {
+        config: configServiceRef,
+        catalog: catalogProcessingExtensionPoint,
+        logger: loggerServiceRef,
+        scheduler: schedulerServiceRef,
+      },
+      async init({ config, catalog, logger, scheduler }) {
+        const scheduleDef = options?.schedule ?? {
+          frequency: { seconds: 600 },
+          timeout: { seconds: 900 },
+          initialDelay: { seconds: 3 },
+        };
+
+        catalog.addEntityProvider(
+          GitHubEntityProvider.fromConfig(config, {
+            logger: loggerToWinstonLogger(logger),
+            schedule: scheduler.createScheduledTaskRunner(scheduleDef),
+          }),
+        );
+      },
+    });
+  },
+});

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

@@ -35,12 +35,16 @@ class CatalogExtensionPointImpl implements CatalogProcessingExtensionPoint {
   #processors = new Array<CatalogProcessor>();
   #entityProviders = new Array<EntityProvider>();
 
-  addProcessor(processor: CatalogProcessor): void {
-    this.#processors.push(processor);
+  addProcessor(
+    ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
+  ): void {
+    this.#processors.push(...processors.flat());
   }
 
-  addEntityProvider(provider: EntityProvider): void {
-    this.#entityProviders.push(provider);
+  addEntityProvider(
+    ...providers: Array<EntityProvider | Array<EntityProvider>>
+  ): void {
+    this.#entityProviders.push(...providers.flat());
   }
 
   get processors() {

plugins/catalog-node/api-report.md

@@ -13,9 +13,13 @@ import { JsonValue } from '@backstage/types';
 // @alpha (undocumented)
 export interface CatalogProcessingExtensionPoint {
   // (undocumented)
-  addEntityProvider(provider: EntityProvider): void;
+  addEntityProvider(
+    ...providers: Array<EntityProvider | Array<EntityProvider>>
+  ): void;
   // (undocumented)
-  addProcessor(processor: CatalogProcessor): void;
+  addProcessor(
+    ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
+  ): void;
 }
 
 // @alpha (undocumented)

plugins/catalog-node/src/extensions.ts

@@ -21,8 +21,12 @@ import { CatalogProcessor } from './api/processor';
  * @alpha
  */
 export interface CatalogProcessingExtensionPoint {
-  addProcessor(processor: CatalogProcessor): void;
-  addEntityProvider(provider: EntityProvider): void;
+  addProcessor(
+    ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>
+  ): void;
+  addEntityProvider(
+    ...providers: Array<EntityProvider | Array<EntityProvider>>
+  ): void;
 }
 
 /**