@temporalio/common 1.3.0 → 1.4.1

package/src/activity-options.ts

@@ -0,0 +1,159 @@
+import type { coresdk } from '@temporalio/proto';
+import { RetryPolicy } from './retry-policy';
+import { checkExtends } from './type-helpers';
+
+// Avoid importing the proto implementation to reduce workflow bundle size
+// Copied from coresdk.workflow_commands.ActivityCancellationType
+export enum ActivityCancellationType {
+  TRY_CANCEL = 0,
+  WAIT_CANCELLATION_COMPLETED = 1,
+  ABANDON = 2,
+}
+
+checkExtends<coresdk.workflow_commands.ActivityCancellationType, ActivityCancellationType>();
+checkExtends<ActivityCancellationType, coresdk.workflow_commands.ActivityCancellationType>();
+
+/**
+ * Options for remote activity invocation
+ */
+export interface ActivityOptions {
+  /**
+   * Identifier to use for tracking the activity in Workflow history.
+   * The `activityId` can be accessed by the activity function.
+   * Does not need to be unique.
+   *
+   * @default an incremental sequence number
+   */
+  activityId?: string;
+
+  /**
+   * Task queue name.
+   *
+   * @default current worker task queue
+   */
+  taskQueue?: string;
+
+  /**
+   * Heartbeat interval. Activity must heartbeat before this interval passes after a last heartbeat or activity start.
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  heartbeatTimeout?: string | number;
+
+  /**
+   * RetryPolicy that define how activity is retried in case of failure. If this is not set, then the server-defined default activity retry policy will be used. To ensure zero retries, set maximum attempts to 1.
+   */
+  retry?: RetryPolicy;
+
+  /**
+   * Maximum time of a single Activity execution attempt.
+Note that the Temporal Server doesn't detect Worker process failures directly. It relies on this timeout to detect that an Activity that didn't complete on time. So this timeout should be as short as the longest possible execution of the Activity body. Potentially long running Activities must specify {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for timely failure detection.
+
+   * Either this option or {@link scheduleToCloseTimeout} is required.
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  startToCloseTimeout?: string | number;
+  /**
+   * Time that the Activity Task can stay in the Task Queue before it is picked up by a Worker. Do not specify this timeout unless using host specific Task Queues for Activity Tasks are being used for routing.
+   * `scheduleToStartTimeout` is always non-retryable. Retrying after this timeout doesn't make sense as it would just put the Activity Task back into the same Task Queue.
+   * @default unlimited
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  scheduleToStartTimeout?: string | number;
+
+  /**
+   * Total time that a workflow is willing to wait for Activity to complete.
+   * `scheduleToCloseTimeout` limits the total time of an Activity's execution including retries (use {@link startToCloseTimeout} to limit the time of a single attempt).
+   *
+   * Either this option or {@link startToCloseTimeout} is required
+   * @default unlimited
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  scheduleToCloseTimeout?: string | number;
+
+  /**
+   * Determines what the SDK does when the Activity is cancelled.
+   * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
+   * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
+   *   cancellation notification. This can block the cancellation for a long time if activity doesn't
+   *   heartbeat or chooses to ignore the cancellation request.
+   * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+   */
+  cancellationType?: ActivityCancellationType;
+
+  /**
+   * Eager dispatch is an optimization that improves the throughput and load on the server for scheduling Activities.
+   * When used, the server will hand out Activity tasks back to the Worker when it completes a Workflow task.
+   * It is available from server version 1.17 behind the `system.enableActivityEagerExecution` feature flag.
+   *
+   * Eager dispatch will only be used if `allowEagerDispatch` is enabled (the default) and {@link taskQueue} is either
+   * omitted or the same as the current Workflow.
+   *
+   * @default true
+   */
+  allowEagerDispatch?: boolean;
+}
+
+/**
+ * Options for local activity invocation
+ */
+export interface LocalActivityOptions {
+  /**
+   * RetryPolicy that defines how an activity is retried in case of failure. If this is not set, then the SDK-defined default activity retry policy will be used.
+   * Note that local activities are always executed at least once, even if maximum attempts is set to 1 due to Workflow task retries.
+   */
+  retry?: RetryPolicy;
+
+  /**
+   * Maximum time the local activity is allowed to execute after the task is dispatched. This
+   * timeout is always retryable.
+   *
+   * Either this option or {@link scheduleToCloseTimeout} is required.
+   * If set, this must be <= {@link scheduleToCloseTimeout}, otherwise, it will be clamped down.
+   *
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  startToCloseTimeout?: string | number;
+
+  /**
+   * Limits time the local activity can idle internally before being executed. That can happen if
+   * the worker is currently at max concurrent local activity executions. This timeout is always
+   * non retryable as all a retry would achieve is to put it back into the same queue. Defaults
+   * to {@link scheduleToCloseTimeout} if not specified and that is set. Must be <=
+   * {@link scheduleToCloseTimeout} when set, otherwise, it will be clamped down.
+   *
+   * @default unlimited
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  scheduleToStartTimeout?: string | number;
+
+  /**
+   * Indicates how long the caller is willing to wait for local activity completion. Limits how
+   * long retries will be attempted. When not specified defaults to the workflow execution
+   * timeout (which may be unset).
+   *
+   * Either this option or {@link startToCloseTimeout} is required.
+   *
+   * @default unlimited
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   */
+  scheduleToCloseTimeout?: string | number;
+
+  /**
+   * If the activity is retrying and backoff would exceed this value, a server side timer will be scheduled for the next attempt.
+   * Otherwise, backoff will happen internally in the SDK.
+   *
+   * @default 1 minute
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+   **/
+  localRetryThreshold?: string | number;
+
+  /**
+   * Determines what the SDK does when the Activity is cancelled.
+   * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
+   * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
+   *   cancellation notification. This can block the cancellation for a long time if activity doesn't
+   *   heartbeat or chooses to ignore the cancellation request.
+   * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+   */
+  cancellationType?: coresdk.workflow_commands.ActivityCancellationType;
+}

