Move TechdocsContainerRunner interface from publish to generate where it is used

Signed-off-by: Jörg Siebahn <joerg.siebahn@sda-se.com>

.changeset/big-garlics-punch.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-node': patch
+---
+
+Move `TechdocsContainerRunner` from `publish` to `generate`.

plugins/techdocs-node/src/stages/generate/DockerContainerRunner.ts

@@ -20,6 +20,7 @@ import { ForwardedError } from '@backstage/errors';
 import { PassThrough } from 'stream';
 import { pipeline as pipelineStream } from 'stream';
 import { promisify } from 'util';
+import { TechDocsContainerRunner } from './types';
 import { Writable } from 'stream';
 
 const pipeline = promisify(pipelineStream);
@@ -31,7 +32,7 @@ export type UserOptions = {
 /**
  * @internal
  */
-export class DockerContainerRunner {
+export class DockerContainerRunner implements TechDocsContainerRunner {
   private readonly dockerClient: Docker;
 
   constructor() {

plugins/techdocs-node/src/stages/generate/generators.ts

@@ -24,7 +24,7 @@ import {
   SupportedGeneratorKey,
 } from './types';
 import { LoggerService } from '@backstage/backend-plugin-api';
-import { TechDocsContainerRunner } from '../publish/types';
+import { TechDocsContainerRunner } from './types';
 
 /**
  * Collection of docs generators

plugins/techdocs-node/src/stages/generate/index.ts

@@ -22,6 +22,7 @@ export type {
   GeneratorBuilder,
   GeneratorRunOptions,
   SupportedGeneratorKey,
+  TechDocsContainerRunner,
 } from './types';
 import { getMkdocsYml } from './helpers';
 /**

plugins/techdocs-node/src/stages/generate/techdocs.ts

@@ -43,7 +43,7 @@ import {
 import { ForwardedError } from '@backstage/errors';
 import { DockerContainerRunner } from './DockerContainerRunner';
 import { LoggerService } from '@backstage/backend-plugin-api';
-import { TechDocsContainerRunner } from '../publish/types';
+import { TechDocsContainerRunner } from './types';
 
 /**
  * Generates documentation files

plugins/techdocs-node/src/stages/generate/types.ts

@@ -19,9 +19,11 @@ import { Writable } from 'stream';
 import { Logger } from 'winston';
 import { ParsedLocationAnnotation } from '../../helpers';
 import { LoggerService } from '@backstage/backend-plugin-api';
-import { TechDocsContainerRunner } from '../publish/types';
 
-// Determines where the generator will be run
+/**
+ * Determines where the generator will be run. `'docker'` is a shorthand for running the generator in a container.
+ * If no {@link GeneratorOptions.containerRunner} is specified, the internal `DockerContainerRunner` will be used.
+ */
 export type GeneratorRunInType = 'docker' | 'local';
 
 /**
@@ -30,10 +32,6 @@ export type GeneratorRunInType = 'docker' | 'local';
  */
 export type GeneratorOptions = {
   logger: LoggerService;
-  /**
-   * @deprecated containerRunner is now instantiated in
-   * the generator and this option will be removed in the future
-   */
   containerRunner?: TechDocsContainerRunner;
 };
 
@@ -104,3 +102,39 @@ export type DefaultMkdocsContent = {
   docs_dir: string;
   plugins: String[];
 };
+
+/**
+ * Handles the running of containers to generate TechDocs.
+ *
+ * Custom implementations, e.g. for Kubernetes or other execution environments, can be inspired by the internal default
+ * implementation `DockerContainerRunner`.
+ *
+ * @public
+ */
+export interface TechDocsContainerRunner {
+  /**
+   * Runs a container image to completion.
+   */
+  runContainer(opts: {
+    imageName: string;
+    command?: string | string[];
+    args: string[];
+    logStream?: Writable;
+    mountDirs?: Record<string, string>;
+    workingDir?: string;
+    envVars?: Record<string, string>;
+    pullImage?: boolean;
+    defaultUser?: boolean;
+    pullOptions?: {
+      authconfig?: {
+        username?: string;
+        password?: string;
+        auth?: string;
+        email?: string;
+        serveraddress?: string;
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    };
+  }): Promise<void>;
+}

plugins/techdocs-node/src/stages/publish/index.ts

@@ -24,5 +24,4 @@ export type {
   MigrateRequest,
   ReadinessResponse,
   TechDocsMetadata,
-  TechDocsContainerRunner,
 } from './types';

plugins/techdocs-node/src/stages/publish/types.ts

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Writable } from 'stream';
 import express from 'express';
 import { Config } from '@backstage/config';
 import { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';
@@ -168,36 +167,3 @@ export type PublisherBuilder = {
   register(type: PublisherType, publisher: PublisherBase): void;
   get(config: Config): PublisherBase;
 };
-
-/**
- * Handles the running of containers, on behalf of others.
- *
- * @public
- */
-export interface TechDocsContainerRunner {
-  /**
-   * Runs a container image to completion.
-   */
-  runContainer(opts: {
-    imageName: string;
-    command?: string | string[];
-    args: string[];
-    logStream?: Writable;
-    mountDirs?: Record<string, string>;
-    workingDir?: string;
-    envVars?: Record<string, string>;
-    pullImage?: boolean;
-    defaultUser?: boolean;
-    pullOptions?: {
-      authconfig?: {
-        username?: string;
-        password?: string;
-        auth?: string;
-        email?: string;
-        serveraddress?: string;
-        [key: string]: unknown;
-      };
-      [key: string]: unknown;
-    };
-  }): Promise<void>;
-}