TechDocs legacy

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
2025-03-14 15:02:20 -05:00
parent d5c4a9db09
commit 7a2cfbbd31
13 changed files with 40 additions and 242 deletions
@@ -58,7 +58,7 @@
    "test": "backstage-cli package test"
  },
  "dependencies": {
-    "@backstage/backend-common": "^0.25.0",
+    "@backstage/backend-defaults": "workspace:^",
    "@backstage/backend-plugin-api": "workspace:^",
    "@backstage/catalog-client": "workspace:^",
    "@backstage/catalog-model": "workspace:^",
@@ -3,76 +3,9 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).

 ```ts
-import { AuthService } from '@backstage/backend-plugin-api';
 import { BackendFeature } from '@backstage/backend-plugin-api';
-import { CatalogApi } from '@backstage/catalog-client';
-import { Config } from '@backstage/config';
-import { DiscoveryService } from '@backstage/backend-plugin-api';
-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';
-import { HttpAuthService } from '@backstage/backend-plugin-api';
-import { Knex } from 'knex';
-import { PluginCacheManager } from '@backstage/backend-common';
-import { PreparerBuilder } from '@backstage/plugin-techdocs-node';
-import { PublisherBase } from '@backstage/plugin-techdocs-node';
-import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdocs-node';
-import * as winston from 'winston';
-
-// @public @deprecated
-export function createRouter(options: RouterOptions): Promise<express.Router>;
-
-// @public @deprecated (undocumented)
-export type DocsBuildStrategy = DocsBuildStrategy_2;
-
-// @public
-export type OutOfTheBoxDeploymentOptions = {
-  preparers: PreparerBuilder;
-  generators: GeneratorBuilder;
-  publisher: PublisherBase;
-  logger: winston.Logger;
-  discovery: DiscoveryService;
-  database?: Knex;
-  config: Config;
-  cache: PluginCacheManager;
-  docsBuildStrategy?: DocsBuildStrategy_2;
-  buildLogTransport?: winston.transport;
-  catalogClient?: CatalogApi;
-  httpAuth?: HttpAuthService;
-  auth?: AuthService;
-};
-
-// @public @deprecated
-export type RecommendedDeploymentOptions = {
-  publisher: PublisherBase;
-  logger: winston.Logger;
-  discovery: DiscoveryService;
-  config: Config;
-  cache: PluginCacheManager;
-  docsBuildStrategy?: DocsBuildStrategy_2;
-  buildLogTransport?: winston.transport;
-  catalogClient?: CatalogApi;
-  httpAuth?: HttpAuthService;
-  auth?: AuthService;
-};
-
-// @public @deprecated
-export type RouterOptions =
-  | RecommendedDeploymentOptions
-  | OutOfTheBoxDeploymentOptions;
-
-// @public @deprecated (undocumented)
-export type ShouldBuildParameters = {
-  entity: Entity;
-};
-
-// @public @deprecated (undocumented)
-export type TechDocsDocument = TechDocsDocument_2;

 // @public
 const techdocsPlugin: BackendFeature;
 export default techdocsPlugin;
-
-export * from '@backstage/plugin-techdocs-node';
 ```
@@ -20,36 +20,4 @@
 * @packageDocumentation
 */

-import { Entity } from '@backstage/catalog-model';
-import {
-  DocsBuildStrategy as _DocsBuildStrategy,
-  TechDocsDocument as _TechDocsDocument,
-} from '@backstage/plugin-techdocs-node';
-
 export { techdocsPlugin as default } from './plugin';
-export { createRouter } from './service';
-export type {
-  RouterOptions,
-  RecommendedDeploymentOptions,
-  OutOfTheBoxDeploymentOptions,
-} from './service';
-
-/**
- * @public
- * @deprecated import from `@backstage/plugin-techdocs-node` instead
- */
-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';
@@ -14,10 +14,6 @@
 * limitations under the License.
 */

-import {
-  cacheToPluginCacheManager,
-  loggerToWinstonLogger,
-} from '@backstage/backend-common';
 import {
  coreServices,
  createBackendPlugin,
@@ -38,9 +34,9 @@ import {
  techdocsPreparerExtensionPoint,
  techdocsPublisherExtensionPoint,
 } from '@backstage/plugin-techdocs-node';
-import { createRouter } from './service';
 import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
 import * as winston from 'winston';
+import { createRouter } from './service/router';

 /**
 * The TechDocs plugin is responsible for serving and building documentation for any entity.
@@ -129,11 +125,10 @@ export const techdocsPlugin = createBackendPlugin({
        auth,
        catalog,
      }) {
-        const winstonLogger = loggerToWinstonLogger(logger);
        // Preparers are responsible for fetching source files for documentation.
        const preparers = await Preparers.fromConfig(config, {
          reader: urlReader,
-          logger: winstonLogger,
+          logger: logger,
        });
        for (const [protocol, preparer] of customPreparers.entries()) {
          preparers.register(protocol, preparer);
@@ -141,7 +136,7 @@ export const techdocsPlugin = createBackendPlugin({

        // Generators are used for generating documentation sites.
        const generators = await Generators.fromConfig(config, {
-          logger: winstonLogger,
+          logger: logger,
          customGenerator: customTechdocsGenerator,
        });

@@ -149,7 +144,7 @@ export const techdocsPlugin = createBackendPlugin({
        // 1. Publishing generated files to storage
        // 2. Fetching files from storage and passing them to TechDocs frontend.
        const publisher = await Publisher.fromConfig(config, {
-          logger: winstonLogger,
+          logger: logger,
          discovery: discovery,
          customPublisher: customTechdocsPublisher,
          publisherSettings,
@@ -158,11 +153,10 @@ export const techdocsPlugin = createBackendPlugin({
        // checks if the publisher is working and logs the result
        await publisher.getReadiness();

-        const cacheManager = cacheToPluginCacheManager(cache);
        http.use(
          await createRouter({
-            logger: winstonLogger,
-            cache: cacheManager,
+            logger: logger,
+            cache,
            docsBuildStrategy,
            buildLogTransport,
            preparers,
@@ -14,7 +14,6 @@
 * limitations under the License.
 */

-import { loggerToWinstonLogger } from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import { ScmIntegrations } from '@backstage/integration';
 import {
@@ -87,7 +86,7 @@ describe('DocsSynchronizer', () => {
    docsSynchronizer = new DocsSynchronizer({
      publisher,
      config: new ConfigReader({}),
-      logger: loggerToWinstonLogger(mockServices.logger.mock()),
+      logger: mockServices.logger.mock(),
      buildLogTransport: mockBuildLogTransport,
      scmIntegrations: ScmIntegrations.fromConfig(new ConfigReader({})),
      cache,
@@ -343,7 +342,7 @@ describe('DocsSynchronizer', () => {
        config: new ConfigReader({
          techdocs: { legacyUseCaseSensitiveTripletPaths: true },
        }),
-        logger: loggerToWinstonLogger(mockServices.logger.mock()),
+        logger: mockServices.logger.mock(),
        buildLogTransport: new winston.transports.Stream({
          stream: new PassThrough(),
        }),
@@ -36,7 +36,7 @@ import {
  DocsBuilder,
  shouldCheckForUpdate,
 } from '../DocsBuilder';
-import { DiscoveryService } from '@backstage/backend-plugin-api';
+import { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';

 export type DocsSynchronizerSyncOpts = {
  log: (message: string) => void;
@@ -46,7 +46,7 @@ export type DocsSynchronizerSyncOpts = {

 export class DocsSynchronizer {
  private readonly publisher: PublisherBase;
-  private readonly logger: winston.Logger;
+  private readonly logger: LoggerService;
  private readonly buildLogTransport?: winston.transport;
  private readonly config: Config;
  private readonly scmIntegrations: ScmIntegrationRegistry;
@@ -62,7 +62,7 @@ export class DocsSynchronizer {
    cache,
  }: {
    publisher: PublisherBase;
-    logger: winston.Logger;
+    logger: LoggerService;
    buildLogTransport?: winston.transport;
    config: Config;
    scmIntegrations: ScmIntegrationRegistry;
@@ -1,22 +0,0 @@
-/*
- * Copyright 2022 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.
- */
-
-export { createRouter } from './router';
-export type {
-  RouterOptions,
-  RecommendedDeploymentOptions,
-  OutOfTheBoxDeploymentOptions,
-} from './router';
@@ -14,10 +14,6 @@
 * limitations under the License.
 */

-import {
-  PluginCacheManager,
-  loggerToWinstonLogger,
-} from '@backstage/backend-common';
 import { ConfigReader } from '@backstage/config';
 import {
  DocsBuildStrategy,
@@ -111,9 +107,7 @@ describe('createRouter', () => {
    publish: jest.fn(),
  };
  const discovery = mockServices.discovery.mock();
-  const cache: jest.Mocked<PluginCacheManager> = {
-    getClient: jest.fn(),
-  };
+
  const docsBuildStrategy: jest.Mocked<DocsBuildStrategy> = {
    shouldBuild: jest.fn(),
  };
@@ -122,18 +116,22 @@ describe('createRouter', () => {
    generators,
    publisher,
    config: new ConfigReader({}),
-    logger: loggerToWinstonLogger(mockServices.logger.mock()),
+    logger: mockServices.logger.mock(),
    discovery,
-    cache,
+    cache: mockServices.cache.mock(),
    docsBuildStrategy,
+    auth: mockServices.auth(),
+    httpAuth: mockServices.httpAuth(),
  };
  const recommendedOptions = {
    publisher,
    config: new ConfigReader({}),
-    logger: loggerToWinstonLogger(mockServices.logger.mock()),
+    logger: mockServices.logger.mock(),
    discovery,
-    cache,
+    cache: mockServices.cache.mock(),
    docsBuildStrategy,
+    auth: mockServices.auth(),
+    httpAuth: mockServices.httpAuth(),
  };

  beforeEach(() => {
@@ -14,10 +14,6 @@
 * limitations under the License.
 */

-import {
-  createLegacyAuthAdapters,
-  PluginCacheManager,
-} from '@backstage/backend-common';
 import { CatalogApi, CatalogClient } from '@backstage/catalog-client';
 import { stringifyEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
@@ -40,57 +36,57 @@ import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy';
 import * as winston from 'winston';
 import {
  AuthService,
+  CacheService,
  DiscoveryService,
  HttpAuthService,
+  LoggerService,
 } from '@backstage/backend-plugin-api';

 /**
 * Required dependencies for running TechDocs in the "out-of-the-box"
 * deployment configuration (prepare/generate/publish all in the Backend).
 *
- * @public
+ * @internal
 */
 export type OutOfTheBoxDeploymentOptions = {
  preparers: PreparerBuilder;
  generators: GeneratorBuilder;
  publisher: PublisherBase;
-  logger: winston.Logger;
+  logger: LoggerService;
  discovery: DiscoveryService;
  database?: Knex; // TODO: Make database required when we're implementing database stuff.
  config: Config;
-  cache: PluginCacheManager;
+  cache: CacheService;
  docsBuildStrategy?: DocsBuildStrategy;
  buildLogTransport?: winston.transport;
  catalogClient?: CatalogApi;
-  httpAuth?: HttpAuthService;
-  auth?: AuthService;
+  httpAuth: HttpAuthService;
+  auth: AuthService;
 };

 /**
 * Required dependencies for running TechDocs in the "recommended" deployment
 * configuration (prepare/generate handled externally in CI/CD).
 *
- * @public
- * @deprecated This type is only exported for legacy reasons and will be removed in the future.
+ * @internal
 */
 export type RecommendedDeploymentOptions = {
  publisher: PublisherBase;
-  logger: winston.Logger;
+  logger: LoggerService;
  discovery: DiscoveryService;
  config: Config;
-  cache: PluginCacheManager;
+  cache: CacheService;
  docsBuildStrategy?: DocsBuildStrategy;
  buildLogTransport?: winston.transport;
  catalogClient?: CatalogApi;
-  httpAuth?: HttpAuthService;
-  auth?: AuthService;
+  httpAuth: HttpAuthService;
+  auth: AuthService;
 };

 /**
 * One of the two deployment configurations must be provided.
 *
- * @public
- * @deprecated This type is only exported for legacy reasons and will be removed in the future.
+ * @internal
 */
 export type RouterOptions =
  | RecommendedDeploymentOptions
@@ -100,7 +96,7 @@ export type RouterOptions =
 * Typeguard to help createRouter() understand when we are in a "recommended"
 * deployment vs. when we are in an out-of-the-box deployment configuration.
 *
- * @public
+ * @internal
 */
 function isOutOfTheBoxOption(
  opt: RouterOptions,
@@ -111,17 +107,13 @@ function isOutOfTheBoxOption(
 /**
 * Creates a techdocs router.
 *
- * @public
- * @deprecated This function is only exported for legacy reasons and will be removed in the future.
- * Please {@link https://backstage.io/docs/backend-system/building-backends/migrating | migrate } to use the new backend system and follow these {@link https://backstage.io/docs/features/techdocs/getting-started#new-backend-system | instructions } to install the user settings backend plugin.
+ * @internal
 */
 export async function createRouter(
  options: RouterOptions,
 ): Promise<express.Router> {
  const router = Router();
-  const { publisher, config, logger, discovery } = options;
-
-  const { auth, httpAuth } = createLegacyAuthAdapters(options);
+  const { publisher, config, logger, discovery, httpAuth, auth } = options;

  const catalogClient =
    options.catalogClient ?? new CatalogClient({ discoveryApi: discovery });
@@ -133,14 +125,14 @@ export async function createRouter(
  // when loading a single techdocs page.
  const entityLoader = new CachedEntityLoader({
    catalog: catalogClient,
-    cache: options.cache.getClient(),
+    cache: options.cache,
  });

  // Set up a cache client if configured.
  let cache: TechDocsCache | undefined;
  const defaultTtl = config.getOptionalNumber('techdocs.cache.ttl');
  if (defaultTtl) {
-    const cacheClient = options.cache.getClient({ defaultTtl });
+    const cacheClient = options.cache.withOptions({ defaultTtl });
    cache = TechDocsCache.fromConfig(config, { cache: cacheClient, logger });
  }