@backstage/plugin-techdocs-backend 1.10.14-next.1 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @backstage/plugin-techdocs-backend
 
+## 1.11.0
+
+### Minor Changes
+
+- 3109c24: The export for the new backend system at the `/alpha` export is now also available via the main entry point, which means that you can remove the `/alpha` suffix from the import.
+
+### Patch Changes
+
+- 094eaa3: Remove references to in-repo backend-common
+- fbdc631: Allow to pass StorageOptions to GCS Publisher
+- Updated dependencies
+  - @backstage/plugin-search-backend-module-techdocs@0.3.0
+  - @backstage/plugin-catalog-node@1.13.1
+  - @backstage/plugin-techdocs-node@1.12.12
+  - @backstage/integration@1.15.1
+  - @backstage/catalog-client@1.7.1
+  - @backstage/backend-plugin-api@1.0.1
+  - @backstage/catalog-model@1.7.0
+  - @backstage/config@1.2.0
+  - @backstage/errors@1.2.4
+  - @backstage/plugin-catalog-common@1.1.0
+  - @backstage/plugin-permission-common@0.8.1
+  - @backstage/plugin-techdocs-common@0.1.0
+
+## 1.10.14-next.2
+
+### Patch Changes
+
+- fbdc631: Allow to pass StorageOptions to GCS Publisher
+- Updated dependencies
+  - @backstage/plugin-catalog-node@1.13.1-next.1
+  - @backstage/plugin-techdocs-node@1.12.12-next.2
+  - @backstage/integration@1.15.1-next.1
+  - @backstage/catalog-client@1.7.1-next.0
+  - @backstage/backend-plugin-api@1.0.1-next.1
+  - @backstage/catalog-model@1.7.0
+  - @backstage/config@1.2.0
+  - @backstage/errors@1.2.4
+  - @backstage/plugin-catalog-common@1.1.0
+  - @backstage/plugin-permission-common@0.8.1
+  - @backstage/plugin-search-backend-module-techdocs@0.2.3-next.2
+  - @backstage/plugin-techdocs-common@0.1.0
+
 ## 1.10.14-next.1
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-techdocs-backend__alpha",
-  "version": "1.10.14-next.1",
+  "version": "1.11.0",
   "main": "../dist/alpha.cjs.js",
   "types": "../dist/alpha.d.ts"
 }

package/dist/DocsBuilder/BuildMetadataStorage.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const lastUpdatedRecord = {};
+class BuildMetadataStorage {
+  entityUid;
+  lastUpdatedRecord;
+  constructor(entityUid) {
+    this.entityUid = entityUid;
+    this.lastUpdatedRecord = lastUpdatedRecord;
+  }
+  setLastUpdated() {
+    this.lastUpdatedRecord[this.entityUid] = Date.now();
+  }
+  getLastUpdated() {
+    return this.lastUpdatedRecord[this.entityUid];
+  }
+}
+const shouldCheckForUpdate = (entityUid) => {
+  const lastUpdated = new BuildMetadataStorage(entityUid).getLastUpdated();
+  if (lastUpdated) {
+    if (Date.now() - lastUpdated < 60 * 1e3) {
+      return false;
+    }
+  }
+  return true;
+};
+
+exports.BuildMetadataStorage = BuildMetadataStorage;
+exports.shouldCheckForUpdate = shouldCheckForUpdate;
+//# sourceMappingURL=BuildMetadataStorage.cjs.js.map

package/dist/DocsBuilder/BuildMetadataStorage.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildMetadataStorage.cjs.js","sources":["../../src/DocsBuilder/BuildMetadataStorage.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// Entity uid: unix timestamp\nconst lastUpdatedRecord = {} as Record<string, number>;\n\n/**\n * Store timestamps of the most recent TechDocs update of each Entity. This is\n * used to avoid checking for an update on each and every request to TechDocs.\n */\nexport class BuildMetadataStorage {\n  private entityUid: string;\n  private lastUpdatedRecord: Record<string, number>;\n\n  constructor(entityUid: string) {\n    this.entityUid = entityUid;\n    this.lastUpdatedRecord = lastUpdatedRecord;\n  }\n\n  setLastUpdated(): void {\n    this.lastUpdatedRecord[this.entityUid] = Date.now();\n  }\n\n  getLastUpdated(): number | undefined {\n    return this.lastUpdatedRecord[this.entityUid];\n  }\n}\n\n/**\n * Return false if a check for update has happened in last 60 seconds.\n */\nexport const shouldCheckForUpdate = (entityUid: string) => {\n  const lastUpdated = new BuildMetadataStorage(entityUid).getLastUpdated();\n  if (lastUpdated) {\n    // The difference is in milliseconds\n    if (Date.now() - lastUpdated < 60 * 1000) {\n      return false;\n    }\n  }\n  return true;\n};\n"],"names":[],"mappings":";;AAiBA,MAAM,oBAAoB,EAAC,CAAA;AAMpB,MAAM,oBAAqB,CAAA;AAAA,EACxB,SAAA,CAAA;AAAA,EACA,iBAAA,CAAA;AAAA,EAER,YAAY,SAAmB,EAAA;AAC7B,IAAA,IAAA,CAAK,SAAY,GAAA,SAAA,CAAA;AACjB,IAAA,IAAA,CAAK,iBAAoB,GAAA,iBAAA,CAAA;AAAA,GAC3B;AAAA,EAEA,cAAuB,GAAA;AACrB,IAAA,IAAA,CAAK,iBAAkB,CAAA,IAAA,CAAK,SAAS,CAAA,GAAI,KAAK,GAAI,EAAA,CAAA;AAAA,GACpD;AAAA,EAEA,cAAqC,GAAA;AACnC,IAAO,OAAA,IAAA,CAAK,iBAAkB,CAAA,IAAA,CAAK,SAAS,CAAA,CAAA;AAAA,GAC9C;AACF,CAAA;AAKa,MAAA,oBAAA,GAAuB,CAAC,SAAsB,KAAA;AACzD,EAAA,MAAM,WAAc,GAAA,IAAI,oBAAqB,CAAA,SAAS,EAAE,cAAe,EAAA,CAAA;AACvE,EAAA,IAAI,WAAa,EAAA;AAEf,IAAA,IAAI,IAAK,CAAA,GAAA,EAAQ,GAAA,WAAA,GAAc,KAAK,GAAM,EAAA;AACxC,MAAO,OAAA,KAAA,CAAA;AAAA,KACT;AAAA,GACF;AACA,EAAO,OAAA,IAAA,CAAA;AACT;;;;;"}

