getUpdateHandle (#1312)

Add `getUpdateHandle` API. Fixes #1306.

Author: dandavison

packages/client/src/workflow-client.ts

@@ -164,6 +164,15 @@ export interface WorkflowHandle<T extends Workflow = Workflow> extends BaseWorkf
     options?: WorkflowUpdateOptions & { args?: Args }
   ): Promise<WorkflowUpdateHandle<Ret>>;
 
+  /**
+   * Get a handle to an Update.
+   */
+  getUpdateHandle<Ret>(
+    updateId: string,
+    workflowId: string,
+    options?: GetWorkflowUpdateHandleOptions
+  ): WorkflowUpdateHandle<Ret>;
+
   /**
    * Query a running or completed Workflow.
    *
@@ -296,6 +305,9 @@ export interface WorkflowResultOptions {
   followRuns?: boolean;
 }
 
+/**
+ * Options for {@link WorkflowClient.getHandle}
+ */
 export interface GetWorkflowHandleOptions extends WorkflowResultOptions {
   /**
    * ID of the first execution in the Workflow execution chain.
@@ -351,7 +363,7 @@ export interface WorkflowUpdateHandle<Ret> {
   /**
    * The ID of the Run of the Workflow being targeted by this Update request.
    */
-  workflowRunId: string;
+  workflowRunId?: string;
 
   /**
    * Return the result of the Update.
@@ -360,6 +372,16 @@ export interface WorkflowUpdateHandle<Ret> {
   result(): Promise<Ret>;
 }
 
+/**
+ * Options for {@link WorkflowHandle.getUpdateHandle}
+ */
+export interface GetWorkflowUpdateHandleOptions {
+  /**
+   * The ID of the Run of the Workflow targeted by the Update.
+   */
+  workflowRunId?: string;
+}
+
 /**
  * Options for {@link WorkflowClient.list}
  */
@@ -775,15 +797,19 @@ export class WorkflowClient extends BaseClient {
   }
 
   protected createWorkflowUpdateHandle<Ret>(
-    input: WorkflowStartUpdateInput,
-    { updateId, workflowRunId, outcome }: WorkflowStartUpdateOutput
+    updateId: string,
+    workflowId: string,
+    options?: GetWorkflowUpdateHandleOptions,
+    outcome?: temporal.api.update.v1.IOutcome
   ): WorkflowUpdateHandle<Ret> {
+    const workflowRunId = options?.workflowRunId;
     return {
       updateId,
-      workflowId: input.workflowExecution.workflowId,
+      workflowId,
       workflowRunId,
       result: async () => {
-        const completedOutcome = outcome ?? (await this._pollForUpdateOutcome(updateId, input.workflowExecution));
+        const completedOutcome =
+          outcome ?? (await this._pollForUpdateOutcome(updateId, { workflowId, runId: workflowRunId }));
         if (completedOutcome.failure) {
           throw new WorkflowUpdateFailedError(
             'Workflow Update failed',
@@ -1048,7 +1074,12 @@ export class WorkflowClient extends BaseClient {
         options: opts,
       };
       const output = await fn(input);
-      return this.createWorkflowUpdateHandle<Ret>(input, output);
+      return this.createWorkflowUpdateHandle<Ret>(
+        output.updateId,
+        input.workflowExecution.workflowId,
+        { workflowRunId: output.workflowRunId },
+        output.outcome
+      );
     };
 
     return {
@@ -1113,7 +1144,6 @@ export class WorkflowClient extends BaseClient {
           options
         );
       },
-
       async executeUpdate<Ret, Args extends any[]>(
         def: UpdateDefinition<Ret, Args> | string,
         options?: WorkflowUpdateOptions & { args?: Args }
@@ -1126,7 +1156,13 @@ export class WorkflowClient extends BaseClient {
         );
         return await handle.result();
       },
-
+      getUpdateHandle<Ret>(
+        updateId: string,
+        workflowId: string,
+        options?: GetWorkflowUpdateHandleOptions
+      ): WorkflowUpdateHandle<Ret> {
+        return this.client.createWorkflowUpdateHandle(updateId, workflowId, options);
+      },
       async signal<Args extends any[]>(def: SignalDefinition<Args> | string, ...args: Args): Promise<void> {
         const next = this.client._signalWorkflowHandler.bind(this.client);
         const fn = composeInterceptors(interceptors, 'signal', next);

packages/test/src/test-integration-update.ts

@@ -1,3 +1,5 @@
+import { status as grpcStatus } from '@grpc/grpc-js';
+import { isGrpcServiceError } from '@temporalio/client';
 import * as wf from '@temporalio/workflow';
 import { helpers, makeTestFunction } from './helpers-integration';
 
@@ -59,6 +61,30 @@ test('Update can be executed via startUpdate() and handle.result()', async (t) =
   });
 });
 
+test('Update handle can be created from identifiers and used to obtain result', async (t) => {
+  const { createWorker, startWorkflow } = helpers(t);
+  const worker = await createWorker();
+  await worker.runUntil(async () => {
+    const updateId = 'my-update-id';
+    const wfHandle = await startWorkflow(workflowWithUpdates);
+    const updateHandleFromStartUpdate = await wfHandle.startUpdate(update, { args: ['1'], updateId });
+
+    const updateHandle = wfHandle.getUpdateHandle(updateId, wfHandle.workflowId);
+    t.deepEqual(await updateHandle.result(), ['1']);
+
+    t.truthy(updateHandleFromStartUpdate.workflowRunId);
+    const updateHandle2 = wfHandle.getUpdateHandle(updateId, wfHandle.workflowId, {
+      workflowRunId: updateHandleFromStartUpdate.workflowRunId,
+    });
+    t.deepEqual(await updateHandle2.result(), ['1']);
+
+    const incorrectRunId = wf.uuid4();
+    const updateHandle3 = wfHandle.getUpdateHandle(updateId, wfHandle.workflowId, { workflowRunId: incorrectRunId });
+    const err = await t.throwsAsync(updateHandle3.result());
+    t.true(isGrpcServiceError(err) && err.code === grpcStatus.NOT_FOUND);
+  });
+});
+
 const activities = {
   async myActivity(): Promise<number> {
     return 3;