Address todos / add missed new file

Author: Sushisource

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ env:
   # Use these variables to force specific version of CLI/Time Skipping Server for SDK tests
   # TESTS_CLI_VERSION: 'v0.13.2'
   TESTS_CLI_VERSION: 'v1.3.1-priority.0'
-  # TESTS_TIME_SKIPPING_SERVER_VERSION: 'v1.3.1-priority.0'
+  # TESTS_TIME_SKIPPING_SERVER_VERSION: 'v1.24.1'
 
 jobs:
   # Compile native bridge code for each target platform.

packages/common/src/worker-deployments.ts

@@ -1,15 +1,28 @@
 /**
  * Represents the version of a specific worker deployment.
  *
- * @experimental Worker deployments are experimental
+ * @experimental Deployment based versioning is experimental and may change in the future.
  */
 export interface WorkerDeploymentVersion {
   readonly buildId: string;
   readonly deploymentName: string;
 }
 
+/**
+ * @returns The canonical representation of a deployment version, which is a string in the format
+ * `deploymentName.buildId`.
+ */
 export function toCanonicalString(version: WorkerDeploymentVersion): string {
   return `${version.deploymentName}.${version.buildId}`;
 }
 
+/**
+ * Specifies when a workflow might move from a worker of one Build Id to another.
+ *
+ * * 'pinned' - The workflow will be pinned to the current Build ID unless manually moved.
+ * * 'auto-upgrade' - The workflow will automatically move to the latest version (default Build ID
+ *    of the task queue) when the next task is dispatched.
+ *
+ * @experimental Deployment based versioning is experimental and may change in the future.
+ */
 export type VersioningBehavior = 'pinned' | 'auto-upgrade';

packages/test/src/deployment-versioning-no-annotations/index.ts

@@ -0,0 +1,14 @@
+import { setHandler, condition } from '@temporalio/workflow';
+import { unblockSignal, versionQuery } from '../workflows';
+
+export async function deploymentVersioning(): Promise<string> {
+  let doFinish = false;
+  setHandler(unblockSignal, () => void (doFinish = true));
+  setHandler(versionQuery, () => 'v1');
+  await condition(() => doFinish);
+  return 'version-v1';
+}
+
+export default async function (): Promise<string> {
+  return 'dynamic';
+}

packages/test/src/helpers-integration.ts

