Special behaviour for temporal prefixes #1644

THardy98 · 2025-03-11T02:12:54Z

What was changed

Special behavior handling reserved temporal prefixes. Prevent users from:

registering activities, task queues, signals/updates/queries with a reserved prefix
calling default handlers with reserved names
going through interceptors when calling internal queries

Note: this change does not cover handling reserved temporal prefixes for workflows, as it involves non-trivial changes to the workflow bundling.

Closes [Feature Request] Special behavior for Temporal built-in prefixes #1599
How was this tested:
unit/integration tests
Any docs updates needed?
I'm not sure.

THardy98 · 2025-03-11T02:18:46Z

In this change, users are prevented from registering signals/updates/queries with reserved names from the handler.

Users can still defineQuery, defineSignal, defineUpdate that have reserved names. The reason for this is because we use defineQuery to create the reserved queries ourselves.

Alternatively, we can do the blocking in define<X> and create our internal queries/signals/updates using internal functions. Or we can do both (blocking in the define and the handler). I picked one because it seemed sufficient.

THardy98 · 2025-03-25T18:48:12Z

this is blocked on #1640 so we can handle the same prefix cases for updates as well

packages/test/src/test-workflows.ts

mjameswh · 2025-04-28T19:40:27Z

packages/workflow/src/internals.ts

@@ -619,6 +625,8 @@ export class Activator implements ActivationHandler {
  protected queryWorkflowNextHandler({ queryName, args }: QueryInput): Promise<unknown> {
    let fn = this.queryHandlers.get(queryName)?.handler;
    if (fn === undefined && this.defaultQueryHandler !== undefined) {
+      // Do not call default query handler with reserved query name.
+      throwIfReservedName('query', queryName);


I think we should not be throwing this way here. Code below is clearly designed to make sure that we are not throwing synchronously. Also, UI expects that we'll answer back with a list of accepted query types.

Actually, I'd just skip the default handler if query name is reserved. We'll still throw below, but we'll then be going the same code path as if that wasn't a reserved type name.

moved reserved prefix handling to the parent function queryWorkflow, it throws if a reserved query tries to use a default query handler

mjameswh · 2025-04-28T19:48:56Z

packages/workflow/src/internals.ts

@@ -797,6 +816,8 @@ export class Activator implements ActivationHandler {
    if (fn) {
      return await fn(...args);
    } else if (this.defaultSignalHandler) {
+      // Do not call default signal handler with reserved signal name.
+      throwIfReservedName('signal', signalName);


We definitely shouldn't throw here, as that means that adding reserved signals in the future would make those poison pills for any workers that don't yet know about them if there's a default signal handler registered. In fact, we should simply not enter signalWorkflowNextHandler if that's a reserved name and there is no registered signalHandlers for that name.

yup, moved reserved prefix handling to signalWorkflow, it throws if a reserved query tries to use a default signal handler

… test needs to be fixed, need to add behaviour reserving prefixes from workflows, and waiting for default update to be merged to add behaviour preventing default update handler to be called with reserved names

mjameswh · 2025-07-10T14:33:39Z

packages/common/src/reserved.ts

+  }
+}
+
+export function maybeGetReservedPrefix(name: string): string | undefined {


This check needs to vary based on type; not all reserved name patterns apply to all types. Also, not all reserved name patterns are prefixes; __stack_trace and __enhanced_stack_trace are exact matches.

With that in mind, I don't think using a loop makes sense. Also, I have no strong opinion about having the check logic externalized to this file, but it looks that's not what we did in other SDKs.

mjameswh · 2025-07-10T14:41:40Z

packages/common/src/reserved.ts

+  ENHANCED_STACK_TRACE_RESERVED_PREFIX,
+];
+
+export class ReservedPrefixError extends Error {


Is there a good reason to make a custom error type for this, rather than just throwing a TypeError? It's not like users will want to catch that error and do instanceof on it.

But if we'd want to keep that error class (I don't think so), it should have the @SymbolBasedInstanceOfError('...') annotation, and be exported from index.ts.

mjameswh · 2025-07-10T14:43:03Z

packages/common/src/reserved.ts

+  }
+}
+
+export function throwIfReservedName(type: string, name: string): void {


type should be a union of expected values, rather than any string.

mjameswh · 2025-07-10T14:48:44Z

packages/worker/src/worker-options.ts

@@ -953,6 +954,9 @@ export function compileWorkerOptions(
  }

  const activities = new Map(Object.entries(opts.activities ?? {}).filter(([_, v]) => typeof v === 'function'));
+  for (const activityName of activities.keys()) {


We also need to check sinks.

mjameswh · 2025-07-10T14:56:03Z

packages/worker/src/worker.ts

@@ -467,6 +468,7 @@ export class Worker {
   * This method initiates a connection to the server and will throw (asynchronously) on connection failure.
   */
  public static async create(options: WorkerOptions): Promise<Worker> {
+    throwIfReservedName('task queue', options.taskQueue);


At this point, taskQueue can be undefined. Won't that cause an NPE in throwIfServedName?

mjameswh · 2025-07-10T14:56:56Z

packages/common/src/reserved.ts

@@ -0,0 +1,31 @@
+export const TEMPORAL_RESERVED_PREFIX = '__temporal_';
+export const STACK_TRACE_RESERVED_PREFIX = '__stack_trace';


That's not a prefix. Same for next line.

THardy98 requested a review from a team as a code owner March 11, 2025 02:12

THardy98 force-pushed the handle_temporal_builtin_prefixes branch from 8170bc5 to 5f5103a Compare March 17, 2025 20:53

THardy98 changed the title ~~[WIP] Special behaviour for temporal prefixes~~ Special behaviour for temporal prefixes Mar 20, 2025

THardy98 changed the title ~~Special behaviour for temporal prefixes~~ [WIP] Special behaviour for temporal prefixes Mar 20, 2025

THardy98 changed the title ~~[WIP] Special behaviour for temporal prefixes~~ Special behaviour for temporal prefixes Mar 25, 2025

mjameswh reviewed Apr 28, 2025

View reviewed changes

packages/test/src/test-workflows.ts Outdated Show resolved Hide resolved

mjameswh reviewed Apr 28, 2025

View reviewed changes

THardy98 added 3 commits June 16, 2025 18:20

init impl for special behaviour for temporal prefixes. Default signal…

3b3a6d5

… test needs to be fixed, need to add behaviour reserving prefixes from workflows, and waiting for default update to be merged to add behaviour preventing default update handler to be called with reserved names

improvements

0d05950

special prefix behaviour, does not cover workflows

8237158

THardy98 requested a review from mjameswh June 17, 2025 14:18

THardy98 force-pushed the handle_temporal_builtin_prefixes branch from 5f5103a to 8237158 Compare June 17, 2025 14:18

THardy98 added 3 commits June 17, 2025 16:24

formatting & linting

efe9d69

remove timeout

dfb0244

fix test timeout failure

55c641f

THardy98 force-pushed the handle_temporal_builtin_prefixes branch from 1a7b249 to 55c641f Compare June 17, 2025 18:27

mjameswh reviewed Jul 10, 2025

View reviewed changes

Merge branch 'main' into handle_temporal_builtin_prefixes

12062bc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Special behaviour for temporal prefixes #1644

Special behaviour for temporal prefixes #1644

Uh oh!

THardy98 commented Mar 11, 2025 •

edited

Loading

Uh oh!

THardy98 commented Mar 11, 2025

Uh oh!

THardy98 commented Mar 25, 2025

Uh oh!

Uh oh!

mjameswh Apr 28, 2025

Uh oh!

THardy98 Jun 17, 2025

Uh oh!

mjameswh Apr 28, 2025

Uh oh!

THardy98 Jun 17, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

mjameswh Jul 10, 2025

Uh oh!

Uh oh!

		@@ -0,0 +1,31 @@
		export const TEMPORAL_RESERVED_PREFIX = '__temporal_';
		export const STACK_TRACE_RESERVED_PREFIX = '__stack_trace';

Special behaviour for temporal prefixes #1644

Are you sure you want to change the base?

Special behaviour for temporal prefixes #1644

Uh oh!

Conversation

THardy98 commented Mar 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Uh oh!

THardy98 commented Mar 11, 2025

Uh oh!

THardy98 commented Mar 25, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

THardy98 commented Mar 11, 2025 •

edited

Loading