inline options, lazily decode summary/details on workflow description

Author: THardy98

packages/client/src/schedule-helpers.ts

@@ -1,11 +1,5 @@
 import Long from 'long'; // eslint-disable-line import/no-named-as-default
-import {
-  compileRetryPolicy,
-  decompileRetryPolicy,
-  extractWorkflowType,
-  JsonPayloadConverter,
-  LoadedDataConverter,
-} from '@temporalio/common';
+import { compileRetryPolicy, decompileRetryPolicy, extractWorkflowType, LoadedDataConverter } from '@temporalio/common';
 import {
   encodeUnifiedSearchAttributes,
   decodeSearchAttributes,
@@ -340,8 +334,8 @@ export async function decodeScheduleAction(
       workflowExecutionTimeout: optionalTsToMs(pb.startWorkflow.workflowExecutionTimeout),
       workflowRunTimeout: optionalTsToMs(pb.startWorkflow.workflowRunTimeout),
       workflowTaskTimeout: optionalTsToMs(pb.startWorkflow.workflowTaskTimeout),
-      staticSummary: await decodeOptionalSinglePayload(dataConverter, userMetadata?.summary) ?? undefined,
-      staticDetails: await decodeOptionalSinglePayload(dataConverter, userMetadata?.details) ?? undefined,
+      staticSummary: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.summary)) ?? undefined,
+      staticDetails: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.details)) ?? undefined,
     };
   }
   throw new TypeError('Unsupported schedule action');

packages/client/src/types.ts

@@ -65,11 +65,25 @@ export interface CountWorkflowExecution {
 export type WorkflowExecutionDescription = Replace<
   WorkflowExecutionInfo,
   {
-    staticSummary?: string;
-    staticDetails?: string;
     raw: DescribeWorkflowExecutionResponse;
   }
->;
+> & {
+  /**
+   * General fixed details for this workflow execution that may appear in UI/CLI.
+   * This can be in Temporal markdown format and can span multiple lines.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticDetails: () => Promise<string | undefined>;
+
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary: () => Promise<string | undefined>;
+};
 
 export type WorkflowService = proto.temporal.api.workflowservice.v1.WorkflowService;
 export const { WorkflowService } = proto.temporal.api.workflowservice.v1;

packages/client/src/workflow-client.ts

@@ -1438,8 +1438,10 @@ export class WorkflowClient extends BaseClient {
         const userMetadata = raw.executionConfig?.userMetadata;
         return {
           ...info,
-          staticDetails: await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.details) ?? undefined,
-          staticSummary: await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.summary) ?? undefined,
+          staticDetails: async () =>
+            (await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.details)) ?? undefined,
+          staticSummary: async () =>
+            (await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.summary)) ?? undefined,
           raw,
         };
       },

packages/common/src/activity-options.ts

@@ -122,6 +122,14 @@ export interface ActivityOptions {
    * @experimental The Worker Versioning API is still being designed. Major changes are expected.
    */
   versioningIntent?: VersioningIntent;
+
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary?: string;
 }
 
 /**
@@ -186,4 +194,12 @@ export interface LocalActivityOptions {
    * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
    */
   cancellationType?: ActivityCancellationType;
+
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary?: string;
 }

packages/common/src/internal-non-workflow/codec-helpers.ts

@@ -95,13 +95,13 @@ export async function encodeToPayload(converter: LoadedDataConverter, value: unk
  * Run {@link PayloadConverter.toPayload} on an optional value, and then encode it.
  */
 export async function encodeOptionalToPayload(
-  converter: LoadedDataConverter, 
+  converter: LoadedDataConverter,
   value: unknown
 ): Promise<Payload | null | undefined> {
   if (value == null) return value;
-  
+
   const { payloadConverter, payloadCodecs } = converter;
-  const payload = payloadConverter.toPayload(value);  
+  const payload = payloadConverter.toPayload(value);
   return await encodeSingle(payloadCodecs, payload);
 }
 

packages/common/src/workflow-options.ts

@@ -195,14 +195,14 @@ export interface BaseWorkflowOptions {
    * General fixed details for this workflow execution that may appear in UI/CLI.
    * This can be in Temporal markdown format and can span multiple lines.
    *
-   * @experimental
+   * @experimental User metadata is a new API and suspectible to change.
    */
   staticDetails?: string;
   /**
    * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
    * This can be in single-line Temporal markdown format.
    *
-   * @experimental
+   * @experimental User metadata is a new API and suspectible to change.
    */
   staticSummary?: string;
 }

packages/test/package.json

@@ -8,7 +8,11 @@
     "build:ts": "tsc --build",
     "build:protos": "node ./scripts/compile-proto.js",
     "test": "ava ./lib/test-*.js",
-    "test.watch": "ava --watch ./lib/test-*.js"
+    "test.watch": "ava --watch ./lib/test-*.js",
+    "test-int": "ava ./lib/test-integration-workflows.js",
+    "test-schedules": "ava ./lib/test-schedules.js",
+    "test-wf": "ava ./lib/test-integration-workflows.js",
+    "test-pr": "ava ./lib/test-integration-split-two.js"
   },
   "ava": {
     "timeout": "60s",

packages/test/src/test-integration-workflows.ts

@@ -14,13 +14,13 @@ import {
   ActivityCancellationType,
   ApplicationFailure,
   defineSearchAttributeKey,
-  JsonPayloadConverter,
   SearchAttributePair,
   SearchAttributeType,
   TypedSearchAttributes,
   WorkflowExecutionAlreadyStartedError,
 } from '@temporalio/common';
 import { temporal } from '@temporalio/proto';
+import { decodeOptionalSinglePayload } from '@temporalio/common/lib/internal-non-workflow';
 import { signalSchedulingWorkflow } from './activities/helpers';
 import { activityStartedSignal } from './workflows/definitions';
 import * as workflows from './workflows';
@@ -1348,12 +1348,15 @@ export async function userMetadataWorkflow(): Promise<string> {
   });
 
   // That workflow should call an activity (with summary)
