From cd8bf7a4abb9a586e1d9eba70d5771458b96ffec Mon Sep 17 00:00:00 2001 From: Jussi Hallila Date: Thu, 13 Jan 2022 16:34:22 +0100 Subject: [PATCH] Add more breaking changes. Update API reports. Signed-off-by: Jussi Hallila --- .changeset/six-coins-admire.md | 13 ++++++++++- plugins/tech-insights-backend/api-report.md | 17 +++++++++----- plugins/tech-insights-backend/src/index.ts | 1 + .../src/service/fact/FactRetrieverEngine.ts | 6 ++++- .../src/service/fact/createFactRetriever.ts | 10 ++++++++- .../persistence/TechInsightsDatabase.test.ts | 12 +++++++--- .../persistence/TechInsightsDatabase.ts | 14 +++++++----- plugins/tech-insights-node/api-report.md | 22 +++++++++++-------- plugins/tech-insights-node/src/persistence.ts | 14 +++++++----- 9 files changed, 79 insertions(+), 30 deletions(-) diff --git a/.changeset/six-coins-admire.md b/.changeset/six-coins-admire.md index f2ef03fe01..658672d1c4 100644 --- a/.changeset/six-coins-admire.md +++ b/.changeset/six-coins-admire.md @@ -6,7 +6,7 @@ BREAKING CHANGES: - The helper function to create a fact retriever registration is now expecting an object of configuration items instead of individual arguments. - Modify your techInsights.ts plugin configuration in `packages/backend/src/plugins/techInsights.ts` (or equivalent) the following way: + Modify your `techInsights.ts` plugin configuration in `packages/backend/src/plugins/techInsights.ts` (or equivalent) the following way: ```diff -createFactRetrieverRegistration( @@ -20,6 +20,17 @@ BREAKING CHANGES: ``` +- `TechInsightsStore` interface has changed its signature of `insertFacts` method. If you have created your own implementation of either `TechInsightsDatabase` or `FactRetrieverEngine` you need to modify the implementation/call to this method to accept/pass-in an object instead if individual arguments. The interface now accepts an additional `lifecycle` argument which is optional (defined below). An example modification to fact retriever engine: + +```diff +-await this.repository.insertFacts(factRetriever.id, facts); ++await this.repository.insertFacts({ ++ id: factRetriever.id, ++ facts, ++ lifecycle, ++}); +``` + Adds a configuration option to fact retrievers to define lifecycle for facts the retriever persists. Possible values are either 'max items' or 'time-to-live'. The former will keep only n number of items in the database for each fact per entity. The latter will remove all facts that are older than the TTL value. Possible values: diff --git a/plugins/tech-insights-backend/api-report.md b/plugins/tech-insights-backend/api-report.md index c5cefd2619..1d19123a00 100644 --- a/plugins/tech-insights-backend/api-report.md +++ b/plugins/tech-insights-backend/api-report.md @@ -26,11 +26,11 @@ export const buildTechInsightsContext: < ) => Promise>; // @public -export function createFactRetrieverRegistration( - cadence: string, - factRetriever: FactRetriever, - lifecycle?: FactLifecycle, -): FactRetrieverRegistration; +export function createFactRetrieverRegistration({ + cadence, + factRetriever, + lifecycle, +}: FactRetrieverRegistrationOptions): FactRetrieverRegistration; // @public export function createRouter< @@ -44,6 +44,13 @@ export const entityMetadataFactRetriever: FactRetriever; // @public export const entityOwnershipFactRetriever: FactRetriever; +// @public (undocumented) +export type FactRetrieverRegistrationOptions = { + cadence: string; + factRetriever: FactRetriever; + lifecycle?: FactLifecycle; +}; + // @public export type PersistenceContext = { techInsightsStore: TechInsightsStore; diff --git a/plugins/tech-insights-backend/src/index.ts b/plugins/tech-insights-backend/src/index.ts index 763c565108..82fda47367 100644 --- a/plugins/tech-insights-backend/src/index.ts +++ b/plugins/tech-insights-backend/src/index.ts @@ -25,4 +25,5 @@ export type { export type { PersistenceContext } from './service/persistence/persistenceContext'; export { createFactRetrieverRegistration } from './service/fact/createFactRetriever'; +export type { FactRetrieverRegistrationOptions } from './service/fact/createFactRetriever'; export * from './service/fact/factRetrievers'; diff --git a/plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts b/plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts index 51a68635b1..0334599b96 100644 --- a/plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts +++ b/plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts @@ -125,7 +125,11 @@ export class FactRetrieverEngine { } try { - await this.repository.insertFacts(factRetriever.id, facts, lifecycle); + await this.repository.insertFacts({ + id: factRetriever.id, + facts, + lifecycle, + }); this.logger.info( `Stored ${facts.length} facts for fact retriever ${ factRetriever.id diff --git a/plugins/tech-insights-backend/src/service/fact/createFactRetriever.ts b/plugins/tech-insights-backend/src/service/fact/createFactRetriever.ts index eae579b49f..bd85b3c873 100644 --- a/plugins/tech-insights-backend/src/service/fact/createFactRetriever.ts +++ b/plugins/tech-insights-backend/src/service/fact/createFactRetriever.ts @@ -19,6 +19,14 @@ import { FactRetrieverRegistration, } from '@backstage/plugin-tech-insights-node'; +/** + * @public + * + * @param cadence - cron expression to indicate when the fact retriever should be triggered + * @param factRetriever - Implementation of fact retriever consisting of at least id, version, schema and handler + * @param lifecycle - Optional lifecycle definition indicating the cleanup logic of facts when this retriever is run + * + */ export type FactRetrieverRegistrationOptions = { cadence: string; factRetriever: FactRetriever; @@ -50,7 +58,7 @@ export type FactRetrieverRegistrationOptions = { * * Valid lifecycle values: * \{ ttl: \{ weeks: 2 \} \} -- This fact retriever will remove items that are older than 2 weeks when it is run - * \{ itl: 7 \} -- This fact retriever will leave 7 newest items in the database when it is run + * \{ maxItems: 7 \} -- This fact retriever will leave 7 newest items in the database when it is run * */ export function createFactRetrieverRegistration({ diff --git a/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.test.ts b/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.test.ts index 07c01eb5b0..bd330bd378 100644 --- a/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.test.ts +++ b/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.test.ts @@ -290,7 +290,11 @@ describe('Tech Insights database', () => { }, }; const maxItems = 2; - await store.insertFacts('test-fact', [factToBeInserted], { maxItems }); + await store.insertFacts({ + id: 'test-fact', + facts: [factToBeInserted], + lifecycle: { maxItems }, + }); const afterInsertionFacts = await testDbClient('facts').select(); expect(afterInsertionFacts).toHaveLength(maxItems); @@ -334,8 +338,10 @@ describe('Tech Insights database', () => { testNumberFact: 555, }, }; - await store.insertFacts('test-fact', [factToBeInserted], { - timeToLive: { weeks: 2 }, + await store.insertFacts({ + id: 'test-fact', + facts: [factToBeInserted], + lifecycle: { timeToLive: { weeks: 2 } }, }); const afterInsertionFacts = await testDbClient('facts') diff --git a/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.ts b/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.ts index 682b7967bb..be761ff555 100644 --- a/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.ts +++ b/plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.ts @@ -87,11 +87,15 @@ export class TechInsightsDatabase implements TechInsightsStore { } } - async insertFacts( - id: string, - facts: TechInsightFact[], - lifecycle?: FactLifecycle, - ): Promise { + async insertFacts({ + id, + facts, + lifecycle, + }: { + id: string; + facts: TechInsightFact[]; + lifecycle?: FactLifecycle; + }): Promise { if (facts.length === 0) return; const currentSchema = await this.getLatestSchema(id); const factRows = facts.map(it => { diff --git a/plugins/tech-insights-node/api-report.md b/plugins/tech-insights-node/api-report.md index ec822bf5e2..77a9d77871 100644 --- a/plugins/tech-insights-node/api-report.md +++ b/plugins/tech-insights-node/api-report.md @@ -39,7 +39,7 @@ export interface FactCheckerFactory< } // @public -export type FactLifecycle = TTL | ITL; +export type FactLifecycle = TTL | MaxItems; // @public export interface FactRetriever { @@ -88,8 +88,8 @@ export type FlatTechInsightFact = TechInsightFact & { }; // @public -export type ITL = { - itl: number; +export type MaxItems = { + maxItems: number; }; // @public @@ -154,17 +154,21 @@ export interface TechInsightsStore { [factRef: string]: FlatTechInsightFact; }>; getLatestSchemas(ids?: string[]): Promise; - insertFacts( - id: string, - facts: TechInsightFact[], - lifecycle?: FactLifecycle, - ): Promise; + insertFacts({ + id, + facts, + lifecycle, + }: { + id: string; + facts: TechInsightFact[]; + lifecycle?: FactLifecycle; + }): Promise; insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise; } // @public export type TTL = { - ttl: DurationLike; + timeToLive: DurationLike; }; // (No @packageDocumentation comment for this package) diff --git a/plugins/tech-insights-node/src/persistence.ts b/plugins/tech-insights-node/src/persistence.ts index 17a3867347..4324c24c42 100644 --- a/plugins/tech-insights-node/src/persistence.ts +++ b/plugins/tech-insights-node/src/persistence.ts @@ -38,11 +38,15 @@ export interface TechInsightsStore { * @param facts - A collection of TechInsightFacts * @param lifecycle - (Optional) Fact lifecycle object indicating the expiration logic for these items */ - insertFacts( - id: string, - facts: TechInsightFact[], - lifecycle?: FactLifecycle, - ): Promise; + insertFacts({ + id, + facts, + lifecycle, + }: { + id: string; + facts: TechInsightFact[]; + lifecycle?: FactLifecycle; + }): Promise; /** * @param ids - A collection of fact row identifiers