From 7a2cfbbd3165f413eb3b1f1e6ffcf514e5fc27b0 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Fri, 14 Mar 2025 15:02:20 -0500 Subject: [PATCH] TechDocs legacy Signed-off-by: Andre Wanlin --- .changeset/four-months-beg.md | 2 +- packages/backend-legacy/src/index.ts | 3 - .../backend-legacy/src/plugins/techdocs.ts | 60 ----------------- plugins/techdocs-backend/package.json | 2 +- plugins/techdocs-backend/report.api.md | 67 ------------------- plugins/techdocs-backend/src/index.ts | 32 --------- plugins/techdocs-backend/src/plugin.ts | 18 ++--- .../src/service/DocsSynchronizer.test.ts | 5 +- .../src/service/DocsSynchronizer.ts | 6 +- plugins/techdocs-backend/src/service/index.ts | 22 ------ .../src/service/router.test.ts | 20 +++--- .../techdocs-backend/src/service/router.ts | 44 +++++------- yarn.lock | 1 - 13 files changed, 40 insertions(+), 242 deletions(-) delete mode 100644 packages/backend-legacy/src/plugins/techdocs.ts delete mode 100644 plugins/techdocs-backend/src/service/index.ts diff --git a/.changeset/four-months-beg.md b/.changeset/four-months-beg.md index 5a4f3cd79b..2bebcb134b 100644 --- a/.changeset/four-months-beg.md +++ b/.changeset/four-months-beg.md @@ -2,4 +2,4 @@ '@backstage/plugin-techdocs-backend': major --- -**BREAKING** Removed deprecated code `DefaultTechDocsCollatorFactory`. Use the `@backstage/plugin-search-backend-module-techdocs` for this instead. +**BREAKING** Removed support for the legacy backend, please migrate to the new backend system. Also removed deprecated `DefaultTechDocsCollatorFactory`. Use the `@backstage/plugin-search-backend-module-techdocs` for this instead. Finally, deprecated `DocsBuildStrategy` and `TechDocsDocument` were removed, use the versions in `@backstage/plugin-techdocs-node` instead. diff --git a/packages/backend-legacy/src/index.ts b/packages/backend-legacy/src/index.ts index f85fa798e8..799b35051f 100644 --- a/packages/backend-legacy/src/index.ts +++ b/packages/backend-legacy/src/index.ts @@ -43,7 +43,6 @@ import catalog from './plugins/catalog'; import events from './plugins/events'; import kubernetes from './plugins/kubernetes'; import scaffolder from './plugins/scaffolder'; -import techdocs from './plugins/techdocs'; import permission from './plugins/permission'; import { PluginEnvironment } from './types'; import { ServerPermissionClient } from '@backstage/plugin-permission-node'; @@ -132,7 +131,6 @@ async function main() { const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder')); const authEnv = useHotMemoize(module, () => createEnv('auth')); - const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs')); const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes')); const permissionEnv = useHotMemoize(module, () => createEnv('permission')); const eventsEnv = useHotMemoize(module, () => createEnv('events')); @@ -142,7 +140,6 @@ async function main() { apiRouter.use('/events', await events(eventsEnv)); apiRouter.use('/scaffolder', await scaffolder(scaffolderEnv)); apiRouter.use('/auth', await authPlugin(authEnv)); - apiRouter.use('/techdocs', await techdocs(techdocsEnv)); apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv)); apiRouter.use('/permission', await permission(permissionEnv)); apiRouter.use(notFoundHandler()); diff --git a/packages/backend-legacy/src/plugins/techdocs.ts b/packages/backend-legacy/src/plugins/techdocs.ts deleted file mode 100644 index 21048d4bb9..0000000000 --- a/packages/backend-legacy/src/plugins/techdocs.ts +++ /dev/null @@ -1,60 +0,0 @@ -/* - * Copyright 2020 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 { - createRouter, - Generators, - Preparers, - Publisher, -} from '@backstage/plugin-techdocs-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - // Preparers are responsible for fetching source files for documentation. - const preparers = await Preparers.fromConfig(env.config, { - logger: env.logger, - reader: env.reader, - }); - - // Generators are used for generating documentation sites. - const generators = await Generators.fromConfig(env.config, { - logger: env.logger, - }); - - // Publisher is used for - // 1. Publishing generated files to storage - // 2. Fetching files from storage and passing them to TechDocs frontend. - const publisher = await Publisher.fromConfig(env.config, { - logger: env.logger, - discovery: env.discovery, - }); - - // checks if the publisher is working and logs the result - await publisher.getReadiness(); - - return await createRouter({ - preparers, - generators, - publisher, - logger: env.logger, - config: env.config, - discovery: env.discovery, - cache: env.cache, - }); -} diff --git a/plugins/techdocs-backend/package.json b/plugins/techdocs-backend/package.json index 27b9d8c9c7..b438f56456 100644 --- a/plugins/techdocs-backend/package.json +++ b/plugins/techdocs-backend/package.json @@ -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:^", diff --git a/plugins/techdocs-backend/report.api.md b/plugins/techdocs-backend/report.api.md index 03e5c46fa2..17e54f863e 100644 --- a/plugins/techdocs-backend/report.api.md +++ b/plugins/techdocs-backend/report.api.md @@ -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; - -// @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'; ``` diff --git a/plugins/techdocs-backend/src/index.ts b/plugins/techdocs-backend/src/index.ts index a3fe3b2064..185e613c3a 100644 --- a/plugins/techdocs-backend/src/index.ts +++ b/plugins/techdocs-backend/src/index.ts @@ -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'; diff --git a/plugins/techdocs-backend/src/plugin.ts b/plugins/techdocs-backend/src/plugin.ts index c7d6ae5259..ac16e43dab 100644 --- a/plugins/techdocs-backend/src/plugin.ts +++ b/plugins/techdocs-backend/src/plugin.ts @@ -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, diff --git a/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts b/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts index 5248ca6dad..201f93dbf9 100644 --- a/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts +++ b/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts @@ -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(), }), diff --git a/plugins/techdocs-backend/src/service/DocsSynchronizer.ts b/plugins/techdocs-backend/src/service/DocsSynchronizer.ts index a1375ec142..21192b29e7 100644 --- a/plugins/techdocs-backend/src/service/DocsSynchronizer.ts +++ b/plugins/techdocs-backend/src/service/DocsSynchronizer.ts @@ -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; diff --git a/plugins/techdocs-backend/src/service/index.ts b/plugins/techdocs-backend/src/service/index.ts deleted file mode 100644 index 0065e33a2a..0000000000 --- a/plugins/techdocs-backend/src/service/index.ts +++ /dev/null @@ -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'; diff --git a/plugins/techdocs-backend/src/service/router.test.ts b/plugins/techdocs-backend/src/service/router.test.ts index c74167552d..233f679fac 100644 --- a/plugins/techdocs-backend/src/service/router.test.ts +++ b/plugins/techdocs-backend/src/service/router.test.ts @@ -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 = { - getClient: jest.fn(), - }; + const docsBuildStrategy: jest.Mocked = { 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(() => { diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index b99579e0eb..bfaf072717 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -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 { 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 }); } diff --git a/yarn.lock b/yarn.lock index 10e1a78361..9b875d9b64 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8450,7 +8450,6 @@ __metadata: version: 0.0.0-use.local resolution: "@backstage/plugin-techdocs-backend@workspace:plugins/techdocs-backend" dependencies: - "@backstage/backend-common": ^0.25.0 "@backstage/backend-defaults": "workspace:^" "@backstage/backend-plugin-api": "workspace:^" "@backstage/backend-test-utils": "workspace:^"