@backstage/plugin-techdocs-node 1.12.11-next.2 → 1.12.12-next.0

package/dist/index.d.ts

@@ -3,10 +3,10 @@ import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
 import { LoggerService, UrlReaderService, DiscoveryService } from '@backstage/backend-plugin-api';
-import { Writable } from 'stream';
 import express from 'express';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { IndexableDocument } from '@backstage/plugin-search-common';
+import { Writable } from 'stream';
 import * as winston from 'winston';
 import { Logger } from 'winston';
 
@@ -137,176 +137,12 @@ declare const getDocFilesFromRepository: (reader: UrlReaderService, entity: Enti
     logger?: LoggerService;
 }) => Promise<PreparerResponse>;
 
-/**
- * Options for building publishers
- * @public
- */
-type PublisherFactory = {
-    logger: LoggerService;
-    discovery: DiscoveryService;
-    customPublisher?: PublisherBase | undefined;
-};
-/**
- * Key for all the different types of TechDocs publishers that are supported.
- * @public
- */
-type PublisherType = 'local' | 'googleGcs' | 'awsS3' | 'azureBlobStorage' | 'openStackSwift';
-/**
- * Request publish definition
- * @public
- */
-type PublishRequest = {
-    entity: Entity;
-    directory: string;
-};
-/**
- * Response containing metadata about where files were published and what may
- * have been published or updated.
- * @public
- */
-type PublishResponse = {
-    /**
-     * The URL which serves files from the local publisher's static directory.
-     */
-    remoteUrl?: string;
-    /**
-     * The list of objects (specifically their paths) that were published.
-     * Objects do not have a preceding slash, and match how one would load the
-     * object over the `/static/docs/*` TechDocs Backend Plugin endpoint.
-     */
-    objects?: string[];
-} | void;
-/**
- * Result for the validation check.
- * @public
- */
-type ReadinessResponse = {
-    /** If true, the publisher is able to interact with the backing storage. */
-    isAvailable: boolean;
-};
-/**
- * Type to hold metadata found in techdocs_metadata.json and associated with each site
- * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
- * @public
- */
-type TechDocsMetadata = {
-    site_name: string;
-    site_description: string;
-    etag: string;
-    build_timestamp: number;
-    files?: string[];
-};
-/**
- * TechDocs entity triplet migration request
- * @public
- */
-type MigrateRequest = {
-    /**
-     * Whether or not to remove the source file. Defaults to false (acting like a
-     * copy instead of a move).
-     */
-    removeOriginal?: boolean;
-    /**
-     * Maximum number of files/objects to migrate at once. Defaults to 25.
-     */
-    concurrency?: number;
-};
-/**
- * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)
- * The publisher handles publishing of the generated static files after the prepare and generate steps of TechDocs.
- * It also provides APIs to communicate with the storage service.
- *
- * @public
- */
-interface PublisherBase {
-    /**
-     * Check if the publisher is ready. This check tries to perform certain checks to see if the
-     * publisher is configured correctly and can be used to publish or read documentations.
-     * The different implementations might e.g. use the provided service credentials to access the
-     * target or check if a folder/bucket is available.
-     */
-    getReadiness(): Promise<ReadinessResponse>;
-    /**
-     * Store the generated static files onto a storage service (either local filesystem or external service).
-     *
-     * @param request - Object containing the entity from the service
-     *                  catalog, and the directory that contains the generated static files from TechDocs.
-     */
-    publish(request: PublishRequest): Promise<PublishResponse>;
-    /**
-     * Retrieve TechDocs Metadata about a site e.g. name, contributors, last updated, etc.
-     * This API uses the techdocs_metadata.json file that co-exists along with the generated docs.
-     */
-    fetchTechDocsMetadata(entityName: CompoundEntityRef): Promise<TechDocsMetadata>;
-    /**
-     * Route middleware to serve static documentation files for an entity.
-     */
-    docsRouter(): express.Handler;
-    /**
-     * Check if the index.html is present for the Entity at the Storage location.
-     */
-    hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
-    /**
-     * Migrates documentation objects with case sensitive entity triplets to
-     * lowercase entity triplets. This was (will be) a change introduced in
-     * `techdocs-cli` version `{0.x.y}` and `techdocs-backend` version `{0.x.y}`.
-     *
-     * Implementation of this method is unnecessary in publishers introduced
-     * after version `{0.x.y}` of `techdocs-node`.
-     */
-    migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
-}
-/**
- * Definition for a TechDocs publisher builder
- * @public
- */
-type PublisherBuilder = {
-    register(type: PublisherType, publisher: PublisherBase): void;
-    get(config: Config): PublisherBase;
-};
-/**
- * Handles the running of containers, on behalf of others.
- *
- * @public
- */
-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>;
-}
-
 /**
  * Options for building generators
  * @public
  */
 type GeneratorOptions = {
     logger: LoggerService;
-    /**
-     * @deprecated containerRunner is now instantiated in
-     * the generator and this option will be removed in the future
-     */
     containerRunner?: TechDocsContainerRunner;
 };
 /**
@@ -357,6 +193,41 @@ type GeneratorBuilder = {
     register(protocol: SupportedGeneratorKey, generator: GeneratorBase): void;
     get(entity: Entity): GeneratorBase;
 };
+/**
+ * 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
+ */
+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>;
+}
 
 /**
  * Generates documentation files
@@ -515,6 +386,134 @@ declare class Preparers implements PreparerBuilder {
     get(entity: Entity): PreparerBase;
 }
 
+/**
+ * Options for building publishers
+ * @public
+ */
+type PublisherFactory = {
+    logger: LoggerService;
+    discovery: DiscoveryService;
+    customPublisher?: PublisherBase | undefined;
+};
+/**
+ * Key for all the different types of TechDocs publishers that are supported.
+ * @public
+ */
+type PublisherType = 'local' | 'googleGcs' | 'awsS3' | 'azureBlobStorage' | 'openStackSwift';
+/**
+ * Request publish definition
+ * @public
+ */
+type PublishRequest = {
+    entity: Entity;
+    directory: string;
+};
+/**
+ * Response containing metadata about where files were published and what may
+ * have been published or updated.
+ * @public
+ */
+type PublishResponse = {
+    /**
+     * The URL which serves files from the local publisher's static directory.
+     */
+    remoteUrl?: string;
+    /**
+     * The list of objects (specifically their paths) that were published.
+     * Objects do not have a preceding slash, and match how one would load the
+     * object over the `/static/docs/*` TechDocs Backend Plugin endpoint.
+     */
+    objects?: string[];
+} | void;
+/**
+ * Result for the validation check.
+ * @public
+ */
+type ReadinessResponse = {
+    /** If true, the publisher is able to interact with the backing storage. */
+    isAvailable: boolean;
+};
+/**
+ * Type to hold metadata found in techdocs_metadata.json and associated with each site
+ * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
+ * @public
+ */
+type TechDocsMetadata = {
+    site_name: string;
+    site_description: string;
+    etag: string;
+    build_timestamp: number;
+    files?: string[];
+};
+/**
+ * TechDocs entity triplet migration request
+ * @public
+ */
+type MigrateRequest = {
+    /**
+     * Whether or not to remove the source file. Defaults to false (acting like a
+     * copy instead of a move).
+     */
+    removeOriginal?: boolean;
+    /**
+     * Maximum number of files/objects to migrate at once. Defaults to 25.
+     */
+    concurrency?: number;
+};
+/**
+ * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)
+ * The publisher handles publishing of the generated static files after the prepare and generate steps of TechDocs.
+ * It also provides APIs to communicate with the storage service.
+ *
+ * @public
+ */
+interface PublisherBase {
+    /**
+     * Check if the publisher is ready. This check tries to perform certain checks to see if the
+     * publisher is configured correctly and can be used to publish or read documentations.
+     * The different implementations might e.g. use the provided service credentials to access the
+     * target or check if a folder/bucket is available.
+     */
+    getReadiness(): Promise<ReadinessResponse>;
+    /**
+     * Store the generated static files onto a storage service (either local filesystem or external service).
+     *
+     * @param request - Object containing the entity from the service
+     *                  catalog, and the directory that contains the generated static files from TechDocs.
+     */
+    publish(request: PublishRequest): Promise<PublishResponse>;
+    /**
+     * Retrieve TechDocs Metadata about a site e.g. name, contributors, last updated, etc.
+     * This API uses the techdocs_metadata.json file that co-exists along with the generated docs.
+     */
+    fetchTechDocsMetadata(entityName: CompoundEntityRef): Promise<TechDocsMetadata>;
+    /**
+     * Route middleware to serve static documentation files for an entity.
+     */
+    docsRouter(): express.Handler;
+    /**
+     * Check if the index.html is present for the Entity at the Storage location.
+     */
+    hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
+    /**
+     * Migrates documentation objects with case sensitive entity triplets to
+     * lowercase entity triplets. This was (will be) a change introduced in
+     * `techdocs-cli` version `{0.x.y}` and `techdocs-backend` version `{0.x.y}`.
+     *
+     * Implementation of this method is unnecessary in publishers introduced
+     * after version `{0.x.y}` of `techdocs-node`.
+     */
+    migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
+}
+/**
+ * Definition for a TechDocs publisher builder
+ * @public
+ */
+type PublisherBuilder = {
+    register(type: PublisherType, publisher: PublisherBase): void;
+    get(config: Config): PublisherBase;
+};
+
 /**
  * Factory class to create a TechDocs publisher based on defined publisher type in app config.
  * Uses `techdocs.publisher.type`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-node",
-  "version": "1.12.11-next.2",
+  "version": "1.12.12-next.0",
   "description": "Common node.js functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli",
   "backstage": {
     "role": "node-library",
@@ -53,11 +53,11 @@
     "@aws-sdk/types": "^3.347.0",
     "@azure/identity": "^4.0.0",
     "@azure/storage-blob": "^12.5.0",
-    "@backstage/backend-plugin-api": "^1.0.0-next.2",
-    "@backstage/catalog-model": "^1.6.0",
+    "@backstage/backend-plugin-api": "^1.0.1-next.0",
+    "@backstage/catalog-model": "^1.7.0",
     "@backstage/config": "^1.2.0",
     "@backstage/errors": "^1.2.4",
-    "@backstage/integration": "^1.15.0-next.0",
+    "@backstage/integration": "^1.15.0",
     "@backstage/integration-aws-node": "^0.1.12",
     "@backstage/plugin-search-common": "^1.2.14",
     "@backstage/plugin-techdocs-common": "^0.1.0",
@@ -78,8 +78,8 @@
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.0.0-next.2",
-    "@backstage/cli": "^0.27.1-next.2",
+    "@backstage/backend-test-utils": "^1.0.1-next.0",
+    "@backstage/cli": "^0.28.0-next.0",
     "@types/fs-extra": "^11.0.0",
     "@types/js-yaml": "^4.0.0",
     "@types/mime-types": "^2.1.0",