Modify tech insights backend to expose FactRetrieverEngine.

* Wrap FactRetrieverEngine to an interface for a slimmer export.
* Update API report to match expected.
* Fix router endpoint docs to match actual functionality.

Signed-off-by: Jussi Hallila <jussi@hallila.com>

.changeset/tiny-oranges-thank.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-tech-insights-backend': patch
+---
+
+Modify Tech insight initialization to expose FactRetrieverEngine. Enables users to trigger fact retrieval manually or reschedule retrievers on runtime.

plugins/tech-insights-backend/api-report.md

@@ -45,6 +45,13 @@ export const entityMetadataFactRetriever: FactRetriever;
 // @public
 export const entityOwnershipFactRetriever: FactRetriever;
 
+// @public
+export interface FactRetrieverEngine {
+  getJobRegistration(ref: string): Promise<FactRetrieverRegistration>;
+  schedule(): Promise<void>;
+  triggerJob(ref: string): Promise<void>;
+}
+
 // @public (undocumented)
 export type FactRetrieverRegistrationOptions = {
   cadence: string;
@@ -92,6 +99,7 @@ export type TechInsightsContext<
 > = {
   factChecker?: FactChecker<CheckType, CheckResultType>;
   persistenceContext: PersistenceContext;
+  factRetrieverEngine: FactRetrieverEngine;
 };
 
 // @public (undocumented)

plugins/tech-insights-backend/package.json

@@ -56,6 +56,7 @@
   "devDependencies": {
     "@backstage/backend-test-utils": "^0.1.26-next.3",
     "@backstage/cli": "^0.18.0-next.3",
+    "@types/luxon": "^2.0.5",
     "@types/supertest": "^2.0.8",
     "@types/semver": "^7.3.8",
     "supertest": "^6.1.3",

plugins/tech-insights-backend/src/index.ts

@@ -22,7 +22,7 @@ export type {
   TechInsightsOptions,
   TechInsightsContext,
 } from './service/techInsightsContextBuilder';
-
+export type { FactRetrieverEngine } from './service/fact/FactRetrieverEngine';
 export type { PersistenceContext } from './service/persistence/persistenceContext';
 export { createFactRetrieverRegistration } from './service/fact/createFactRetriever';
 export type { FactRetrieverRegistry } from './service/fact/FactRetrieverRegistry';

plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.test.ts

@@ -21,7 +21,10 @@ import {
   TechInsightsStore,
 } from '@backstage/plugin-tech-insights-node';
 import { FactRetrieverRegistry } from './FactRetrieverRegistry';
-import { FactRetrieverEngine } from './FactRetrieverEngine';
+import {
+  DefaultFactRetrieverEngine,
+  FactRetrieverEngine,
+} from './FactRetrieverEngine';
 import {
   DatabaseManager,
   getVoidLogger,
@@ -131,7 +134,7 @@ describe('FactRetrieverEngine', () => {
     };
     const manager = databaseManager as DatabaseManager;
     const scheduler = new TaskScheduler(manager, getVoidLogger());
-    return await FactRetrieverEngine.create({
+    return await DefaultFactRetrieverEngine.create({
       factRetrieverContext: {
         logger: getVoidLogger(),
         config: ConfigReader.fromConfigs([]),

plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts

@@ -38,7 +38,36 @@ function duration(startTimestamp: [number, number]): string {
   return `${seconds.toFixed(1)}s`;
 }
 
-export class FactRetrieverEngine {
+/**
+ * @public
+ *
+ * FactRetrieverEngine responsible scheduling and running fact retrieval tasks.
+ */
+export interface FactRetrieverEngine {
+  /**
+   * Schedules fact retriever run cycles based on configuration provided in the registration.
+   *
+   * Default implementation uses backend-tasks to handle scheduling. This function can be called multiple
+   * times, where initial calls schedule the tasks and subsequents invocations update the schedules.
+   */
+  schedule(): Promise<void>;
+
+  /**
+   * Provides possibility to manually run a fact retriever job and construct fact data
+   *
+   * @param ref - Reference to the task name stored in the executor database. By convention this is the fact retriever id
+   */
+  triggerJob(ref: string): Promise<void>;
+
+  /**
+   * Exposes fact retriever job configuration information about previous and next runs and schedule
+   *
+   * @param ref - Reference to the task name stored in the executor database. By convention this is the fact retriever id
+   */
+  getJobRegistration(ref: string): Promise<FactRetrieverRegistration>;
+}
+
+export class DefaultFactRetrieverEngine implements FactRetrieverEngine {
   private constructor(
     private readonly repository: TechInsightsStore,
     private readonly factRetrieverRegistry: FactRetrieverRegistry,
@@ -69,7 +98,7 @@ export class FactRetrieverEngine {
     const retrievers = await factRetrieverRegistry.listRetrievers();
     await Promise.all(retrievers.map(it => repository.insertFactSchema(it)));
 
-    return new FactRetrieverEngine(
+    return new DefaultFactRetrieverEngine(
       repository,
       factRetrieverRegistry,
       factRetrieverContext,

plugins/tech-insights-backend/src/service/fact/FactRetrieverRegistry.ts

@@ -36,7 +36,7 @@ export interface FactRetrieverRegistry {
 /**
  * A basic in memory fact retriever registry.
  *
- * You can replace this with a persistance based version using the FactRetrieverRegistry interface.
+ * You can replace this with a persistence based version using the FactRetrieverRegistry interface.
  *
  */
 export class DefaultFactRetrieverRegistry implements FactRetrieverRegistry {

plugins/tech-insights-backend/src/service/router.ts

@@ -142,7 +142,7 @@ export async function createRouter<
   });
 
   /**
-   * /facts/latest?entity=component:default/mycomponent&startDateTime=2021-12-24T01:23:45&endDateTime=2021-12-31T23:59:59&ids[]=factRetrieverId1&ids[]=factRetrieverId2
+   * /facts/range?entity=component:default/mycomponent&startDateTime=2021-12-24T01:23:45&endDateTime=2021-12-31T23:59:59&ids[]=factRetrieverId1&ids[]=factRetrieverId2
    */
   router.get('/facts/range', async (req, res) => {
     const { entity } = req.query;

plugins/tech-insights-backend/src/service/techInsightsContextBuilder.ts

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 
-import { FactRetrieverEngine } from './fact/FactRetrieverEngine';
+import {
+  DefaultFactRetrieverEngine,
+  FactRetrieverEngine,
+} from './fact/FactRetrieverEngine';
 import { Logger } from 'winston';
 import {
   DefaultFactRetrieverRegistry,
@@ -93,6 +96,7 @@ export type TechInsightsContext<
 > = {
   factChecker?: FactChecker<CheckType, CheckResultType>;
   persistenceContext: PersistenceContext;
+  factRetrieverEngine: FactRetrieverEngine;
 };
 
 /**
@@ -140,7 +144,7 @@ export const buildTechInsightsContext = async <
     { logger },
   );
 
-  const factRetrieverEngine = await FactRetrieverEngine.create({
+  const factRetrieverEngine = await DefaultFactRetrieverEngine.create({
     scheduler,
     repository: persistenceContext.techInsightsStore,
     factRetrieverRegistry,
@@ -161,10 +165,12 @@ export const buildTechInsightsContext = async <
     return {
       persistenceContext,
       factChecker,
+      factRetrieverEngine,
     };
   }
 
   return {
     persistenceContext,
+    factRetrieverEngine,
   };
 };