package/dist/DocsBuilder/builder.cjs.js

@@ -0,0 +1,172 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var errors = require('@backstage/errors');
+var pluginTechdocsNode = require('@backstage/plugin-techdocs-node');
+var fs = require('fs-extra');
+var os = require('os');
+var path = require('path');
+var BuildMetadataStorage = require('./BuildMetadataStorage.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefaultCompat(fs);
+var os__default = /*#__PURE__*/_interopDefaultCompat(os);
+var path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+class DocsBuilder {
+  preparer;
+  generator;
+  publisher;
+  entity;
+  logger;
+  config;
+  scmIntegrations;
+  logStream;
+  cache;
+  constructor({
+    preparers,
+    generators,
+    publisher,
+    entity,
+    logger,
+    config,
+    scmIntegrations,
+    logStream,
+    cache
+  }) {
+    this.preparer = preparers.get(entity);
+    this.generator = generators.get(entity);
+    this.publisher = publisher;
+    this.entity = entity;
+    this.logger = logger;
+    this.config = config;
+    this.scmIntegrations = scmIntegrations;
+    this.logStream = logStream;
+    this.cache = cache;
+  }
+  /**
+   * Build the docs and return whether they have been newly generated or have been cached
+   * @returns true, if the docs have been built. false, if the cached docs are still up-to-date.
+   */
+  async build() {
+    if (!this.entity.metadata.uid) {
+      throw new Error(
+        "Trying to build documentation for entity not in software catalog"
+      );
+    }
+    this.logger.info(
+      `Step 1 of 3: Preparing docs for entity ${catalogModel.stringifyEntityRef(
+        this.entity
+      )}`
+    );
+    let storedEtag;
+    if (await this.publisher.hasDocsBeenGenerated(this.entity)) {
+      try {
+        storedEtag = (await this.publisher.fetchTechDocsMetadata({
+          namespace: this.entity.metadata.namespace ?? catalogModel.DEFAULT_NAMESPACE,
+          kind: this.entity.kind,
+          name: this.entity.metadata.name
+        })).etag;
+      } catch (err) {
+        this.logger.warn(
+          `Unable to read techdocs_metadata.json, proceeding with fresh build, error ${err}.`
+        );
+      }
+    }
+    let preparedDir;
+    let newEtag;
+    try {
+      const preparerResponse = await this.preparer.prepare(this.entity, {
+        etag: storedEtag,
+        logger: this.logger
+      });
+      preparedDir = preparerResponse.preparedDir;
+      newEtag = preparerResponse.etag;
+    } catch (err) {
+      if (errors.isError(err) && err.name === "NotModifiedError") {
+        new BuildMetadataStorage.BuildMetadataStorage(this.entity.metadata.uid).setLastUpdated();
+        this.logger.debug(
+          `Docs for ${catalogModel.stringifyEntityRef(
+            this.entity
+          )} are unmodified. Using cache, skipping generate and prepare`
+        );
+        return false;
+      }
+      throw err;
+    }
+    this.logger.info(
+      `Prepare step completed for entity ${catalogModel.stringifyEntityRef(
+        this.entity
+      )}, stored at ${preparedDir}`
+    );
+    this.logger.info(
+      `Step 2 of 3: Generating docs for entity ${catalogModel.stringifyEntityRef(
+        this.entity
+      )}`
+    );
+    const workingDir = this.config.getOptionalString(
+      "backend.workingDirectory"
+    );
+    const tmpdirPath = workingDir || os__default.default.tmpdir();
+    const tmpdirResolvedPath = fs__default.default.realpathSync(tmpdirPath);
+    const outputDir = await fs__default.default.mkdtemp(
+      path__default.default.join(tmpdirResolvedPath, "techdocs-tmp-")
+    );
+    const parsedLocationAnnotation = pluginTechdocsNode.getLocationForEntity(
+      this.entity,
+      this.scmIntegrations
+    );
+    await this.generator.run({
+      inputDir: preparedDir,
+      outputDir,
+      parsedLocationAnnotation,
+      etag: newEtag,
+      logger: this.logger,
+      logStream: this.logStream,
+      siteOptions: {
+        name: this.entity.metadata.title ?? this.entity.metadata.name
+      }
+    });
+    if (this.preparer.shouldCleanPreparedDirectory()) {
+      this.logger.debug(
+        `Removing prepared directory ${preparedDir} since the site has been generated`
+      );
+      try {
+        fs__default.default.remove(preparedDir);
+      } catch (error) {
+        errors.assertError(error);
+        this.logger.debug(`Error removing prepared directory ${error.message}`);
+      }
+    }
+    this.logger.info(
+      `Step 3 of 3: Publishing docs for entity ${catalogModel.stringifyEntityRef(
+        this.entity
+      )}`
+    );
+    const published = await this.publisher.publish({
+      entity: this.entity,
+      directory: outputDir
+    });
+    if (this.cache && published && published?.objects?.length) {
+      this.logger.debug(
+        `Invalidating ${published.objects.length} cache objects`
+      );
+      await this.cache.invalidateMultiple(published.objects);
+    }
+    try {
+      fs__default.default.remove(outputDir);
+      this.logger.debug(
+        `Removing generated directory ${outputDir} since the site has been published`
+      );
+    } catch (error) {
+      errors.assertError(error);
+      this.logger.debug(`Error removing generated directory ${error.message}`);
+    }
+    new BuildMetadataStorage.BuildMetadataStorage(this.entity.metadata.uid).setLastUpdated();
+    return true;
+  }
+}
+
+exports.DocsBuilder = DocsBuilder;
+//# sourceMappingURL=builder.cjs.js.map

package/dist/DocsBuilder/builder.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.cjs.js","sources":["../../src/DocsBuilder/builder.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  DEFAULT_NAMESPACE,\n  Entity,\n  stringifyEntityRef,\n} from '@backstage/catalog-model';\nimport { Config } from '@backstage/config';\nimport { assertError, isError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport {\n  GeneratorBase,\n  GeneratorBuilder,\n  getLocationForEntity,\n  PreparerBase,\n  PreparerBuilder,\n  PublisherBase,\n} from '@backstage/plugin-techdocs-node';\nimport fs from 'fs-extra';\nimport os from 'os';\nimport path from 'path';\nimport { Writable } from 'stream';\nimport { Logger } from 'winston';\nimport { BuildMetadataStorage } from './BuildMetadataStorage';\nimport { TechDocsCache } from '../cache';\n\ntype DocsBuilderArguments = {\n  preparers: PreparerBuilder;\n  generators: GeneratorBuilder;\n  publisher: PublisherBase;\n  entity: Entity;\n  logger: Logger;\n  config: Config;\n  scmIntegrations: ScmIntegrationRegistry;\n  logStream?: Writable;\n  cache?: TechDocsCache;\n};\n\nexport class DocsBuilder {\n  private preparer: PreparerBase;\n  private generator: GeneratorBase;\n  private publisher: PublisherBase;\n  private entity: Entity;\n  private logger: Logger;\n  private config: Config;\n  private scmIntegrations: ScmIntegrationRegistry;\n  private logStream: Writable | undefined;\n  private cache?: TechDocsCache;\n\n  constructor({\n    preparers,\n    generators,\n    publisher,\n    entity,\n    logger,\n    config,\n    scmIntegrations,\n    logStream,\n    cache,\n  }: DocsBuilderArguments) {\n    this.preparer = preparers.get(entity);\n    this.generator = generators.get(entity);\n    this.publisher = publisher;\n    this.entity = entity;\n    this.logger = logger;\n    this.config = config;\n    this.scmIntegrations = scmIntegrations;\n    this.logStream = logStream;\n    this.cache = cache;\n  }\n\n  /**\n   * Build the docs and return whether they have been newly generated or have been cached\n   * @returns true, if the docs have been built. false, if the cached docs are still up-to-date.\n   */\n  public async build(): Promise<boolean> {\n    if (!this.entity.metadata.uid) {\n      throw new Error(\n        'Trying to build documentation for entity not in software catalog',\n      );\n    }\n\n    /**\n     * Prepare (and cache check)\n     */\n\n    this.logger.info(\n      `Step 1 of 3: Preparing docs for entity ${stringifyEntityRef(\n        this.entity,\n      )}`,\n    );\n\n    // If available, use the etag stored in techdocs_metadata.json to\n    // check if docs are outdated and need to be regenerated.\n    let storedEtag: string | undefined;\n    if (await this.publisher.hasDocsBeenGenerated(this.entity)) {\n      try {\n        storedEtag = (\n          await this.publisher.fetchTechDocsMetadata({\n            namespace: this.entity.metadata.namespace ?? DEFAULT_NAMESPACE,\n            kind: this.entity.kind,\n            name: this.entity.metadata.name,\n          })\n        ).etag;\n      } catch (err) {\n        // Proceed with a fresh build\n        this.logger.warn(\n          `Unable to read techdocs_metadata.json, proceeding with fresh build, error ${err}.`,\n        );\n      }\n    }\n\n    let preparedDir: string;\n    let newEtag: string;\n    try {\n      const preparerResponse = await this.preparer.prepare(this.entity, {\n        etag: storedEtag,\n        logger: this.logger,\n      });\n\n      preparedDir = preparerResponse.preparedDir;\n      newEtag = preparerResponse.etag;\n    } catch (err) {\n      if (isError(err) && err.name === 'NotModifiedError') {\n        // No need to prepare anymore since cache is valid.\n        // Set last check happened to now\n        new BuildMetadataStorage(this.entity.metadata.uid).setLastUpdated();\n        this.logger.debug(\n          `Docs for ${stringifyEntityRef(\n            this.entity,\n          )} are unmodified. Using cache, skipping generate and prepare`,\n        );\n        return false;\n      }\n      throw err;\n    }\n\n    this.logger.info(\n      `Prepare step completed for entity ${stringifyEntityRef(\n        this.entity,\n      )}, stored at ${preparedDir}`,\n    );\n\n    /**\n     * Generate\n     */\n\n    this.logger.info(\n      `Step 2 of 3: Generating docs for entity ${stringifyEntityRef(\n        this.entity,\n      )}`,\n    );\n\n    const workingDir = this.config.getOptionalString(\n      'backend.workingDirectory',\n    );\n    const tmpdirPath = workingDir || os.tmpdir();\n    // Fixes a problem with macOS returning a path that is a symlink\n    const tmpdirResolvedPath = fs.realpathSync(tmpdirPath);\n    const outputDir = await fs.mkdtemp(\n      path.join(tmpdirResolvedPath, 'techdocs-tmp-'),\n    );\n\n    const parsedLocationAnnotation = getLocationForEntity(\n      this.entity,\n      this.scmIntegrations,\n    );\n    await this.generator.run({\n      inputDir: preparedDir,\n      outputDir,\n      parsedLocationAnnotation,\n      etag: newEtag,\n      logger: this.logger,\n      logStream: this.logStream,\n      siteOptions: {\n        name: this.entity.metadata.title ?? this.entity.metadata.name,\n      },\n    });\n\n    // Remove Prepared directory since it is no longer needed.\n    // Caveat: Can not remove prepared directory in case of git preparer since the\n    // local git repository is used to get etag on subsequent requests.\n    if (this.preparer.shouldCleanPreparedDirectory()) {\n      this.logger.debug(\n        `Removing prepared directory ${preparedDir} since the site has been generated`,\n      );\n      try {\n        // Not a blocker hence no need to await this.\n        fs.remove(preparedDir);\n      } catch (error) {\n        assertError(error);\n        this.logger.debug(`Error removing prepared directory ${error.message}`);\n      }\n    }\n\n    /**\n     * Publish\n     */\n\n    this.logger.info(\n      `Step 3 of 3: Publishing docs for entity ${stringifyEntityRef(\n        this.entity,\n      )}`,\n    );\n\n    const published = await this.publisher.publish({\n      entity: this.entity,\n      directory: outputDir,\n    });\n\n    // Invalidate the cache for any published objects.\n    if (this.cache && published && published?.objects?.length) {\n      this.logger.debug(\n        `Invalidating ${published.objects.length} cache objects`,\n      );\n      await this.cache.invalidateMultiple(published.objects);\n    }\n\n    try {\n      // Not a blocker hence no need to await this.\n      fs.remove(outputDir);\n      this.logger.debug(\n        `Removing generated directory ${outputDir} since the site has been published`,\n      );\n    } catch (error) {\n      assertError(error);\n      this.logger.debug(`Error removing generated directory ${error.message}`);\n    }\n\n    // Update the last check time for the entity\n    new BuildMetadataStorage(this.entity.metadata.uid).setLastUpdated();\n\n    return true;\n  }\n}\n"],"names":["stringifyEntityRef","DEFAULT_NAMESPACE","isError","BuildMetadataStorage","os","fs","path","getLocationForEntity","assertError"],"mappings":"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"}

package/dist/alpha.cjs.js

@@ -2,126 +2,9 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var backendCommon = require('@backstage/backend-common');
-var backendPluginApi = require('@backstage/backend-plugin-api');
-var pluginTechdocsNode = require('@backstage/plugin-techdocs-node');
-var pluginTechdocsBackend = require('@backstage/plugin-techdocs-backend');
-var alpha = require('@backstage/plugin-catalog-node/alpha');
+var plugin = require('./plugin.cjs.js');
 
-const techdocsPlugin = backendPluginApi.createBackendPlugin({
-  pluginId: "techdocs",
-  register(env) {
-    let docsBuildStrategy;
-    let buildLogTransport;
-    env.registerExtensionPoint(pluginTechdocsNode.techdocsBuildsExtensionPoint, {
-      setBuildStrategy(buildStrategy) {
-        if (docsBuildStrategy) {
-          throw new Error("DocsBuildStrategy may only be set once");
-        }
-        docsBuildStrategy = buildStrategy;
-      },
-      setBuildLogTransport(transport) {
-        if (buildLogTransport) {
-          throw new Error("BuildLogTransport may only be set once");
-        }
-        buildLogTransport = transport;
-      }
-    });
-    let customTechdocsGenerator;
-    env.registerExtensionPoint(pluginTechdocsNode.techdocsGeneratorExtensionPoint, {
-      setTechdocsGenerator(generator) {
-        if (customTechdocsGenerator) {
-          throw new Error("TechdocsGenerator may only be set once");
-        }
-        customTechdocsGenerator = generator;
-      }
-    });
-    const customPreparers = /* @__PURE__ */ new Map();
-    env.registerExtensionPoint(pluginTechdocsNode.techdocsPreparerExtensionPoint, {
-      registerPreparer(protocol, preparer) {
-        if (customPreparers.has(protocol)) {
-          throw new Error(
-            `Preparer for protocol ${protocol} is already registered`
-          );
-        }
-        customPreparers.set(protocol, preparer);
-      }
-    });
-    let customTechdocsPublisher;
-    env.registerExtensionPoint(pluginTechdocsNode.techdocsPublisherExtensionPoint, {
-      registerPublisher(type, publisher) {
-        if (customTechdocsPublisher) {
-          throw new Error(`Publisher for type ${type} is already registered`);
-        }
-        customTechdocsPublisher = publisher;
-      }
-    });
-    env.registerInit({
-      deps: {
-        config: backendPluginApi.coreServices.rootConfig,
-        logger: backendPluginApi.coreServices.logger,
-        urlReader: backendPluginApi.coreServices.urlReader,
-        http: backendPluginApi.coreServices.httpRouter,
-        discovery: backendPluginApi.coreServices.discovery,
-        cache: backendPluginApi.coreServices.cache,
-        httpAuth: backendPluginApi.coreServices.httpAuth,
-        auth: backendPluginApi.coreServices.auth,
-        catalog: alpha.catalogServiceRef
-      },
-      async init({
-        config,
-        logger,
-        urlReader,
-        http,
-        discovery,
-        cache,
-        httpAuth,
-        auth,
-        catalog
-      }) {
-        const winstonLogger = backendCommon.loggerToWinstonLogger(logger);
-        const preparers = await pluginTechdocsNode.Preparers.fromConfig(config, {
-          reader: urlReader,
-          logger: winstonLogger
-        });
-        for (const [protocol, preparer] of customPreparers.entries()) {
-          preparers.register(protocol, preparer);
-        }
-        const generators = await pluginTechdocsNode.Generators.fromConfig(config, {
-          logger: winstonLogger,
-          customGenerator: customTechdocsGenerator
-        });
-        const publisher = await pluginTechdocsNode.Publisher.fromConfig(config, {
-          logger: winstonLogger,
-          discovery,
-          customPublisher: customTechdocsPublisher
-        });
-        await publisher.getReadiness();
-        const cacheManager = backendCommon.cacheToPluginCacheManager(cache);
-        http.use(
-          await pluginTechdocsBackend.createRouter({
-            logger: winstonLogger,
-            cache: cacheManager,
-            docsBuildStrategy,
-            buildLogTransport,
-            preparers,
-            generators,
-            publisher,
-            config,
-            discovery,
-            httpAuth,
-            auth,
-            catalogClient: catalog
-          })
-        );
-        http.addAuthPolicy({
-          path: "/static",
-          allow: "user-cookie"
-        });
-      }
-    });
-  }
-});
+const _feature = plugin.techdocsPlugin;
 
-exports.default = techdocsPlugin;
+exports.default = _feature;
 //# sourceMappingURL=alpha.cjs.js.map

package/dist/alpha.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"alpha.cjs.js","sources":["../src/plugin.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  cacheToPluginCacheManager,\n  loggerToWinstonLogger,\n} from '@backstage/backend-common';\nimport {\n  coreServices,\n  createBackendPlugin,\n} from '@backstage/backend-plugin-api';\nimport {\n  DocsBuildStrategy,\n  Generators,\n  PreparerBase,\n  Preparers,\n  Publisher,\n  PublisherBase,\n  PublisherType,\n  RemoteProtocol,\n  techdocsBuildsExtensionPoint,\n  TechdocsGenerator,\n  techdocsGeneratorExtensionPoint,\n  techdocsPreparerExtensionPoint,\n  techdocsPublisherExtensionPoint,\n} from '@backstage/plugin-techdocs-node';\nimport { createRouter } from '@backstage/plugin-techdocs-backend';\nimport { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';\nimport * as winston from 'winston';\n\n/**\n * The TechDocs plugin is responsible for serving and building documentation for any entity.\n * @alpha\n */\nexport const techdocsPlugin = createBackendPlugin({\n  pluginId: 'techdocs',\n  register(env) {\n    let docsBuildStrategy: DocsBuildStrategy | undefined;\n    let buildLogTransport: winston.transport | undefined;\n    env.registerExtensionPoint(techdocsBuildsExtensionPoint, {\n      setBuildStrategy(buildStrategy: DocsBuildStrategy) {\n        if (docsBuildStrategy) {\n          throw new Error('DocsBuildStrategy may only be set once');\n        }\n        docsBuildStrategy = buildStrategy;\n      },\n      setBuildLogTransport(transport: winston.transport) {\n        if (buildLogTransport) {\n          throw new Error('BuildLogTransport may only be set once');\n        }\n        buildLogTransport = transport;\n      },\n    });\n\n    let customTechdocsGenerator: TechdocsGenerator | undefined;\n    env.registerExtensionPoint(techdocsGeneratorExtensionPoint, {\n      setTechdocsGenerator(generator: TechdocsGenerator) {\n        if (customTechdocsGenerator) {\n          throw new Error('TechdocsGenerator may only be set once');\n        }\n\n        customTechdocsGenerator = generator;\n      },\n    });\n\n    const customPreparers = new Map<RemoteProtocol, PreparerBase>();\n    env.registerExtensionPoint(techdocsPreparerExtensionPoint, {\n      registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase) {\n        if (customPreparers.has(protocol)) {\n          throw new Error(\n            `Preparer for protocol ${protocol} is already registered`,\n          );\n        }\n        customPreparers.set(protocol, preparer);\n      },\n    });\n\n    let customTechdocsPublisher: PublisherBase | undefined;\n    env.registerExtensionPoint(techdocsPublisherExtensionPoint, {\n      registerPublisher(type: PublisherType, publisher: PublisherBase) {\n        if (customTechdocsPublisher) {\n          throw new Error(`Publisher for type ${type} is already registered`);\n        }\n        customTechdocsPublisher = publisher;\n      },\n    });\n\n    env.registerInit({\n      deps: {\n        config: coreServices.rootConfig,\n        logger: coreServices.logger,\n        urlReader: coreServices.urlReader,\n        http: coreServices.httpRouter,\n        discovery: coreServices.discovery,\n        cache: coreServices.cache,\n        httpAuth: coreServices.httpAuth,\n        auth: coreServices.auth,\n        catalog: catalogServiceRef,\n      },\n      async init({\n        config,\n        logger,\n        urlReader,\n        http,\n        discovery,\n        cache,\n        httpAuth,\n        auth,\n        catalog,\n      }) {\n        const winstonLogger = loggerToWinstonLogger(logger);\n        // Preparers are responsible for fetching source files for documentation.\n        const preparers = await Preparers.fromConfig(config, {\n          reader: urlReader,\n          logger: winstonLogger,\n        });\n        for (const [protocol, preparer] of customPreparers.entries()) {\n          preparers.register(protocol, preparer);\n        }\n\n        // Generators are used for generating documentation sites.\n        const generators = await Generators.fromConfig(config, {\n          logger: winstonLogger,\n          customGenerator: customTechdocsGenerator,\n        });\n\n        // Publisher is used for\n        // 1. Publishing generated files to storage\n        // 2. Fetching files from storage and passing them to TechDocs frontend.\n        const publisher = await Publisher.fromConfig(config, {\n          logger: winstonLogger,\n          discovery: discovery,\n          customPublisher: customTechdocsPublisher,\n        });\n\n        // checks if the publisher is working and logs the result\n        await publisher.getReadiness();\n\n        const cacheManager = cacheToPluginCacheManager(cache);\n        http.use(\n          await createRouter({\n            logger: winstonLogger,\n            cache: cacheManager,\n            docsBuildStrategy,\n            buildLogTransport,\n            preparers,\n            generators,\n            publisher,\n            config,\n            discovery,\n            httpAuth,\n            auth,\n            catalogClient: catalog,\n          }),\n        );\n\n        http.addAuthPolicy({\n          path: '/static',\n          allow: 'user-cookie',\n        });\n      },\n    });\n  },\n});\n"],"names":["createBackendPlugin","techdocsBuildsExtensionPoint","techdocsGeneratorExtensionPoint","techdocsPreparerExtensionPoint","techdocsPublisherExtensionPoint","coreServices","catalogServiceRef","loggerToWinstonLogger","Preparers","Generators","Publisher","cacheToPluginCacheManager","createRouter"],"mappings":"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"}
+{"version":3,"file":"alpha.cjs.js","sources":["../src/alpha.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { techdocsPlugin } from './plugin';\n\n/** @alpha */\nconst _feature = techdocsPlugin;\nexport default _feature;\n"],"names":["techdocsPlugin"],"mappings":";;;;;;AAmBA,MAAM,QAAW,GAAAA;;;;"}

package/dist/alpha.d.ts

@@ -1,9 +1,6 @@
 import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
 
-/**
- * The TechDocs plugin is responsible for serving and building documentation for any entity.
- * @alpha
- */
-declare const techdocsPlugin: _backstage_backend_plugin_api.BackendFeature;
+/** @alpha */
+declare const _feature: _backstage_backend_plugin_api.BackendFeature;
 
-export { techdocsPlugin as default };
+export { _feature as default };

package/dist/cache/TechDocsCache.cjs.js

@@ -0,0 +1,70 @@
+'use strict';
+
+var errors = require('@backstage/errors');
+
+class CacheInvalidationError extends errors.CustomErrorBase {
+}
+class TechDocsCache {
+  cache;
+  logger;
+  readTimeout;
+  constructor({
+    cache,
+    logger,
+    readTimeout
+  }) {
+    this.cache = cache;
+    this.logger = logger;
+    this.readTimeout = readTimeout;
+  }
+  static fromConfig(config, { cache, logger }) {
+    const timeout = config.getOptionalNumber("techdocs.cache.readTimeout");
+    const readTimeout = timeout === void 0 ? 1e3 : timeout;
+    return new TechDocsCache({ cache, logger, readTimeout });
+  }
+  async get(path) {
+    try {
+      const response = await Promise.race([
+        this.cache.get(path),
+        new Promise((cancelAfter) => setTimeout(cancelAfter, this.readTimeout))
+      ]);
+      if (response !== void 0) {
+        this.logger.debug(`Cache hit: ${path}`);
+        return Buffer.from(response, "base64");
+      }
+      this.logger.debug(`Cache miss: ${path}`);
+      return response;
+    } catch (e) {
+      errors.assertError(e);
+      this.logger.warn(`Error getting cache entry ${path}: ${e.message}`);
+      this.logger.debug(e.message, e);
+      return void 0;
+    }
+  }
+  async set(path, data) {
+    this.logger.debug(`Writing cache entry for ${path}`);
+    this.cache.set(path, data.toString("base64")).catch((e) => this.logger.error("write error", e));
+  }
+  async invalidate(path) {
+    return this.cache.delete(path);
+  }
+  async invalidateMultiple(paths) {
+    const settled = await Promise.allSettled(
+      paths.map((path) => this.cache.delete(path))
+    );
+    const rejected = settled.filter(
+      (s) => s.status === "rejected"
+    );
+    if (rejected.length) {
+      throw new CacheInvalidationError(
+        "TechDocs cache invalidation error",
+        rejected
+      );
+    }
+    return settled;
+  }
+}
+
+exports.CacheInvalidationError = CacheInvalidationError;
+exports.TechDocsCache = TechDocsCache;
+//# sourceMappingURL=TechDocsCache.cjs.js.map

package/dist/cache/TechDocsCache.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TechDocsCache.cjs.js","sources":["../../src/cache/TechDocsCache.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { assertError, CustomErrorBase } from '@backstage/errors';\nimport { Config } from '@backstage/config';\nimport { CacheService, LoggerService } from '@backstage/backend-plugin-api';\n\nexport class CacheInvalidationError extends CustomErrorBase {}\n\nexport class TechDocsCache {\n  protected readonly cache: CacheService;\n  protected readonly logger: LoggerService;\n  protected readonly readTimeout: number;\n\n  private constructor({\n    cache,\n    logger,\n    readTimeout,\n  }: {\n    cache: CacheService;\n    logger: LoggerService;\n    readTimeout: number;\n  }) {\n    this.cache = cache;\n    this.logger = logger;\n    this.readTimeout = readTimeout;\n  }\n\n  static fromConfig(\n    config: Config,\n    { cache, logger }: { cache: CacheService; logger: LoggerService },\n  ) {\n    const timeout = config.getOptionalNumber('techdocs.cache.readTimeout');\n    const readTimeout = timeout === undefined ? 1000 : timeout;\n    return new TechDocsCache({ cache, logger, readTimeout });\n  }\n\n  async get(path: string): Promise<Buffer | undefined> {\n    try {\n      // Promise.race ensures we don't hang the client for long if the cache is\n      // temporarily unreachable.\n      const response = (await Promise.race([\n        this.cache.get(path),\n        new Promise(cancelAfter => setTimeout(cancelAfter, this.readTimeout)),\n      ])) as string | undefined;\n\n      if (response !== undefined) {\n        this.logger.debug(`Cache hit: ${path}`);\n        return Buffer.from(response, 'base64');\n      }\n\n      this.logger.debug(`Cache miss: ${path}`);\n      return response;\n    } catch (e) {\n      assertError(e);\n      this.logger.warn(`Error getting cache entry ${path}: ${e.message}`);\n      this.logger.debug(e.message, e);\n      return undefined;\n    }\n  }\n\n  async set(path: string, data: Buffer): Promise<void> {\n    this.logger.debug(`Writing cache entry for ${path}`);\n    this.cache\n      .set(path, data.toString('base64'))\n      .catch(e => this.logger.error('write error', e));\n  }\n\n  async invalidate(path: string): Promise<void> {\n    return this.cache.delete(path);\n  }\n\n  async invalidateMultiple(\n    paths: string[],\n  ): Promise<PromiseSettledResult<void>[]> {\n    const settled = await Promise.allSettled(\n      paths.map(path => this.cache.delete(path)),\n    );\n    const rejected = settled.filter(\n      s => s.status === 'rejected',\n    ) as PromiseRejectedResult[];\n\n    if (rejected.length) {\n      throw new CacheInvalidationError(\n        'TechDocs cache invalidation error',\n        rejected,\n      );\n    }\n\n    return settled;\n  }\n}\n"],"names":["CustomErrorBase","assertError"],"mappings":"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"}

package/dist/cache/cacheMiddleware.cjs.js

@@ -0,0 +1,52 @@
+'use strict';
+
+var router = require('express-promise-router');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var router__default = /*#__PURE__*/_interopDefaultCompat(router);
+
+const createCacheMiddleware = ({
+  cache
+}) => {
+  const cacheMiddleware = router__default.default();
+  cacheMiddleware.use(async (req, res, next) => {
+    const socket = res.socket;
+    const isCacheable = req.path.startsWith("/static/docs/");
+    const isGetRequest = req.method === "GET";
+    if (!isCacheable || !socket) {
+      next();
+      return;
+    }
+    const reqPath = decodeURI(req.path.match(/\/static\/docs\/(.*)$/)[1]);
+    const realEnd = socket.end.bind(socket);
+    const realWrite = socket.write.bind(socket);
+    let writeToCache = true;
+    const chunks = [];
+    socket.write = (data, encoding, callback) => {
+      chunks.push(Buffer.from(data));
+      if (typeof encoding === "function") {
+        return realWrite(data, encoding);
+      }
+      return realWrite(data, encoding, callback);
+    };
+    socket.on("close", async (hadError) => {
+      const content = Buffer.concat(chunks);
+      const head = content.toString("utf8", 0, 12);
+      if (isGetRequest && writeToCache && !hadError && head.match(/HTTP\/\d\.\d 200/)) {
+        await cache.set(reqPath, content);
+      }
+    });
+    const cached = await cache.get(reqPath);
+    if (cached) {
+      writeToCache = false;
+      realEnd(cached);
+      return;
+    }
+    next();
+  });
+  return cacheMiddleware;
+};
+
+exports.createCacheMiddleware = createCacheMiddleware;
+//# sourceMappingURL=cacheMiddleware.cjs.js.map

package/dist/cache/cacheMiddleware.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheMiddleware.cjs.js","sources":["../../src/cache/cacheMiddleware.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { Router } from 'express';\nimport router from 'express-promise-router';\nimport { TechDocsCache } from './TechDocsCache';\nimport { LoggerService } from '@backstage/backend-plugin-api';\n\ntype CacheMiddlewareOptions = {\n  cache: TechDocsCache;\n  logger: LoggerService;\n};\n\ntype ErrorCallback = (err?: Error) => void;\n\nexport const createCacheMiddleware = ({\n  cache,\n}: CacheMiddlewareOptions): Router => {\n  const cacheMiddleware = router();\n\n  // Middleware that, through socket monkey patching, captures responses as\n  // they're sent over /static/docs/* and caches them. Subsequent requests are\n  // loaded from cache. Cache key is the object's path (after `/static/docs/`).\n  cacheMiddleware.use(async (req, res, next) => {\n    const socket = res.socket;\n    const isCacheable = req.path.startsWith('/static/docs/');\n    const isGetRequest = req.method === 'GET';\n\n    // Continue early if this is non-cacheable, or there's no socket.\n    if (!isCacheable || !socket) {\n      next();\n      return;\n    }\n\n    // Make concrete references to these things.\n    const reqPath = decodeURI(req.path.match(/\\/static\\/docs\\/(.*)$/)![1]);\n    const realEnd = socket.end.bind(socket);\n    const realWrite = socket.write.bind(socket);\n    let writeToCache = true;\n    const chunks: Buffer[] = [];\n\n    // Monkey-patch the response's socket to keep track of chunks as they are\n    // written over the wire.\n    socket.write = (\n      data: string | Uint8Array,\n      encoding?: BufferEncoding | ErrorCallback,\n      callback?: ErrorCallback,\n    ) => {\n      chunks.push(Buffer.from(data));\n      if (typeof encoding === 'function') {\n        return realWrite(data, encoding);\n      }\n      return realWrite(data, encoding, callback);\n    };\n\n    // When a socket is closed, if there were no errors and the data written\n    // over the socket should be cached, cache it!\n    socket.on('close', async hadError => {\n      const content = Buffer.concat(chunks);\n      const head = content.toString('utf8', 0, 12);\n      if (\n        isGetRequest &&\n        writeToCache &&\n        !hadError &&\n        head.match(/HTTP\\/\\d\\.\\d 200/)\n      ) {\n        await cache.set(reqPath, content);\n      }\n    });\n\n    // Attempt to retrieve data from the cache.\n    const cached = await cache.get(reqPath);\n\n    // If there is a cache hit, write it out on the socket, ensure we don't re-\n    // cache the data, and prevent going back to canonical storage by never\n    // calling next().\n    if (cached) {\n      writeToCache = false;\n      realEnd(cached);\n      return;\n    }\n\n    // No data retrieved from cache: allow retrieval from canonical storage.\n    next();\n  });\n\n  return cacheMiddleware;\n};\n"],"names":["router"],"mappings":";;;;;;;;AA2BO,MAAM,wBAAwB,CAAC;AAAA,EACpC,KAAA;AACF,CAAsC,KAAA;AACpC,EAAA,MAAM,kBAAkBA,uBAAO,EAAA,CAAA;AAK/B,EAAA,eAAA,CAAgB,GAAI,CAAA,OAAO,GAAK,EAAA,GAAA,EAAK,IAAS,KAAA;AAC5C,IAAA,MAAM,SAAS,GAAI,CAAA,MAAA,CAAA;AACnB,IAAA,MAAM,WAAc,GAAA,GAAA,CAAI,IAAK,CAAA,UAAA,CAAW,eAAe,CAAA,CAAA;AACvD,IAAM,MAAA,YAAA,GAAe,IAAI,MAAW,KAAA,KAAA,CAAA;AAGpC,IAAI,IAAA,CAAC,WAAe,IAAA,CAAC,MAAQ,EAAA;AAC3B,MAAK,IAAA,EAAA,CAAA;AACL,MAAA,OAAA;AAAA,KACF;AAGA,IAAM,MAAA,OAAA,GAAU,UAAU,GAAI,CAAA,IAAA,CAAK,MAAM,uBAAuB,CAAA,CAAG,CAAC,CAAC,CAAA,CAAA;AACrE,IAAA,MAAM,OAAU,GAAA,MAAA,CAAO,GAAI,CAAA,IAAA,CAAK,MAAM,CAAA,CAAA;AACtC,IAAA,MAAM,SAAY,GAAA,MAAA,CAAO,KAAM,CAAA,IAAA,CAAK,MAAM,CAAA,CAAA;AAC1C,IAAA,IAAI,YAAe,GAAA,IAAA,CAAA;AACnB,IAAA,MAAM,SAAmB,EAAC,CAAA;AAI1B,IAAA,MAAA,CAAO,KAAQ,GAAA,CACb,IACA,EAAA,QAAA,EACA,QACG,KAAA;AACH,MAAA,MAAA,CAAO,IAAK,CAAA,MAAA,CAAO,IAAK,CAAA,IAAI,CAAC,CAAA,CAAA;AAC7B,MAAI,IAAA,OAAO,aAAa,UAAY,EAAA;AAClC,QAAO,OAAA,SAAA,CAAU,MAAM,QAAQ,CAAA,CAAA;AAAA,OACjC;AACA,MAAO,OAAA,SAAA,CAAU,IAAM,EAAA,QAAA,EAAU,QAAQ,CAAA,CAAA;AAAA,KAC3C,CAAA;AAIA,IAAO,MAAA,CAAA,EAAA,CAAG,OAAS,EAAA,OAAM,QAAY,KAAA;AACnC,MAAM,MAAA,OAAA,GAAU,MAAO,CAAA,MAAA,CAAO,MAAM,CAAA,CAAA;AACpC,MAAA,MAAM,IAAO,GAAA,OAAA,CAAQ,QAAS,CAAA,MAAA,EAAQ,GAAG,EAAE,CAAA,CAAA;AAC3C,MAAA,IACE,gBACA,YACA,IAAA,CAAC,YACD,IAAK,CAAA,KAAA,CAAM,kBAAkB,CAC7B,EAAA;AACA,QAAM,MAAA,KAAA,CAAM,GAAI,CAAA,OAAA,EAAS,OAAO,CAAA,CAAA;AAAA,OAClC;AAAA,KACD,CAAA,CAAA;AAGD,IAAA,MAAM,MAAS,GAAA,MAAM,KAAM,CAAA,GAAA,CAAI,OAAO,CAAA,CAAA;AAKtC,IAAA,IAAI,MAAQ,EAAA;AACV,MAAe,YAAA,GAAA,KAAA,CAAA;AACf,MAAA,OAAA,CAAQ,MAAM,CAAA,CAAA;AACd,MAAA,OAAA;AAAA,KACF;AAGA,IAAK,IAAA,EAAA,CAAA;AAAA,GACN,CAAA,CAAA;AAED,EAAO,OAAA,eAAA,CAAA;AACT;;;;"}