@temporalio/workflow 1.11.8 → 1.12.0-rc.0

package/src/metrics.ts

@@ -0,0 +1,191 @@
+import {
+  MetricCounter,
+  MetricGauge,
+  MetricHistogram,
+  MetricMeter,
+  MetricMeterWithComposedTags,
+  MetricTags,
+  NumericMetricValueType,
+} from '@temporalio/common';
+import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { proxySinks, Sink, Sinks } from './sinks';
+import { workflowInfo } from './workflow';
+import { assertInWorkflowContext } from './global-attributes';
+
+class WorkflowMetricMeterImpl implements MetricMeter {
+  constructor() {}
+
+  createCounter(name: string, unit?: string, description?: string): MetricCounter {
+    assertInWorkflowContext("Workflow's `metricMeter` can only be used while in Workflow Context");
+    return new WorkflowMetricCounter(name, unit, description);
+  }
+
+  createHistogram(
+    name: string,
+    valueType: NumericMetricValueType = 'int',
+    unit?: string,
+    description?: string
+  ): MetricHistogram {
+    assertInWorkflowContext("Workflow's `metricMeter` can only be used while in Workflow Context");
+    return new WorkflowMetricHistogram(name, valueType, unit, description);
+  }
+
+  createGauge(
+    name: string,
+    valueType: NumericMetricValueType = 'int',
+    unit?: string,
+    description?: string
+  ): MetricGauge {
+    assertInWorkflowContext("Workflow's `metricMeter` can only be used while in Workflow Context");
+    return new WorkflowMetricGauge(name, valueType, unit, description);
+  }
+
+  withTags(_tags: MetricTags): MetricMeter {
+    assertInWorkflowContext("Workflow's `metricMeter` can only be used while in Workflow Context");
+    // Tags composition is handled by a MetricMeterWithComposedTags wrapper over this one
+    throw new Error(`withTags is not supported directly on WorkflowMetricMeter`);
+  }
+}
+
+class WorkflowMetricCounter implements MetricCounter {
+  constructor(
+    public readonly name: string,
+    public readonly unit: string | undefined,
+    public readonly description: string | undefined
+  ) {}
+
+  add(value: number, extraTags: MetricTags = {}): void {
+    if (value < 0) {
+      throw new Error(`MetricCounter value must be non-negative (got ${value})`);
+    }
+    if (!workflowInfo().unsafe.isReplaying) {
+      metricSink.addMetricCounterValue(this.name, this.unit, this.description, value, extraTags);
+    }
+  }
+
+  withTags(_tags: MetricTags): MetricCounter {
+    // Tags composition is handled by a MetricMeterWithComposedTags wrapper over this one
+    throw new Error(`withTags is not supported directly on WorkflowMetricCounter`);
+  }
+}
+
+class WorkflowMetricHistogram implements MetricHistogram {
+  constructor(
+    public readonly name: string,
+    public readonly valueType: NumericMetricValueType,
+    public readonly unit: string | undefined,
+    public readonly description: string | undefined
+  ) {}
+
+  record(value: number, extraTags: MetricTags = {}): void {
+    if (value < 0) {
+      throw new Error(`MetricHistogram value must be non-negative (got ${value})`);
+    }
+    if (!workflowInfo().unsafe.isReplaying) {
+      metricSink.recordMetricHistogramValue(this.name, this.valueType, this.unit, this.description, value, extraTags);
+    }
+  }
+
+  withTags(_tags: MetricTags): MetricHistogram {
+    // Tags composition is handled by a MetricMeterWithComposedTags wrapper over this one
+    throw new Error(`withTags is not supported directly on WorkflowMetricHistogram`);
+  }
+}
+
+class WorkflowMetricGauge implements MetricGauge {
+  constructor(
+    public readonly name: string,
+    public readonly valueType: NumericMetricValueType,
+    public readonly unit: string | undefined,
+    public readonly description: string | undefined
+  ) {}
+
+  set(value: number, tags?: MetricTags): void {
+    if (value < 0) {
+      throw new Error(`MetricGauge value must be non-negative (got ${value})`);
+    }
+    if (!workflowInfo().unsafe.isReplaying) {
+      metricSink.setMetricGaugeValue(this.name, this.valueType, this.unit, this.description, value, tags ?? {});
+    }
+  }
+
+  withTags(_tags: MetricTags): MetricGauge {
+    // Tags composition is handled by a MetricMeterWithComposedTags wrapper over this one
+    throw new Error(`withTags is not supported directly on WorkflowMetricGauge`);
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+// Note: given that forwarding metrics outside of the sanbox can be quite chatty and add non
+// negligeable overhead, we eagerly check for `isReplaying` and completely skip doing sink
+// calls if we are replaying.
+const metricSink = proxySinks<MetricSinks>().__temporal_metrics;
+
+/**
+ * Sink interface for forwarding metrics from the Workflow sandbox to the Worker.
+ *
+ * These sink functions are not intended to be called directly from workflow code; instead,
+ * developers should use the `metricMeter` object exposed to workflow code by the SDK, which
+ * provides an API that is easier to work with.
+ *
+ * This sink interface is also not meant to be implemented by user.
+ *
+ * @hidden
+ * @internal Users should not implement this interface, nor use it directly. Use `metricMeter` instead.
+ */
+export interface MetricSinks extends Sinks {
+  __temporal_metrics: WorkflowMetricMeter;
+}
+
+/**
+ * @hidden
+ * @internal Users should not implement this interface, nor use it directly. Use `metricMeter` instead.
+ */
+export interface WorkflowMetricMeter extends Sink {
+  addMetricCounterValue(
+    metricName: string,
+    unit: string | undefined,
+    description: string | undefined,
+    value: number,
+    attrs: MetricTags
+  ): void;
+
+  recordMetricHistogramValue(
+    metricName: string,
+    valueType: NumericMetricValueType,
+    unit: string | undefined,
+    description: string | undefined,
+    value: number,
+    attrs: MetricTags
+  ): void;
+
+  setMetricGaugeValue(
+    metricName: string,
+    valueType: NumericMetricValueType,
+    unit: string | undefined,
+    description: string | undefined,
+    value: number,
+    attrs: MetricTags
+  ): void;
+}
+
+/**
+ * A MetricMeter that can be used to emit metrics from within a Workflow.
+ *
+ * @experimental The Metric API is an experimental feature and may be subject to change.
+ */
+export const metricMeter: MetricMeter = MetricMeterWithComposedTags.compose(
+  new WorkflowMetricMeterImpl(),
+  () => {
+    const activator = assertInWorkflowContext('Workflow.metricMeter may only be used from workflow context.');
+    const getMetricTags = composeInterceptors(activator.interceptors.outbound, 'getMetricTags', (a) => a);
+
+    const info = activator.info;
+    return getMetricTags({
+      // namespace and taskQueue will be added by the Worker
+      workflowType: info.workflowType,
+    });
+  },
+  true
+);

package/src/worker-interface.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { IllegalStateError } from '@temporalio/common';
+import { encodeVersioningBehavior, IllegalStateError, WorkflowFunctionWithOptions } from '@temporalio/common';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { coresdk } from '@temporalio/proto';
 import { disableStorage } from './cancellation-scope';
@@ -37,54 +37,68 @@ export function initRuntime(options: WorkflowCreateOptionsInternal): void {
   // as well as Date and Math.random.
   setActivatorUntyped(activator);
 
-  // webpack alias to payloadConverterPath
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const customPayloadConverter = require('__temporal_custom_payload_converter').payloadConverter;
-  // The `payloadConverter` export is validated in the Worker
-  if (customPayloadConverter != null) {
-    activator.payloadConverter = customPayloadConverter;
-  }
-  // webpack alias to failureConverterPath
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const customFailureConverter = require('__temporal_custom_failure_converter').failureConverter;
-  // The `failureConverter` export is validated in the Worker
-  if (customFailureConverter != null) {
-    activator.failureConverter = customFailureConverter;
-  }
+  activator.rethrowSynchronously = true;
+  try {
+    // webpack alias to payloadConverterPath
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const customPayloadConverter = require('__temporal_custom_payload_converter').payloadConverter;
+    // The `payloadConverter` export is validated in the Worker
+    if (customPayloadConverter != null) {
+      activator.payloadConverter = customPayloadConverter;
+    }
+    // webpack alias to failureConverterPath
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const customFailureConverter = require('__temporal_custom_failure_converter').failureConverter;
+    // The `failureConverter` export is validated in the Worker
+    if (customFailureConverter != null) {
+      activator.failureConverter = customFailureConverter;
+    }
 
-  const { importWorkflows, importInterceptors } = global.__TEMPORAL__;
-  if (importWorkflows === undefined || importInterceptors === undefined) {
-    throw new IllegalStateError('Workflow bundle did not register import hooks');
-  }
+    const { importWorkflows, importInterceptors } = global.__TEMPORAL__;
+    if (importWorkflows === undefined || importInterceptors === undefined) {
+      throw new IllegalStateError('Workflow bundle did not register import hooks');
+    }
 
-  const interceptors = importInterceptors();
-  for (const mod of interceptors) {
-    const factory: WorkflowInterceptorsFactory = mod.interceptors;
-    if (factory !== undefined) {
-      if (typeof factory !== 'function') {
-        throw new TypeError(`Failed to initialize workflows interceptors: expected a function, but got: '${factory}'`);
+    const interceptors = importInterceptors();
+    for (const mod of interceptors) {
+      const factory: WorkflowInterceptorsFactory = mod.interceptors;
+      if (factory !== undefined) {
+        if (typeof factory !== 'function') {
+          throw new TypeError(
+            `Failed to initialize workflows interceptors: expected a function, but got: '${factory}'`
+          );
+        }
+        const interceptors = factory();
+        activator.interceptors.inbound.push(...(interceptors.inbound ?? []));
+        activator.interceptors.outbound.push(...(interceptors.outbound ?? []));
+        activator.interceptors.internals.push(...(interceptors.internals ?? []));
       }
-      const interceptors = factory();
-      activator.interceptors.inbound.push(...(interceptors.inbound ?? []));
-      activator.interceptors.outbound.push(...(interceptors.outbound ?? []));
-      activator.interceptors.internals.push(...(interceptors.internals ?? []));
     }
-  }
 
-  const mod = importWorkflows();
-  const workflowFn = mod[activator.info.workflowType];
-  const defaultWorkflowFn = mod['default'];
-
-  if (typeof workflowFn === 'function') {
-    activator.workflow = workflowFn;
-  } else if (typeof defaultWorkflowFn === 'function') {
-    activator.workflow = defaultWorkflowFn;
-  } else {
-    const details =
-      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 '${activator.info.workflowType}': ${details}`);
+    const mod = importWorkflows();
+    const workflowFn = mod[activator.info.workflowType];
+    const defaultWorkflowFn = mod['default'];
+
+    if (typeof workflowFn === 'function') {
+      activator.workflow = workflowFn;
+    } else if (typeof defaultWorkflowFn === 'function') {
+      activator.workflow = defaultWorkflowFn;
+    } else {
+      const details =
+        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 '${activator.info.workflowType}': ${details}`);
+    }
+    if (isWorkflowFunctionWithOptions(activator.workflow)) {
+      if (typeof activator.workflow.workflowDefinitionOptions === 'object') {
+        activator.versioningBehavior = activator.workflow.workflowDefinitionOptions.versioningBehavior;
+      } else {
+        activator.workflowDefinitionOptionsGetter = activator.workflow.workflowDefinitionOptions;
+      }
+    }
+  } finally {
+    activator.rethrowSynchronously = false;
   }
 }
 
@@ -111,53 +125,70 @@ function fixPrototypes<X>(obj: X): X {
  * Initialize the workflow. Or to be exact, _complete_ initialization, as most part has been done in constructor).
  */
 export function initialize(initializeWorkflowJob: coresdk.workflow_activation.IInitializeWorkflow): void {
-  getActivator().initializeWorkflow(initializeWorkflowJob);
+  const activator = getActivator();
+  activator.rethrowSynchronously = true;
+  try {
+    activator.initializeWorkflow(initializeWorkflowJob);
+  } finally {
+    activator.rethrowSynchronously = false;
+  }
 }
 
 /**
- * Run a chunk of activation jobs
+ * Run a chunk of activation jobs.
+ *
+ * Notice that this function is not async and runs _inside_ the VM context. Therefore, no microtask
+ * will get executed _while_ this function is active; they will however get executed _after_ this
+ * function returns (i.e. all outstanding microtasks in the VM will get executed before execution
+ * resumes out of the VM, in `vm-shared.ts:activate()`).
  */
 export function activate(activation: coresdk.workflow_activation.IWorkflowActivation, batchIndex = 0): void {
   const activator = getActivator();
-  const intercept = composeInterceptors(activator.interceptors.internals, 'activate', ({ activation }) => {
-    // Cast from the interface to the class which has the `variant` attribute.
-    // This is safe because we know that activation is a proto class.
-    const jobs = activation.jobs as coresdk.workflow_activation.WorkflowActivationJob[];
+  activator.rethrowSynchronously = true;
+  try {
+    const intercept = composeInterceptors(activator.interceptors.internals, 'activate', ({ activation }) => {
+      // Cast from the interface to the class which has the `variant` attribute.
+      // This is safe because we know that activation is a proto class.
+      const jobs = activation.jobs as coresdk.workflow_activation.WorkflowActivationJob[];
 
-    // Initialization will have been handled already, but we might still need to start the workflow function
-    const startWorkflowJob = jobs[0].variant === 'initializeWorkflow' ? jobs.shift()?.initializeWorkflow : undefined;
+      // Initialization will have been handled already, but we might still need to start the workflow function
+      const startWorkflowJob = jobs[0].variant === 'initializeWorkflow' ? jobs.shift()?.initializeWorkflow : undefined;
 
-    for (const job of jobs) {
-      if (job.variant === undefined) throw new TypeError('Expected job.variant to be defined');
+      for (const job of jobs) {
+        if (job.variant === undefined) throw new TypeError('Expected job.variant to be defined');
 
-      const variant = job[job.variant];
-      if (!variant) throw new TypeError(`Expected job.${job.variant} to be set`);
+        const variant = job[job.variant];
+        if (!variant) throw new TypeError(`Expected job.${job.variant} to be set`);
 
-      activator[job.variant](variant as any /* TS can't infer this type */);
-
-      if (job.variant !== 'queryWorkflow') tryUnblockConditions();
-    }
+        activator[job.variant](variant as any /* TS can't infer this type */);
 
-    if (startWorkflowJob) {
-      const safeJobTypes: coresdk.workflow_activation.WorkflowActivationJob['variant'][] = [
-        'initializeWorkflow',
-        'signalWorkflow',
-        'doUpdate',
-        'cancelWorkflow',
-        'updateRandomSeed',
-      ];
-      if (jobs.some((job) => !safeJobTypes.includes(job.variant))) {
-        throw new TypeError(
-          'Received both initializeWorkflow and non-signal/non-update jobs in the same activation: ' +
-            JSON.stringify(jobs.map((job) => job.variant))
-        );
+        if (job.variant !== 'queryWorkflow') tryUnblockConditions();
       }
 
-      activator.startWorkflow(startWorkflowJob);
-      tryUnblockConditions();
-    }
-  });
-  intercept({ activation, batchIndex });
+      if (startWorkflowJob) {
+        const safeJobTypes: coresdk.workflow_activation.WorkflowActivationJob['variant'][] = [
+          'initializeWorkflow',
+          'signalWorkflow',
+          'doUpdate',
+          'cancelWorkflow',
+          'updateRandomSeed',
+        ];
+        if (jobs.some((job) => !safeJobTypes.includes(job.variant))) {
+          throw new TypeError(
+            'Received both initializeWorkflow and non-signal/non-update jobs in the same activation: ' +
+              JSON.stringify(jobs.map((job) => job.variant))
+          );
+        }
+
+        activator.startWorkflow(startWorkflowJob);
+
+        tryUnblockConditions();
+      }
+    });
+    intercept({ activation, batchIndex });
+  } finally {
+    activator.rethrowSynchronously = false;
+  }
 }
 
 /**
@@ -168,18 +199,26 @@ export function activate(activation: coresdk.workflow_activation.IWorkflowActiva
  */
 export function concludeActivation(): coresdk.workflow_completion.IWorkflowActivationCompletion {
   const activator = getActivator();
-  activator.rejectBufferedUpdates();
-  const intercept = composeInterceptors(activator.interceptors.internals, 'concludeActivation', (input) => input);
-  const activationCompletion = activator.concludeActivation();
-  const { commands } = intercept({ commands: activationCompletion.commands });
-  if (activator.completed) {
-    activator.warnIfUnfinishedHandlers();
+  activator.rethrowSynchronously = true;
+  try {
+    activator.rejectBufferedUpdates();
+    const intercept = composeInterceptors(activator.interceptors.internals, 'concludeActivation', (input) => input);
+    const activationCompletion = activator.concludeActivation();
+    const { commands } = intercept({ commands: activationCompletion.commands });
+    if (activator.completed) {
+      activator.warnIfUnfinishedHandlers();
+    }
+    return {
+      runId: activator.info.runId,
+      successful: {
+        ...activationCompletion,
+        commands,
+        versioningBehavior: encodeVersioningBehavior(activationCompletion.versioningBehavior),
+      },
+    };
+  } finally {
+    activator.rethrowSynchronously = false;
   }
-
-  return {
-    runId: activator.info.runId,
-    successful: { ...activationCompletion, commands },
-  };
 }
 
 /**
@@ -188,28 +227,46 @@ export function concludeActivation(): coresdk.workflow_completion.IWorkflowActiv
  * @returns number of unblocked conditions.
  */
 export function tryUnblockConditions(): number {
-  let numUnblocked = 0;
-  for (;;) {
-    const prevUnblocked = numUnblocked;
-    for (const [seq, cond] of getActivator().blockedConditions.entries()) {
-      if (cond.fn()) {
-        cond.resolve();
-        numUnblocked++;
-        // It is safe to delete elements during map iteration
-        getActivator().blockedConditions.delete(seq);
+  const activator = getActivator();
+  activator.rethrowSynchronously = true;
+  try {
+    let numUnblocked = 0;
+    for (;;) {
+      activator.maybeRethrowWorkflowTaskError();
+      const prevUnblocked = numUnblocked;
+      for (const [seq, cond] of activator.blockedConditions.entries()) {
+        if (cond.fn()) {
+          cond.resolve();
+          numUnblocked++;
+          // It is safe to delete elements during map iteration
+          activator.blockedConditions.delete(seq);
+        }
+      }
+      if (prevUnblocked === numUnblocked) {
+        break;
       }
     }
-    if (prevUnblocked === numUnblocked) {
-      break;
-    }
+    return numUnblocked;
+  } finally {
+    activator.rethrowSynchronously = false;
   }
-  return numUnblocked;
 }
 
 export function dispose(): void {
-  const dispose = composeInterceptors(getActivator().interceptors.internals, 'dispose', async () => {
-    disableStorage();
-    disableUpdateStorage();
-  });
-  dispose({});
+  const activator = getActivator();
+  activator.rethrowSynchronously = true;
+  try {
+    const dispose = composeInterceptors(activator.interceptors.internals, 'dispose', async () => {
+      disableStorage();
+      disableUpdateStorage();
+    });
+    dispose({});
+  } finally {
+    activator.rethrowSynchronously = false;
+  }
+}
+
+function isWorkflowFunctionWithOptions(obj: any): obj is WorkflowFunctionWithOptions<any[], any> {
+  if (obj == null) return false;
+  return Object.hasOwn(obj, 'workflowDefinitionOptions');
 }