@temporalio/client - npm Package Compare versions

Comparing version 1.10.3 to 1.11.0

lib/connection.js

@@ -48,2 +48,3 @@ "use strict";
             'grpc.keepalive_timeout_ms': 15000,
+            max_receive_message_length: 128 * 1024 * 1024, // 128 MB
             ...channelArgs,
@@ -50,0 +51,0 @@ },

lib/errors.d.ts

@@ -35,2 +35,12 @@ import { ServiceError as GrpcServiceError } from '@grpc/grpc-js';
 /**
+ * Thrown by the client if the Update call timed out or was cancelled.
+ * This doesn't mean the update itself was timed out or cancelled.
+ */
+export declare class WorkflowUpdateRPCTimeoutOrCancelledError extends Error {
+    readonly cause?: Error;
+    constructor(message: string, opts?: {
+        cause: Error;
+    });
+}
+/**
  * Thrown the by client while waiting on Workflow execution result if Workflow
@@ -37,0 +47,0 @@ * continues as new.

lib/errors.js

@@ -9,3 +9,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isServerErrorResponse = exports.isGrpcServiceError = exports.WorkflowContinuedAsNewError = exports.WorkflowUpdateFailedError = exports.WorkflowFailedError = exports.ServiceError = void 0;
+exports.isServerErrorResponse = exports.isGrpcServiceError = exports.WorkflowContinuedAsNewError = exports.WorkflowUpdateRPCTimeoutOrCancelledError = exports.WorkflowUpdateFailedError = exports.WorkflowFailedError = exports.ServiceError = void 0;
 const type_helpers_1 = require("@temporalio/common/lib/type-helpers");
@@ -60,2 +60,16 @@ /**
 /**
+ * Thrown by the client if the Update call timed out or was cancelled.
+ * This doesn't mean the update itself was timed out or cancelled.
+ */
+let WorkflowUpdateRPCTimeoutOrCancelledError = class WorkflowUpdateRPCTimeoutOrCancelledError extends Error {
+    constructor(message, opts) {
+        super(message);
+        this.cause = opts?.cause;
+    }
+};
+exports.WorkflowUpdateRPCTimeoutOrCancelledError = WorkflowUpdateRPCTimeoutOrCancelledError;
+exports.WorkflowUpdateRPCTimeoutOrCancelledError = WorkflowUpdateRPCTimeoutOrCancelledError = __decorate([
+    (0, type_helpers_1.SymbolBasedInstanceOfError)('WorkflowUpdateRPCTimeoutOrCancelledError')
+], WorkflowUpdateRPCTimeoutOrCancelledError);
+/**
  * Thrown the by client while waiting on Workflow execution result if Workflow
@@ -62,0 +76,0 @@ * continues as new.

lib/grpc-retry.js

@@ -72,2 +72,33 @@ "use strict";
 function isRetryableError(status) {
+    // gRPC INTERNAL status is ambiguous and may be used in many unrelated situations, including:
+    // - TLS errors
+    // - Compression errors
+    // - Errors decoding protobuf messages (either client-side or server-side)
+    // - Transient HTTP/2 network errors
+    // - Failing some server-side request validation
+    // - etc.
+    //
+    // In most case, retrying is useless and would only be a waste of resource.
+    // However, in case of transient network errors, retrying is highly desirable.
+    // Unfortunately, the only way of differenciating between those various cases
+    // is pattern matching the error messages.
+    if (status.code === grpc.status.INTERNAL) {
+        // RST_STREAM code 0 means the HTTP2 request completed with HTTP status 200, but without
+        // the mandatory `grpc-status` header. That's generally due to some HTTP2 proxy or load balancer
+        // that doesn't know about gRPC-specifics. Retrying may help.
+        if (/RST_STREAM with code 0|Call ended without gRPC status/i.test(status.details))
+            return true;
+        // RST_STREAM code 2 is pretty generic and encompasses most HTTP2 protocol errors.
+        // That may for example happen if the client tries to reuse the connection at the
+        // same time as the server initiate graceful closing. Retrying may help.
+        if (/RST_STREAM with code 2/i.test(status.details)) {
+            // Some TLS errors surfaces with message:
+            // "Received RST_STREAM with code 2 triggered by internal client error: […] SSL alert number XX"
+            // At this time, no TLS error is worth retrying, so dismiss those.
+            if (/SSL alert number/i.test(status.details))
+                return false;
+            return true;
+        }
+        return false;
+    }
     return retryableCodes.has(status.code);
@@ -74,0 +105,0 @@ }

lib/index.d.ts

@@ -28,2 +28,3 @@ /**
 export * from './task-queue-client';
+export { WorkflowUpdateStage } from './workflow-update-stage';
 export { WorkerBuildIdVersionSets, BuildIdVersionSet, BuildIdOperation, PromoteSetByBuildId, PromoteBuildIdWithinSet, MergeSets, AddNewIdInNewDefaultSet, AddNewCompatibleVersion, } from './build-id-types';

lib/index.js

@@ -27,3 +27,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOCAL_TARGET = exports.Connection = exports.TimeoutFailure = exports.TerminatedFailure = exports.TemporalFailure = exports.ServerFailure = exports.defaultPayloadConverter = exports.ChildWorkflowFailure = exports.CancelledFailure = exports.ApplicationFailure = exports.ActivityFailure = void 0;
+exports.WorkflowUpdateStage = exports.LOCAL_TARGET = exports.Connection = exports.TimeoutFailure = exports.TerminatedFailure = exports.TemporalFailure = exports.ServerFailure = exports.defaultPayloadConverter = exports.ChildWorkflowFailure = exports.CancelledFailure = exports.ApplicationFailure = exports.ActivityFailure = void 0;
 var common_1 = require("@temporalio/common");
@@ -56,2 +56,4 @@ Object.defineProperty(exports, "ActivityFailure", { enumerable: true, get: function () { return common_1.ActivityFailure; } });
 __exportStar(require("./task-queue-client"), exports);
+var workflow_update_stage_1 = require("./workflow-update-stage");
+Object.defineProperty(exports, "WorkflowUpdateStage", { enumerable: true, get: function () { return workflow_update_stage_1.WorkflowUpdateStage; } });
 //# sourceMappingURL=index.js.map

lib/schedule-types.d.ts

@@ -39,3 +39,3 @@ import { Replace } from '@temporalio/common/lib/type-helpers';
          *
-         * @default 1 minute
+         * @default 1 year
          * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
@@ -42,0 +42,0 @@ */

lib/workflow-client.d.ts

@@ -9,2 +9,3 @@ import { status as grpcStatus } from '@grpc/grpc-js';
 import { BaseClient, BaseClientOptions, LoadedWithDefaults } from './base-client';
+import { WorkflowUpdateStage } from './workflow-update-stage';
 /**
@@ -47,3 +48,4 @@ * A client side handle to a single Workflow instance.
      * @throws {@link WorkflowUpdateFailedError} if Update validation fails or if ApplicationFailure is thrown in the Update handler.
-     *
+     * @throws {@link WorkflowUpdateRPCTimeoutOrCancelledError} if this Update call timed out or was cancelled. This doesn't
+     *  mean the update itself was timed out or cancelled.
      * @param def an Update definition as returned from {@link defineUpdate}
@@ -64,4 +66,4 @@ * @param options Update arguments
     /**
-     * Start an Update and receive a handle to the Update.
-     * The Update validator (if present) is run before the handle is returned.
+     * Start an Update and receive a handle to the Update. The Update validator (if present) is run
+     * before the handle is returned.
      *
@@ -71,9 +73,24 @@ * @experimental Update is an experimental feature.
      * @throws {@link WorkflowUpdateFailedError} if Update validation fails.
+     * @throws {@link WorkflowUpdateRPCTimeoutOrCancelledError} if this Update call timed out or was cancelled. This doesn't
+     *  mean the update itself was timed out or cancelled.
      *
      * @param def an Update definition as returned from {@link defineUpdate}
-     * @param options Update arguments
+     * @param options update arguments, and update lifecycle stage to wait for
      *
+     * Currently, startUpdate always waits until a worker is accepting tasks for the workflow and the
+     * update is accepted or rejected, and the options object must be at least
+     * ```ts
+     * {
+     *   waitForStage: WorkflowUpdateStage.ACCEPTED
+     * }
+     * ```
+     * If the update takes arguments, then the options object must additionally contain an `args`
+     * property with an array of argument values.
+     *
      * @example
      * ```ts
-     * const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, { args: [2] });
+     * const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, {
+     *   args: [2],
+     *   waitForStage: WorkflowUpdateStage.ACCEPTED,
+     * });
      * const updateResult = await updateHandle.result();
@@ -84,5 +101,7 @@ * ```
         args: Args;
+        waitForStage: WorkflowUpdateStage.ACCEPTED;
     }): Promise<WorkflowUpdateHandle<Ret>>;
-    startUpdate<Ret, Args extends [], Name extends string = string>(def: UpdateDefinition<Ret, Args, Name> | string, options?: WorkflowUpdateOptions & {
+    startUpdate<Ret, Args extends [], Name extends string = string>(def: UpdateDefinition<Ret, Args, Name> | string, options: WorkflowUpdateOptions & {
         args?: Args;
+        waitForStage: WorkflowUpdateStage.ACCEPTED;
     }): Promise<WorkflowUpdateHandle<Ret>>;
@@ -349,2 +368,3 @@ /**
     result<T extends Workflow>(workflowId: string, runId?: string, opts?: WorkflowResultOptions): Promise<WorkflowResultType<T>>;
+    protected rethrowUpdateGrpcError(err: unknown, fallbackMessage: string, workflowExecution?: WorkflowExecution): never;
     protected rethrowGrpcError(err: unknown, fallbackMessage: string, workflowExecution?: WorkflowExecution): never;
@@ -362,3 +382,3 @@ /**
      */
