From 1572d02b63ea458f1bbed4b588368b02512d02f5 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 21 Sep 2021 13:24:17 +0200 Subject: [PATCH] catalog-backend: add changeset for caching + update API report Signed-off-by: Patrik Oldsberg --- .changeset/seven-bulldogs-grin.md | 11 +++++++++ plugins/catalog-backend/api-report.md | 33 ++++++++++++--------------- 2 files changed, 26 insertions(+), 18 deletions(-) create mode 100644 .changeset/seven-bulldogs-grin.md diff --git a/.changeset/seven-bulldogs-grin.md b/.changeset/seven-bulldogs-grin.md new file mode 100644 index 0000000000..2d6f0c14c1 --- /dev/null +++ b/.changeset/seven-bulldogs-grin.md @@ -0,0 +1,11 @@ +--- +'@backstage/plugin-catalog-backend': minor +--- + +Introduced a new `CatalogProcessorCache` that is available to catalog processors. It allows arbitrary values to be saved that will then be visible during the next run. The cache is scoped to each individual processor and entity, but is shared across processing steps in a single processor. + +The cache is available as a new argument to each of the processing steps, except for `validateEntityKind` and `handleError`. + +This also introduces an optional `getProcessorName` to the `CatalogProcessor` interface, which is used to provide a stable identifier for the processor. While it is currently optional it will move to be required in the future. + +The breaking part of this change is the modification of the `state` field in the `EntityProcessingRequest` and `EntityProcessingResult` types. This is unlikely to have any impact as the `state` field was previously unused, but could require some minor updates. diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 2422221d6d..10f149f850 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -17,7 +17,6 @@ import { EntityPolicy } from '@backstage/catalog-model'; import { EntityRelationSpec } from '@backstage/catalog-model'; import express from 'express'; import { IndexableDocument } from '@backstage/search-common'; -import { JsonObject } from '@backstage/config'; import { JsonValue } from '@backstage/config'; import { Knex } from 'knex'; import { Location as Location_2 } from '@backstage/catalog-model'; @@ -302,23 +301,27 @@ export interface CatalogProcessingOrchestrator { // // @public (undocumented) export type CatalogProcessor = { + getProcessorName?(): string; readLocation?( location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, + cache: CatalogProcessorCache, ): Promise; preProcessEntity?( entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, originLocation: LocationSpec, + cache: CatalogProcessorCache, ): Promise; validateEntityKind?(entity: Entity): Promise; postProcessEntity?( entity: Entity, location: LocationSpec, emit: CatalogProcessorEmit, + cache: CatalogProcessorCache, ): Promise; handleError?( error: Error, @@ -327,6 +330,12 @@ export type CatalogProcessor = { ): Promise; }; +// @public +export interface CatalogProcessorCache { + get(key: string): Promise; + set(key: string, value: ItemType): Promise; +} + // Warning: (ae-missing-release-tag) "CatalogProcessorEmit" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) @@ -868,7 +877,7 @@ export type EntityPagination = { // @public (undocumented) export type EntityProcessingRequest = { entity: Entity; - state: Map; + state?: JsonValue; }; // Warning: (ae-missing-release-tag) "EntityProcessingResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -877,7 +886,7 @@ export type EntityProcessingRequest = { export type EntityProcessingResult = | { ok: true; - state: Map; + state: JsonValue; completedEntity: Entity; deferredEntities: DeferredEntity[]; relations: EntityRelationSpec[]; @@ -1478,11 +1487,14 @@ export class UrlReaderProcessor implements CatalogProcessor { // Warning: (ae-forgotten-export) The symbol "Options" needs to be exported by the entry point index.d.ts constructor(options: Options_3); // (undocumented) + getProcessorName(): string; + // (undocumented) readLocation( location: LocationSpec, optional: boolean, emit: CatalogProcessorEmit, parser: CatalogProcessorParser, + cache: CatalogProcessorCache, ): Promise; } @@ -1505,21 +1517,6 @@ export class UrlReaderProcessor implements CatalogProcessor { // src/database/types.d.ts:164:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/database/types.d.ts:165:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/ingestion/processors/GithubMultiOrgReaderProcessor.d.ts:23:9 - (ae-forgotten-export) The symbol "GithubMultiOrgConfig" needs to be exported by the entry point index.d.ts -// src/ingestion/processors/types.d.ts:7:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:8:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:9:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:10:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:23:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:24:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:25:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:26:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:36:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:47:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:48:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:49:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:56:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:57:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/ingestion/processors/types.d.ts:58:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/ingestion/types.d.ts:17:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // src/ingestion/types.d.ts:41:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen ```