@temporalio/workflow 1.11.8 → 1.12.0-rc.0

package/src/interfaces.ts

@@ -1,7 +1,6 @@
 import type { RawSourceMap } from 'source-map';
 import {
   RetryPolicy,
-  TemporalFailure,
   CommonWorkflowOptions,
   HandlerUnfinishedPolicy,
   SearchAttributes,
@@ -10,6 +9,11 @@ import {
   QueryDefinition,
   Duration,
   VersioningIntent,
+  TypedSearchAttributes,
+  SearchAttributePair,
+  Priority,
+  WorkerDeploymentVersion,
+  VersioningBehavior,
 } from '@temporalio/common';
 import { SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
 import { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow/enums-helpers';
@@ -39,8 +43,16 @@ export interface WorkflowInfo {
    * Indexed information attached to the Workflow Execution
    *
    * This value may change during the lifetime of an Execution.
+   * @deprecated Use {@link typedSearchAttributes} instead.
    */
-  readonly searchAttributes: SearchAttributes;
+  readonly searchAttributes: SearchAttributes; // eslint-disable-line deprecation/deprecation
+
+  /**
+   * Indexed information attached to the Workflow Execution, exposed through an interface.
+   *
+   * This value may change during the lifetime of an Execution.
+   */
+  readonly typedSearchAttributes: TypedSearchAttributes;
 
   /**
    * Non-indexed information attached to the Workflow Execution
@@ -52,6 +64,22 @@ export interface WorkflowInfo {
    */
   readonly parent?: ParentWorkflowInfo;
 
+  /**
+   * The root workflow execution, defined as follows:
+   * 1. A workflow without a parent workflow is its own root workflow.
+   * 2. A workflow with a parent workflow has the same root workflow as
+   * its parent.
+   *
+   * When there is no parent workflow, i.e., the workflow is its own root workflow,
+   * this field is `undefined`.
+   *
+   * Note that Continue-as-New (or reset) propagates the workflow parentage relationship,
+   * and therefore, whether the new workflow has the same root workflow as the original one
+   * depends on whether it had a parent.
+   *
+   */
+  readonly root?: RootWorkflowInfo;
+
   /**
    * Result from the previous Run (present if this is a Cron Workflow or was Continued As New).
    *
@@ -62,7 +90,7 @@ export interface WorkflowInfo {
   /**
    * Failure from the previous Run (present when this Run is a retry, or the last Run of a Cron Workflow failed)
    */
-  readonly lastFailure?: TemporalFailure;
+  readonly lastFailure?: Error;
 
   /**
    * Length of Workflow history up until the current Workflow Task.
@@ -169,10 +197,28 @@ export interface WorkflowInfo {
    * task was completed by a worker without a Build ID. If this worker is the one executing this
    * task for the first time and has a Build ID set, then its ID will be used. This value may change
    * over the lifetime of the workflow run, but is deterministic and safe to use for branching.
+   *
+   * @deprecated Use `currentDeploymentVersion` instead
    */
   readonly currentBuildId?: string;
 
+  /**
+   * The Deployment Version of the worker which executed the current Workflow Task. May be undefined
+   * if the task was completed by a worker without a Deployment Version. If this worker is the one
+   * executing this task for the first time and has a Deployment Version set, then its ID will be
+   * used. This value may change over the lifetime of the workflow run, but is deterministic and
+   * safe to use for branching.
+   *
+   * @experimental Deployment based versioning is experimental and may change in the future.
+   */
+  readonly currentDeploymentVersion?: WorkerDeploymentVersion;
+
   readonly unsafe: UnsafeWorkflowInfo;
+
+  /**
+   * Priority of this workflow
+   */
+  readonly priority?: Priority;
 }
 
 /**
@@ -213,6 +259,11 @@ export interface ParentWorkflowInfo {
   namespace: string;
 }
 
+export interface RootWorkflowInfo {
+  workflowId: string;
+  runId: string;
+}
+
 /**
  * Not an actual error, used by the Workflow runtime to abort execution when {@link continueAsNew} is called
  */
@@ -251,15 +302,27 @@ export interface ContinueAsNewOptions {
   memo?: Record<string, unknown>;
   /**
    * Searchable attributes to attach to next Workflow run
+   * @deprecated Use {@link typedSearchAttributes} instead.
+   */
+  searchAttributes?: SearchAttributes; // eslint-disable-line deprecation/deprecation
+  /**
+   * Specifies additional indexed information to attach to the Workflow Execution. More info:
+   * https://docs.temporal.io/docs/typescript/search-attributes
+   *
+   * Values are always converted using {@link JsonPayloadConverter}, even when a custom data converter is provided.
+   * Note that search attributes are not encoded, as such, do not include any sensitive information.
+   *
+   * If both {@link searchAttributes} and {@link typedSearchAttributes} are provided, conflicting keys will be overwritten
+   * by {@link typedSearchAttributes}.
    */
-  searchAttributes?: SearchAttributes;
+  typedSearchAttributes?: SearchAttributePair[] | TypedSearchAttributes;
   /**
    * When using the Worker Versioning feature, specifies whether this Workflow should
    * Continue-as-New onto a worker with a compatible Build Id or not. See {@link VersioningIntent}.
    *
    * @default 'COMPATIBLE'
    *
-   * @experimental
+   * @experimental The Worker Versioning API is still being designed. Major changes are expected.
    */
   versioningIntent?: VersioningIntent;
 }
@@ -390,7 +453,7 @@ export const [encodeParentClosePolicy, decodeParentClosePolicy] = makeProtoEnumC
   'PARENT_CLOSE_POLICY_'
 );
 
-export interface ChildWorkflowOptions extends CommonWorkflowOptions {
+export interface ChildWorkflowOptions extends Omit<CommonWorkflowOptions, 'workflowIdConflictPolicy'> {
   /**
    * Workflow id to use when starting. If not specified a UUID is generated. Note that it is
    * dangerous as in case of client side retries no deduplication will happen based on the
@@ -429,7 +492,7 @@ export interface ChildWorkflowOptions extends CommonWorkflowOptions {
    *
    * @default 'COMPATIBLE'
    *
-   * @experimental
+   * @experimental The Worker Versioning API is still being designed. Major changes are expected.
    */
   versioningIntent?: VersioningIntent;
 }
@@ -538,6 +601,16 @@ export type Handler<
  */
 export type DefaultSignalHandler = (signalName: string, ...args: unknown[]) => void | Promise<void>;
 
+/**
+ * A handler function accepting update calls for non-registered update names.
+ */
+export type DefaultUpdateHandler = (updateName: string, ...args: unknown[]) => Promise<unknown> | unknown;
+
+/**
+ * A handler function accepting query calls for non-registered query names.
+ */
+export type DefaultQueryHandler = (queryName: string, ...args: unknown[]) => unknown;
+
 /**
  * A validation function capable of accepting the arguments for a given UpdateDefinition.
  */
@@ -565,4 +638,5 @@ export type UpdateHandlerOptions<Args extends any[]> = {
 export interface ActivationCompletion {
   commands: coresdk.workflow_commands.IWorkflowCommand[];
   usedInternalFlags: number[];
+  versioningBehavior?: VersioningBehavior;
 }

package/src/internals.ts

@@ -19,10 +19,15 @@ import {
   WorkflowUpdateType,
   WorkflowUpdateValidatorType,
   mapFromPayloads,
-  searchAttributePayloadConverter,
   fromPayloadsAtIndex,
-  SearchAttributes,
+  WorkflowFunctionWithOptions,
+  VersioningBehavior,
+  WorkflowDefinitionOptions,
 } from '@temporalio/common';
+import {
+  decodeSearchAttributes,
+  decodeTypedSearchAttributes,
+} from '@temporalio/common/lib/converter/payload-search-attributes';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow';
 import type { coresdk, temporal } from '@temporalio/proto';
@@ -41,6 +46,8 @@ import {
   WorkflowInfo,
   WorkflowCreateOptionsInternal,
   ActivationCompletion,
+  DefaultUpdateHandler,
+  DefaultQueryHandler,
 } from './interfaces';
 import { type SinkCall } from './sinks';
 import { untrackPromise } from './stack-helpers';
@@ -189,6 +196,16 @@ export class Activator implements ActivationHandler {
    */
   defaultSignalHandler?: DefaultSignalHandler;
 
+  /**
+   * A update handler that catches calls for non-registered update names.
+   */
+  defaultUpdateHandler?: DefaultUpdateHandler;
+
+  /**
+   * A query handler that catches calls for non-registered query names.
+   */
+  defaultQueryHandler?: DefaultQueryHandler;
+
   /**
    * Source map file for looking up the source files in response to __enhanced_stack_trace
    */
@@ -204,6 +221,38 @@ export class Activator implements ActivationHandler {
     childToParent: new Map(),
   };
 
+  /**
+   * The error that caused the current Workflow Task to fail. Sets if a non-`TemporalFailure`
+   * error bubbles up out of the Workflow function, or out of a Signal or Update handler. We
+   * capture errors this way because those functions are not technically awaited when started,
+   * but left to run asynchronously. There is therefore no real "parent" function that can
+   * directly handle those errors, and not capturing it would result in an Unhandled Promise
+   * Rejection. So instead, we buffer the error here, to then be processed in the context
+   * of our own synchronous Activation handling event loop.
+   *
+   * Our code does a best effort to stop processing the current activation as soon as possible
+   * after this field is set:
+   *  - If an error is thrown while executing code synchronously (e.g. anything before the
+   *    first `await` statement in a Workflow function or a signal/update handler), the error
+   *    will be _immediately_ rethrown, which will prevent execution of further jobs in the
+   *    current activation. We know we're currently running code synchronously thanks to the
+   *    `rethrowSynchronously` flag below.
+   *  - It an error is thrown while executing microtasks, then the error will be rethrown on
+   *    the next call to `tryUnblockConditions()`.
+   *
+   * Unfortunately, there's no way for us to prevent further execution of microtasks that have
+   * already been scheduled, nor those that will be recursively scheduled from those microtasks.
+   * Should more errors get thrown while settling microtasks, those will be ignored (i.e. only
+   * the first captured error is preserved).
+   */
+  public workflowTaskError: unknown;
+
+  /**
+   * Set to true when running synchronous code (e.g. while processing activation jobs and when calling
+   * `tryUnblockConditions()`). While this flag is set, it is safe to let errors bubble up.
+   */
+  public rethrowSynchronously = false;
+
   public readonly rootScope = new RootCancellationScope();
 
   /**
@@ -336,7 +385,7 @@ export class Activator implements ActivationHandler {
   /**
    * Reference to the current Workflow, initialized when a Workflow is started
    */
-  public workflow?: Workflow;
+  public workflow?: Workflow | WorkflowFunctionWithOptions<any[], any>;
 
   /**
    * Information about the current Workflow
@@ -370,12 +419,17 @@ export class Activator implements ActivationHandler {
   sinkCalls = Array<SinkCall>();
 
   /**
-   * A nanosecond resolution time function, externally injected
+   * A nanosecond resolution time function, externally injected. This is used to
+   * precisely sort logs entries emitted from the Workflow Context vs those emitted
+   * from other sources (e.g. main thread, Core, etc).
    */
   public readonly getTimeOfDay: () => bigint;
 
   public readonly registeredActivityNames: Set<string>;
 
+  public versioningBehavior?: VersioningBehavior;
+  public workflowDefinitionOptionsGetter?: () => WorkflowDefinitionOptions;
+
   constructor({
     info,
     now,
@@ -448,6 +502,7 @@ export class Activator implements ActivationHandler {
     return {
       commands: this.commands.splice(0),
       usedInternalFlags: [...this.knownFlags],
+      versioningBehavior: this.versioningBehavior,
     };
   }
 
@@ -478,8 +533,10 @@ export class Activator implements ActivationHandler {
     // Most things related to initialization have already been handled in the constructor
     this.mutateWorkflowInfo((info) => ({
       ...info,
-      searchAttributes:
-        (mapFromPayloads(searchAttributePayloadConverter, searchAttributes?.indexedFields) as SearchAttributes) ?? {},
+
+      searchAttributes: decodeSearchAttributes(searchAttributes?.indexedFields),
+      typedSearchAttributes: decodeTypedSearchAttributes(searchAttributes?.indexedFields),
+
       memo: mapFromPayloads(this.payloadConverter, memo?.fields),
       lastResult: fromPayloadsAtIndex(this.payloadConverter, 0, lastCompletionResult?.payloads),
       lastFailure:
@@ -487,6 +544,9 @@ export class Activator implements ActivationHandler {
           ? this.failureConverter.failureToError(continuedFailure, this.payloadConverter)
           : undefined,
     }));
+    if (this.workflowDefinitionOptionsGetter) {
+      this.versioningBehavior = this.workflowDefinitionOptionsGetter().versioningBehavior;
+    }
   }
 
   public cancelWorkflow(_activation: coresdk.workflow_activation.ICancelWorkflow): void {
@@ -523,16 +583,6 @@ export class Activator implements ActivationHandler {
     }
   }
 
-  public resolveNexusOperationStart(_activation: coresdk.workflow_activation.IResolveNexusOperationStart): void {
-    // This will never be called as we can't produce Nexus-related commands anyway
-    throw new Error('Nexus is not yet implemented');
-  }
-
-  public resolveNexusOperation(_activation: coresdk.workflow_activation.IResolveNexusOperation): void {
-    // This will never be called as we can't produce Nexus-related commands anyway
-    throw new Error('Nexus is not yet implemented');
-  }
-
   public resolveChildWorkflowExecutionStart(
     activation: coresdk.workflow_activation.IResolveChildWorkflowExecutionStart
   ): void {
@@ -587,9 +637,21 @@ export class Activator implements ActivationHandler {
     }
   }
 
+  public resolveNexusOperationStart(_: coresdk.workflow_activation.IResolveNexusOperationStart): void {
+    throw new Error('TODO');
+  }
+
+  public resolveNexusOperation(_: coresdk.workflow_activation.IResolveNexusOperation): void {
+    throw new Error('TODO');
+  }
+
   // Intentionally non-async function so this handler doesn't show up in the stack trace
   protected queryWorkflowNextHandler({ queryName, args }: QueryInput): Promise<unknown> {
-    const fn = this.queryHandlers.get(queryName)?.handler;
+    let fn = this.queryHandlers.get(queryName)?.handler;
+    if (fn === undefined && this.defaultQueryHandler !== undefined) {
+      fn = this.defaultQueryHandler.bind(undefined, queryName);
+    }
+    // No handler or default registered, fail.
     if (fn === undefined) {
       const knownQueryTypes = [...this.queryHandlers.keys()].join(' ');
       // Fail the query
@@ -599,6 +661,7 @@ export class Activator implements ActivationHandler {
         )
       );
     }
+    // Execute handler.
     try {
       const ret = fn(...args);
       if (ret instanceof Promise) {
@@ -643,8 +706,20 @@ export class Activator implements ActivationHandler {
     if (!protocolInstanceId) {
       throw new TypeError('Missing activation update protocolInstanceId');
     }
-    const entry = this.updateHandlers.get(name);
-    if (!entry) {
+
+    const entry =
+      this.updateHandlers.get(name) ??
+      (this.defaultUpdateHandler
+        ? {
+            handler: this.defaultUpdateHandler.bind(undefined, name),
+            validator: undefined,
+            // Default to a warning policy.
+            unfinishedPolicy: HandlerUnfinishedPolicy.WARN_AND_ABANDON,
+          }
+        : null);
+
+    // If we don't have an entry from either source, buffer and return
+    if (entry === null) {
       this.bufferedUpdates.push(activation);
       return;
     }
@@ -713,7 +788,7 @@ export class Activator implements ActivationHandler {
           if (error instanceof TemporalFailure) {
             this.rejectUpdate(protocolInstanceId, error);
           } else {
-            throw error;
+            this.handleWorkflowFailure(error);
           }
         })
         .finally(() => this.inProgressUpdates.delete(updateId));
@@ -736,13 +811,21 @@ export class Activator implements ActivationHandler {
   public dispatchBufferedUpdates(): void {
     const bufferedUpdates = this.bufferedUpdates;
     while (bufferedUpdates.length) {
-      const foundIndex = bufferedUpdates.findIndex((update) => this.updateHandlers.has(update.name as string));
-      if (foundIndex === -1) {
-        // No buffered Updates have a handler yet.
-        break;
+      // We have a default update handler, so all updates are dispatchable.
+      if (this.defaultUpdateHandler) {
+        const update = bufferedUpdates.shift();
+        // Logically, this must be defined as we're in the loop.
+        // But Typescript doesn't know that so we use a non-null assertion (!).
+        this.doUpdate(update!);
+      } else {
+        const foundIndex = bufferedUpdates.findIndex((update) => this.updateHandlers.has(update.name as string));
+        if (foundIndex === -1) {
+          // No buffered Updates have a handler yet.
+          break;
+        }
+        const [update] = bufferedUpdates.splice(foundIndex, 1);
+        this.doUpdate(update);
       }
-      const [update] = bufferedUpdates.splice(foundIndex, 1);
-      this.doUpdate(update);
     }
   }
 
@@ -840,6 +923,8 @@ export class Activator implements ActivationHandler {
   }
 
   public warnIfUnfinishedHandlers(): void {
+    if (this.workflowTaskError) return;
+
     const getWarnable = (handlerExecutions: Iterable<MessageHandlerExecution>): MessageHandlerExecution[] => {
       return Array.from(handlerExecutions).filter(
         (ex) => ex.unfinishedPolicy === HandlerUnfinishedPolicy.WARN_AND_ABANDON
@@ -951,17 +1036,12 @@ export class Activator implements ActivationHandler {
    * Transforms failures into a command to be sent to the server.
    * Used to handle any failure emitted by the Workflow.
    */
-  async handleWorkflowFailure(error: unknown): Promise<void> {
+  handleWorkflowFailure(error: unknown): void {
     if (this.cancelled && isCancellation(error)) {
       this.pushCommand({ cancelWorkflowExecution: {} }, true);
     } else if (error instanceof ContinueAsNew) {
       this.pushCommand({ continueAsNewWorkflowExecution: error.command }, true);
-    } else {
-      if (!(error instanceof TemporalFailure)) {
-        // This results in an unhandled rejection which will fail the activation
-        // preventing it from completing.
-        throw error;
-      }
+    } else if (error instanceof TemporalFailure) {
       // Fail the workflow. We do not want to issue unfinishedHandlers warnings. To achieve that, we
       // mark all handlers as completed now.
       this.inProgressSignals.clear();
@@ -974,9 +1054,29 @@ export class Activator implements ActivationHandler {
         },
         true
       );
+    } else {
+      this.recordWorkflowTaskError(error);
     }
   }
 
+  recordWorkflowTaskError(error: unknown): void {
+    // Only keep the first error that bubbles up; subsequent errors will be ignored.
+    if (this.workflowTaskError === undefined) this.workflowTaskError = error;
+
+    // Immediately rethrow the error if we know it is safe to do so (i.e. we are not running async
+    // microtasks). Otherwise, the error will be rethrown whenever we get an opportunity to do so,
+    // e.g. the next time `tryUnblockConditions()` is called.
+    if (this.rethrowSynchronously) this.maybeRethrowWorkflowTaskError();
+  }
+
+  /**
+   * If a Workflow Task error was captured, and we are running in synchronous mode,
+   * then bubble it up now. This is safe to call even if there is no error to rethrow.
+   */
+  maybeRethrowWorkflowTaskError(): void {
+    if (this.workflowTaskError) throw this.workflowTaskError;
+  }
+
   private completeQuery(queryId: string, result: unknown): void {
     this.pushCommand({
       respondToQuery: { queryId, succeeded: { response: this.payloadConverter.toPayload(result) } },

package/src/logs.ts

@@ -5,6 +5,7 @@ import { type Sink, type Sinks, proxySinks } from './sinks';
 import { isCancellation } from './errors';
 import { WorkflowInfo, ContinueAsNew } from './interfaces';
 import { assertInWorkflowContext } from './global-attributes';
+import { currentUpdateInfo, inWorkflowContext } from './workflow';
 
 export interface WorkflowLogger extends Sink {
   trace(message: string, attrs?: Record<string, unknown>): void;
@@ -117,11 +118,20 @@ export function executeWithLifecycleLogging(fn: () => Promise<unknown>): Promise
  * Note that this function may be called from outside of the Workflow context (eg. by the worker itself).
  */
 export function workflowLogAttributes(info: WorkflowInfo): Record<string, unknown> {
-  return {
+  const attributes: { [key: string]: string } = {
     namespace: info.namespace,
     taskQueue: info.taskQueue,
     workflowId: info.workflowId,
     runId: info.runId,
     workflowType: info.workflowType,
   };
+  if (inWorkflowContext()) {
+    const updateInfo = currentUpdateInfo();
+    if (updateInfo) {
+      // Add update info if it exists
+      attributes['updateId'] = updateInfo.id;
+      attributes['updateName'] = updateInfo.name;
+    }
+  }
+  return attributes;
 }