Merge pull request #20576 from kuangp/feat/buildStrategyExtension

feat(techdocs): add extension for setting build strategy

.changeset/two-jars-melt.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-techdocs-backend': minor
+'@backstage/plugin-techdocs-node': minor
+---
+
+Expose an extension point to set a custom build strategy. Also move `DocsBuildStrategy` type to `@backstage/plugin-techdocs-node` and deprecate `ShouldBuildParameters` type.

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

plugins/techdocs-node/api-report.md

@@ -10,6 +10,7 @@ import { Config } from '@backstage/config';
 import { ContainerRunner } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import express from 'express';
+import { ExtensionPoint } from '@backstage/backend-plugin-api';
 import { IndexableDocument } from '@backstage/plugin-search-common';
 import { Logger } from 'winston';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -24,6 +25,12 @@ export class DirectoryPreparer implements PreparerBase {
   shouldCleanPreparedDirectory(): boolean;
 }
 
+// @public
+export interface DocsBuildStrategy {
+  // (undocumented)
+  shouldBuild(params: { entity: Entity }): Promise<boolean>;
+}
+
 // @public
 export type ETag = string;
 
@@ -229,6 +236,15 @@ export type RemoteProtocol = 'url' | 'dir';
 // @public
 export type SupportedGeneratorKey = 'techdocs' | string;
 
+// @public
+export interface TechdocsBuildsExtensionPoint {
+  // (undocumented)
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+// @public
+export const techdocsBuildsExtensionPoint: ExtensionPoint<TechdocsBuildsExtensionPoint>;
+
 // @public
 export interface TechDocsDocument extends IndexableDocument {
   kind: string;

plugins/techdocs-node/package.json

@@ -46,6 +46,7 @@
     "@azure/identity": "^3.2.1",
     "@azure/storage-blob": "^12.5.0",
     "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/errors": "workspace:^",

plugins/techdocs-node/src/extensions.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2023 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 { createExtensionPoint } from '@backstage/backend-plugin-api';
+import { DocsBuildStrategy } from './techdocsTypes';
+
+/**
+ * Extension point type for configuring Techdocs builds.
+ *
+ * @public
+ */
+export interface TechdocsBuildsExtensionPoint {
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+/**
+ * Extension point for configuring Techdocs builds.
+ *
+ * @public
+ */
+export const techdocsBuildsExtensionPoint =
+  createExtensionPoint<TechdocsBuildsExtensionPoint>({
+    id: 'techdocs.builds',
+  });

plugins/techdocs-node/src/index.ts

@@ -23,3 +23,7 @@
 export * from './stages';
 export * from './helpers';
 export * from './techdocsTypes';
+export {
+  techdocsBuildsExtensionPoint,
+  type TechdocsBuildsExtensionPoint,
+} from './extensions';

plugins/techdocs-node/src/techdocsTypes.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { Entity } from '@backstage/catalog-model';
 import { IndexableDocument } from '@backstage/plugin-search-common';
 
 /**
@@ -46,3 +47,12 @@ export interface TechDocsDocument extends IndexableDocument {
    */
   path: string;
 }
+
+/**
+ * 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: { entity: Entity }): Promise<boolean>;
+}

yarn.lock

@@ -9820,6 +9820,7 @@ __metadata:
     "@azure/identity": ^3.2.1
     "@azure/storage-blob": ^12.5.0
     "@backstage/backend-common": "workspace:^"
+    "@backstage/backend-plugin-api": "workspace:^"
     "@backstage/backend-test-utils": "workspace:^"
     "@backstage/catalog-model": "workspace:^"
     "@backstage/cli": "workspace:^"