Merge pull request #20576 from kuangp/feat/buildStrategyExtension

feat(techdocs): add extension for setting build strategy

plugins/techdocs-backend/src/index.ts

@@ -20,13 +20,17 @@
  * @packageDocumentation
  */
 
+import { Entity } from '@backstage/catalog-model';
+import {
+  DocsBuildStrategy as _DocsBuildStrategy,
+  TechDocsDocument as _TechDocsDocument,
+} from '@backstage/plugin-techdocs-node';
+
 export { createRouter } from './service';
 export type {
   RouterOptions,
   RecommendedDeploymentOptions,
   OutOfTheBoxDeploymentOptions,
-  DocsBuildStrategy,
-  ShouldBuildParameters,
 } from './service';
 
 export {
@@ -39,8 +43,21 @@ export type {
 } from './search';
 
 /**
- * @deprecated Use directly from @backstage/plugin-techdocs-node
+ * @public
+ * @deprecated import from `@backstage/plugin-techdocs-node` instead
  */
-export type { TechDocsDocument } from '@backstage/plugin-techdocs-node';
+export type DocsBuildStrategy = _DocsBuildStrategy;
+/**
+ * @public
+ * @deprecated use direct type definition instead
+ */
+export type ShouldBuildParameters = {
+  entity: Entity;
+};
+/**
+ * @public
+ * @deprecated import from `@backstage/plugin-techdocs-node` instead
+ */
+export type TechDocsDocument = _TechDocsDocument;
 
 export * from '@backstage/plugin-techdocs-node';

plugins/techdocs-backend/src/plugin.ts

@@ -25,9 +25,11 @@ import {
 } from '@backstage/backend-plugin-api';
 
 import {
+  DocsBuildStrategy,
   Preparers,
   Generators,
   Publisher,
+  techdocsBuildsExtensionPoint,
 } from '@backstage/plugin-techdocs-node';
 import Docker from 'dockerode';
 import { createRouter } from '@backstage/plugin-techdocs-backend';
@@ -39,6 +41,16 @@ import { createRouter } from '@backstage/plugin-techdocs-backend';
 export const techdocsPlugin = createBackendPlugin({
   pluginId: 'techdocs',
   register(env) {
+    let docsBuildStrategy: DocsBuildStrategy | undefined;
+    env.registerExtensionPoint(techdocsBuildsExtensionPoint, {
+      setBuildStrategy(buildStrategy: DocsBuildStrategy) {
+        if (docsBuildStrategy) {
+          throw new Error('DocsBuildStrategy may only be set once');
+        }
+        docsBuildStrategy = buildStrategy;
+      },
+    });
+
     env.registerInit({
       deps: {
         config: coreServices.rootConfig,
@@ -82,6 +94,7 @@ export const techdocsPlugin = createBackendPlugin({
           await createRouter({
             logger: winstonLogger,
             cache: cacheManager,
+            docsBuildStrategy,
             preparers,
             generators,
             publisher,

plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { DefaultDocsBuildStrategy } from './DocsBuildStrategy';
+import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy';
 import { ConfigReader } from '@backstage/config';
 
 const MockedConfigReader = ConfigReader as jest.MockedClass<

plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts

@@ -15,26 +15,9 @@
  */
 import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
+import { DocsBuildStrategy } from '@backstage/plugin-techdocs-node';
 
-/**
- * Parameters passed to the shouldBuild method on the DocsBuildStrategy interface
- *
- * @public
- */
-export type ShouldBuildParameters = {
-  entity: Entity;
-};
-
-/**
- * A strategy for when to build TechDocs locally, and when to skip building TechDocs (allowing for an external build)
- *
- * @public
- */
-export interface DocsBuildStrategy {
-  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
-}
-
-export class DefaultDocsBuildStrategy {
+export class DefaultDocsBuildStrategy implements DocsBuildStrategy {
   private readonly config: Config;
 
   private constructor(config: Config) {
@@ -45,7 +28,7 @@ export class DefaultDocsBuildStrategy {
     return new DefaultDocsBuildStrategy(config);
   }
 
-  async shouldBuild(_: ShouldBuildParameters): Promise<boolean> {
+  async shouldBuild(_: { entity: Entity }): Promise<boolean> {
     return this.config.getString('techdocs.builder') === 'local';
   }
 }

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

@@ -20,7 +20,3 @@ export type {
   RecommendedDeploymentOptions,
   OutOfTheBoxDeploymentOptions,
 } from './router';
-export type {
-  DocsBuildStrategy,
-  ShouldBuildParameters,
-} from './DocsBuildStrategy';

plugins/techdocs-backend/src/service/router.test.ts

@@ -22,6 +22,7 @@ import {
 } from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import {
+  DocsBuildStrategy,
   GeneratorBuilder,
   PreparerBuilder,
   PublisherBase,
@@ -32,7 +33,6 @@ import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer';
 import { CachedEntityLoader } from './CachedEntityLoader';
 import { createEventStream, createRouter, RouterOptions } from './router';
 import { TechDocsCache } from '../cache';
-import { DocsBuildStrategy } from './DocsBuildStrategy';
 
 jest.mock('@backstage/catalog-client');
 jest.mock('@backstage/config');

plugins/techdocs-backend/src/service/router.ts

@@ -22,6 +22,7 @@ import { stringifyEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { NotFoundError } from '@backstage/errors';
 import {
+  DocsBuildStrategy,
   GeneratorBuilder,
   getLocationForEntity,
   PreparerBuilder,
@@ -34,10 +35,7 @@ import { ScmIntegrations } from '@backstage/integration';
 import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer';
 import { createCacheMiddleware, TechDocsCache } from '../cache';
 import { CachedEntityLoader } from './CachedEntityLoader';
-import {
-  DefaultDocsBuildStrategy,
-  DocsBuildStrategy,
-} from './DocsBuildStrategy';
+import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy';
 import * as winston from 'winston';
 import { PassThrough } from 'stream';