@@ -101,11 +101,6 @@ export async function createLocalTestEnvironment(
     ...(opts || {}), // Use provided options or default to an empty object
     server: {
       searchAttributes: Object.values(defaultSAKeys),
-      // TODO: Remove after next CLI release
-      executable: {
-        type: 'cached-download',
-        version: 'v1.3.1-priority.0',
-      },
       ...(opts?.server || {}), // Use provided server options or default to an empty object
       extraArgs: [
         ...defaultDynamicConfigOptions.flatMap((opt) => ['--dynamic-config-value', opt]),

packages/test/src/test-worker-deployment-versioning.ts

@@ -7,12 +7,12 @@ import assert from 'assert';
 import { randomUUID } from 'crypto';
 import asyncRetry from 'async-retry';
 import { Client } from '@temporalio/client';
+import { toCanonicalString, WorkerDeploymentVersion } from '@temporalio/common';
+import { temporal } from '@temporalio/proto';
 import { Worker } from './helpers';
 import * as activities from './activities';
-import { toCanonicalString, WorkerDeploymentVersion } from '@temporalio/common';
 import { makeTestFunction } from './helpers-integration';
-import { unblockSignal, versionQuery } from './workflows/';
-import { temporal } from '@temporalio/proto';
+import { unblockSignal, versionQuery } from './workflows';
 
 const test = makeTestFunction({ workflowsPath: __filename });
 
@@ -23,15 +23,15 @@ test('Worker deployment based versioning', async (t) => {
 
   const w1DeploymentVersion = {
     buildId: '1.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
   const w2DeploymentVersion = {
     buildId: '2.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
   const w3DeploymentVersion = {
     buildId: '3.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
 
   const worker1 = await Worker.create({
@@ -144,11 +144,11 @@ test('Worker deployment based versioning with ramping', async (t) => {
 
   const v1 = {
     buildId: '1.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
   const v2 = {
     buildId: '2.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
 
   const worker1 = await Worker.create({
@@ -255,7 +255,7 @@ test('Worker deployment with dynamic workflow on run', async (t) => {
 
   const version = {
     buildId: '1.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
 
   const worker = await Worker.create({
@@ -264,7 +264,7 @@ test('Worker deployment with dynamic workflow on run', async (t) => {
     taskQueue,
     workerDeploymentOptions: {
       useWorkerVersioning: true,
-      version: version,
+      version,
       defaultVersioningBehavior: 'auto-upgrade',
     },
   });
@@ -308,7 +308,7 @@ test('Workflows can use default versioning behavior', async (t) => {
 
   const workerV1 = {
     buildId: '1.0',
-    deploymentName: deploymentName,
+    deploymentName,
   };
 
   const worker = await Worker.create({
@@ -337,9 +337,7 @@ test('Workflows can use default versioning behavior', async (t) => {
 
   await wf.result();
 
-  // Check history for versioning behavior
   const history = await wf.fetchHistory();
-
   const hasPinnedVersioningBehavior = history.events!.some(
     (event) =>
       event.workflowTaskCompletedEventAttributes &&

packages/worker/src/worker-options.ts

@@ -123,7 +123,7 @@ export interface WorkerOptions {
 
   /**
    * Deployment options for the worker. Exclusive with `build_id` and `use_worker_versioning`.
-
+   *
    * @experimental Deployment based versioning is still experimental.
    */
   workerDeploymentOptions?: {

packages/worker/src/workflow/vm-shared.ts

@@ -14,9 +14,9 @@ import * as internals from '@temporalio/workflow/lib/worker-interface';
 import { Activator } from '@temporalio/workflow/lib/internals';
 import { SdkFlags } from '@temporalio/workflow/lib/flags';
 import { UnhandledRejectionError } from '../errors';
+import { convertDeploymentVersion } from '../utils';
 import { Workflow } from './interface';
 import { WorkflowBundleWithSourceMapAndFilename } from './workflow-worker-thread/input';
-import { convertDeploymentVersion } from '../utils';
 
 // Best effort to catch unhandled rejections from workflow code.
 // We crash the thread if we cannot find the culprit.

packages/workflow/src/interfaces.ts

@@ -192,6 +192,8 @@ export interface WorkflowInfo {
    * 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;
 

packages/workflow/src/internals.ts

@@ -498,7 +498,7 @@ export class Activator implements ActivationHandler {
     return {
       commands: this.commands.splice(0),
       usedInternalFlags: [...this.knownFlags],
-      versioningBehavior: versioningBehavior,
+      versioningBehavior,
     };
   }
 

packages/workflow/src/workflow.ts

@@ -31,6 +31,7 @@ import { versioningIntentToProto } from '@temporalio/common/lib/versioning-inten
 import { Duration, msOptionalToTs, msToNumber, msToTs, requiredTsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { temporal } from '@temporalio/proto';
+import { WorkflowDefinitionOptions, WorkflowFunctionWithOptions } from '@temporalio/common';
 import { CancellationScope, registerSleepImplementation } from './cancellation-scope';
 import { UpdateScope } from './update-scope';
 import {
@@ -62,7 +63,6 @@ import { LocalActivityDoBackoff } from './errors';
 import { assertInWorkflowContext, getActivator, maybeGetActivator } from './global-attributes';
 import { untrackPromise } from './stack-helpers';
 import { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
-import { WorkflowDefinitionOptions, WorkflowFunctionWithOptions } from '@temporalio/common';
 
 // Avoid a circular dependency
 registerSleepImplementation(sleep);
@@ -1589,13 +1589,35 @@ export function allHandlersFinished(): boolean {
 }
 
 /**
-* Can be used to define workflow functions with certain options specified at definition time.
-
-* @param options Options for the workflow defintion.
-* @param fn The workflow function.
-* @returns The same passed in workflow function, with the specified options applied. You can export
-* this function to make it available as a workflow function.
-*/
+ * Can be used to alter or define workflow functions with certain options specified at definition
+ * time. In order to ensure that workflows are loaded properly by their name, you typically will not
+ * need to use the return value of this function.
+ *
+ * @example
+ * For example:
+ * ```ts
+ * defineWorkflowWithOptions({ versioningBehavior: 'pinned' }, myWorkflow);
+ * export async function myWorkflow(): Promise<string> {
+ *   // Workflow code here
+ *   return "hi";
+ * }
+ * ```
+ *
+ * @example
+ * To annotate a default or dynamic workflow:
+ * ```ts
+ * export default defineWorkflowWithOptions({ versioningBehavior: 'pinned' }, myDefaultWorkflow);
+ * async function myDefaultWorkflow(): Promise<string> {
+ *   // Workflow code here
+ *   return "hi";
+ * }
+ * ```
+ *
+ * @param options Options for the workflow defintion.
+ * @param fn The workflow function.
+ * @returns The same passed in workflow function, with the specified options applied. You can export
+ * this function to make it available as a workflow function.
+ */
 export function defineWorkflowWithOptions<A extends any[], RT>(
   options: WorkflowDefinitionOptions,
   fn: (...args: A) => Promise<RT>