package/src/converter/data-converter.ts

@@ -1,6 +1,6 @@
+import { DefaultFailureConverter, FailureConverter } from './failure-converter';
 import { PayloadCodec } from './payload-codec';
-import { PayloadConverter } from './payload-converter';
-import { defaultPayloadConverter } from './payload-converters';
+import { defaultPayloadConverter, PayloadConverter } from './payload-converter';
 
 /**
  * When your data (arguments and return values) is sent over the wire and stored by Temporal Server, it is encoded in
@@ -29,11 +29,20 @@ import { defaultPayloadConverter } from './payload-converters';
 export interface DataConverter {
   /**
    * Path of a file that has a `payloadConverter` named export.
-   * `payloadConverter` should be an instance of a class that implements {@link PayloadConverter}.
+   * `payloadConverter` should be an object that implements {@link PayloadConverter}.
    * If no path is provided, {@link defaultPayloadConverter} is used.
    */
   payloadConverterPath?: string;
 
+  /**
+   * Path of a file that has a `failureConverter` named export.
+   * `failureConverter` should be an object that implements {@link FailureConverter}.
+   * If no path is provided, {@link defaultFailureConverter} is used.
+   *
+   * @experimental
+   */
+  failureConverterPath?: string;
+
   /**
    * An array of {@link PayloadCodec} instances.
    *
@@ -49,10 +58,22 @@ export interface DataConverter {
  */
 export interface LoadedDataConverter {
   payloadConverter: PayloadConverter;
+  failureConverter: FailureConverter;
   payloadCodecs: PayloadCodec[];
 }
 
+/**
+ * The default {@link FailureConverter} used by the SDK.
+ *
+ * Error messages and stack traces are serizalized as plain text.
+ */
+export const defaultFailureConverter: FailureConverter = new DefaultFailureConverter();
+
+/**
+ * A "loaded" data converter that uses the default set of failure and payload converters.
+ */
 export const defaultDataConverter: LoadedDataConverter = {
   payloadConverter: defaultPayloadConverter,
+  failureConverter: defaultFailureConverter,
   payloadCodecs: [],
 };

package/src/converter/failure-converter.ts

