@temporalio/workflow 1.8.6 → 1.9.0

package/src/internals.ts

@@ -12,15 +12,18 @@ import {
   WorkflowExecutionAlreadyStartedError,
   WorkflowQueryType,
   WorkflowSignalType,
+  WorkflowUpdateType,
   ProtoFailure,
+  WorkflowUpdateValidatorType,
+  ApplicationFailure,
 } from '@temporalio/common';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
-import { checkExtends, SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
+import { checkExtends } from '@temporalio/common/lib/type-helpers';
 import type { coresdk } from '@temporalio/proto';
 import { alea, RNG } from './alea';
 import { RootCancellationScope } from './cancellation-scope';
-import { DeterminismViolationError, isCancellation } from './errors';
-import { QueryInput, SignalInput, WorkflowExecuteInput, WorkflowInterceptors } from './interceptors';
+import { DeterminismViolationError, LocalActivityDoBackoff, isCancellation } from './errors';
+import { QueryInput, SignalInput, UpdateInput, WorkflowExecuteInput, WorkflowInterceptors } from './interceptors';
 import {
   ContinueAsNew,
   DefaultSignalHandler,
@@ -31,10 +34,10 @@ import {
   WorkflowInfo,
   WorkflowCreateOptionsInternal,
 } from './interfaces';
-import { SinkCall } from './sinks';
+import { type SinkCall } from './sinks';
 import { untrackPromise } from './stack-helpers';
 import pkg from './pkg';
-import { maybeGetActivatorUntyped } from './global-attributes';
+import { executeWithLifecycleLogging } from './logs';
 
 enum StartChildWorkflowExecutionFailedCause {
   START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_UNSPECIFIED = 0,
@@ -67,16 +70,6 @@ export interface Condition {
   resolve(): void;
 }
 
-/**
- * A class that acts as a marker for this special result type
- */
-@SymbolBasedInstanceOfError('LocalActivityDoBackoff')
-export class LocalActivityDoBackoff extends Error {
-  constructor(public readonly backoff: coresdk.activity_result.IDoBackoff) {
-    super();
-  }
-}
-
 export type ActivationHandlerFunction<K extends keyof coresdk.workflow_activation.IWorkflowActivationJob> = (
   activation: NonNullable<coresdk.workflow_activation.IWorkflowActivationJob[K]>
 ) => void;
@@ -110,6 +103,11 @@ export class Activator implements ActivationHandler {
     cancelWorkflow: new Map<number, Completion>(),
   };
 
+  /**
+   * Holds buffered Update calls until a handler is registered
+   */
+  readonly bufferedUpdates = Array<coresdk.workflow_activation.IDoUpdate>();
+
   /**
    * Holds buffered signal calls until a handler is registered
    */
@@ -124,6 +122,11 @@ export class Activator implements ActivationHandler {
    */
   protected readonly bufferedQueries = Array<coresdk.workflow_activation.IQueryWorkflow>();
 
+  /**
+   * Mapping of update name to handler and validator
+   */
+  readonly updateHandlers = new Map<string, { handler: WorkflowUpdateType; validator?: WorkflowUpdateValidatorType }>();
+
   /**
    * Mapping of signal name to handler
    */
@@ -253,7 +256,7 @@ export class Activator implements ActivationHandler {
   /**
    * Information about the current Workflow
    */
-  public readonly info: WorkflowInfo;
+  public info: WorkflowInfo;
 
   /**
    * A deterministic RNG, used by the isolate's overridden Math.random
@@ -310,6 +313,10 @@ export class Activator implements ActivationHandler {
     }
   }
 
+  mutateWorkflowInfo(fn: (info: WorkflowInfo) => WorkflowInfo): void {
+    this.info = fn(this.info);
+  }
+
   protected getStackTraces(): Stack[] {
     const { childToParent, promiseToStack } = this.promiseStackStore;
     const internalNodes = [...childToParent.values()].reduce((acc, curr) => {
@@ -367,8 +374,7 @@ export class Activator implements ActivationHandler {
     try {
       promise = workflow(...args);
     } finally {
-      // Guarantee this runs even if there was an exception when invoking the Workflow function
-      // Otherwise this Workflow will now be queryable.
+      // Queries must be handled even if there was an exception when invoking the Workflow function.
       this.workflowFunctionWasCalled = true;
       // Empty the buffer
       const buffer = this.bufferedQueries.splice(0);
@@ -381,11 +387,14 @@ export class Activator implements ActivationHandler {
 
   public startWorkflow(activation: coresdk.workflow_activation.IStartWorkflow): void {
     const execute = composeInterceptors(this.interceptors.inbound, 'execute', this.startWorkflowNextHandler.bind(this));
+
     untrackPromise(
-      execute({
-        headers: activation.headers ?? {},
-        args: arrayFromPayloads(this.payloadConverter, activation.arguments),
-      }).then(this.completeWorkflow.bind(this), this.handleWorkflowFailure.bind(this))
+      executeWithLifecycleLogging(() =>
+        execute({
+          headers: activation.headers ?? {},
+          args: arrayFromPayloads(this.payloadConverter, activation.arguments),
+        })
+      ).then(this.completeWorkflow.bind(this), this.handleWorkflowFailure.bind(this))
     );
   }
 
@@ -480,7 +489,7 @@ export class Activator implements ActivationHandler {
     }
   }
 
-  // Intentionally not made function async so this handler doesn't show up in the stack trace
+  // 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);
     if (fn === undefined) {
@@ -530,6 +539,128 @@ export class Activator implements ActivationHandler {
     );
   }
 
+  public doUpdate(activation: coresdk.workflow_activation.IDoUpdate): void {
+    const { id: updateId, protocolInstanceId, name, headers, runValidator } = activation;
+    if (!updateId) {
+      throw new TypeError('Missing activation update id');
+    }
+    if (!name) {
+      throw new TypeError('Missing activation update name');
+    }
+    if (!protocolInstanceId) {
+      throw new TypeError('Missing activation update protocolInstanceId');
+    }
+    if (!this.updateHandlers.has(name)) {
+      this.bufferedUpdates.push(activation);
+      return;
+    }
+
+    const makeInput = (): UpdateInput => ({
+      updateId,
+      args: arrayFromPayloads(this.payloadConverter, activation.input),
+      name,
+      headers: headers ?? {},
+    });
+
+    // The implementation below is responsible for upholding, and constrained
+    // by, the following contract:
+    //
+    // 1. If no validator is present then validation interceptors will not be run.
+    //
+    // 2. During validation, any error must fail the Update; during the Update
+    //    itself, Temporal errors fail the Update whereas other errors fail the
+    //    activation.
+    //
+    // 3. The handler must not see any mutations of the arguments made by the
+    //    validator.
+    //
+    // 4. Any error when decoding/deserializing input must be caught and result
+    //    in rejection of the Update before it is accepted, even if there is no
+    //    validator.
+    //
+    // 5. The initial synchronous portion of the (async) Update handler should
+    //    be executed after the (sync) validator completes such that there is
+    //    minimal opportunity for a different concurrent task to be scheduled
+    //    between them.
+    //
+    // 6. The stack trace view provided in the Temporal UI must not be polluted
+    //    by promises that do not derive from user code. This implies that
+    //    async/await syntax may not be used.
+    //
+    // Note that there is a deliberately unhandled promise rejection below.
+    // These are caught elsewhere and fail the corresponding activation.
+    let input: UpdateInput;
+    try {
+      if (runValidator && this.updateHandlers.get(name)?.validator) {
+        const validate = composeInterceptors(
+          this.interceptors.inbound,
+          'validateUpdate',
+          this.validateUpdateNextHandler.bind(this)
+        );
+        validate(makeInput());
+      }
+      input = makeInput();
+    } catch (error) {
+      this.rejectUpdate(protocolInstanceId, error);
+      return;
+    }
+    const execute = composeInterceptors(this.interceptors.inbound, 'handleUpdate', this.updateNextHandler.bind(this));
+    this.acceptUpdate(protocolInstanceId);
+    untrackPromise(
+      execute(input)
+        .then((result) => this.completeUpdate(protocolInstanceId, result))
+        .catch((error) => {
+          if (error instanceof TemporalFailure) {
+            this.rejectUpdate(protocolInstanceId, error);
+          } else {
+            throw error;
+          }
+        })
+    );
+  }
+
+  protected async updateNextHandler({ name, args }: UpdateInput): Promise<unknown> {
+    const entry = this.updateHandlers.get(name);
+    if (!entry) {
+      return Promise.reject(new IllegalStateError(`No registered update handler for update: ${name}`));
+    }
+    const { handler } = entry;
+    return await handler(...args);
+  }
+
+  protected validateUpdateNextHandler({ name, args }: UpdateInput): void {
+    const { validator } = this.updateHandlers.get(name) ?? {};
+    if (validator) {
+      validator(...args);
+    }
+  }
+
+  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;
+      }
+      const [update] = bufferedUpdates.splice(foundIndex, 1);
+      this.doUpdate(update);
+    }
+  }
+
+  public rejectBufferedUpdates(): void {
+    while (this.bufferedUpdates.length) {
+      const update = this.bufferedUpdates.shift();
+      if (update) {
+        this.rejectUpdate(
+          /* eslint-disable @typescript-eslint/no-non-null-assertion */
+          update.protocolInstanceId!,
+          ApplicationFailure.nonRetryable(`No registered handler for update: ${update.name}`)
+        );
+      }
+    }
+  }
+
   public async signalWorkflowNextHandler({ signalName, args }: SignalInput): Promise<void> {
     const fn = this.signalHandlers.get(signalName);
     if (fn) {
@@ -537,7 +668,7 @@ export class Activator implements ActivationHandler {
     } else if (this.defaultSignalHandler) {
       return await this.defaultSignalHandler(signalName, ...args);
     } else {
-      throw new IllegalStateError(`No registered signal handler for signal ${signalName}`);
+      throw new IllegalStateError(`No registered signal handler for signal: ${signalName}`);
     }
   }
 
@@ -572,7 +703,7 @@ export class Activator implements ActivationHandler {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         this.signalWorkflow(bufferedSignals.shift()!);
       } else {
-        const foundIndex = bufferedSignals.findIndex((signal) => this.signalHandlers.has(signal.signalName ?? ''));
+        const foundIndex = bufferedSignals.findIndex((signal) => this.signalHandlers.has(signal.signalName as string));
         if (foundIndex === -1) break;
         const [signal] = bufferedSignals.splice(foundIndex, 1);
         this.signalWorkflow(signal);
@@ -660,6 +791,25 @@ export class Activator implements ActivationHandler {
     });
   }
 
+  private acceptUpdate(protocolInstanceId: string): void {
+    this.pushCommand({ updateResponse: { protocolInstanceId, accepted: {} } });
+  }
+
+  private completeUpdate(protocolInstanceId: string, result: unknown): void {
+    this.pushCommand({
+      updateResponse: { protocolInstanceId, completed: this.payloadConverter.toPayload(result) },
+    });
+  }
+
+  private rejectUpdate(protocolInstanceId: string, error: unknown): void {
+    this.pushCommand({
+      updateResponse: {
+        protocolInstanceId,
+        rejected: this.errorToFailure(ensureTemporalFailure(error)),
+      },
+    });
+  }
+
   /** Consume a completion if it exists in Workflow state */
   private maybeConsumeCompletion(type: keyof Activator['completions'], taskSeq: number): Completion | undefined {
     const completion = this.completions[type].get(taskSeq);
@@ -698,18 +848,6 @@ export class Activator implements ActivationHandler {
   }
 }
 
-export function maybeGetActivator(): Activator | undefined {
-  return maybeGetActivatorUntyped() as Activator | undefined;
-}
-
-export function getActivator(): Activator {
-  const activator = maybeGetActivator();
-  if (activator === undefined) {
-    throw new IllegalStateError('Workflow uninitialized');
-  }
-  return activator;
-}
-
 function getSeq<T extends { seq?: number | null }>(activation: T): number {
   const seq = activation.seq;
   if (seq === undefined || seq === null) {

package/src/logs.ts

@@ -0,0 +1,118 @@
+import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { untrackPromise } from './stack-helpers';
+import { type Sink, type Sinks, proxySinks } from './sinks';
+import { isCancellation } from './errors';
+import { WorkflowInfo, ContinueAsNew } from './interfaces';
+import { assertInWorkflowContext } from './global-attributes';
+
+export interface WorkflowLogger extends Sink {
+  trace(message: string, attrs?: Record<string, unknown>): void;
+  debug(message: string, attrs?: Record<string, unknown>): void;
+  info(message: string, attrs?: Record<string, unknown>): void;
+  warn(message: string, attrs?: Record<string, unknown>): void;
+  error(message: string, attrs?: Record<string, unknown>): void;
+}
+
+/**
+ * Sink interface for forwarding logs from the Workflow sandbox to the Worker
+ *
+ * @deprecated Do not use LoggerSinks directly. To log from Workflow code, use the `log` object
+ *             exported by the `@temporalio/workflow` package. To capture log messages emitted
+ *             by Workflow code, set the {@link Runtime.logger} property.
+ */
+export interface LoggerSinksDeprecated extends Sinks {
+  /**
+   * @deprecated Do not use LoggerSinks directly. To log from Workflow code, use the `log` object
+   *             exported by the `@temporalio/workflow` package. To capture log messages emitted
+   *             by Workflow code, set the {@link Runtime.logger} property.
+   */
+  defaultWorkerLogger: WorkflowLogger;
+}
+
+/**
+ * Sink interface for forwarding logs from the Workflow sandbox to the Worker
+ */
+export interface LoggerSinksInternal extends Sinks {
+  __temporal_logger: WorkflowLogger;
+}
+
+const loggerSink = proxySinks<LoggerSinksInternal>().__temporal_logger;
+
+/**
+ * Symbol used by the SDK logger to extract a timestamp from log attributes.
+ * Also defined in `worker/logger.ts` - intentionally not shared.
+ */
+const LogTimestamp = Symbol.for('log_timestamp');
+
+/**
+ * Default workflow logger.
+ *
+ * This logger is replay-aware and will omit log messages on workflow replay. Messages emitted by this logger are
+ * funnelled through a sink that forwards them to the logger registered on {@link Runtime.logger}.
+ *
+ * Notice that since sinks are used to power this logger, any log attributes must be transferable via the
+ * {@link https://nodejs.org/api/worker_threads.html#worker_threads_port_postmessage_value_transferlist | postMessage}
+ * API.
+ *
+ * NOTE: Specifying a custom logger through {@link defaultSink} or by manually registering a sink named
+ * `defaultWorkerLogger` has been deprecated. Please use {@link Runtime.logger} instead.
+ */
+export const log: WorkflowLogger = Object.fromEntries(
+  (['trace', 'debug', 'info', 'warn', 'error'] as Array<keyof WorkflowLogger>).map((level) => {
+    return [
+      level,
+      (message: string, attrs?: Record<string, unknown>) => {
+        const activator = assertInWorkflowContext('Workflow.log(...) may only be used from workflow context.');
+        const getLogAttributes = composeInterceptors(activator.interceptors.outbound, 'getLogAttributes', (a) => a);
+        return loggerSink[level](message, {
+          // Inject the call time in nanosecond resolution as expected by the worker logger.
+          [LogTimestamp]: activator.getTimeOfDay(),
+          ...getLogAttributes(workflowLogAttributes(activator.info)),
+          ...attrs,
+        });
+      },
+    ];
+  })
+) as any;
+
+export function executeWithLifecycleLogging(fn: () => Promise<unknown>): Promise<unknown> {
+  log.debug('Workflow started');
+  const p = fn().then(
+    (res) => {
+      log.debug('Workflow completed');
+      return res;
+    },
+    (error) => {
+      // Avoid using instanceof checks in case the modules they're defined in loaded more than once,
+      // e.g. by jest or when multiple versions are installed.
+      if (typeof error === 'object' && error != null) {
+        if (isCancellation(error)) {
+          log.debug('Workflow completed as cancelled');
+          throw error;
+        } else if (error instanceof ContinueAsNew) {
+          log.debug('Workflow continued as new');
+          throw error;
+        }
+      }
+      log.warn('Workflow failed', { error });
+      throw error;
+    }
+  );
+  // Avoid showing this interceptor in stack trace query
+  untrackPromise(p);
+  return p;
+}
+
+/**
+ * Returns a map of attributes to be set _by default_ on log messages for a given Workflow.
+ * 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 {
+    namespace: info.namespace,
+    taskQueue: info.taskQueue,
+    workflowId: info.workflowId,
+    runId: info.runId,
+    workflowType: info.workflowType,
+  };
+}

package/src/sinks.ts

@@ -15,6 +15,7 @@
  */
 
 import { WorkflowInfo } from './interfaces';
+import { assertInWorkflowContext } from './global-attributes';
 
 /**
  * Any function signature can be used for Sink functions as long as the return type is `void`.
@@ -44,14 +45,64 @@ export interface SinkCall {
 }
 
 /**
- * Sink interface for forwarding logs from the Workflow sandbox to the Worker
+ * Get a reference to Sinks for exporting data out of the Workflow.
+ *
+ * These Sinks **must** be registered with the Worker in order for this
+ * mechanism to work.
+ *
+ * @example
+ * ```ts
+ * import { proxySinks, Sinks } from '@temporalio/workflow';
+ *
+ * interface MySinks extends Sinks {
+ *   logger: {
+ *     info(message: string): void;
+ *     error(message: string): void;
+ *   };
+ * }
+ *
+ * const { logger } = proxySinks<MyDependencies>();
+ * logger.info('setting up');
+ *
+ * export function myWorkflow() {
+ *   return {
+ *     async execute() {
+ *       logger.info("hey ho");
+ *       logger.error("lets go");
+ *     }
+ *   };
+ * }
+ * ```
  */
-export interface LoggerSinks extends Sinks {
-  defaultWorkerLogger: {
-    trace(message: string, attrs?: Record<string, unknown>): void;
-    debug(message: string, attrs?: Record<string, unknown>): void;
-    info(message: string, attrs?: Record<string, unknown>): void;
-    warn(message: string, attrs?: Record<string, unknown>): void;
-    error(message: string, attrs?: Record<string, unknown>): void;
-  };
+export function proxySinks<T extends Sinks>(): T {
+  return new Proxy(
+    {},
+    {
+      get(_, ifaceName) {
+        return new Proxy(
+          {},
+          {
+            get(_, fnName) {
+              return (...args: any[]) => {
+                const activator = assertInWorkflowContext(
+                  'Proxied sinks functions may only be used from a Workflow Execution.'
+                );
+                activator.sinkCalls.push({
+                  ifaceName: ifaceName as string,
+                  fnName: fnName as string,
+                  // Sink function doesn't get called immediately. Make a clone of the sink's args, so that further mutations
+                  // to these objects don't corrupt the args that the sink function will receive. Only available from node 17.
+                  args: (globalThis as any).structuredClone ? (globalThis as any).structuredClone(args) : args,
+                  // activator.info is internally copy-on-write. This ensure that any further mutations
+                  // to the workflow state in the context of the present activation will not corrupt the
+                  // workflowInfo state that gets passed when the sink function actually gets called.
+                  workflowInfo: activator.info,
+                });
+              };
+            },
+          }
+        );
+      },
+    }
+  ) as any;
 }

package/src/worker-interface.ts

@@ -6,14 +6,14 @@
 import { IllegalStateError } from '@temporalio/common';
 import { msToTs, tsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
-import type { coresdk } from '@temporalio/proto';
+import { coresdk } from '@temporalio/proto';
 import { disableStorage } from './cancellation-scope';
 import { DeterminismViolationError } from './errors';
 import { WorkflowInterceptorsFactory } from './interceptors';
-import { WorkflowCreateOptionsInternal, WorkflowInfo } from './interfaces';
-import { Activator, getActivator } from './internals';
-import { SinkCall } from './sinks';
-import { setActivatorUntyped } from './global-attributes';
+import { WorkflowCreateOptionsInternal } from './interfaces';
+import { Activator } from './internals';
+import { setActivatorUntyped, getActivator } from './global-attributes';
+import { type SinkCall } from './sinks';
 
 // Export the type for use on the "worker" side
 export { PromiseStackStore } from './internals';
@@ -93,9 +93,13 @@ export function overrideGlobals(): void {
  * Sets required internal state and instantiates the workflow and interceptors.
  */
 export function initRuntime(options: WorkflowCreateOptionsInternal): void {
-  const info: WorkflowInfo = fixPrototypes(options.info);
-  info.unsafe.now = OriginalDate.now;
-  const activator = new Activator({ ...options, info });
+  const activator = new Activator({
+    ...options,
+    info: fixPrototypes({
+      ...options.info,
+      unsafe: { ...options.info.unsafe, now: OriginalDate.now },
+    }),
+  });
   // There's on activator per workflow instance, set it globally on the context.
   // We do this before importing any user code so user code can statically reference @temporalio/workflow functions
   // as well as Date and Math.random.
@@ -136,7 +140,7 @@ export function initRuntime(options: WorkflowCreateOptionsInternal): void {
   }
 
   const mod = importWorkflows();
-  const workflowFn = mod[info.workflowType];
+  const workflowFn = mod[activator.info.workflowType];
   const defaultWorkflowFn = mod['default'];
 
   if (typeof workflowFn === 'function') {
@@ -148,7 +152,7 @@ export function initRuntime(options: WorkflowCreateOptionsInternal): void {
       workflowFn === undefined
         ? 'no such function is exported by the workflow bundle'
         : `expected a function, but got: '${typeof workflowFn}'`;
-    throw new TypeError(`Failed to initialize workflow of type '${info.workflowType}': ${details}`);
+    throw new TypeError(`Failed to initialize workflow of type '${activator.info.workflowType}': ${details}`);
   }
 }
 
@@ -188,12 +192,19 @@ export function activate(activation: coresdk.workflow_activation.WorkflowActivat
       }
 
       // The Rust Core ensures that these activation fields are not null
-      activator.info.unsafe.isReplaying = activation.isReplaying ?? false;
-      activator.info.historyLength = activation.historyLength as number;
-      // Exact truncation for multi-petabyte histories
-      // historySize === 0 means WFT was generated by pre-1.20.0 server, and the history size is unknown
-      activator.info.historySize = activation.historySizeBytes?.toNumber() || 0;
-      activator.info.continueAsNewSuggested = activation.continueAsNewSuggested ?? false;
+      activator.mutateWorkflowInfo((info) => ({
+        ...info,
+        historyLength: activation.historyLength as number,
+        // Exact truncation for multi-petabyte histories
+        // historySize === 0 means WFT was generated by pre-1.20.0 server, and the history size is unknown
+        historySize: activation.historySizeBytes?.toNumber() || 0,
+        continueAsNewSuggested: activation.continueAsNewSuggested ?? false,
+        currentBuildId: activation.buildIdForCurrentTask ?? undefined,
+        unsafe: {
+          ...info.unsafe,
+          isReplaying: activation.isReplaying ?? false,
+        },
+      }));
     }
 
     // Cast from the interface to the class which has the `variant` attribute.
@@ -235,9 +246,11 @@ export function activate(activation: coresdk.workflow_activation.WorkflowActivat
  */
 export function concludeActivation(): coresdk.workflow_completion.IWorkflowActivationCompletion {
   const activator = getActivator();
+  activator.rejectBufferedUpdates();
   const intercept = composeInterceptors(activator.interceptors.internals, 'concludeActivation', (input) => input);
   const { info } = activator;
   const { commands } = intercept({ commands: activator.getAndResetCommands() });
+
   return {
     runId: info.runId,
     successful: { commands },