-  const { activityWithSummary } = workflow.proxyActivities({ scheduleToCloseTimeout: '10s' }).withSummaries({
-    activityWithSummary: 'activity summary',
-  });
-  await activityWithSummary();
+  const { activityWithSummary } = workflow.proxyActivities({ scheduleToCloseTimeout: '10s' });
+  await activityWithSummary.runWithOptions(
+    {
+      staticSummary: 'activity summary',
+    },
+    []
+  );
   // Should have a timer (with summary)
-  await workflow.sleep(5, 'timer summary');
+  await workflow.sleep(5, { summary: 'timer summary' });
   // Set current details
   workflow.setCurrentDetails('current wf details');
   // Unblock on var -> query current details (or return)
@@ -1377,8 +1380,8 @@ test('User metadata on workflow, timer, activity', async (t) => {
     });
     // Describe workflow -> static summary, static details
     const desc = await handle.describe();
-    t.true(desc.staticSummary === 'wf static summary');
-    t.true(desc.staticDetails === 'wf static details');
+    t.true((await desc.staticSummary()) === 'wf static summary');
+    t.true((await desc.staticDetails()) === 'wf static details');
 
     await handle.signal('done');
     const res = await handle.result();
@@ -1392,15 +1395,38 @@ test('User metadata on workflow, timer, activity', async (t) => {
         runId: handle.firstExecutionRunId,
       },
     });
-    const jsonConverter = new JsonPayloadConverter();
     for (const event of resp.history?.events ?? []) {
       if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_WORKFLOW_EXECUTION_STARTED) {
-        t.deepEqual(jsonConverter.fromPayload(event.userMetadata?.summary ?? {}), 'wf static summary');
-        t.deepEqual(jsonConverter.fromPayload(event.userMetadata?.details ?? {}), 'wf static details');
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'wf static summary'
+        );
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.details ?? {}
+          ),
+          'wf static details'
+        );
       } else if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_ACTIVITY_TASK_SCHEDULED) {
-        t.deepEqual(jsonConverter.fromPayload(event.userMetadata?.summary ?? {}), 'activity summary');
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'activity summary'
+        );
       } else if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_TIMER_STARTED) {
-        t.deepEqual(jsonConverter.fromPayload(event.userMetadata?.summary ?? {}), 'timer summary');
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'timer summary'
+        );
       }
     }
 

packages/workflow/src/interceptors.ts

@@ -80,7 +80,6 @@ export interface ActivityInput {
   readonly options: ActivityOptions;
   readonly headers: Headers;
   readonly seq: number;
-  readonly cmdOpts?: WorkflowCommandOptions;
 }
 
 /** Input for WorkflowOutboundCallsInterceptor.scheduleLocalActivity */
@@ -92,7 +91,6 @@ export interface LocalActivityInput {
   readonly seq: number;
   readonly originalScheduleTime?: Timestamp;
   readonly attempt: number;
-  readonly cmdOpts?: WorkflowCommandOptions;
 }
 
 /** Input for WorkflowOutboundCallsInterceptor.startChildWorkflowExecution */
@@ -117,19 +115,17 @@ export interface UserMetadata {
   details?: string;
 }
 
-/**
- * Options that can be attached to workflow commands.
- */
-export interface WorkflowCommandOptions {
-  /** User metadata for the command that may be persisted to history */
-  readonly userMetadata?: UserMetadata;
-}
-
 /** Input for WorkflowOutboundCallsInterceptor.startTimer */
 export interface TimerInput {
   readonly durationMs: number;
   readonly seq: number;
-  readonly cmdOpts?: WorkflowCommandOptions;
+  readonly options?: TimerOptions;
+}
+
+/** Options for starting a timer (i.e. sleep) */
+export interface TimerOptions {
+  /** @experimental A single line summary of the command's purpose */
+  readonly summary?: string;
 }
 
 /**