@@ -0,0 +1,355 @@
+import {
+  ActivityFailure,
+  ApplicationFailure,
+  CancelledFailure,
+  ChildWorkflowFailure,
+  FAILURE_SOURCE,
+  ProtoFailure,
+  RetryState,
+  ServerFailure,
+  TemporalFailure,
+  TerminatedFailure,
+  TimeoutFailure,
+  TimeoutType,
+} from '../failure';
+import { hasOwnProperties, isRecord } from '../type-helpers';
+import {
+  arrayFromPayloads,
+  defaultPayloadConverter,
+  fromPayloadsAtIndex,
+  PayloadConverter,
+  toPayloads,
+} from './payload-converter';
+
+/**
+ * Stack traces will be cutoff when on of these patterns is matched
+ */
+const CUTOFF_STACK_PATTERNS = [
+  /** Activity execution */
+  /\s+at Activity\.execute \(.*[\\/]worker[\\/](?:src|lib)[\\/]activity\.[jt]s:\d+:\d+\)/,
+  /** Workflow activation */
+  /\s+at Activator\.\S+NextHandler \(.*[\\/]workflow[\\/](?:src|lib)[\\/]internals\.[jt]s:\d+:\d+\)/,
+  /** Workflow run anything in context */
+  /\s+at Script\.runInContext \((?:node:vm|vm\.js):\d+:\d+\)/,
+];
+
+/**
+ * Cuts out the framework part of a stack trace, leaving only user code entries
+ */
+export function cutoffStackTrace(stack?: string): string {
+  const lines = (stack ?? '').split(/\r?\n/);
+  const acc = Array<string>();
+  lineLoop: for (const line of lines) {
+    for (const pattern of CUTOFF_STACK_PATTERNS) {
+      if (pattern.test(line)) break lineLoop;
+    }
+    acc.push(line);
+  }
+  return acc.join('\n');
+}
+
+/**
+ * A `FailureConverter` is responsible to convert from proto `Failure` instances to JS `Errors` and back.
+ *
+ * It is recommended to use the {@link DefaultFailureConverter} and not attempt to customize the default implementation
+ * in order to maintain cross language failure serialization compatibility.
+ *
+ * @experimental
+ */
+export interface FailureConverter {
+  /**
+   * Converts a caught error to a Failure proto message.
+   */
+  errorToFailure(err: unknown): ProtoFailure;
+  /**
+   * Converts a Failure proto message to a JS Error object.
+   */
+  failureToError(err: ProtoFailure): TemporalFailure;
+}
+
+/**
+ * The "shape" of the attributes set as the {@link ProtoFailure.encodedAttributes} payload in case
+ * {@link DefaultEncodedFailureAttributes.encodeCommonAttributes} is set to `true`.
+ */
+export interface DefaultEncodedFailureAttributes {
+  message: string;
+  stack_trace: string;
+}
+
+/**
+ * Options for the {@link DefaultFailureConverter} constructor.
+ */
+export interface DefaultFailureConverterOptions {
+  /**
+   * The {@link PayloadConverter} to use for converting failure attributes.
+   */
+  payloadConverter: PayloadConverter;
+  /**
+   * Whether to encode error messages and stack traces (for encrypting these attributes use a {@link PayloadCodec}).
+   */
+  encodeCommonAttributes: boolean;
+}
+
+/**
+ * Default cross language compatible failure converter.
+ *
+ * By default, it will leave error messages and stack traces as plain text. In order to encrypt those, set
+ * `encodeCommonAttributes` to `true` in the constructor options and make sure to use a {@link PayloadCodec} that can
+ * encrypt / decrypt payloads in your Worker and Client options.
+ *
+ * @experimental
+ */
+export class DefaultFailureConverter implements FailureConverter {
+  public readonly options: DefaultFailureConverterOptions;
+
+  constructor(options?: Partial<DefaultFailureConverterOptions>) {
+    const { encodeCommonAttributes, payloadConverter } = options ?? {};
+    this.options = {
+      encodeCommonAttributes: encodeCommonAttributes ?? false,
+      payloadConverter: payloadConverter ?? defaultPayloadConverter,
+    };
+  }
+
+  /**
+   * Converts a Failure proto message to a JS Error object.
+   *
+   * Does not set common properties, that is done in {@link failureToError}.
+   */
+  failureToErrorInner(failure: ProtoFailure): TemporalFailure {
+    if (failure.applicationFailureInfo) {
+      return new ApplicationFailure(
+        failure.message ?? undefined,
+        failure.applicationFailureInfo.type,
+        Boolean(failure.applicationFailureInfo.nonRetryable),
+        arrayFromPayloads(this.options.payloadConverter, failure.applicationFailureInfo.details?.payloads),
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    if (failure.serverFailureInfo) {
+      return new ServerFailure(
+        failure.message ?? undefined,
+        Boolean(failure.serverFailureInfo.nonRetryable),
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    if (failure.timeoutFailureInfo) {
+      return new TimeoutFailure(
+        failure.message ?? undefined,
+        fromPayloadsAtIndex(
+          this.options.payloadConverter,
+          0,
+          failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads
+        ),
+        failure.timeoutFailureInfo.timeoutType ?? TimeoutType.TIMEOUT_TYPE_UNSPECIFIED
+      );
+    }
+    if (failure.terminatedFailureInfo) {
+      return new TerminatedFailure(failure.message ?? undefined, this.optionalFailureToOptionalError(failure.cause));
+    }
+    if (failure.canceledFailureInfo) {
+      return new CancelledFailure(
+        failure.message ?? undefined,
+        arrayFromPayloads(this.options.payloadConverter, failure.canceledFailureInfo.details?.payloads),
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    if (failure.resetWorkflowFailureInfo) {
+      return new ApplicationFailure(
+        failure.message ?? undefined,
+        'ResetWorkflow',
+        false,
+        arrayFromPayloads(
+          this.options.payloadConverter,
+          failure.resetWorkflowFailureInfo.lastHeartbeatDetails?.payloads
+        ),
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    if (failure.childWorkflowExecutionFailureInfo) {
+      const { namespace, workflowType, workflowExecution, retryState } = failure.childWorkflowExecutionFailureInfo;
+      if (!(workflowType?.name && workflowExecution)) {
+        throw new TypeError('Missing attributes on childWorkflowExecutionFailureInfo');
+      }
+      return new ChildWorkflowFailure(
+        namespace ?? undefined,
+        workflowExecution,
+        workflowType.name,
+        retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    if (failure.activityFailureInfo) {
+      if (!failure.activityFailureInfo.activityType?.name) {
+        throw new TypeError('Missing activityType?.name on activityFailureInfo');
+      }
+      return new ActivityFailure(
+        failure.activityFailureInfo.activityType.name,
+        failure.activityFailureInfo.activityId ?? undefined,
+        failure.activityFailureInfo.retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
+        failure.activityFailureInfo.identity ?? undefined,
+        this.optionalFailureToOptionalError(failure.cause)
+      );
+    }
+    return new TemporalFailure(failure.message ?? undefined, this.optionalFailureToOptionalError(failure.cause));
+  }
+
+  failureToError(failure: ProtoFailure): TemporalFailure {
+    if (failure.encodedAttributes) {
+      const attrs = this.options.payloadConverter.fromPayload<DefaultEncodedFailureAttributes>(
+        failure.encodedAttributes
+      );
+      // Don't apply encodedAttributes unless they conform to an expected schema
+      if (typeof attrs === 'object' && attrs !== null) {
+        const { message, stack_trace } = attrs;
+        // Avoid mutating the argument
+        failure = { ...failure };
+        if (typeof message === 'string') {
+          failure.message = message;
+        }
+        if (typeof stack_trace === 'string') {
+          failure.stackTrace = stack_trace;
+        }
+      }
+    }
+    const err = this.failureToErrorInner(failure);
+    err.stack = failure.stackTrace ?? '';
+    err.failure = failure;
+    return err;
+  }
+
+  errorToFailure(err: unknown): ProtoFailure {
+    const failure = this.errorToFailureInner(err);
+    if (this.options.encodeCommonAttributes) {
+      const { message, stackTrace } = failure;
+      failure.message = 'Encoded failure';
+      failure.stackTrace = '';
+      failure.encodedAttributes = this.options.payloadConverter.toPayload({ message, stack_trace: stackTrace });
+    }
+    return failure;
+  }
+
+  errorToFailureInner(err: unknown): ProtoFailure {
+    if (err instanceof TemporalFailure) {
+      if (err.failure) return err.failure;
+      const base = {
+        message: err.message,
+        stackTrace: cutoffStackTrace(err.stack),
+        cause: this.optionalErrorToOptionalFailure(err.cause),
+        source: FAILURE_SOURCE,
+      };
+
+      if (err instanceof ActivityFailure) {
+        return {
+          ...base,
+          activityFailureInfo: {
+            ...err,
+            activityType: { name: err.activityType },
+          },
+        };
+      }
+      if (err instanceof ChildWorkflowFailure) {
+        return {
+          ...base,
+          childWorkflowExecutionFailureInfo: {
+            ...err,
+            workflowExecution: err.execution,
+            workflowType: { name: err.workflowType },
+          },
+        };
+      }
+      if (err instanceof ApplicationFailure) {
+        return {
+          ...base,
+          applicationFailureInfo: {
+            type: err.type,
+            nonRetryable: err.nonRetryable,
+            details:
+              err.details && err.details.length
+                ? { payloads: toPayloads(this.options.payloadConverter, ...err.details) }
+                : undefined,
+          },
+        };
+      }
+      if (err instanceof CancelledFailure) {
+        return {
+          ...base,
+          canceledFailureInfo: {
+            details:
+              err.details && err.details.length
+                ? { payloads: toPayloads(this.options.payloadConverter, ...err.details) }
+                : undefined,
+          },
+        };
+      }
+      if (err instanceof TimeoutFailure) {
+        return {
+          ...base,
+          timeoutFailureInfo: {
+            timeoutType: err.timeoutType,
+            lastHeartbeatDetails: err.lastHeartbeatDetails
+              ? { payloads: toPayloads(this.options.payloadConverter, err.lastHeartbeatDetails) }
+              : undefined,
+          },
+        };
+      }
+      if (err instanceof TerminatedFailure) {
+        return {
+          ...base,
+          terminatedFailureInfo: {},
+        };
+      }
+      if (err instanceof ServerFailure) {
+        return {
+          ...base,
+          serverFailureInfo: { nonRetryable: err.nonRetryable },
+        };
+      }
+      // Just a TemporalFailure
+      return base;
+    }
+
+    const base = {
+      source: FAILURE_SOURCE,
+    };
+
+    if (isRecord(err) && hasOwnProperties(err, ['message', 'stack'])) {
+      return {
+        ...base,
+        message: String(err.message) ?? '',
+        stackTrace: cutoffStackTrace(String(err.stack)),
+        cause: this.optionalErrorToOptionalFailure(err.cause),
+      };
+    }
+
+    const recommendation = ` [A non-Error value was thrown from your code. We recommend throwing Error objects so that we can provide a stack trace]`;
+
+    if (typeof err === 'string') {
+      return { ...base, message: err + recommendation };
+    }
+    if (typeof err === 'object') {
+      let message = '';
+      try {
+        message = JSON.stringify(err);
+      } catch (_err) {
+        message = String(err);
+      }
+      return { ...base, message: message + recommendation };
+    }
+
+    return { ...base, message: String(err) + recommendation };
+  }
+
+  /**
+   * Converts a Failure proto message to a JS Error object if defined or returns undefined.
+   */
+  optionalFailureToOptionalError(failure: ProtoFailure | undefined | null): TemporalFailure | undefined {
+    return failure ? this.failureToError(failure) : undefined;
+  }
+
+  /**
+   * Converts an error to a Failure proto message if defined or returns undefined
+   */
+  optionalErrorToOptionalFailure(err: unknown): ProtoFailure | undefined {
+    return err ? this.errorToFailure(err) : undefined;
+  }
+}

package/src/converter/payload-codec.ts

@@ -1,4 +1,4 @@
-import { Payload } from './types';
+import { Payload } from '../interfaces';
 
 /**
  * `PayloadCodec` is an optional step that happens between the wire and the {@link PayloadConverter}: