feat(worker): Add a workflow metadata query (#1319)

Co-authored-by: James Watkins-Harvey <mjameswh@users.noreply.github.com>

Author: antlai-temporal

packages/common/src/interfaces.ts

@@ -6,8 +6,15 @@ export type Payload = temporal.api.common.v1.IPayload;
 export type WorkflowReturnType = Promise<any>;
 export type WorkflowUpdateType = (...args: any[]) => Promise<any> | any;
 export type WorkflowUpdateValidatorType = (...args: any[]) => void;
+export type WorkflowUpdateAnnotatedType = {
+  handler: WorkflowUpdateType;
+  validator?: WorkflowUpdateValidatorType;
+  description?: string;
+};
 export type WorkflowSignalType = (...args: any[]) => Promise<void> | void;
+export type WorkflowSignalAnnotatedType = { handler: WorkflowSignalType; description?: string };
 export type WorkflowQueryType = (...args: any[]) => any;
+export type WorkflowQueryAnnotatedType = { handler: WorkflowQueryType; description?: string };
 
 /**
  * Broad Workflow function definition, specific Workflows will typically use a narrower type definition, e.g:

packages/proto/scripts/compile-proto.js

@@ -15,6 +15,7 @@ const coreProtoPath = resolve(protoBaseDir, 'local/temporal/sdk/core/core_interf
 const workflowServiceProtoPath = resolve(protoBaseDir, 'api_upstream/temporal/api/workflowservice/v1/service.proto');
 const operatorServiceProtoPath = resolve(protoBaseDir, 'api_upstream/temporal/api/operatorservice/v1/service.proto');
 const errorDetailsProtoPath = resolve(protoBaseDir, 'api_upstream/temporal/api/errordetails/v1/message.proto');
+const workflowMetadataProtoPath = resolve(protoBaseDir, 'api_upstream/temporal/api/sdk/v1/workflow_metadata.proto');
 const testServiceRRProtoPath = resolve(
   protoBaseDir,
   'testsrv_upstream/temporal/api/testservice/v1/request_response.proto'
@@ -51,6 +52,7 @@ async function compileProtos(dtsOutputFile, ...args) {
     workflowServiceProtoPath,
     operatorServiceProtoPath,
     errorDetailsProtoPath,
+    workflowMetadataProtoPath,
     testServiceRRProtoPath,
     testServiceProtoPath,
     healthServiceProtoPath,

packages/test/src/integration-tests-old.ts

@@ -398,7 +398,7 @@ export function runIntegrationTests(codec?: PayloadCodec): void {
     await t.throwsAsync(workflow.query('not found'), {
       instanceOf: QueryNotRegisteredError,
       message:
-        'Workflow did not register a handler for not found. Registered queries: [__stack_trace __enhanced_stack_trace isBlocked]',
+        'Workflow did not register a handler for not found. Registered queries: [__stack_trace __enhanced_stack_trace __temporal_workflow_metadata isBlocked]',
     });
   });
 

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

@@ -224,6 +224,46 @@ test('Start of workflow with signal is delayed', async (t) => {
   t.is(tsToMs(startDelay), 4678000);
 });
 
+export async function queryWorkflowMetadata(): Promise<void> {
+  const dummyQuery1 = workflow.defineQuery<void>('dummyQuery1');
+  const dummyQuery2 = workflow.defineQuery<void>('dummyQuery2');
+  const dummyQuery3 = workflow.defineQuery<void>('dummyQuery3');
+  const dummySignal1 = workflow.defineSignal('dummySignal1');
+  const dummyUpdate1 = workflow.defineUpdate<void>('dummyUpdate1');
+
+  workflow.setHandler(dummyQuery1, () => void {}, { description: 'ignore' });
+  // Override description
+  workflow.setHandler(dummyQuery1, () => void {}, { description: 'query1' });
+  workflow.setHandler(dummyQuery2, () => void {}, { description: 'query2' });
+  workflow.setHandler(dummyQuery3, () => void {}, { description: 'query3' });
+  // Remove handler
+  workflow.setHandler(dummyQuery3, undefined);
+  workflow.setHandler(dummySignal1, () => void {}, { description: 'signal1' });
+  workflow.setHandler(dummyUpdate1, () => void {}, { description: 'update1' });
+  await workflow.condition(() => false);
+}
+
+test('Query workflow metadata returns handler descriptions', async (t) => {
+  const { createWorker, startWorkflow } = helpers(t);
+
+  const worker = await createWorker();
+
+  await worker.runUntil(async () => {
+    const handle = await startWorkflow(queryWorkflowMetadata);
+    const meta = await handle.query(workflow.workflowMetadataQuery);
+    t.is(meta.definition?.type, 'queryWorkflowMetadata');
+    const queryDefinitions = meta.definition?.queryDefinitions;
+    // Three built-in ones plus dummyQuery1 and dummyQuery2
+    t.is(queryDefinitions?.length, 5);
+    t.deepEqual(queryDefinitions?.[3], { name: 'dummyQuery1', description: 'query1' });
+    t.deepEqual(queryDefinitions?.[4], { name: 'dummyQuery2', description: 'query2' });
+    const signalDefinitions = meta.definition?.signalDefinitions;
+    t.deepEqual(signalDefinitions, [{ name: 'dummySignal1', description: 'signal1' }]);
+    const updateDefinitions = meta.definition?.updateDefinitions;
+    t.deepEqual(updateDefinitions, [{ name: 'dummyUpdate1', description: 'update1' }]);
+  });
+});
+
 export async function executeEagerActivity(): Promise<void> {
   const scheduleActivity = () =>
     workflow

packages/test/src/test-workflows.ts

@@ -1922,10 +1922,10 @@ test('query not found - successString', async (t) => {
           queryId: 'qid',
           failed: {
             message:
-              'Workflow did not register a handler for not-found. Registered queries: [__stack_trace __enhanced_stack_trace]',
+              'Workflow did not register a handler for not-found. Registered queries: [__stack_trace __enhanced_stack_trace __temporal_workflow_metadata]',
             source: 'TypeScriptSDK',
             stackTrace:
-              'ReferenceError: Workflow did not register a handler for not-found. Registered queries: [__stack_trace __enhanced_stack_trace]',
+              'ReferenceError: Workflow did not register a handler for not-found. Registered queries: [__stack_trace __enhanced_stack_trace __temporal_workflow_metadata]',
             applicationFailureInfo: {
               type: 'ReferenceError',
               nonRetryable: false,

packages/workflow/src/interfaces.ts

@@ -464,3 +464,18 @@ export type DefaultSignalHandler = (signalName: string, ...args: unknown[]) => v
  * A validation function capable of accepting the arguments for a given UpdateDefinition.
  */
 export type UpdateValidator<Args extends any[]> = (...args: Args) => void;
+
+/**
+ * A description of a query handler.
+ */
+export type QueryHandlerOptions = { description?: string };
+
+/**
+ * A description of a signal handler.
+ */
+export type SignalHandlerOptions = { description?: string };
+
+/**
+ * A validator and description of an update handler.
+ */
+export type UpdateHandlerOptions<Args extends any[]> = { validator?: UpdateValidator<Args>; description?: string };

packages/workflow/src/internals.ts

@@ -10,16 +10,15 @@ import {
   TemporalFailure,
   Workflow,
   WorkflowExecutionAlreadyStartedError,
-  WorkflowQueryType,
-  WorkflowSignalType,
-  WorkflowUpdateType,
+  WorkflowQueryAnnotatedType,
+  WorkflowSignalAnnotatedType,
+  WorkflowUpdateAnnotatedType,
   ProtoFailure,
-  WorkflowUpdateValidatorType,
   ApplicationFailure,
 } from '@temporalio/common';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { checkExtends } from '@temporalio/common/lib/type-helpers';
-import type { coresdk } from '@temporalio/proto';
+import type { coresdk, temporal } from '@temporalio/proto';
 import { alea, RNG } from './alea';
 import { RootCancellationScope } from './cancellation-scope';
 import { DeterminismViolationError, LocalActivityDoBackoff, isCancellation } from './errors';
@@ -125,12 +124,12 @@ export class Activator implements ActivationHandler {
   /**
    * Mapping of update name to handler and validator
    */
-  readonly updateHandlers = new Map<string, { handler: WorkflowUpdateType; validator?: WorkflowUpdateValidatorType }>();
+  readonly updateHandlers = new Map<string, WorkflowUpdateAnnotatedType>();
 
   /**
    * Mapping of signal name to handler
    */
-  readonly signalHandlers = new Map<string, WorkflowSignalType>();
+  readonly signalHandlers = new Map<string, WorkflowSignalAnnotatedType>();
 
   /**
    * A signal handler that catches calls for non-registered signal names.
@@ -157,38 +156,74 @@ export class Activator implements ActivationHandler {
   /**
    * Mapping of query name to handler
    */
-  public readonly queryHandlers = new Map<string, WorkflowQueryType>([
+  public readonly queryHandlers = new Map<string, WorkflowQueryAnnotatedType>([
     [
       '__stack_trace',
-      () => {
-        return this.getStackTraces()
-          .map((s) => s.formatted)
-          .join('\n\n');
+      {
+        handler: () => {
+          return this.getStackTraces()
+            .map((s) => s.formatted)
+            .join('\n\n');
+        },
+        description: 'Returns a sensible stack trace.',
       },
     ],
     [
       '__enhanced_stack_trace',
-      (): EnhancedStackTrace => {
-        const { sourceMap } = this;
-        const sdk: SDKInfo = { name: 'typescript', version: pkg.version };
-        const stacks = this.getStackTraces().map(({ structured: locations }) => ({ locations }));
-        const sources: Record<string, FileSlice[]> = {};
-        if (this.showStackTraceSources) {
-          for (const { locations } of stacks) {
-            for (const { filePath } of locations) {
-              if (!filePath) continue;
-              const content = sourceMap?.sourcesContent?.[sourceMap?.sources.indexOf(filePath)];
-              if (!content) continue;
-              sources[filePath] = [
-                {
-                  content,
-                  lineOffset: 0,
-                },
-              ];
+      {
+        handler: (): EnhancedStackTrace => {
+          const { sourceMap } = this;
+          const sdk: SDKInfo = { name: 'typescript', version: pkg.version };
+          const stacks = this.getStackTraces().map(({ structured: locations }) => ({ locations }));
+          const sources: Record<string, FileSlice[]> = {};
+          if (this.showStackTraceSources) {
+            for (const { locations } of stacks) {
+              for (const { filePath } of locations) {
+                if (!filePath) continue;
+                const content = sourceMap?.sourcesContent?.[sourceMap?.sources.indexOf(filePath)];
+                if (!content) continue;
+                sources[filePath] = [
+                  {
+                    content,
+                    lineOffset: 0,
+                  },
+                ];
+              }
             }
           }
-        }
-        return { sdk, stacks, sources };
+          return { sdk, stacks, sources };
+        },
+        description: 'Returns a stack trace annotated with source information.',
+      },
+    ],
+    [
+      '__temporal_workflow_metadata',
+      {
+        handler: (): temporal.api.sdk.v1.IWorkflowMetadata => {
+          const workflowType = this.info.workflowType;
+          const queryDefinitions = Array.from(this.queryHandlers.entries()).map(([name, value]) => ({
+            name,
+            description: value.description,
+          }));
+          const signalDefinitions = Array.from(this.signalHandlers.entries()).map(([name, value]) => ({
+            name,
+            description: value.description,
+          }));
+          const updateDefinitions = Array.from(this.updateHandlers.entries()).map(([name, value]) => ({
+            name,
+            description: value.description,
+          }));
+          return {
+            definition: {
+              type: workflowType,
+              description: null, // For now, do not set the workflow description in the TS SDK.
+              queryDefinitions,
+              signalDefinitions,
+              updateDefinitions,
+            },
+          };
+        },
+        description: 'Returns metadata associated with this workflow.',
       },
     ],
   ]);
@@ -491,7 +526,7 @@ export class Activator implements ActivationHandler {
 
   // 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);
+    const fn = this.queryHandlers.get(queryName)?.handler;
     if (fn === undefined) {
       const knownQueryTypes = [...this.queryHandlers.keys()].join(' ');
       // Fail the query
@@ -662,7 +697,7 @@ export class Activator implements ActivationHandler {
   }
 
   public async signalWorkflowNextHandler({ signalName, args }: SignalInput): Promise<void> {
-    const fn = this.signalHandlers.get(signalName);
+    const fn = this.signalHandlers.get(signalName)?.handler;
     if (fn) {
       return await fn(...args);
     } else if (this.defaultSignalHandler) {

packages/workflow/src/workflow.ts

@@ -22,6 +22,7 @@ import {
 import { versioningIntentToProto } from '@temporalio/common/lib/versioning-intent-enum';
 import { Duration, msOptionalToTs, msToNumber, msToTs, tsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { temporal } from '@temporalio/proto';
 import { CancellationScope, registerSleepImplementation } from './cancellation-scope';
 import {
   ActivityInput,
@@ -39,7 +40,9 @@ import {
   DefaultSignalHandler,
   EnhancedStackTrace,
   Handler,
-  UpdateValidator,
+  QueryHandlerOptions,
+  SignalHandlerOptions,
+  UpdateHandlerOptions,
   WorkflowInfo,
 } from './interfaces';
 import { LocalActivityDoBackoff } from './errors';
@@ -1143,15 +1146,22 @@ export function defineQuery<Ret, Args extends any[] = [], Name extends string =
  *
  * @param def an {@link UpdateDefinition}, {@link SignalDefinition}, or {@link QueryDefinition} as returned by {@link defineUpdate}, {@link defineSignal}, or {@link defineQuery} respectively.
  * @param handler a compatible handler function for the given definition or `undefined` to unset the handler.
+ * @param options an optional `description` of the handler and an optional update `validator` function.
  */
-export function setHandler<Ret, Args extends any[], T extends SignalDefinition<Args> | QueryDefinition<Ret, Args>>(
+export function setHandler<Ret, Args extends any[], T extends QueryDefinition<Ret, Args>>(
   def: T,
-  handler: Handler<Ret, Args, T> | undefined
+  handler: Handler<Ret, Args, T> | undefined,
+  options?: QueryHandlerOptions
+): void;
+export function setHandler<Ret, Args extends any[], T extends SignalDefinition<Args>>(
+  def: T,
+  handler: Handler<Ret, Args, T> | undefined,
+  options?: SignalHandlerOptions
 ): void;
 export function setHandler<Ret, Args extends any[], T extends UpdateDefinition<Ret, Args>>(
   def: T,
   handler: Handler<Ret, Args, T> | undefined,
-  options?: { validator: UpdateValidator<Args> }
+  options?: UpdateHandlerOptions<Args>
 ): void;
 
 // For Updates and Signals we want to make a public guarantee something like the
@@ -1240,12 +1250,18 @@ export function setHandler<
   Ret,
   Args extends any[],
   T extends UpdateDefinition<Ret, Args> | SignalDefinition<Args> | QueryDefinition<Ret, Args>,
->(def: T, handler: Handler<Ret, Args, T> | undefined, options?: { validator: UpdateValidator<Args> }): void {
+>(
+  def: T,
+  handler: Handler<Ret, Args, T> | undefined,
+  options?: QueryHandlerOptions | SignalHandlerOptions | UpdateHandlerOptions<Args>
+): void {
   const activator = assertInWorkflowContext('Workflow.setHandler(...) may only be used from a Workflow Execution.');
+  const description = options?.description;
   if (def.type === 'update') {
     if (typeof handler === 'function') {
-      const validator = options?.validator as WorkflowUpdateValidatorType | undefined;
-      activator.updateHandlers.set(def.name, { handler, validator });
+      const updateOptions = options as UpdateHandlerOptions<Args> | undefined;
+      const validator = updateOptions?.validator as WorkflowUpdateValidatorType | undefined;
+      activator.updateHandlers.set(def.name, { handler, validator, description });
       activator.dispatchBufferedUpdates();
     } else if (handler == null) {
       activator.updateHandlers.delete(def.name);
@@ -1254,7 +1270,7 @@ export function setHandler<
     }
   } else if (def.type === 'signal') {
     if (typeof handler === 'function') {
-      activator.signalHandlers.set(def.name, handler as any);
+      activator.signalHandlers.set(def.name, { handler: handler as any, description });
       activator.dispatchBufferedSignals();
     } else if (handler == null) {
       activator.signalHandlers.delete(def.name);
@@ -1263,7 +1279,7 @@ export function setHandler<
     }
   } else if (def.type === 'query') {
     if (typeof handler === 'function') {
-      activator.queryHandlers.set(def.name, handler as any);
+      activator.queryHandlers.set(def.name, { handler: handler as any, description });
     } else if (handler == null) {
       activator.queryHandlers.delete(def.name);
     } else {
@@ -1354,3 +1370,4 @@ export function upsertSearchAttributes(searchAttributes: SearchAttributes): void
 
 export const stackTraceQuery = defineQuery<string>('__stack_trace');
 export const enhancedStackTraceQuery = defineQuery<EnhancedStackTrace>('__enhanced_stack_trace');
+export const workflowMetadataQuery = defineQuery<temporal.api.sdk.v1.IWorkflowMetadata>('__temporal_workflow_metadata');