Merge pull request #20576 from kuangp/feat/buildStrategyExtension

feat(techdocs): add extension for setting build strategy

plugins/techdocs-backend/api-report.md

@@ -7,6 +7,7 @@ import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogClient } from '@backstage/catalog-client';
 import { Config } from '@backstage/config';
 import { DefaultTechDocsCollatorFactory as DefaultTechDocsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-techdocs';
+import { DocsBuildStrategy as DocsBuildStrategy_2 } from '@backstage/plugin-techdocs-node';
 import { Entity } from '@backstage/catalog-model';
 import express from 'express';
 import { GeneratorBuilder } from '@backstage/plugin-techdocs-node';
@@ -18,7 +19,7 @@ import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { PreparerBuilder } from '@backstage/plugin-techdocs-node';
 import { PublisherBase } from '@backstage/plugin-techdocs-node';
 import type { TechDocsCollatorFactoryOptions as TechDocsCollatorFactoryOptions_2 } from '@backstage/plugin-search-backend-module-techdocs';
-import { TechDocsDocument } from '@backstage/plugin-techdocs-node';
+import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdocs-node';
 import { TokenManager } from '@backstage/backend-common';
 import * as winston from 'winston';
 
@@ -33,7 +34,7 @@ export class DefaultTechDocsCollator {
     args: Record<string, string>,
   ): string;
   // (undocumented)
-  execute(): Promise<TechDocsDocument[]>;
+  execute(): Promise<TechDocsDocument_2[]>;
   // (undocumented)
   static fromConfig(
     config: Config,
@@ -48,11 +49,8 @@ export class DefaultTechDocsCollator {
 // @public @deprecated (undocumented)
 export const DefaultTechDocsCollatorFactory: typeof DefaultTechDocsCollatorFactory_2;
 
-// @public
-export interface DocsBuildStrategy {
-  // (undocumented)
-  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
-}
+// @public @deprecated (undocumented)
+export type DocsBuildStrategy = DocsBuildStrategy_2;
 
 // @public
 export type OutOfTheBoxDeploymentOptions = {
@@ -64,7 +62,7 @@ export type OutOfTheBoxDeploymentOptions = {
   database?: Knex;
   config: Config;
   cache: PluginCacheManager;
-  docsBuildStrategy?: DocsBuildStrategy;
+  docsBuildStrategy?: DocsBuildStrategy_2;
   buildLogTransport?: winston.transport;
   catalogClient?: CatalogClient;
 };
@@ -76,7 +74,7 @@ export type RecommendedDeploymentOptions = {
   discovery: PluginEndpointDiscovery;
   config: Config;
   cache: PluginCacheManager;
-  docsBuildStrategy?: DocsBuildStrategy;
+  docsBuildStrategy?: DocsBuildStrategy_2;
   buildLogTransport?: winston.transport;
   catalogClient?: CatalogClient;
 };
@@ -86,7 +84,7 @@ export type RouterOptions =
   | RecommendedDeploymentOptions
   | OutOfTheBoxDeploymentOptions;
 
-// @public
+// @public @deprecated (undocumented)
 export type ShouldBuildParameters = {
   entity: Entity;
 };
@@ -105,7 +103,8 @@ export type TechDocsCollatorOptions = {
   legacyPathCasing?: boolean;
 };
 
-export { TechDocsDocument };
+// @public @deprecated (undocumented)
+export type TechDocsDocument = TechDocsDocument_2;
 
 export * from '@backstage/plugin-techdocs-node';
 ```

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';