fix(core): allow Next.js route groups and dynamic segments in workflow names (#4070)

A workflow name is derived from the module path it is defined in, so Next.js
App Router conventions end up in the name verbatim. `SAFE_WORKFLOW_NAME_PATTERN`
permitted alphanumerics, `_`, `-`, `.`, `/` and `@`, but not parentheses or
square brackets. Any workflow inside a route group (`app/(dashboard)/...`) or a
dynamic segment (`app/[teamId]/...`, `app/[...slug]/...`) threw

    Invalid workflow name "workflow//./app/(group)/workflows/": must only
    contain alphanumeric characters, ...

before it could be enqueued, and the generated name cannot be overridden.

The pattern exists to keep unsafe characters out of the queue name it is
interpolated into. These four are inert there: `ValidQueueName` accepts any
suffix after its prefix, and the only other consumers of the name are OpenTelemetry
span names. It is never placed in a URL or a SQL identifier.

Fixes #3991

Signed-off-by: Matias Torsello <23641125+torsello@users.noreply.github.com>
Co-authored-by: Matias Torsello <23641125+torsello@users.noreply.github.com>
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>

Author: torsello

.changeset/workflow-name-nextjs-route-segments.md

@@ -0,0 +1,16 @@
+---
+"@workflow/core": patch
+---
+
+Allow parentheses and square brackets in workflow names
+
+A workflow name is derived from the module path it is defined in, so Next.js App
+Router conventions end up in the name verbatim. `SAFE_WORKFLOW_NAME_PATTERN` did
+not permit `(`, `)`, `[` or `]`, so any workflow inside a route group
+(`app/(dashboard)/…`) or a dynamic segment (`app/[teamId]/…`, `app/[...slug]/…`)
+threw `Invalid workflow name` before it could be enqueued, with no way to
+override the generated name.
+
+These characters are inert in the queue name the pattern guards: `ValidQueueName`
+already accepts any suffix after its prefix, and the name is never interpolated
+into a URL or a SQL identifier.

packages/core/src/runtime/helpers.test.ts

@@ -151,6 +151,32 @@ describe('getWorkflowQueueName', () => {
     );
   });
 
+  it('should allow parentheses for Next.js route groups', () => {
+    expect(
+      getWorkflowQueueName(
+        'workflow//./app/(marketing)/workflows/checkout.ts//processOrder'
+      )
+    ).toBe(
+      '__wkf_workflow_workflow//./app/(marketing)/workflows/checkout.ts//processOrder'
+    );
+  });
+
+  it('should allow square brackets for Next.js dynamic segments', () => {
+    expect(
+      getWorkflowQueueName(
+        'workflow//./app/[teamId]/workflows/sync.ts//syncTeam'
+      )
+    ).toBe(
+      '__wkf_workflow_workflow//./app/[teamId]/workflows/sync.ts//syncTeam'
+    );
+    expect(
+      getWorkflowQueueName('workflow//./app/[...slug]/workflows/x.ts//run')
+    ).toBe('__wkf_workflow_workflow//./app/[...slug]/workflows/x.ts//run');
+    expect(
+      getWorkflowQueueName('workflow//./app/[[...slug]]/workflows/x.ts//run')
+    ).toBe('__wkf_workflow_workflow//./app/[[...slug]]/workflows/x.ts//run');
+  });
+
   it('should throw for names containing spaces', () => {
     expect(() => getWorkflowQueueName('my workflow')).toThrow(
       'Invalid workflow name'

packages/core/src/runtime/helpers.ts

@@ -43,9 +43,11 @@ const DEFAULT_HEALTH_CHECK_TIMEOUT = 30_000;
 /**
  * Pattern for safe workflow names. Only allows alphanumeric characters,
  * underscores, hyphens, dots, forward slashes (for namespaced workflows),
- * and at signs (for scoped packages).
+ * at signs (for scoped packages), and parentheses and square brackets (for
+ * Next.js route groups and dynamic segments, which appear verbatim in the
+ * module path a workflow name is derived from).
  */
-const SAFE_WORKFLOW_NAME_PATTERN = /^[a-zA-Z0-9_\-./@]+$/;
+const SAFE_WORKFLOW_NAME_PATTERN = /^[a-zA-Z0-9_\-./@()[\]]+$/;
 
 /**
  * Validates a workflow name and returns the corresponding queue name.
@@ -58,7 +60,7 @@ export function getWorkflowQueueName(
 ): ValidQueueName {
   if (!SAFE_WORKFLOW_NAME_PATTERN.test(workflowName)) {
     throw new Error(
-      `Invalid workflow name "${workflowName}": must only contain alphanumeric characters, underscores, hyphens, dots, forward slashes, or at signs`
+      `Invalid workflow name "${workflowName}": must only contain alphanumeric characters, underscores, hyphens, dots, forward slashes, at signs, parentheses, or square brackets`
     );
   }
   const prefix = getQueueTopicPrefix(