Merge pull request #9670 from backstage/blam/deprecations/3

deprecations: More small type fixes and deprecations for `scaffolder-backend`

.changeset/eight-houses-remain.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+- **DEPRECATED** - `TaskState` has been deprecated in favour of `CurrentClaimedTask`
+- Narrowed the types from `JSONValue` to `JSONObject` as the usage is and should always be `JSONObject` for `complete` and `emitLog` `metadata` in `TaskContext`

plugins/scaffolder-backend/api-report.md

@@ -322,6 +322,16 @@ export type CreateWorkerOptions = {
   additionalTemplateFilters?: Record<string, TemplateFilter>;
 };
 
+// @public
+export interface CurrentClaimedTask {
+  // (undocumented)
+  secrets?: TaskSecrets;
+  // (undocumented)
+  spec: TaskSpec;
+  // (undocumented)
+  taskId: string;
+}
+
 // @public
 export class DatabaseTaskStore implements TaskStore {
   // (undocumented)
@@ -514,11 +524,11 @@ export type TaskCompletionState = 'failed' | 'completed';
 // @public
 export interface TaskContext {
   // (undocumented)
-  complete(result: TaskCompletionState, metadata?: JsonValue): Promise<void>;
+  complete(result: TaskCompletionState, metadata?: JsonObject): Promise<void>;
   // (undocumented)
   done: boolean;
   // (undocumented)
-  emitLog(message: string, metadata?: JsonValue): Promise<void>;
+  emitLog(message: string, logMetadata?: JsonObject): Promise<void>;
   // (undocumented)
   getWorkspaceName(): Promise<string>;
   // (undocumented)
@@ -536,14 +546,14 @@ export class TaskManager implements TaskContext {
   complete(result: TaskCompletionState, metadata?: JsonObject): Promise<void>;
   // (undocumented)
   static create(
-    state: TaskState,
+    task: CurrentClaimedTask,
     storage: TaskStore,
     logger: Logger_2,
   ): TaskManager;
   // (undocumented)
   get done(): boolean;
   // (undocumented)
-  emitLog(message: string, metadata?: JsonObject): Promise<void>;
+  emitLog(message: string, logMetadata?: JsonObject): Promise<void>;
   // (undocumented)
   getWorkspaceName(): Promise<string>;
   // (undocumented)
@@ -563,15 +573,8 @@ export { TaskSpecV1beta2 };
 
 export { TaskSpecV1beta3 };
 
-// @public
-export interface TaskState {
-  // (undocumented)
-  secrets?: TaskSecrets;
-  // (undocumented)
-  spec: TaskSpec;
-  // (undocumented)
-  taskId: string;
-}
+// @public @deprecated
+export type TaskState = CurrentClaimedTask;
 
 // @public
 export type TaskStatus =

plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts

@@ -38,39 +38,39 @@ export class TaskManager implements TaskContext {
 
   private heartbeatTimeoutId?: ReturnType<typeof setInterval>;
 
-  static create(state: TaskState, storage: TaskStore, logger: Logger) {
-    const agent = new TaskManager(state, storage, logger);
+  static create(task: CurrentClaimedTask, storage: TaskStore, logger: Logger) {
+    const agent = new TaskManager(task, storage, logger);
     agent.startTimeout();
     return agent;
   }
 
   // Runs heartbeat internally
   private constructor(
-    private readonly state: TaskState,
+    private readonly task: CurrentClaimedTask,
     private readonly storage: TaskStore,
     private readonly logger: Logger,
   ) {}
 
   get spec() {
-    return this.state.spec;
+    return this.task.spec;
   }
 
   get secrets() {
-    return this.state.secrets;
+    return this.task.secrets;
   }
 
   async getWorkspaceName() {
-    return this.state.taskId;
+    return this.task.taskId;
   }
 
   get done() {
     return this.isDone;
   }
 
-  async emitLog(message: string, metadata?: JsonObject): Promise<void> {
+  async emitLog(message: string, logMetadata?: JsonObject): Promise<void> {
     await this.storage.emitLogEvent({
-      taskId: this.state.taskId,
-      body: { message, ...metadata },
+      taskId: this.task.taskId,
+      body: { message, ...logMetadata },
     });
   }
 
@@ -79,7 +79,7 @@ export class TaskManager implements TaskContext {
     metadata?: JsonObject,
   ): Promise<void> {
     await this.storage.completeTask({
-      taskId: this.state.taskId,
+      taskId: this.task.taskId,
       status: result === 'failed' ? 'failed' : 'completed',
       eventBody: {
         message: `Run completed with status: ${result}`,
@@ -95,13 +95,13 @@ export class TaskManager implements TaskContext {
   private startTimeout() {
     this.heartbeatTimeoutId = setTimeout(async () => {
       try {
-        await this.storage.heartbeatTask(this.state.taskId);
+        await this.storage.heartbeatTask(this.task.taskId);
         this.startTimeout();
       } catch (error) {
         this.isDone = true;
 
         this.logger.error(
-          `Heartbeat for task ${this.state.taskId} failed`,
+          `Heartbeat for task ${this.task.taskId} failed`,
           error,
         );
       }
@@ -110,16 +110,24 @@ export class TaskManager implements TaskContext {
 }
 
 /**
- * TaskState
+ * Stores the state of the current claimed task passed to the TaskContext
  *
  * @public
  */
-export interface TaskState {
+export interface CurrentClaimedTask {
   spec: TaskSpec;
   taskId: string;
   secrets?: TaskSecrets;
 }
 
+/**
+ * TaskState
+ *
+ * @public
+ * @deprecated use CurrentClaimedTask instead
+ */
+export type TaskState = CurrentClaimedTask;
+
 function defer() {
   let resolve = () => {};
   const promise = new Promise<void>(_resolve => {

plugins/scaffolder-backend/src/scaffolder/tasks/index.ts

@@ -15,7 +15,7 @@
  */
 export { DatabaseTaskStore } from './DatabaseTaskStore';
 export { TaskManager } from './StorageTaskBroker';
-export type { TaskState } from './StorageTaskBroker';
+export type { CurrentClaimedTask, TaskState } from './StorageTaskBroker';
 export { TaskWorker } from './TaskWorker';
 export type { CreateWorkerOptions } from './TaskWorker';
 export type {

plugins/scaffolder-backend/src/scaffolder/tasks/types.ts

@@ -146,8 +146,8 @@ export interface TaskContext {
   spec: TaskSpec;
   secrets?: TaskSecrets;
   done: boolean;
-  emitLog(message: string, metadata?: JsonValue): Promise<void>;
-  complete(result: TaskCompletionState, metadata?: JsonValue): Promise<void>;
+  emitLog(message: string, logMetadata?: JsonObject): Promise<void>;
+  complete(result: TaskCompletionState, metadata?: JsonObject): Promise<void>;
   getWorkspaceName(): Promise<string>;
 }