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

Address various code review comments.

Browse Source 
Signed-off-by: Jussi Hallila <jussi@hallila.com>
This commit is contained in:
Jussi Hallila
2021-10-25 17:04:33 +02:00
parent a1afbe0498
commit df000b9596
31 changed files with 529 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/tech-insights-common/CHANGELOG.md
-7
View File
@@ -1,7 +0,0 @@
# @backstage/plugin-tech-insights-backend
## 0.0.1
### Patch Changes
- Initial implementation
plugins/tech-insights-common/api-report.md
+32 -23
View File
@@ -17,7 +17,7 @@ export interface BooleanCheckResult extends CheckResult {
// @public
export interface CheckResponse {
description: string;
factRefs: string[];
factIds: string[];
id: string;
metadata?: Record<string, any>;
name: string;
@@ -68,22 +68,23 @@ export interface FactCheckerFactory<
// @public
export type FactResponse = {
[key: string]: {
ref: string;
[id: string]: {
id: string;
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
description: string;
value: number | string | boolean | DateTime | [];
since?: string;
metadata?: Record<string, any>;
entityKinds: string[];
};
};
// @public
export interface FactRetriever {
entityTypes?: string[];
handler: (ctx: FactRetrieverContext) => Promise<TechInsightFact[]>;
ref: string;
id: string;
schema: FactSchema;
version: string;
}
// @public
@@ -101,30 +102,28 @@ export type FactRetrieverRegistration = {
// @public
export type FactSchema = {
version: string;
schema: FactValueDefinitions;
};
// @public
export type FactValueDefinitions = {
[key: string]: {
[name: string]: {
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
description: string;
since?: string;
metadata?: Record<string, any>;
entityKinds: string[];
};
};
// 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 & {
ref: string;
id: string;
};
// @public
export interface TechInsightCheck {
description: string;
factRefs: string[];
factIds: string[];
failureMetadata?: Record<string, any>;
id: string;
name: string;
@@ -151,14 +150,24 @@ export type TechInsightFact = {
kind: string;
name: string;
};
facts: Record<string, number | string | boolean | DateTime | []>;
facts: Record<
string,
| number
| string
| boolean
| DateTime
| number[]
| string[]
| boolean[]
| DateTime[]
>;
timestamp?: DateTime;
};
// @public
export interface TechInsightsStore {
getFactsBetweenTimestampsForRefs(
refs: string[],
getFactsBetweenTimestampsByIds(
ids: string[],
entity: string,
startDateTime: DateTime,
endDateTime: DateTime,
@@ -166,15 +175,15 @@ export interface TechInsightsStore {
[factRef: string]: FlatTechInsightFact[];
}>;
// (undocumented)
getLatestFactsForRefs(
refs: string[],
getLatestFactsByIds(
ids: string[],
entity: string,
): Promise<{
[factRef: string]: FlatTechInsightFact;
}>;
getLatestSchemas(refs?: string[]): Promise<FactSchema[]>;
insertFacts(ref: string, facts: TechInsightFact[]): Promise<void>;
insertFactSchema(ref: string, schema: FactSchema): Promise<void>;
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/src/checks.ts
+1 -1
View File
@@ -157,7 +157,7 @@ export interface TechInsightCheck {
*
* References the fact container, aka fact retriever itself which may or may not contain multiple individual facts and values
*/
factRefs: string[];
factIds: string[];
/**
* Metadata to be returned in case a check has been successfully evaluated
plugins/tech-insights-common/src/facts.ts
+38 -26
View File
@@ -42,7 +42,17 @@ export type TechInsightFact = {
*
* Key indicates fact name as it is defined in FactSchema
*/
facts: Record<string, number | string | boolean | DateTime | []>;
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.
@@ -62,7 +72,7 @@ export type FlatTechInsightFact = TechInsightFact & {
/**
* Reference and unique identifier of the fact row
*/
ref: string;
id: string;
};
/**
@@ -73,8 +83,11 @@ export type FlatTechInsightFact = TechInsightFact & {
* Used as part of a schema to validate, identify and generically construct usage implementations
* of individual fact values in the system.
*/
export type FactValueDefinitions = {
[key: string]: {
export type FactSchema = {
/**
* Name of the fact
*/
[name: string]: {
/**
* Type of the individual fact value
*
@@ -109,30 +122,9 @@ export type FactValueDefinitions = {
* ```
*/
metadata?: Record<string, any>;
/**
* A list of entity kind descriptors to indicate if this fact is valid for an entity kind
*/
entityKinds: string[];
};
};
/**
* @public
*
* Container for FactSchema
*/
export type FactSchema = {
/**
* Semver string indicating the version of this schema
*/
version: string;
/**
* Actual schema definitions for this schema
*/
schema: FactValueDefinitions;
};
/**
* @public
*
@@ -159,7 +151,15 @@ export interface FactRetriever {
* Used to identify and store individual facts returned from this retriever
* and schemas defined by this retriever.
*/
ref: string;
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.
@@ -173,8 +173,20 @@ export interface FactRetriever {
* 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
*
plugins/tech-insights-common/src/persistence.ts
+18 -14
View File
@@ -13,7 +13,12 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { FactSchema, TechInsightFact, FlatTechInsightFact } from './facts';
import {
FactSchema,
TechInsightFact,
FlatTechInsightFact,
FactSchemaDefinition,
} from './facts';
import { DateTime } from 'luxon';
/**
@@ -28,34 +33,34 @@ export interface TechInsightsStore {
*
* Each row may contain multiple individual facts and values
*
* @param ref - Unique identifier of the fact retriever these facts relate to
* @param id - Unique identifier of the fact retriever these facts relate to
* @param facts - A collection of TechInsightFacts
*/
insertFacts(ref: string, facts: TechInsightFact[]): Promise<void>;
insertFacts(id: string, facts: TechInsightFact[]): Promise<void>;
/**
* @param refs - A collection of reference string to a fact row
* @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
*/
getLatestFactsForRefs(
refs: string[],
getLatestFactsByIds(
ids: string[],
entity: string,
): Promise<{ [factRef: string]: FlatTechInsightFact }>;
/**
* Retrieves fact values identified by fact row references for an individual entity.
*
* @param refs - A collection of reference string to a fact row
* @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
*/
getFactsBetweenTimestampsForRefs(
refs: string[],
getFactsBetweenTimestampsByIds(
ids: string[],
entity: string,
startDateTime: DateTime,
endDateTime: DateTime,
@@ -64,16 +69,15 @@ export interface TechInsightsStore {
/**
* Stores versioned fact schemas into data store
*
* @param ref - Identifier of the fact schema. Reference to a fact retriever.
* @param schema - The actual schema to store
* @param schemaDefinition - FactSchemaDefinition containing id, version, schema and entityTypes.
*/
insertFactSchema(ref: string, schema: FactSchema): Promise<void>;
insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise<void>;
/**
* Retrieves latest versions (as defined by semver) of fact schemas from the data store.
*
* @param refs - Collection of refs to return. If omitted, all Schemas should be returned.
* @param ids - Collection of ids to return. If omitted, all Schemas should be returned.
* @returns - A collection of schemas
*/
getLatestSchemas(refs?: string[]): Promise<FactSchema[]>;
getLatestSchemas(ids?: string[]): Promise<FactSchema[]>;
}
plugins/tech-insights-common/src/responses.ts
+3 -8
View File
@@ -44,7 +44,7 @@ export interface CheckResponse {
/**
* A collection of references to fact rows used to run this checks against
*/
factRefs: string[];
factIds: string[];
/**
* Metadata related to a check.
@@ -62,11 +62,11 @@ export interface CheckResponse {
* Keyed by the name of the fact
*/
export type FactResponse = {
[key: string]: {
[id: string]: {
/**
* Reference and unique identifier of the fact row
*/
ref: string;
id: string;
/**
* Type of the individual fact value
*
@@ -97,10 +97,5 @@ export type FactResponse = {
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
*/
metadata?: Record<string, any>;
/**
* A list of entity kind descriptors to indicate if this fact is valid for an entity kind
*/
entityKinds: string[];
};
};