-    protected _startUpdateHandler(waitForStage: temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage, input: WorkflowStartUpdateInput): Promise<WorkflowStartUpdateOutput>;
+    protected _startUpdateHandler(waitForStage: WorkflowUpdateStage, input: WorkflowStartUpdateInput): Promise<WorkflowStartUpdateOutput>;
     protected createWorkflowUpdateHandle<Ret>(updateId: string, workflowId: string, workflowRunId?: string, outcome?: temporal.api.update.v1.IOutcome): WorkflowUpdateHandle<Ret>;
@@ -365,0 +385,0 @@ /**

lib/workflow-client.js

 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
@@ -8,2 +24,9 @@ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 };
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -23,2 +46,4 @@ exports.QueryNotRegisteredError = exports.QueryRejectedError = exports.WorkflowClient = void 0;
 const iterators_utils_1 = require("./iterators-utils");
+const workflow_update_stage_1 = require("./workflow-update-stage");
+const workflowUpdateStage = __importStar(require("./workflow-update-stage"));
 function defaultWorkflowClientOptions() {
@@ -249,2 +274,17 @@ return {
     }
+    rethrowUpdateGrpcError(err, fallbackMessage, workflowExecution) {
+        if ((0, errors_1.isGrpcServiceError)(err)) {
+            if (err.code === grpc_js_1.status.DEADLINE_EXCEEDED || err.code === grpc_js_1.status.CANCELLED) {
+                throw new errors_1.WorkflowUpdateRPCTimeoutOrCancelledError(err.details ?? 'Workflow update call timeout or cancelled', {
+                    cause: err,
+                });
+            }
+        }
+        if (err instanceof common_1.CancelledFailure) {
+            throw new errors_1.WorkflowUpdateRPCTimeoutOrCancelledError(err.message ?? 'Workflow update call timeout or cancelled', {
+                cause: err,
+            });
+        }
+        this.rethrowGrpcError(err, fallbackMessage, workflowExecution);
+    }
     rethrowGrpcError(err, fallbackMessage, workflowExecution) {
@@ -307,2 +347,4 @@ if ((0, errors_1.isGrpcServiceError)(err)) {
     async _startUpdateHandler(waitForStage, input) {
+        waitForStage = waitForStage >= workflow_update_stage_1.WorkflowUpdateStage.ACCEPTED ? waitForStage : workflow_update_stage_1.WorkflowUpdateStage.ACCEPTED;
+        const waitForStageProto = workflowUpdateStage.toProtoEnum(waitForStage);
         const updateId = input.options?.updateId ?? (0, uuid_1.v4)();
@@ -313,3 +355,5 @@ const req = {
             firstExecutionRunId: input.firstExecutionRunId,
-            waitPolicy: { lifecycleStage: waitForStage },
+            waitPolicy: {
+                lifecycleStage: waitForStageProto,
+            },
             request: {
@@ -327,8 +371,13 @@ meta: {
         };
+        // Repeatedly send UpdateWorkflowExecution until update is >= Accepted or >= `waitForStage` (if
+        // the server receives a request with an update ID that already exists, it responds with
+        // information for the existing update).
         let response;
         try {
-            response = await this.workflowService.updateWorkflowExecution(req);
+            do {
+                response = await this.workflowService.updateWorkflowExecution(req);
+            } while (response.stage < waitForStageProto);
         }
         catch (err) {
-            this.rethrowGrpcError(err, 'Workflow Update failed', input.workflowExecution);
+            this.rethrowUpdateGrpcError(err, 'Workflow Update failed', input.workflowExecution);
         }
@@ -368,14 +417,5 @@ return {
             waitPolicy: {
-                lifecycleStage: proto_1.temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-                    .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED,
+                lifecycleStage: workflowUpdateStage.toProtoEnum(workflow_update_stage_1.WorkflowUpdateStage.COMPLETED),
             },
         };
-        // TODO: Users should be able to use client.withDeadline(timestamp) with a
-        // Date (as opposed to a duration) to control the total amount of time
-        // allowed for polling. However, this requires a server change such that the
-        // server swallows the gRPC timeout and instead responds with a well-formed
-        // PollWorkflowExecutionUpdateResponse, indicating that the requested
-        // lifecycle stage has not yet been reached at the time of the deadline
-        // expiry. See https://github.com/temporalio/temporal/issues/4742
-        // TODO: When temporal#4742 is released, stop catching DEADLINE_EXCEEDED.
         for (;;) {
@@ -389,5 +429,4 @@ try {
             catch (err) {
-                if (!((0, errors_1.isGrpcServiceError)(err) && err.code === grpc_js_1.status.DEADLINE_EXCEEDED)) {
-                    throw err;
-                }
+                const wE = typeof workflowExecution.workflowId === 'string' ? workflowExecution : undefined;
+                this.rethrowUpdateGrpcError(err, 'Workflow Update Poll failed', wE);
             }
@@ -570,3 +609,2 @@ }
     _createWorkflowHandle({ workflowId, runId, firstExecutionRunId, interceptors, runIdForResult, ...resultOptions }) {
-        // TODO (dan): Convert to class with this as a protected method
         const _startUpdate = async (def, waitForStage, options) => {
@@ -586,3 +624,7 @@ const next = this._startUpdateHandler.bind(this, waitForStage);
             const output = await fn(input);
-            return this.createWorkflowUpdateHandle(output.updateId, input.workflowExecution.workflowId, output.workflowRunId, output.outcome);
+            const handle = this.createWorkflowUpdateHandle(output.updateId, input.workflowExecution.workflowId, output.workflowRunId, output.outcome);
+            if (!output.outcome && waitForStage === workflow_update_stage_1.WorkflowUpdateStage.COMPLETED) {
+                await this._pollForUpdateOutcome(handle.updateId, input.workflowExecution);
+            }
+            return handle;
         };
@@ -641,8 +683,6 @@ return {
             async startUpdate(def, options) {
-                return await _startUpdate(def, proto_1.temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-                    .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED, options);
+                return await _startUpdate(def, options.waitForStage, options);
             },
             async executeUpdate(def, options) {
-                const handle = await _startUpdate(def, proto_1.temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-                    .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED, options);
+                const handle = await _startUpdate(def, workflow_update_stage_1.WorkflowUpdateStage.COMPLETED, options);
                 return await handle.result();
@@ -745,5 +785,3 @@ },
                     workflowId,
-                    history: await this.getHandle(workflowId, runId)
-                        .fetchHistory()
-                        .catch((_) => undefined),
+                    history: await this.getHandle(workflowId, runId).fetchHistory(),
                 }), { concurrency: intoHistoriesOptions?.concurrency ?? 5 });
@@ -750,0 +788,0 @@ },

package.json

 {
   "name": "@temporalio/client",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "Temporal.io SDK Client sub-package",
@@ -16,5 +16,5 @@ "main": "lib/index.js",
   "dependencies": {
-    "@grpc/grpc-js": "^1.10.6",
-    "@temporalio/common": "1.10.3",
-    "@temporalio/proto": "1.10.3",
+    "@grpc/grpc-js": "^1.10.7",
+    "@temporalio/common": "1.11.0",
+    "@temporalio/proto": "1.11.0",
     "abort-controller": "^3.0.0",
@@ -43,3 +43,3 @@ "long": "^5.2.3",
   ],
-  "gitHead": "7832067434443145e1f0ddf07cb37b0b90158bfb"
+  "gitHead": "3d7dd521cadc2ebcc4989360eeb0bedacd4533ab"
 }

src/connection.ts

@@ -146,2 +146,3 @@ import { AsyncLocalStorage } from 'node:async_hooks';
       'grpc.keepalive_timeout_ms': 15_000,
+      max_receive_message_length: 128 * 1024 * 1024, // 128 MB
       ...channelArgs,
@@ -148,0 +149,0 @@ },

src/errors.ts

@@ -53,2 +53,16 @@ import { ServiceError as GrpcServiceError } from '@grpc/grpc-js';
 /**
+ * Thrown by the client if the Update call timed out or was cancelled.
+ * This doesn't mean the update itself was timed out or cancelled.
+ */
+@SymbolBasedInstanceOfError('WorkflowUpdateRPCTimeoutOrCancelledError')
+export class WorkflowUpdateRPCTimeoutOrCancelledError extends Error {
+  public readonly cause?: Error;
+
+  public constructor(message: string, opts?: { cause: Error }) {
+    super(message);
+    this.cause = opts?.cause;
+  }
+}
+
+/**
  * Thrown the by client while waiting on Workflow execution result if Workflow
@@ -55,0 +69,0 @@ * continues as new.

src/grpc-retry.ts

@@ -110,2 +110,35 @@ import { InterceptingCall, Interceptor, ListenerBuilder, RequesterBuilder, StatusObject } from '@grpc/grpc-js';
 export function isRetryableError(status: StatusObject): boolean {
+  // gRPC INTERNAL status is ambiguous and may be used in many unrelated situations, including:
+  // - TLS errors
+  // - Compression errors
+  // - Errors decoding protobuf messages (either client-side or server-side)
+  // - Transient HTTP/2 network errors
+  // - Failing some server-side request validation
+  // - etc.
+  //
+  // In most case, retrying is useless and would only be a waste of resource.
+  // However, in case of transient network errors, retrying is highly desirable.
+  // Unfortunately, the only way of differenciating between those various cases
+  // is pattern matching the error messages.
+  if (status.code === grpc.status.INTERNAL) {
+    // RST_STREAM code 0 means the HTTP2 request completed with HTTP status 200, but without
+    // the mandatory `grpc-status` header. That's generally due to some HTTP2 proxy or load balancer
+    // that doesn't know about gRPC-specifics. Retrying may help.
+    if (/RST_STREAM with code 0|Call ended without gRPC status/i.test(status.details)) return true;
+
+    // RST_STREAM code 2 is pretty generic and encompasses most HTTP2 protocol errors.
+    // That may for example happen if the client tries to reuse the connection at the
+    // same time as the server initiate graceful closing. Retrying may help.
+    if (/RST_STREAM with code 2/i.test(status.details)) {
+      // Some TLS errors surfaces with message:
+      // "Received RST_STREAM with code 2 triggered by internal client error: […] SSL alert number XX"
+      // At this time, no TLS error is worth retrying, so dismiss those.
+      if (/SSL alert number/i.test(status.details)) return false;
+
+      return true;
+    }
+
+    return false;
+  }
+
   return retryableCodes.has(status.code);
@@ -112,0 +145,0 @@ }

src/index.ts

@@ -42,2 +42,3 @@ /**
 export * from './task-queue-client';
+export { WorkflowUpdateStage } from './workflow-update-stage';
 export {
@@ -44,0 +45,0 @@ WorkerBuildIdVersionSets,

src/schedule-types.ts

@@ -44,3 +44,3 @@ import { checkExtends, Replace } from '@temporalio/common/lib/type-helpers';
      *
-     * @default 1 minute
+     * @default 1 year
      * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
@@ -47,0 +47,0 @@ */

