From 6ee137693feda26e518f1c9e72fe18183f042ba6 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 15 Mar 2022 09:45:01 +0100 Subject: [PATCH 1/3] catalog-backend: Reduce public API surface Signed-off-by: Johan Haals --- plugins/catalog-backend/api-report.md | 135 ------------------ .../src/modules/core/DefaultLocationStore.ts | 2 +- .../catalog-backend/src/processing/index.ts | 9 +- .../src/service/CatalogBuilder.ts | 9 +- plugins/catalog-backend/src/service/index.ts | 9 -- 5 files changed, 3 insertions(+), 161 deletions(-) diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 42e05722c4..7737cdc7cf 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -14,11 +14,8 @@ import { Config } from '@backstage/config'; import { DocumentCollatorFactory } from '@backstage/plugin-search-common'; import { Entity } from '@backstage/catalog-model'; import { EntityPolicy } from '@backstage/catalog-model'; -import express from 'express'; import { GetEntitiesRequest } from '@backstage/catalog-client'; -import { JsonObject } from '@backstage/types'; import { JsonValue } from '@backstage/types'; -import { Location as Location_2 } from '@backstage/catalog-client'; import { Logger } from 'winston'; import { Permission } from '@backstage/plugin-permission-common'; import { PermissionAuthorizer } from '@backstage/plugin-permission-common'; @@ -121,10 +118,7 @@ export class CatalogBuilder { ): void; addProcessor(...processors: CatalogProcessor[]): CatalogBuilder; build(): Promise<{ - entitiesCatalog: EntitiesCatalog; - locationAnalyzer: LocationAnalyzer; processingEngine: CatalogProcessingEngine; - locationService: LocationService; router: Router; }>; static create(env: CatalogEnvironment): CatalogBuilder; @@ -187,12 +181,6 @@ export interface CatalogProcessingEngine { stop(): Promise; } -// @public -export interface CatalogProcessingOrchestrator { - // (undocumented) - process(request: EntityProcessingRequest): Promise; -} - // @public (undocumented) export type CatalogProcessor = { getProcessorName(): string; @@ -320,9 +308,6 @@ export function createRandomProcessingInterval(options: { maxSeconds: number; }): ProcessingIntervalFunction; -// @public -export function createRouter(options: RouterOptions): Promise; - // @public @deprecated (undocumented) export class DefaultCatalogCollator { constructor(options: { @@ -389,22 +374,6 @@ export type DefaultCatalogCollatorFactoryOptions = { catalogClient?: CatalogApi; }; -// @public (undocumented) -export class DefaultCatalogProcessingOrchestrator - implements CatalogProcessingOrchestrator -{ - constructor(options: { - processors: CatalogProcessor[]; - integrations: ScmIntegrationRegistry; - logger: Logger; - parser: CatalogProcessorParser; - policy: EntityPolicy; - rulesEnforcer: CatalogRulesEnforcer; - }); - // (undocumented) - process(request: EntityProcessingRequest): Promise; -} - // @public export class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer { constructor(rules: CatalogRule[]); @@ -504,27 +473,6 @@ export type EntityPagination = { after?: string; }; -// @public -export type EntityProcessingRequest = { - entity: Entity; - state?: JsonObject; -}; - -// @public -export type EntityProcessingResult = - | { - ok: true; - state: JsonObject; - completedEntity: Entity; - deferredEntities: DeferredEntity[]; - relations: EntityRelationSpec[]; - errors: Error[]; - } - | { - ok: false; - errors: Error[]; - }; - // @public export interface EntityProvider { connect(connection: EntityProviderConnection): Promise; @@ -593,48 +541,6 @@ export type LocationEntityProcessorOptions = { integrations: ScmIntegrationRegistry; }; -// @public -export interface LocationInput { - // (undocumented) - target: string; - // (undocumented) - type: string; -} - -// @public -export interface LocationService { - // (undocumented) - createLocation( - location: LocationInput, - dryRun: boolean, - options?: { - authorizationToken?: string; - }, - ): Promise<{ - location: Location_2; - entities: Entity[]; - exists?: boolean; - }>; - // (undocumented) - deleteLocation( - id: string, - options?: { - authorizationToken?: string; - }, - ): Promise; - // (undocumented) - getLocation( - id: string, - options?: { - authorizationToken?: string; - }, - ): Promise; - // (undocumented) - listLocations(options?: { - authorizationToken?: string; - }): Promise; -} - // @public export type LocationSpec = { type: string; @@ -642,18 +548,6 @@ export type LocationSpec = { presence?: 'optional' | 'required'; }; -// @public -export interface LocationStore { - // (undocumented) - createLocation(location: LocationInput): Promise; - // (undocumented) - deleteLocation(id: string): Promise; - // (undocumented) - getLocation(id: string): Promise; - // (undocumented) - listLocations(): Promise; -} - // @public (undocumented) export type PageInfo = | { @@ -760,35 +654,6 @@ export const processingResult: Readonly<{ readonly relation: (spec: EntityRelationSpec) => CatalogProcessorResult; }>; -// @public -export type RefreshOptions = { - entityRef: string; - authorizationToken?: string; -}; - -// @public -export interface RefreshService { - refresh(options: RefreshOptions): Promise; -} - -// @public -export interface RouterOptions { - // (undocumented) - config: Config; - // (undocumented) - entitiesCatalog?: EntitiesCatalog; - // (undocumented) - locationAnalyzer?: LocationAnalyzer; - // (undocumented) - locationService: LocationService; - // (undocumented) - logger: Logger; - // (undocumented) - permissionIntegrationRouter?: express.Router; - // (undocumented) - refreshService?: RefreshService; -} - // @public (undocumented) export class UrlReaderProcessor implements CatalogProcessor { constructor(options: { reader: UrlReader; logger: Logger }); diff --git a/plugins/catalog-backend/src/modules/core/DefaultLocationStore.ts b/plugins/catalog-backend/src/modules/core/DefaultLocationStore.ts index d637f4eda0..0d4bedabbb 100644 --- a/plugins/catalog-backend/src/modules/core/DefaultLocationStore.ts +++ b/plugins/catalog-backend/src/modules/core/DefaultLocationStore.ts @@ -22,7 +22,7 @@ import { DbLocationsRow } from '../../database/tables'; import { getEntityLocationRef } from '../../processing/util'; import { EntityProvider, EntityProviderConnection } from '../../api'; import { locationSpecToLocationEntity } from '../../util/conversion'; -import { LocationInput, LocationStore } from '../../service'; +import { LocationInput, LocationStore } from '../../service/types'; export class DefaultLocationStore implements LocationStore, EntityProvider { private _connection: EntityProviderConnection | undefined; diff --git a/plugins/catalog-backend/src/processing/index.ts b/plugins/catalog-backend/src/processing/index.ts index 315cea37d7..b392c3aa76 100644 --- a/plugins/catalog-backend/src/processing/index.ts +++ b/plugins/catalog-backend/src/processing/index.ts @@ -14,14 +14,7 @@ * limitations under the License. */ -export type { - CatalogProcessingOrchestrator, - CatalogProcessingEngine, - EntityProcessingRequest, - EntityProcessingResult, - DeferredEntity, -} from './types'; -export { DefaultCatalogProcessingOrchestrator } from './DefaultCatalogProcessingOrchestrator'; +export type { CatalogProcessingEngine, DeferredEntity } from './types'; export { createRandomProcessingInterval } from './refresh'; export type { ProcessingIntervalFunction } from './refresh'; diff --git a/plugins/catalog-backend/src/service/CatalogBuilder.ts b/plugins/catalog-backend/src/service/CatalogBuilder.ts index 8dd507c74e..fb4ed6086f 100644 --- a/plugins/catalog-backend/src/service/CatalogBuilder.ts +++ b/plugins/catalog-backend/src/service/CatalogBuilder.ts @@ -32,7 +32,7 @@ import { ScmIntegrations } from '@backstage/integration'; import { createHash } from 'crypto'; import { Router } from 'express'; import lodash, { keyBy } from 'lodash'; -import { EntitiesCatalog, EntitiesSearchFilter } from '../catalog'; +import { EntitiesSearchFilter } from '../catalog'; import { CatalogProcessor, @@ -76,7 +76,6 @@ import { AuthorizedRefreshService } from './AuthorizedRefreshService'; import { DefaultCatalogRulesEnforcer } from '../ingestion/CatalogRules'; import { Config } from '@backstage/config'; import { Logger } from 'winston'; -import { LocationService } from './types'; import { connectEntityProviders } from '../processing/connectEntityProviders'; import { permissionRules as catalogPermissionRules } from '../permissions/rules'; import { PermissionAuthorizer } from '@backstage/plugin-permission-common'; @@ -355,10 +354,7 @@ export class CatalogBuilder { * Wires up and returns all of the component parts of the catalog */ async build(): Promise<{ - entitiesCatalog: EntitiesCatalog; - locationAnalyzer: LocationAnalyzer; processingEngine: CatalogProcessingEngine; - locationService: LocationService; router: Router; }> { const { config, database, logger, permissions } = this.env; @@ -460,10 +456,7 @@ export class CatalogBuilder { await connectEntityProviders(processingDatabase, entityProviders); return { - entitiesCatalog, - locationAnalyzer, processingEngine, - locationService, router, }; } diff --git a/plugins/catalog-backend/src/service/index.ts b/plugins/catalog-backend/src/service/index.ts index e1c7f54475..b1e91e4382 100644 --- a/plugins/catalog-backend/src/service/index.ts +++ b/plugins/catalog-backend/src/service/index.ts @@ -14,14 +14,5 @@ * limitations under the License. */ -export type { - LocationService, - RefreshService, - RefreshOptions, - LocationStore, - LocationInput, -} from './types'; -export { createRouter } from './createRouter'; -export type { RouterOptions } from './createRouter'; export type { CatalogEnvironment } from './CatalogBuilder'; export { CatalogBuilder } from './CatalogBuilder'; From 6145ca7189a65a37c988899d95c096d18cdf58bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Tue, 15 Mar 2022 11:29:59 +0100 Subject: [PATCH 2/3] more removals MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/fluffy-cameras-shop.md | 44 ++++++++ plugins/catalog-backend/api-report.md | 100 ------------------ plugins/catalog-backend/src/catalog/index.ts | 13 +-- plugins/catalog-backend/src/catalog/types.ts | 14 +-- .../src/ingestion/CatalogRules.ts | 6 -- .../catalog-backend/src/ingestion/index.ts | 2 - .../src/service/createRouter.test.ts | 2 +- .../src/service/createRouter.ts | 2 +- .../request/parseEntityPaginationParams.ts | 2 +- 9 files changed, 50 insertions(+), 135 deletions(-) create mode 100644 .changeset/fluffy-cameras-shop.md diff --git a/.changeset/fluffy-cameras-shop.md b/.changeset/fluffy-cameras-shop.md new file mode 100644 index 0000000000..aee6fa6ebb --- /dev/null +++ b/.changeset/fluffy-cameras-shop.md @@ -0,0 +1,44 @@ +--- +'@backstage/plugin-catalog-backend': minor +--- + +**BREAKING**: A number of types and classes have been removed, without a prior deprecation period. These were all very internal, essentially unused by the vast majority of users, and their being exposed was leading to excessive breaking of public interfaces for little-to-zero benefit. So for the 1.0 release of the catalog, the following interface changes have been made (but should have no effect on most users): + +- The return type of `CatalogBuilder.build()` now only has the fields `processingEngine` and `router` which is what most users actually consume; the other three fields (`entitiesCatalog`, `locationAnalyzer`, `locationService`) that see very little use have been removed + +- The function `createRouter` is removed; use `CatalogBuilder` as follows instead: + + ```ts + const builder = await CatalogBuilder.create(env); + // add things as needed, e.g builder.addProcessor(new ScaffolderEntitiesProcessor()); + const { processingEngine, router } = await builder.build(); + await processingEngine.start(); + return router; + ``` + +- The following types were removed: + + - `CatalogProcessingOrchestrator` + - `CatalogRule` + - `CatalogRulesEnforcer` + - `EntityAncestryResponse` + - `EntityFacetsRequest` + - `EntityFacetsResponse` + - `EntityPagination` + - `EntityProcessingRequest` + - `EntityProcessingResult` + - `EntitiesCatalog` + - `EntitiesRequest` + - `EntitiesResponse` + - `LocationService` + - `LocationInput` + - `LocationStore` + - `PageInfo` + - `RefreshOptions` + - `RefreshService` + - `RouterOptions` + +- The following classes were removed: + + - `DefaultCatalogProcessingOrchestrator` + - `DefaultCatalogRulesEnforcer` diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 7737cdc7cf..ad80e36232 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -255,22 +255,6 @@ export type CatalogProcessorResult = | CatalogProcessorRelationResult | CatalogProcessorErrorResult; -// @public -export type CatalogRule = { - allow: Array<{ - kind: string; - }>; - locations?: Array<{ - target?: string; - type: string; - }>; -}; - -// @public -export type CatalogRulesEnforcer = { - isAllowed(entity: Entity, location: LocationSpec): boolean; -}; - // @public (undocumented) export class CodeOwnersProcessor implements CatalogProcessor { constructor(options: { @@ -374,85 +358,18 @@ export type DefaultCatalogCollatorFactoryOptions = { catalogClient?: CatalogApi; }; -// @public -export class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer { - constructor(rules: CatalogRule[]); - static readonly defaultRules: CatalogRule[]; - static fromConfig(config: Config): DefaultCatalogRulesEnforcer; - isAllowed(entity: Entity, location: LocationSpec): boolean; -} - // @public export type DeferredEntity = { entity: Entity; locationKey?: string; }; -// @public (undocumented) -export type EntitiesCatalog = { - entities(request?: EntitiesRequest): Promise; - removeEntityByUid( - uid: string, - options?: { - authorizationToken?: string; - }, - ): Promise; - entityAncestry( - entityRef: string, - options?: { - authorizationToken?: string; - }, - ): Promise; - facets(request: EntityFacetsRequest): Promise; -}; - -// @public (undocumented) -export type EntitiesRequest = { - filter?: EntityFilter; - fields?: (entity: Entity) => Entity; - pagination?: EntityPagination; - authorizationToken?: string; -}; - -// @public (undocumented) -export type EntitiesResponse = { - entities: Entity[]; - pageInfo: PageInfo; -}; - // @public export type EntitiesSearchFilter = { key: string; values?: string[]; }; -// @public (undocumented) -export type EntityAncestryResponse = { - rootEntityRef: string; - items: Array<{ - entity: Entity; - parentEntityRefs: string[]; - }>; -}; - -// @public -export interface EntityFacetsRequest { - authorizationToken?: string; - facets: string[]; - filter?: EntityFilter; -} - -// @public -export interface EntityFacetsResponse { - facets: Record< - string, - Array<{ - value: string; - count: number; - }> - >; -} - // @public export type EntityFilter = | { @@ -466,13 +383,6 @@ export type EntityFilter = } | EntitiesSearchFilter; -// @public -export type EntityPagination = { - limit?: number; - offset?: number; - after?: string; -}; - // @public export interface EntityProvider { connect(connection: EntityProviderConnection): Promise; @@ -548,16 +458,6 @@ export type LocationSpec = { presence?: 'optional' | 'required'; }; -// @public (undocumented) -export type PageInfo = - | { - hasNextPage: false; - } - | { - hasNextPage: true; - endCursor: string; - }; - // @public (undocumented) export function parseEntityYaml( data: Buffer, diff --git a/plugins/catalog-backend/src/catalog/index.ts b/plugins/catalog-backend/src/catalog/index.ts index 59f67b2f52..ba34673bba 100644 --- a/plugins/catalog-backend/src/catalog/index.ts +++ b/plugins/catalog-backend/src/catalog/index.ts @@ -14,15 +14,4 @@ * limitations under the License. */ -export type { - EntitiesCatalog, - EntitiesRequest, - EntitiesResponse, - EntitiesSearchFilter, - EntityAncestryResponse, - EntityFacetsRequest, - EntityFacetsResponse, - EntityFilter, - EntityPagination, - PageInfo, -} from './types'; +export type { EntitiesSearchFilter, EntityFilter } from './types'; diff --git a/plugins/catalog-backend/src/catalog/types.ts b/plugins/catalog-backend/src/catalog/types.ts index b575b96c6c..34060814aa 100644 --- a/plugins/catalog-backend/src/catalog/types.ts +++ b/plugins/catalog-backend/src/catalog/types.ts @@ -31,7 +31,6 @@ export type EntityFilter = /** * A pagination rule for entities. - * @public */ export type EntityPagination = { limit?: number; @@ -60,7 +59,6 @@ export type EntitiesSearchFilter = { values?: string[]; }; -/** @public */ export type PageInfo = | { hasNextPage: false; @@ -70,7 +68,6 @@ export type PageInfo = endCursor: string; }; -/** @public */ export type EntitiesRequest = { filter?: EntityFilter; fields?: (entity: Entity) => Entity; @@ -78,13 +75,11 @@ export type EntitiesRequest = { authorizationToken?: string; }; -/** @public */ export type EntitiesResponse = { entities: Entity[]; pageInfo: PageInfo; }; -/** @public */ export type EntityAncestryResponse = { rootEntityRef: string; items: Array<{ @@ -95,8 +90,6 @@ export type EntityAncestryResponse = { /** * The request shape for {@link EntitiesCatalog.facets}. - * - * @public */ export interface EntityFacetsRequest { /** @@ -121,8 +114,6 @@ export interface EntityFacetsRequest { /** * The response shape for {@link EntitiesCatalog.facets}. - * - * @public */ export interface EntityFacetsResponse { /** @@ -131,8 +122,7 @@ export interface EntityFacetsResponse { facets: Record>; } -/** @public */ -export type EntitiesCatalog = { +export interface EntitiesCatalog { /** * Fetch entities. * @@ -167,4 +157,4 @@ export type EntitiesCatalog = { * @param request - Request options */ facets(request: EntityFacetsRequest): Promise; -}; +} diff --git a/plugins/catalog-backend/src/ingestion/CatalogRules.ts b/plugins/catalog-backend/src/ingestion/CatalogRules.ts index 376ea128b7..587a0bd7d5 100644 --- a/plugins/catalog-backend/src/ingestion/CatalogRules.ts +++ b/plugins/catalog-backend/src/ingestion/CatalogRules.ts @@ -23,8 +23,6 @@ import { LocationSpec } from '../api'; * Rules to apply to catalog entities. * * An undefined list of matchers means match all, an empty list of matchers means match none. - * - * @public */ export type CatalogRule = { allow: Array<{ @@ -39,8 +37,6 @@ export type CatalogRule = { /** * Decides whether an entity from a given location is allowed to enter the * catalog, according to some rule set. - * - * @public */ export type CatalogRulesEnforcer = { isAllowed(entity: Entity, location: LocationSpec): boolean; @@ -49,8 +45,6 @@ export type CatalogRulesEnforcer = { /** * Implements the default catalog rule set, consuming the config keys * `catalog.rules` and `catalog.locations.[].rules`. - * - * @public */ export class DefaultCatalogRulesEnforcer implements CatalogRulesEnforcer { /** diff --git a/plugins/catalog-backend/src/ingestion/index.ts b/plugins/catalog-backend/src/ingestion/index.ts index 1f4729b041..c97d029b5c 100644 --- a/plugins/catalog-backend/src/ingestion/index.ts +++ b/plugins/catalog-backend/src/ingestion/index.ts @@ -14,8 +14,6 @@ * limitations under the License. */ -export { DefaultCatalogRulesEnforcer } from './CatalogRules'; -export type { CatalogRule, CatalogRulesEnforcer } from './CatalogRules'; export type { AnalyzeLocationEntityField, AnalyzeLocationExistingEntity, diff --git a/plugins/catalog-backend/src/service/createRouter.test.ts b/plugins/catalog-backend/src/service/createRouter.test.ts index 8db15cb4a1..1602d07d28 100644 --- a/plugins/catalog-backend/src/service/createRouter.test.ts +++ b/plugins/catalog-backend/src/service/createRouter.test.ts @@ -21,7 +21,7 @@ import type { Location } from '@backstage/catalog-client'; import type { Entity } from '@backstage/catalog-model'; import express from 'express'; import request from 'supertest'; -import { EntitiesCatalog } from '../catalog'; +import { EntitiesCatalog } from '../catalog/types'; import { LocationInput, LocationService, RefreshService } from './types'; import { basicEntityFilter } from './request'; import { createRouter } from './createRouter'; diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts index df289d579b..a35309035f 100644 --- a/plugins/catalog-backend/src/service/createRouter.ts +++ b/plugins/catalog-backend/src/service/createRouter.ts @@ -22,7 +22,7 @@ import express from 'express'; import Router from 'express-promise-router'; import { Logger } from 'winston'; import yn from 'yn'; -import { EntitiesCatalog } from '../catalog'; +import { EntitiesCatalog } from '../catalog/types'; import { LocationAnalyzer } from '../ingestion/types'; import { basicEntityFilter, diff --git a/plugins/catalog-backend/src/service/request/parseEntityPaginationParams.ts b/plugins/catalog-backend/src/service/request/parseEntityPaginationParams.ts index c91c0b0214..87b19e13de 100644 --- a/plugins/catalog-backend/src/service/request/parseEntityPaginationParams.ts +++ b/plugins/catalog-backend/src/service/request/parseEntityPaginationParams.ts @@ -15,7 +15,7 @@ */ import { InputError } from '@backstage/errors'; -import { EntityPagination } from '../../catalog'; +import { EntityPagination } from '../../catalog/types'; import { parseIntegerParam, parseStringParam } from './common'; /** From 58a98843aca7d3a1340fabf70b71a0217198dbfa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Tue, 15 Mar 2022 11:49:59 +0100 Subject: [PATCH 3/3] review fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/fluffy-cameras-shop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/fluffy-cameras-shop.md b/.changeset/fluffy-cameras-shop.md index aee6fa6ebb..a84e99c24e 100644 --- a/.changeset/fluffy-cameras-shop.md +++ b/.changeset/fluffy-cameras-shop.md @@ -4,7 +4,7 @@ **BREAKING**: A number of types and classes have been removed, without a prior deprecation period. These were all very internal, essentially unused by the vast majority of users, and their being exposed was leading to excessive breaking of public interfaces for little-to-zero benefit. So for the 1.0 release of the catalog, the following interface changes have been made (but should have no effect on most users): -- The return type of `CatalogBuilder.build()` now only has the fields `processingEngine` and `router` which is what most users actually consume; the other three fields (`entitiesCatalog`, `locationAnalyzer`, `locationService`) that see very little use have been removed +- The return type of `CatalogBuilder.build()` now only has the fields `processingEngine` and `router` which is what most users actually consume; the other three fields (`entitiesCatalog`, `locationAnalyzer`, `locationService`) that see very little use have been removed. If you were relying on the presence of either of these in any way, please [open an issue](https://github.com/backstage/backstage/issues/new/choose) that describes your use case, and we'll see how we could fill the gap. - The function `createRouter` is removed; use `CatalogBuilder` as follows instead: