paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 49 Packages Projects Releases Wiki Activity

Modifications after PR review

Browse Source 
* Change entity filter to be an actual entity filter instead of a list of kinds or types
* Modify/simplify types a little bit
* Split common type libs to one for node and one isomorphic
* Remove unnecessary items from FactChecker interface to simplify execution loop.

Needs still matching README.md changes.

Signed-off-by: Jussi Hallila <jussi@hallila.com>
This commit is contained in:
Jussi Hallila
2021-10-28 16:20:44 +02:00
parent df000b9596
commit 2b3e959ef4
37 changed files with 393 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/tech-insights-common/README.md
+1 -1
View File
@@ -1,3 +1,3 @@
# Tech Insights Common
Common types and functionalities for tech insights, to be shared between tech-insights-backend and individual implementations of FactRetrievers, FactCheckers and their persistence options.
Common types and functionalities for tech insights shared in an isomorphic manner between BE and FE implementations.
plugins/tech-insights-common/api-report.md
-147
View File
@@ -3,10 +3,7 @@
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
import { Config } from '@backstage/config';
import { DateTime } from 'luxon';
import { Logger as Logger_2 } from 'winston';
import { PluginEndpointDiscovery } from '@backstage/backend-common';
// @public
export interface BooleanCheckResult extends CheckResult {
@@ -30,42 +27,6 @@ export type CheckResult = {
check: CheckResponse;
};
// @public
export class CheckValidationError extends Error {
constructor({ message, errors }: { message: string; errors?: any });
// (undocumented)
errors?: any;
}
// @public
export type CheckValidationResponse = {
valid: boolean;
message?: string;
errors?: any;
};
// @public
export interface FactChecker<
CheckType extends TechInsightCheck,
CheckResultType extends CheckResult,
> {
addCheck(check: CheckType): Promise<CheckType>;
getChecks(): Promise<CheckType[]>;
runChecks(entity: string, checks: string[]): Promise<CheckResultType[]>;
validate(check: CheckType): Promise<CheckValidationResponse>;
}
// @public
export interface FactCheckerFactory<
CheckType extends TechInsightCheck,
CheckResultType extends CheckResult,
> {
// (undocumented)
construct(
repository: TechInsightsStore,
): FactChecker<CheckType, CheckResultType>;
}
// @public
export type FactResponse = {
[id: string]: {
@@ -78,113 +39,5 @@ export type FactResponse = {
};
};
// @public
export interface FactRetriever {
entityTypes?: string[];
handler: (ctx: FactRetrieverContext) => Promise<TechInsightFact[]>;
id: string;
schema: FactSchema;
version: string;
}
// @public
export type FactRetrieverContext = {
config: Config;
discovery: PluginEndpointDiscovery;
logger: Logger_2;
};
// @public
export type FactRetrieverRegistration = {
factRetriever: FactRetriever;
cadence?: string;
};
// @public
export type FactSchema = {
[name: string]: {
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
description: string;
since?: string;
metadata?: Record<string, any>;
};
};
// Warning: (ae-missing-release-tag) "FactSchemaDefinition" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type FactSchemaDefinition = Omit<FactRetriever, 'handler'>;
// @public
export type FlatTechInsightFact = TechInsightFact & {
id: string;
};
// @public
export interface TechInsightCheck {
description: string;
factIds: string[];
failureMetadata?: Record<string, any>;
id: string;
name: string;
successMetadata?: Record<string, any>;
type: string;
}
// @public
export interface TechInsightCheckRegistry<CheckType extends TechInsightCheck> {
// (undocumented)
get(checkId: string): Promise<CheckType>;
// (undocumented)
getAll(checks: string[]): Promise<CheckType[]>;
// (undocumented)
list(): Promise<CheckType[]>;
// (undocumented)
register(check: CheckType): Promise<CheckType>;
}
// @public
export type TechInsightFact = {
entity: {
namespace: string;
kind: string;
name: string;
};
facts: Record<
string,
| number
| string
| boolean
| DateTime
| number[]
| string[]
| boolean[]
| DateTime[]
>;
timestamp?: DateTime;
};
// @public
export interface TechInsightsStore {
getFactsBetweenTimestampsByIds(
ids: string[],
entity: string,
startDateTime: DateTime,
endDateTime: DateTime,
): Promise<{
[factRef: string]: FlatTechInsightFact[];
}>;
// (undocumented)
getLatestFactsByIds(
ids: string[],
entity: string,
): Promise<{
[factRef: string]: FlatTechInsightFact;
}>;
getLatestSchemas(ids?: string[]): Promise<FactSchema[]>;
insertFacts(id: string, facts: TechInsightFact[]): Promise<void>;
insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise<void>;
}
// (No @packageDocumentation comment for this package)
```
plugins/tech-insights-common/package.json
+1 -4
View File
@@ -30,11 +30,8 @@
"clean": "backstage-cli clean"
},
"dependencies": {
"@backstage/backend-common": "^0.9.0",
"@backstage/config": "^0.1.8",
"@types/luxon": "^2.0.5",
"luxon": "^2.0.2",
"winston": "^3.2.1"
"luxon": "^2.0.2"
},
"devDependencies": {
"@backstage/cli": "^0.7.1"
plugins/tech-insights-common/src/checks.ts
-201
View File
@@ -1,201 +0,0 @@
/*
* Copyright 2021 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 { TechInsightsStore } from './persistence';
import { CheckResponse, FactResponse } from './responses';
/**
* A factory wrapper to construct FactChecker implementations.
*
* @public
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
* @typeParam CheckResultType - Implementation specific result of a check. Can extend CheckResult with additional information
*/
export interface FactCheckerFactory<
CheckType extends TechInsightCheck,
CheckResultType extends CheckResult,
> {
/**
* @param repository - TechInsightsStore
* @returns an implementation of a FactChecker for generic types defined in the factory
*/
construct(
repository: TechInsightsStore,
): FactChecker<CheckType, CheckResultType>;
}
/**
* FactChecker interface
*
* A generic interface that can be implemented to create checkers for specific check and check return types.
* This is used especially when creating Scorecards and displaying results of rules when run against facts.
*
* @public
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
* @typeParam CheckResultType - Implementation specific result of a check. Can extend CheckResult with additional information
*/
export interface FactChecker<
CheckType extends TechInsightCheck,
CheckResultType extends CheckResult,
> {
/**
* Runs checks against an entity.
*
* @param entity - A reference to an entity to run checks against. In a format namespace/kind/name
* @param checks - A collection of checks to run against provided entity
* @returns - A collection containing check/fact information and the actual results of the check
*/
runChecks(entity: string, checks: string[]): Promise<CheckResultType[]>;
/**
* Adds and stores new checks so they can be run checks against.
* Implementation should ideally run validation against the check.
*
* @param check - The actual check to be added.
* @returns - An indicator if fact was successfully added
*/
addCheck(check: CheckType): Promise<CheckType>;
/**
* Retrieves all available checks that can be used to run checks against.
* The implementation can be just a piping through to CheckRegistry implementation if such is in use.
*
* @returns - A collection of checks
*/
getChecks(): Promise<CheckType[]>;
/**
* Validates if check is valid and can be run with the current implementation
*
* @param check - The check to be validated
* @returns - Validation result
*/
validate(check: CheckType): Promise<CheckValidationResponse>;
}
/**
* Registry containing checks for tech insights.
*
* @public
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
*
*/
export interface TechInsightCheckRegistry<CheckType extends TechInsightCheck> {
register(check: CheckType): Promise<CheckType>;
get(checkId: string): Promise<CheckType>;
getAll(checks: string[]): Promise<CheckType[]>;
list(): Promise<CheckType[]>;
}
/**
* Generic CheckResult
*
* Contains information about the facts used to calculate the check result
* and information about the check itself. Both may include metadata to be able to display additional information.
* A collection of these should be parseable by the frontend to display scorecards
*
* @public
*/
export type CheckResult = {
facts: FactResponse;
check: CheckResponse;
};
/**
* CheckResult of type Boolean.
*
* @public
*/
export interface BooleanCheckResult extends CheckResult {
result: boolean;
}
/**
* Generic definition of a check for Tech Insights
*
* @public
*/
export interface TechInsightCheck {
/**
* Unique identifier of the check
*
* Used to identify which checks to use when running checks.
*/
id: string;
/**
* Type identifier for the check.
* Can be used to determine storage options, logical routing to correct FactChecker implementation
* or to help frontend render correct component types based on this
*/
type: string;
/**
* Human readable name of the check, may be displayed in the UI
*/
name: string;
/**
* Human readable description of the check, may be displayed in the UI
*/
description: string;
/**
* A collection of string referencing fact rows that a check will be run against.
*
* References the fact container, aka fact retriever itself which may or may not contain multiple individual facts and values
*/
factIds: string[];
/**
* Metadata to be returned in case a check has been successfully evaluated
* Can contain links, description texts or other actionable items
*/
successMetadata?: Record<string, any>;
/**
* Metadata to be returned in case a check evaluation has ended in failure
* Can contain links, description texts or other actionable items
*/
failureMetadata?: Record<string, any>;
}
/**
* Validation response from CheckValidator
*
* May contain additional data for display purposes
* @public
*/
export type CheckValidationResponse = {
valid: boolean;
message?: string;
errors?: any;
};
/**
* Error object for Validation Errors
*
* Can be used to short circuit larger execution paths instead of passing validation response around
*
* @public
*/
export class CheckValidationError extends Error {
errors?: any;
constructor({ message, errors }: { message: string; errors?: any }) {
super(message);
this.errors = errors;
}
}
plugins/tech-insights-common/src/facts.ts
-208
View File
@@ -1,208 +0,0 @@
/*
* Copyright 2021 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 { DateTime } from 'luxon';
import { Config } from '@backstage/config';
import { PluginEndpointDiscovery } from '@backstage/backend-common';
import { Logger } from 'winston';
/**
* A container for facts. The shape of the fact records needs to correspond to the FactSchema with same `ref` value.
* Each container contains a reference to an entity which can be a Backstage entity or a generic construct
* outside of backstage with same shape.
*
* Container may contain multiple individual facts and their values
*
* @public
*/
export type TechInsightFact = {
/**
* Entity reference that this fact relates to
*/
entity: {
namespace: string;
kind: string;
name: string;
};
/**
* A collection of fact values as key value pairs.
*
* Key indicates fact name as it is defined in FactSchema
*/
facts: Record<
string,
| number
| string
| boolean
| DateTime
| number[]
| string[]
| boolean[]
| DateTime[]
>;
/**
* Optional timestamp value which can be used to override retrieval time of the fact row.
* Otherwise when stored into data storage, defaults to current time
*/
timestamp?: DateTime;
};
/**
* Response type used when returning from database and API.
* Adds a field for ref for easier usage
*
* @public
*/
export type FlatTechInsightFact = TechInsightFact & {
/**
* Reference and unique identifier of the fact row
*/
id: string;
};
/**
* @public
*
* A record type to specify individual fact shapes
*
* Used as part of a schema to validate, identify and generically construct usage implementations
* of individual fact values in the system.
*/
export type FactSchema = {
/**
* Name of the fact
*/
[name: string]: {
/**
* Type of the individual fact value
*
* Numbers are split into integers and floating point values.
* `set` indicates a collection of values
*/
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
/**
* A description of this individual fact value
*/
description: string;
/**
* Optional semver string to indicate when this specific fact definition was added to the schema
*/
since?: string;
/**
* Metadata related to an individual fact.
* Can contain links, additional description texts and other actionable data.
*
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*
* examples:
* ```
* \{
* link: 'https://sonarqube.mycompany.com/fix-these-issues',
* suggestion: 'To affect this value, you can do x, y, z',
* minValue: 0
* \}
* ```
*/
metadata?: Record<string, any>;
};
};
/**
* @public
*
* FactRetrieverContext injected into individual handler methods of FactRetriever implementations.
* The context can be used to construct logic to retrieve entities, contact integration points
* and fetch and calculate fact values from external sources.
*/
export type FactRetrieverContext = {
config: Config;
discovery: PluginEndpointDiscovery;
logger: Logger;
};
/**
* @public
*
* FactRetriever interface
*
* A component specifying
*/
export interface FactRetriever {
/**
* A unique identifier of the retriever.
* Used to identify and store individual facts returned from this retriever
* and schemas defined by this retriever.
*/
id: string;
/**
* Semver string indicating the version of this fact retriever
* This version is used to determine if the schema this fact retriever matches the data this fact retriever provides.
*
* Should be incremented on changes to returned data from the handler or if the schema changes.
*/
version: string;
/**
* Handler function that needs to be implemented to retrieve fact values for entities.
*
* @param ctx - FactRetrieverContext which can be used to retrieve config and contact integrations
* @returns - A collection of TechInsightFacts grouped by entities.
*/
handler: (ctx: FactRetrieverContext) => Promise<TechInsightFact[]>;
/**
* A fact schema defining the shape of data returned from the handler method for each entity
*/
schema: FactSchema;
/**
* An optional list of entity type descriptors to indicate if this fact retriever is valid for an entity type.
* If omitted, the retriever should apply to all entities.
*
* Should be defined as:
* ['component', 'group', 'user'] for top level items
* ['component:service', 'component:website'] for component types.
*/
entityTypes?: string[];
}
export type FactSchemaDefinition = Omit<FactRetriever, 'handler'>;
/**
* @public
*
* Registration of a fact retriever
* Used to add and schedule individual fact retrievers to the fact retriever engine.
*/
export type FactRetrieverRegistration = {
/**
* Actual FactRetriever implementation
*/
factRetriever: FactRetriever;
/**
* Cron expression to indicate when the retriever should be triggered.
* Defaults to a random point in time every 24h
*
*/
cadence?: string;
};
plugins/tech-insights-common/src/index.ts
+108 -4
View File
@@ -14,7 +14,111 @@
* limitations under the License.
*/
export * from './checks';
export * from './facts';
export * from './persistence';
export * from './responses';
import { DateTime } from 'luxon';
/**
* @public
*
* Response type for checks.
*/
export interface CheckResponse {
/**
* Identifier of the Check
*/
id: string;
/**
* Type identifier for the check.
* Can be used to determine storage options, logical routing to correct FactChecker implementation
* or to help frontend render correct component types based on this
*/
type: string;
/**
* Human readable name of the Check
*/
name: string;
/**
* Description of the Check
*/
description: string;
/**
* A collection of references to fact rows used to run this checks against
*/
factIds: string[];
/**
* Metadata related to a check.
* Can contain links, additional description texts and other actionable data.
*
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*/
metadata?: Record<string, any>;
}
/**
* @public
*
* Individual fact response type.
* Keyed by the name of the fact
*/
export type FactResponse = {
[id: string]: {
/**
* Reference and unique identifier of the fact row
*/
id: string;
/**
* Type of the individual fact value
*
* Numbers are split into integers and floating point values.
* `set` indicates a collection of values
*/
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
/**
* Description of the individual fact
*/
description: string;
/**
* Actual value of the fact
*/
value: number | string | boolean | DateTime | [];
/**
* An optional SemVer version identifying when this fact was added to the FactSchema
*/
since?: string;
/**
* Metadata related to an individual fact.
* Can contain links, additional description texts and other actionable data.
*
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*/
metadata?: Record<string, any>;
};
};
/**
* Generic CheckResult
*
* Contains information about the facts used to calculate the check result
* and information about the check itself. Both may include metadata to be able to display additional information.
* A collection of these should be parseable by the frontend to display scorecards
*
* @public
*/
export type CheckResult = {
facts: FactResponse;
check: CheckResponse;
};
/**
* CheckResult of type Boolean.
*
* @public
*/
export interface BooleanCheckResult extends CheckResult {
result: boolean;
}
plugins/tech-insights-common/src/persistence.ts
-83
View File
@@ -1,83 +0,0 @@
/*
* Copyright 2021 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 {
FactSchema,
TechInsightFact,
FlatTechInsightFact,
FactSchemaDefinition,
} from './facts';
import { DateTime } from 'luxon';
/**
* TechInsights Database
*
* @public
*/
export interface TechInsightsStore {
/**
* Stores fact containers as rows into data store.
* Individual items in array correspond to a fact schema based on reference and entity based on entity identifier.
*
* Each row may contain multiple individual facts and values
*
* @param id - Unique identifier of the fact retriever these facts relate to
* @param facts - A collection of TechInsightFacts
*/
insertFacts(id: string, facts: TechInsightFact[]): Promise<void>;
/**
* @param ids - A collection of fact row identifiers
* @param entity - A string identifying an entity. In a format namespace/kind/name
*
* @returns - An object keyed by a fact reference and containing an individual TechInsightFact
*/
getLatestFactsByIds(
ids: string[],
entity: string,
): Promise<{ [factRef: string]: FlatTechInsightFact }>;
/**
* Retrieves fact values identified by fact row references for an individual entity.
*
* @param ids - A collection of fact row identifiers
* @param entity - A string identifying an entity. In a format namespace/kind/name
* @param startDateTime - DateTime object indicating start of the time frame
* @param endDateTime - DateTime object indicating start of the time frame
*
* @returns - An object keyed by a fact reference and containing a collection of TechInsightFacts matching the time frame
*/
getFactsBetweenTimestampsByIds(
ids: string[],
entity: string,
startDateTime: DateTime,
endDateTime: DateTime,
): Promise<{ [factRef: string]: FlatTechInsightFact[] }>;
/**
* Stores versioned fact schemas into data store
*
* @param schemaDefinition - FactSchemaDefinition containing id, version, schema and entityTypes.
*/
insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise<void>;
/**
* Retrieves latest versions (as defined by semver) of fact schemas from the data store.
*
* @param ids - Collection of ids to return. If omitted, all Schemas should be returned.
* @returns - A collection of schemas
*/
getLatestSchemas(ids?: string[]): Promise<FactSchema[]>;
}
plugins/tech-insights-common/src/responses.ts
-101
View File
@@ -1,101 +0,0 @@
/*
* Copyright 2021 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 { DateTime } from 'luxon';
/**
* @public
*
* Response type for checks.
*/
export interface CheckResponse {
/**
* Identifier of the Check
*/
id: string;
/**
* Type identifier for the check.
* Can be used to determine storage options, logical routing to correct FactChecker implementation
* or to help frontend render correct component types based on this
*/
type: string;
/**
* Human readable name of the Check
*/
name: string;
/**
* Description of the Check
*/
description: string;
/**
* A collection of references to fact rows used to run this checks against
*/
factIds: string[];
/**
* Metadata related to a check.
* Can contain links, additional description texts and other actionable data.
*
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*/
metadata?: Record<string, any>;
}
/**
* @public
*
* Individual fact response type.
* Keyed by the name of the fact
*/
export type FactResponse = {
[id: string]: {
/**
* Reference and unique identifier of the fact row
*/
id: string;
/**
* Type of the individual fact value
*
* Numbers are split into integers and floating point values.
* `set` indicates a collection of values
*/
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
/**
* Description of the individual fact
*/
description: string;
/**
* Actual value of the fact
*/
value: number | string | boolean | DateTime | [];
/**
* An optional SemVer version identifying when this fact was added to the FactSchema
*/
since?: string;
/**
* Metadata related to an individual fact.
* Can contain links, additional description texts and other actionable data.
*
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*/
metadata?: Record<string, any>;
};
};
plugins/tech-insights-common/src/setupTests.ts
-17
View File
@@ -1,17 +0,0 @@
/*
* Copyright 2021 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 {};