diff --git a/.changeset/funny-houses-rest.md b/.changeset/funny-houses-rest.md new file mode 100644 index 0000000000..21efce8c19 --- /dev/null +++ b/.changeset/funny-houses-rest.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs-backend': patch +--- + +The `createRouter` and its related types has been marked as deprecared. This backend should instead be initialized using the new backend system. diff --git a/plugins/techdocs-backend/api-report.md b/plugins/techdocs-backend/api-report.md index ec3c2ada82..a73647c40a 100644 --- a/plugins/techdocs-backend/api-report.md +++ b/plugins/techdocs-backend/api-report.md @@ -8,6 +8,7 @@ import { CatalogApi } from '@backstage/catalog-client'; import { CatalogClient } from '@backstage/catalog-client'; import { Config } from '@backstage/config'; import { DefaultTechDocsCollatorFactory as DefaultTechDocsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-techdocs'; +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'; @@ -17,7 +18,6 @@ import { Knex } from 'knex'; import { Logger } from 'winston'; import { Permission } from '@backstage/plugin-permission-common'; import { PluginCacheManager } from '@backstage/backend-common'; -import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { PreparerBuilder } from '@backstage/plugin-techdocs-node'; import { PublisherBase } from '@backstage/plugin-techdocs-node'; import type { TechDocsCollatorFactoryOptions as TechDocsCollatorFactoryOptions_2 } from '@backstage/plugin-search-backend-module-techdocs'; @@ -25,7 +25,7 @@ import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdo import { TokenManager } from '@backstage/backend-common'; import * as winston from 'winston'; -// @public +// @public @deprecated export function createRouter(options: RouterOptions): Promise; // @public @deprecated @@ -60,7 +60,7 @@ export type OutOfTheBoxDeploymentOptions = { generators: GeneratorBuilder; publisher: PublisherBase; logger: winston.Logger; - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; database?: Knex; config: Config; cache: PluginCacheManager; @@ -71,11 +71,11 @@ export type OutOfTheBoxDeploymentOptions = { auth?: AuthService; }; -// @public +// @public @deprecated export type RecommendedDeploymentOptions = { publisher: PublisherBase; logger: winston.Logger; - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; config: Config; cache: PluginCacheManager; docsBuildStrategy?: DocsBuildStrategy_2; @@ -85,7 +85,7 @@ export type RecommendedDeploymentOptions = { auth?: AuthService; }; -// @public +// @public @deprecated export type RouterOptions = | RecommendedDeploymentOptions | OutOfTheBoxDeploymentOptions; @@ -100,7 +100,7 @@ export type TechDocsCollatorFactoryOptions = TechDocsCollatorFactoryOptions_2; // @public export type TechDocsCollatorOptions = { - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; logger: Logger; tokenManager: TokenManager; locationTemplate?: string; diff --git a/plugins/techdocs-backend/src/cache/TechDocsCache.test.ts b/plugins/techdocs-backend/src/cache/TechDocsCache.test.ts index 7dff7069db..1cdd0174b5 100644 --- a/plugins/techdocs-backend/src/cache/TechDocsCache.test.ts +++ b/plugins/techdocs-backend/src/cache/TechDocsCache.test.ts @@ -14,10 +14,10 @@ * limitations under the License. */ -import { CacheClient, loggerToWinstonLogger } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; import { CacheInvalidationError, TechDocsCache } from './TechDocsCache'; import { mockServices } from '@backstage/backend-test-utils'; +import { CacheService } from '@backstage/backend-plugin-api'; const cached = (str: string): string => { return Buffer.from(str).toString('base64'); @@ -25,7 +25,7 @@ const cached = (str: string): string => { describe('TechDocsCache', () => { let CacheUnderTest: TechDocsCache; - let MockClient: jest.Mocked; + let MockClient: jest.Mocked; beforeEach(() => { MockClient = { @@ -36,7 +36,7 @@ describe('TechDocsCache', () => { }; CacheUnderTest = TechDocsCache.fromConfig(new ConfigReader({}), { cache: MockClient, - logger: loggerToWinstonLogger(mockServices.logger.mock()), + logger: mockServices.logger.mock(), }); }); @@ -83,7 +83,7 @@ describe('TechDocsCache', () => { }), { cache: MockClient, - logger: loggerToWinstonLogger(mockServices.logger.mock()), + logger: mockServices.logger.mock(), }, ); diff --git a/plugins/techdocs-backend/src/cache/TechDocsCache.ts b/plugins/techdocs-backend/src/cache/TechDocsCache.ts index 807d6ca87b..a5eb4d37be 100644 --- a/plugins/techdocs-backend/src/cache/TechDocsCache.ts +++ b/plugins/techdocs-backend/src/cache/TechDocsCache.ts @@ -13,16 +13,15 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { CacheClient } from '@backstage/backend-common'; import { assertError, CustomErrorBase } from '@backstage/errors'; import { Config } from '@backstage/config'; -import { Logger } from 'winston'; +import { CacheService, LoggerService } from '@backstage/backend-plugin-api'; export class CacheInvalidationError extends CustomErrorBase {} export class TechDocsCache { - protected readonly cache: CacheClient; - protected readonly logger: Logger; + protected readonly cache: CacheService; + protected readonly logger: LoggerService; protected readonly readTimeout: number; private constructor({ @@ -30,8 +29,8 @@ export class TechDocsCache { logger, readTimeout, }: { - cache: CacheClient; - logger: Logger; + cache: CacheService; + logger: LoggerService; readTimeout: number; }) { this.cache = cache; @@ -41,7 +40,7 @@ export class TechDocsCache { static fromConfig( config: Config, - { cache, logger }: { cache: CacheClient; logger: Logger }, + { cache, logger }: { cache: CacheService; logger: LoggerService }, ) { const timeout = config.getOptionalNumber('techdocs.cache.readTimeout'); const readTimeout = timeout === undefined ? 1000 : timeout; @@ -67,7 +66,7 @@ export class TechDocsCache { } catch (e) { assertError(e); this.logger.warn(`Error getting cache entry ${path}: ${e.message}`); - this.logger.debug(e.stack); + this.logger.debug(e.message, e); return undefined; } } diff --git a/plugins/techdocs-backend/src/cache/cacheMiddleware.test.ts b/plugins/techdocs-backend/src/cache/cacheMiddleware.test.ts index 1d814c3caa..d64c08e072 100644 --- a/plugins/techdocs-backend/src/cache/cacheMiddleware.test.ts +++ b/plugins/techdocs-backend/src/cache/cacheMiddleware.test.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { loggerToWinstonLogger } from '@backstage/backend-common'; import express from 'express'; import request from 'supertest'; import { createCacheMiddleware } from './cacheMiddleware'; @@ -58,7 +57,7 @@ describe('createCacheMiddleware', () => { invalidateMultiple: jest.fn().mockResolvedValue(undefined), } as unknown as jest.Mocked; const router = await createCacheMiddleware({ - logger: loggerToWinstonLogger(mockServices.logger.mock()), + logger: mockServices.logger.mock(), cache, }); app = express().use(router); diff --git a/plugins/techdocs-backend/src/cache/cacheMiddleware.ts b/plugins/techdocs-backend/src/cache/cacheMiddleware.ts index 51cce6d220..02b35cf7bf 100644 --- a/plugins/techdocs-backend/src/cache/cacheMiddleware.ts +++ b/plugins/techdocs-backend/src/cache/cacheMiddleware.ts @@ -15,12 +15,12 @@ */ import { Router } from 'express'; import router from 'express-promise-router'; -import { Logger } from 'winston'; import { TechDocsCache } from './TechDocsCache'; +import { LoggerService } from '@backstage/backend-plugin-api'; type CacheMiddlewareOptions = { cache: TechDocsCache; - logger: Logger; + logger: LoggerService; }; type ErrorCallback = (err?: Error) => void; diff --git a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts index 96f8cfd696..e010856792 100644 --- a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts +++ b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.test.ts @@ -14,11 +14,7 @@ * limitations under the License. */ -import { - PluginEndpointDiscovery, - TokenManager, - loggerToWinstonLogger, -} from '@backstage/backend-common'; +import { TokenManager, loggerToWinstonLogger } from '@backstage/backend-common'; import { Entity } from '@backstage/catalog-model'; import { DefaultTechDocsCollator } from './DefaultTechDocsCollator'; import { @@ -29,6 +25,7 @@ import { setupServer } from 'msw/node'; import { rest } from 'msw'; import { ConfigReader } from '@backstage/config'; import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; +import { DiscoveryService } from '@backstage/backend-plugin-api'; const logger = loggerToWinstonLogger(mockServices.logger.mock()); @@ -83,7 +80,7 @@ describe('TechDocs Collator', () => { registerMswTestHooks(worker); describe('DefaultTechDocsCollator with legacyPathCasing configuration', () => { - let mockDiscoveryApi: jest.Mocked; + let mockDiscoveryApi: jest.Mocked; let mockTokenManager: jest.Mocked; let collator: DefaultTechDocsCollator; @@ -147,7 +144,7 @@ describe('TechDocs Collator', () => { }); describe('DefaultTechDocsCollator', () => { - let mockDiscoveryApi: jest.Mocked; + let mockDiscoveryApi: jest.Mocked; let mockTokenManager: jest.Mocked; let collator: DefaultTechDocsCollator; diff --git a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts index 527846df79..635833676c 100644 --- a/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts +++ b/plugins/techdocs-backend/src/search/DefaultTechDocsCollator.ts @@ -14,10 +14,7 @@ * limitations under the License. */ -import { - PluginEndpointDiscovery, - TokenManager, -} from '@backstage/backend-common'; +import { TokenManager } from '@backstage/backend-common'; import { Entity, parseEntityRef, @@ -38,6 +35,7 @@ import { } from '@backstage/catalog-client'; import { TechDocsDocument } from '@backstage/plugin-techdocs-node'; import { TECHDOCS_ANNOTATION } from '@backstage/plugin-techdocs-common'; +import { DiscoveryService } from '@backstage/backend-plugin-api'; interface MkSearchIndexDoc { title: string; @@ -51,7 +49,7 @@ interface MkSearchIndexDoc { * @public */ export type TechDocsCollatorOptions = { - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; logger: Logger; tokenManager: TokenManager; locationTemplate?: string; diff --git a/plugins/techdocs-backend/src/service/CachedEntityLoader.test.ts b/plugins/techdocs-backend/src/service/CachedEntityLoader.test.ts index 57e4dccbd4..492690611c 100644 --- a/plugins/techdocs-backend/src/service/CachedEntityLoader.test.ts +++ b/plugins/techdocs-backend/src/service/CachedEntityLoader.test.ts @@ -13,9 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { CacheService } from '@backstage/backend-plugin-api'; import { CachedEntityLoader } from './CachedEntityLoader'; import { CatalogClient } from '@backstage/catalog-client'; -import { CacheClient } from '@backstage/backend-common'; import { CompoundEntityRef } from '@backstage/catalog-model'; describe('CachedEntityLoader', () => { @@ -23,7 +23,7 @@ describe('CachedEntityLoader', () => { getEntityByRef: jest.fn(), } as any; - const cache: jest.Mocked = { + const cache: jest.Mocked = { get: jest.fn(), set: jest.fn(), } as any; diff --git a/plugins/techdocs-backend/src/service/CachedEntityLoader.ts b/plugins/techdocs-backend/src/service/CachedEntityLoader.ts index 424d9b9541..d7d1fbbe2b 100644 --- a/plugins/techdocs-backend/src/service/CachedEntityLoader.ts +++ b/plugins/techdocs-backend/src/service/CachedEntityLoader.ts @@ -13,8 +13,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { CacheService } from '@backstage/backend-plugin-api'; import { CatalogClient } from '@backstage/catalog-client'; -import { CacheClient } from '@backstage/backend-common'; import { Entity, CompoundEntityRef, @@ -23,12 +23,12 @@ import { export type CachedEntityLoaderOptions = { catalog: CatalogClient; - cache: CacheClient; + cache: CacheService; }; export class CachedEntityLoader { private readonly catalog: CatalogClient; - private readonly cache: CacheClient; + private readonly cache: CacheService; private readonly readTimeout = 1000; constructor({ catalog, cache }: CachedEntityLoaderOptions) { diff --git a/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts b/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts index bb66c303b7..a611613716 100644 --- a/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts +++ b/plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts @@ -14,10 +14,7 @@ * limitations under the License. */ -import { - loggerToWinstonLogger, - PluginEndpointDiscovery, -} from '@backstage/backend-common'; +import { loggerToWinstonLogger } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; import { ScmIntegrations } from '@backstage/integration'; import { @@ -31,6 +28,7 @@ import { TechDocsCache } from '../cache'; import { DocsBuilder, shouldCheckForUpdate } from '../DocsBuilder'; import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer'; import { mockServices } from '@backstage/backend-test-utils'; +import { DiscoveryService } from '@backstage/backend-plugin-api'; jest.mock('../DocsBuilder'); jest.useFakeTimers(); @@ -66,7 +64,7 @@ describe('DocsSynchronizer', () => { hasDocsBeenGenerated: jest.fn(), publish: jest.fn(), }; - const discovery: jest.Mocked = { + const discovery: jest.Mocked = { getBaseUrl: jest.fn(), getExternalBaseUrl: jest.fn(), }; diff --git a/plugins/techdocs-backend/src/service/DocsSynchronizer.ts b/plugins/techdocs-backend/src/service/DocsSynchronizer.ts index 7859b55e3f..e4b67e920e 100644 --- a/plugins/techdocs-backend/src/service/DocsSynchronizer.ts +++ b/plugins/techdocs-backend/src/service/DocsSynchronizer.ts @@ -14,7 +14,6 @@ * limitations under the License. */ -import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { DEFAULT_NAMESPACE, Entity, @@ -38,6 +37,7 @@ import { DocsBuilder, shouldCheckForUpdate, } from '../DocsBuilder'; +import { DiscoveryService } from '@backstage/backend-plugin-api'; export type DocsSynchronizerSyncOpts = { log: (message: string) => void; @@ -189,7 +189,7 @@ export class DocsSynchronizer { entity, }: { responseHandler: DocsSynchronizerSyncOpts; - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; token: string | undefined; entity: Entity; }) { diff --git a/plugins/techdocs-backend/src/service/router.test.ts b/plugins/techdocs-backend/src/service/router.test.ts index 72da3023b0..5b5fc52741 100644 --- a/plugins/techdocs-backend/src/service/router.test.ts +++ b/plugins/techdocs-backend/src/service/router.test.ts @@ -14,12 +14,7 @@ * limitations under the License. */ -import { - errorHandler, - loggerToWinstonLogger, - PluginCacheManager, - PluginEndpointDiscovery, -} from '@backstage/backend-common'; +import { loggerToWinstonLogger } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; import { DocsBuildStrategy, @@ -33,7 +28,9 @@ import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer'; import { CachedEntityLoader } from './CachedEntityLoader'; import { createEventStream, createRouter, RouterOptions } from './router'; import { TechDocsCache } from '../cache'; -import { mockServices } from '@backstage/backend-test-utils'; +import { mockErrorHandler, mockServices } from '@backstage/backend-test-utils'; +import { DiscoveryService } from '@backstage/backend-plugin-api'; +import { PluginCacheManager } from '@backstage/backend-defaults/cache'; jest.mock('@backstage/catalog-client'); jest.mock('@backstage/config'); @@ -76,7 +73,7 @@ const getMockHttpResponseFor = (content: string): Buffer => { const createApp = async (options: RouterOptions) => { const app = express(); app.use(await createRouter(options)); - app.use(errorHandler()); + app.use(mockErrorHandler()); return app; }; @@ -112,7 +109,7 @@ describe('createRouter', () => { hasDocsBeenGenerated: jest.fn(), publish: jest.fn(), }; - const discovery: jest.Mocked = { + const discovery: jest.Mocked = { getBaseUrl: jest.fn(), getExternalBaseUrl: jest.fn(), }; diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index fff55a9ed1..0123ee89f2 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -14,9 +14,8 @@ * limitations under the License. */ import { - PluginEndpointDiscovery, - PluginCacheManager, createLegacyAuthAdapters, + PluginCacheManager, } from '@backstage/backend-common'; import { CatalogClient } from '@backstage/catalog-client'; import { stringifyEntityRef } from '@backstage/catalog-model'; @@ -38,20 +37,25 @@ import { createCacheMiddleware, TechDocsCache } from '../cache'; import { CachedEntityLoader } from './CachedEntityLoader'; import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy'; import * as winston from 'winston'; -import { AuthService, HttpAuthService } from '@backstage/backend-plugin-api'; +import { + AuthService, + DiscoveryService, + HttpAuthService, +} 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 + * */ export type OutOfTheBoxDeploymentOptions = { preparers: PreparerBuilder; generators: GeneratorBuilder; publisher: PublisherBase; logger: winston.Logger; - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; database?: Knex; // TODO: Make database required when we're implementing database stuff. config: Config; cache: PluginCacheManager; @@ -67,11 +71,12 @@ export type OutOfTheBoxDeploymentOptions = { * 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. */ export type RecommendedDeploymentOptions = { publisher: PublisherBase; logger: winston.Logger; - discovery: PluginEndpointDiscovery; + discovery: DiscoveryService; config: Config; cache: PluginCacheManager; docsBuildStrategy?: DocsBuildStrategy; @@ -85,6 +90,7 @@ export type RecommendedDeploymentOptions = { * 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. */ export type RouterOptions = | RecommendedDeploymentOptions @@ -94,7 +100,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 + * @public */ function isOutOfTheBoxOption( opt: RouterOptions, @@ -106,6 +112,8 @@ 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. */ export async function createRouter( options: RouterOptions,