diff --git a/packages/backend-tasks/README.md b/packages/backend-tasks/README.md index 71c54b0a7f..abb25079e3 100644 --- a/packages/backend-tasks/README.md +++ b/packages/backend-tasks/README.md @@ -19,15 +19,13 @@ import { TaskManager } from '@backstage/backend-tasks'; const manager = TaskManager.fromConfig(rootConfig).forPlugin('my-plugin'); -const { unschedule } = await manager.scheduleTask( - 'refresh-things', - { - frequency: Duration.fromObject({ minutes: 10 }), - }, - async () => { +const { unschedule } = await manager.scheduleTask({ + id: 'refresh-things', + frequency: Duration.fromObject({ minutes: 10 }), + fn: async () => { await entityProvider.run(); }, -); +}); ``` ## Documentation diff --git a/packages/backend-tasks/api-report.md b/packages/backend-tasks/api-report.md index e9d7884b43..f3aaf0e9bf 100644 --- a/packages/backend-tasks/api-report.md +++ b/packages/backend-tasks/api-report.md @@ -10,15 +10,20 @@ import { Logger as Logger_2 } from 'winston'; // @public export interface PluginTaskManager { - scheduleTask( - id: string, - options: TaskOptions, - fn: () => void | Promise, - ): Promise<{ + scheduleTask(task: TaskDefinition): Promise<{ unschedule: () => Promise; }>; } +// @public +export interface TaskDefinition { + fn: () => void | Promise; + frequency: Duration; + id: string; + initialDelay?: Duration; + timeout: Duration; +} + // @public export class TaskManager { constructor(databaseManager: DatabaseManager, logger: Logger_2); @@ -32,11 +37,4 @@ export class TaskManager { }, ): TaskManager; } - -// @public -export interface TaskOptions { - frequency?: Duration; - initialDelay?: Duration; - timeout?: Duration; -} ``` diff --git a/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.test.ts b/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.test.ts index 193dd2a95d..bbb54a2aa0 100644 --- a/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.test.ts +++ b/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.test.ts @@ -45,14 +45,12 @@ describe('PluginTaskManagerImpl', () => { const { manager } = await init(databaseId); const fn = jest.fn(); - const { unschedule } = await manager.scheduleTask( - 'task1', - { - timeout: Duration.fromMillis(5000), - frequency: Duration.fromMillis(5000), - }, + const { unschedule } = await manager.scheduleTask({ + id: 'task1', + timeout: Duration.fromMillis(5000), + frequency: Duration.fromMillis(5000), fn, - ); + }); await waitForExpect(() => { expect(fn).toBeCalled(); diff --git a/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.ts b/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.ts index 1b890a69c8..fd543cf828 100644 --- a/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.ts +++ b/packages/backend-tasks/src/tasks/PluginTaskManagerImpl.ts @@ -17,7 +17,7 @@ import { Knex } from 'knex'; import { Logger } from 'winston'; import { TaskWorker } from './TaskWorker'; -import { PluginTaskManager, TaskOptions } from './types'; +import { PluginTaskManager, TaskDefinition } from './types'; import { validateId } from './util'; /** @@ -30,25 +30,23 @@ export class PluginTaskManagerImpl implements PluginTaskManager { ) {} async scheduleTask( - id: string, - options: TaskOptions, - fn: () => void | Promise, + task: TaskDefinition, ): Promise<{ unschedule: () => Promise }> { - validateId(id); + validateId(task.id); const knex = await this.databaseFactory(); - const task = new TaskWorker(id, fn, knex, this.logger); - await task.start({ + const worker = new TaskWorker(task.id, task.fn, knex, this.logger); + await worker.start({ version: 1, - initialDelayDuration: options.initialDelay?.toISO(), - recurringAtMostEveryDuration: options.frequency.toISO(), - timeoutAfterDuration: options.timeout.toISO(), + initialDelayDuration: task.initialDelay?.toISO(), + recurringAtMostEveryDuration: task.frequency.toISO(), + timeoutAfterDuration: task.timeout.toISO(), }); return { async unschedule() { - await task.stop(); + await worker.stop(); }, }; } diff --git a/packages/backend-tasks/src/tasks/TaskManager.test.ts b/packages/backend-tasks/src/tasks/TaskManager.test.ts index 002db0b3de..c81cfc8ee9 100644 --- a/packages/backend-tasks/src/tasks/TaskManager.test.ts +++ b/packages/backend-tasks/src/tasks/TaskManager.test.ts @@ -43,14 +43,12 @@ describe('TaskManager', () => { const database = await createDatabase(databaseId); const manager = new TaskManager(database, logger).forPlugin('test'); - const task = await manager.scheduleTask( - 'task1', - { - timeout: Duration.fromMillis(5000), - frequency: Duration.fromMillis(5000), - }, - () => {}, - ); + const task = await manager.scheduleTask({ + id: 'task1', + timeout: Duration.fromMillis(5000), + frequency: Duration.fromMillis(5000), + fn: () => {}, + }); expect(task.unschedule).toBeDefined(); }, ); diff --git a/packages/backend-tasks/src/tasks/index.ts b/packages/backend-tasks/src/tasks/index.ts index d16a30b6c9..e4fe1ad2a3 100644 --- a/packages/backend-tasks/src/tasks/index.ts +++ b/packages/backend-tasks/src/tasks/index.ts @@ -15,4 +15,4 @@ */ export { TaskManager } from './TaskManager'; -export type { PluginTaskManager, TaskOptions } from './types'; +export type { PluginTaskManager, TaskDefinition } from './types'; diff --git a/packages/backend-tasks/src/tasks/types.ts b/packages/backend-tasks/src/tasks/types.ts index 989414ec12..e2dfbea0a1 100644 --- a/packages/backend-tasks/src/tasks/types.ts +++ b/packages/backend-tasks/src/tasks/types.ts @@ -22,7 +22,17 @@ import { z } from 'zod'; * * @public */ -export interface TaskOptions { +export interface TaskDefinition { + /** + * A unique ID (within the scope of the plugin) for the task. + */ + id: string; + + /** + * The actual task function to be invoked regularly. + */ + fn: () => void | Promise; + /** * The maximum amount of time that a single task invocation can take, before * it's considered timed out and gets "released" such that a new invocation @@ -77,17 +87,13 @@ export interface PluginTaskManager { * its options are just overwritten with the given options, and things * continue from there. * - * @param id - A unique ID (within the scope of the plugin) for the task - * @param options - Options for the task - * @param fn - The actual task function to be invoked + * @param definition - The task definition * @returns An `unschedule` function that can be used to stop the task * invocations later on. This removes the task entirely from storage * and stops its invocations across all workers. */ scheduleTask( - id: string, - options: TaskOptions, - fn: () => void | Promise, + task: TaskDefinition, ): Promise<{ unschedule: () => Promise }>; }