src/workflow-client.ts

@@ -41,2 +41,3 @@ import { status as grpcStatus } from '@grpc/grpc-js';
   WorkflowUpdateFailedError,
+  WorkflowUpdateRPCTimeoutOrCancelledError,
   isGrpcServiceError,
@@ -84,2 +85,4 @@ } from './errors';
 import { mapAsyncIterable } from './iterators-utils';
+import { WorkflowUpdateStage } from './workflow-update-stage';
+import * as workflowUpdateStage from './workflow-update-stage';
 
@@ -123,3 +126,4 @@ /**
    * @throws {@link WorkflowUpdateFailedError} if Update validation fails or if ApplicationFailure is thrown in the Update handler.
-   *
+   * @throws {@link WorkflowUpdateRPCTimeoutOrCancelledError} if this Update call timed out or was cancelled. This doesn't
+   *  mean the update itself was timed out or cancelled.
    * @param def an Update definition as returned from {@link defineUpdate}
@@ -144,4 +148,4 @@ * @param options Update arguments
   /**
-   * Start an Update and receive a handle to the Update.
-   * The Update validator (if present) is run before the handle is returned.
+   * Start an Update and receive a handle to the Update. The Update validator (if present) is run
+   * before the handle is returned.
    *
@@ -151,9 +155,24 @@ * @experimental Update is an experimental feature.
    * @throws {@link WorkflowUpdateFailedError} if Update validation fails.
+   * @throws {@link WorkflowUpdateRPCTimeoutOrCancelledError} if this Update call timed out or was cancelled. This doesn't
+   *  mean the update itself was timed out or cancelled.
    *
    * @param def an Update definition as returned from {@link defineUpdate}
-   * @param options Update arguments
+   * @param options update arguments, and update lifecycle stage to wait for
    *
+   * Currently, startUpdate always waits until a worker is accepting tasks for the workflow and the
+   * update is accepted or rejected, and the options object must be at least
+   * ```ts
+   * {
+   *   waitForStage: WorkflowUpdateStage.ACCEPTED
+   * }
+   * ```
+   * If the update takes arguments, then the options object must additionally contain an `args`
+   * property with an array of argument values.
+   *
    * @example
    * ```ts
-   * const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, { args: [2] });
+   * const updateHandle = await handle.startUpdate(incrementAndGetValueUpdate, {
+   *   args: [2],
+   *   waitForStage: WorkflowUpdateStage.ACCEPTED,
+   * });
    * const updateResult = await updateHandle.result();
@@ -164,3 +183,6 @@ * ```
     def: UpdateDefinition<Ret, Args, Name> | string,
-    options: WorkflowUpdateOptions & { args: Args }
+    options: WorkflowUpdateOptions & {
+      args: Args;
+      waitForStage: WorkflowUpdateStage.ACCEPTED;
+    }
   ): Promise<WorkflowUpdateHandle<Ret>>;
@@ -170,3 +192,6 @@
     def: UpdateDefinition<Ret, Args, Name> | string,
-    options?: WorkflowUpdateOptions & { args?: Args }
+    options: WorkflowUpdateOptions & {
+      args?: Args;
+      waitForStage: WorkflowUpdateStage.ACCEPTED;
+    }
   ): Promise<WorkflowUpdateHandle<Ret>>;
@@ -702,2 +727,24 @@
 
+  protected rethrowUpdateGrpcError(
+    err: unknown,
+    fallbackMessage: string,
+    workflowExecution?: WorkflowExecution
+  ): never {
+    if (isGrpcServiceError(err)) {
+      if (err.code === grpcStatus.DEADLINE_EXCEEDED || err.code === grpcStatus.CANCELLED) {
+        throw new WorkflowUpdateRPCTimeoutOrCancelledError(err.details ?? 'Workflow update call timeout or cancelled', {
+          cause: err,
+        });
+      }
+    }
+
+    if (err instanceof CancelledFailure) {
+      throw new WorkflowUpdateRPCTimeoutOrCancelledError(err.message ?? 'Workflow update call timeout or cancelled', {
+        cause: err,
+      });
+    }
+
+    this.rethrowGrpcError(err, fallbackMessage, workflowExecution);
+  }
+
   protected rethrowGrpcError(err: unknown, fallbackMessage: string, workflowExecution?: WorkflowExecution): never {
@@ -767,5 +814,7 @@ if (isGrpcServiceError(err)) {
   protected async _startUpdateHandler(
-    waitForStage: temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage,
+    waitForStage: WorkflowUpdateStage,
     input: WorkflowStartUpdateInput
   ): Promise<WorkflowStartUpdateOutput> {
+    waitForStage = waitForStage >= WorkflowUpdateStage.ACCEPTED ? waitForStage : WorkflowUpdateStage.ACCEPTED;
+    const waitForStageProto = workflowUpdateStage.toProtoEnum(waitForStage);
     const updateId = input.options?.updateId ?? uuid4();
@@ -776,3 +825,5 @@ const req: temporal.api.workflowservice.v1.IUpdateWorkflowExecutionRequest = {
       firstExecutionRunId: input.firstExecutionRunId,
-      waitPolicy: { lifecycleStage: waitForStage },
+      waitPolicy: {
+        lifecycleStage: waitForStageProto,
+      },
       request: {
@@ -790,8 +841,13 @@ meta: {
     };
+
+    // Repeatedly send UpdateWorkflowExecution until update is >= Accepted or >= `waitForStage` (if
+    // the server receives a request with an update ID that already exists, it responds with
+    // information for the existing update).
     let response: temporal.api.workflowservice.v1.UpdateWorkflowExecutionResponse;
-
     try {
-      response = await this.workflowService.updateWorkflowExecution(req);
+      do {
+        response = await this.workflowService.updateWorkflowExecution(req);
+      } while (response.stage < waitForStageProto);
     } catch (err) {
-      this.rethrowGrpcError(err, 'Workflow Update failed', input.workflowExecution);
+      this.rethrowUpdateGrpcError(err, 'Workflow Update failed', input.workflowExecution);
     }
@@ -844,17 +900,5 @@ return {
       waitPolicy: {
-        lifecycleStage:
-          temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-            .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED,
+        lifecycleStage: workflowUpdateStage.toProtoEnum(WorkflowUpdateStage.COMPLETED),
       },
     };
-
-    // TODO: Users should be able to use client.withDeadline(timestamp) with a
-    // Date (as opposed to a duration) to control the total amount of time
-    // allowed for polling. However, this requires a server change such that the
-    // server swallows the gRPC timeout and instead responds with a well-formed
-    // PollWorkflowExecutionUpdateResponse, indicating that the requested
-    // lifecycle stage has not yet been reached at the time of the deadline
-    // expiry. See https://github.com/temporalio/temporal/issues/4742
-
-    // TODO: When temporal#4742 is released, stop catching DEADLINE_EXCEEDED.
     for (;;) {
@@ -867,5 +911,4 @@ try {
       } catch (err) {
-        if (!(isGrpcServiceError(err) && err.code === grpcStatus.DEADLINE_EXCEEDED)) {
-          throw err;
-        }
+        const wE = typeof workflowExecution.workflowId === 'string' ? workflowExecution : undefined;
+        this.rethrowUpdateGrpcError(err, 'Workflow Update Poll failed', wE as WorkflowExecution);
       }
@@ -1066,6 +1109,5 @@ }
   }: WorkflowHandleOptions): WorkflowHandle<T> {
-    // TODO (dan): Convert to class with this as a protected method
     const _startUpdate = async <Ret, Args extends unknown[]>(
       def: UpdateDefinition<Ret, Args> | string,
-      waitForStage: temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage,
+      waitForStage: WorkflowUpdateStage,
       options?: WorkflowUpdateOptions & { args?: Args }
@@ -1086,3 +1128,3 @@ ): Promise<WorkflowUpdateHandle<Ret>> => {
       const output = await fn(input);
-      return this.createWorkflowUpdateHandle<Ret>(
+      const handle = this.createWorkflowUpdateHandle<Ret>(
         output.updateId,
@@ -1093,2 +1135,6 @@ input.workflowExecution.workflowId,
       );
+      if (!output.outcome && waitForStage === WorkflowUpdateStage.COMPLETED) {
+        await this._pollForUpdateOutcome(handle.updateId, input.workflowExecution);
+      }
+      return handle;
     };
@@ -1149,10 +1195,8 @@
         def: UpdateDefinition<Ret, Args> | string,
-        options?: WorkflowUpdateOptions & { args?: Args }
+        options: WorkflowUpdateOptions & {
+          args?: Args;
+          waitForStage: WorkflowUpdateStage.ACCEPTED;
+        }
       ): Promise<WorkflowUpdateHandle<Ret>> {
-        return await _startUpdate(
-          def,
-          temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-            .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED,
-          options
-        );
+        return await _startUpdate(def, options.waitForStage, options);
       },
@@ -1163,8 +1207,3 @@ async executeUpdate<Ret, Args extends any[]>(
       ): Promise<Ret> {
-        const handle = await _startUpdate(
-          def,
-          temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage
-            .UPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED,
-          options
-        );
+        const handle = await _startUpdate(def, WorkflowUpdateStage.COMPLETED, options);
         return await handle.result();
@@ -1275,5 +1314,3 @@ },
             workflowId,
-            history: await this.getHandle(workflowId, runId)
-              .fetchHistory()
-              .catch((_) => undefined),
+            history: await this.getHandle(workflowId, runId).fetchHistory(),
           }),
@@ -1280,0 +1317,0 @@ { concurrency: intoHistoriesOptions?.concurrency ?? 5 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

527676

increased by3.26%

Number of package files

83

increased by5.06%

Lines of code

10917

increased by2.54%

Dependency changes

• + Added@temporalio/common@1.11.0(transitive)

• + Added@temporalio/proto@1.11.0(transitive)

• - Removed@temporalio/common@1.10.3(transitive)

• - Removed@temporalio/proto@1.10.3(transitive)

• Updated@grpc/grpc-js@^1.10.7

• Updated@temporalio/common@1.11.0

• Updated@temporalio/proto@1.11.0