@upstash/workflow 1.3.0 → 1.3.2-rc

package/hono.js

@@ -103,6 +103,22 @@ var formatWorkflowError = (error) => {
     message: `An error occured while executing workflow: '${typeof error === "string" ? error : JSON.stringify(error)}'`
   };
 };
+var attachStepNameToError = (error, stepName) => {
+  if (typeof error !== "object" || error === null) return;
+  if ("errorStepName" in error) return;
+  if (!Object.isExtensible(error)) return;
+  try {
+    error.errorStepName = stepName;
+  } catch {
+  }
+};
+var getStepNameFromError = (error) => {
+  if (typeof error === "object" && error !== null) {
+    const stepName = error.errorStepName;
+    return typeof stepName === "string" ? stepName : void 0;
+  }
+  return void 0;
+};
 function getConstructorName(obj) {
   if (obj === null || obj === void 0) {
     return null;
@@ -196,12 +212,13 @@ var WORKFLOW_RETRIED_HEADER = "Upstash-Retried";
 var WORKFLOW_LABEL_HEADER = "Upstash-Label";
 var WORKFLOW_UNKOWN_SDK_VERSION_HEADER = "Upstash-Workflow-Unknown-Sdk";
 var WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER = "upstash-workflow-trigger-by-sdk";
+var WORKFLOW_ERROR_STEP_NAME_HEADER = "Upstash-Error-Step-Name";
 var WORKFLOW_PROTOCOL_VERSION = "1";
 var WORKFLOW_PROTOCOL_VERSION_HEADER = "Upstash-Workflow-Sdk-Version";
 var DEFAULT_CONTENT_TYPE = "application/json";
 var NO_CONCURRENCY = 1;
 var DEFAULT_RETRIES = 3;
-var VERSION = "v1.2.1";
+var VERSION = "v1.3.2";
 var SDK_TELEMETRY = `@upstash/workflow@${VERSION}`;
 var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
@@ -216,6 +233,31 @@ var import_qstash4 = require("@upstash/qstash");
 // src/utils.ts
 var NANOID_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";
 var NANOID_LENGTH = 21;
+var RESOURCE_NAME_PATTERN = /^[a-zA-Z0-9\-_.]+$/;
+function validateLabel(label) {
+  if (label === void 0) return;
+  const labels = Array.isArray(label) ? label : [label];
+  if (labels.length === 0) {
+    throw new WorkflowNonRetryableError("Invalid label: label array must not be empty.");
+  }
+  for (const value of labels) {
+    if (!RESOURCE_NAME_PATTERN.test(value)) {
+      throw new WorkflowNonRetryableError(
+        `Invalid label "${value}": must be alphanumeric, hyphen, underscore, or period.`
+      );
+    }
+  }
+}
+function serializeLabel(label) {
+  return Array.isArray(label) ? label.join(",") : label;
+}
+function validateFlowControl(flowControl) {
+  if (flowControl?.key !== void 0 && !RESOURCE_NAME_PATTERN.test(flowControl.key)) {
+    throw new WorkflowNonRetryableError(
+      `Invalid flow control key "${flowControl.key}": must be alphanumeric, hyphen, underscore, or period.`
+    );
+  }
+}
 function getRandomInt() {
   return Math.floor(Math.random() * NANOID_CHARS.length);
 }
@@ -751,8 +793,8 @@ var triggerFirstInvocation = async (params) => {
       if (unknownSdk) {
         headers[WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER] = "true";
       }
-      if (workflowContext.label) {
-        headers[WORKFLOW_LABEL_HEADER] = workflowContext.label;
+      if (workflowContext.labels.length > 0) {
+        headers[WORKFLOW_LABEL_HEADER] = serializeLabel(workflowContext.labels);
       }
       const body = typeof workflowContext.requestPayload === "string" ? workflowContext.requestPayload : JSON.stringify(workflowContext.requestPayload);
       return {
@@ -1554,8 +1596,9 @@ var LazyInvokeStep = class extends BaseLazyStep {
     });
     triggerHeaders["Upstash-Workflow-Invoke"] = "true";
     if (label) {
-      triggerHeaders[WORKFLOW_LABEL_HEADER] = label;
-      triggerHeaders[`upstash-forward-${WORKFLOW_LABEL_HEADER}`] = label;
+      const labelHeader = serializeLabel(label);
+      triggerHeaders[WORKFLOW_LABEL_HEADER] = labelHeader;
+      triggerHeaders[`upstash-forward-${WORKFLOW_LABEL_HEADER}`] = labelHeader;
     }
     return { headers: triggerHeaders, contentType };
   }
@@ -1898,7 +1941,13 @@ var submitSingleStep = async ({
   await dispatchLifecycle("beforeExecution", {
     stepName: lazyStep.stepName
   });
-  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
+  let resultStep;
+  try {
+    resultStep = await lazyStep.getResultStep(concurrency, stepId);
+  } catch (error) {
+    attachStepNameToError(error, lazyStep.stepName);
+    throw error;
+  }
   const { headers } = lazyStep.getHeaders({
     context,
     step: resultStep,
@@ -2121,9 +2170,11 @@ var AutoExecutor = class _AutoExecutor {
           if (isInstanceOf(error, WorkflowAbort) || isInstanceOf(error, import_qstash5.QstashError) && error.status === 400 || isInstanceOf(error, import_qstash5.QstashError) && error.status === 412) {
             throw error;
           }
-          throw new WorkflowError(
+          const wrappedError = new WorkflowError(
             `Error submitting steps to QStash in partial parallel step execution: ${error}`
           );
+          attachStepNameToError(wrappedError, parallelSteps[stepIndex].stepName);
+          throw wrappedError;
         }
         break;
       }
@@ -2696,9 +2747,10 @@ var WorkflowContext = class {
    */
   env;
   /**
-   * Label to apply to the workflow run.
+   * Labels attached to the workflow run.
    *
-   * Can be used to filter the workflow run logs.
+   * Can be used to filter the workflow run logs. A run can have multiple
+   * labels when triggered with `label: string[]`.
    *
    * Can be set by passing a `label` parameter when triggering the workflow
    * with `client.trigger`:
@@ -2706,11 +2758,20 @@ var WorkflowContext = class {
    * ```ts
    * await client.trigger({
    *   url: "https://workflow-endpoint.com",
-   *   label: "my-label"
+   *   label: ["label-1", "label-2"]
    * });
    * ```
    */
-  label;
+  labels;
+  /**
+   * Label of the workflow run.
+   *
+   * @deprecated Use `labels` instead. When a run has multiple labels, this
+   *   only returns the first one.
+   */
+  get label() {
+    return this.labels[0];
+  }
   /**
    * Number of times QStash has retried delivering the current request.
    *
@@ -2741,7 +2802,7 @@ var WorkflowContext = class {
     this.headers = headers;
     this.requestPayload = initialPayload;
     this.env = env ?? {};
-    this.label = label;
+    this.labels = label === void 0 ? [] : Array.isArray(label) ? label : label ? label.split(",") : [];
     this.retried = retried ?? 0;
     const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
     middlewareManagerInstance.assignContext(this);
@@ -2822,8 +2883,10 @@ var WorkflowContext = class {
     await this.addStep(new LazySleepUntilStep(this, stepName, time));
   }
   async call(stepName, settings) {
+    validateFlowControl(settings.flowControl);
     let callStep;
     if ("workflow" in settings) {
+      validateLabel(settings.label);
       const url = getNewUrlFromWorkflowId(this.url, settings.workflow.workflowId);
       const stringBody = typeof settings.body === "string" ? settings.body : settings.body === void 0 ? void 0 : JSON.stringify(settings.body);
       callStep = new LazyCallStep({
@@ -2931,6 +2994,8 @@ var WorkflowContext = class {
     );
   }
   async invoke(stepName, settings) {
+    validateLabel(settings.label);
+    validateFlowControl(settings.flowControl);
     return await this.addStep(
       new LazyInvokeStep(this, stepName, settings)
     );
@@ -3016,7 +3081,7 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       url: context.url,
       initialPayload: context.requestPayload,
       env: context.env,
-      label: context.label,
+      label: context.labels,
       retried: context.retried
     });
     try {
@@ -3854,10 +3919,12 @@ var serveBase = (routeFunction, telemetry2, options, internalOptions) => {
       await middlewareManager.dispatchDebug("onError", {
         error: isInstanceOf(error, Error) ? error : new Error(formattedError.message)
       });
+      const stepName = getStepNameFromError(error)?.replace(/[\u0000-\u001F\u007F]+/g, " ").trim();
       return new Response(JSON.stringify(formattedError), {
         status: 500,
         headers: {
-          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
+          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
+          ...stepName ? { [WORKFLOW_ERROR_STEP_NAME_HEADER]: stepName } : {}
         }
       });
     }

package/hono.mjs

@@ -2,7 +2,7 @@ import {
   SDK_TELEMETRY,
   serveBase,
   serveManyBase
-} from "./chunk-G24J5PCC.mjs";
+} from "./chunk-ICDNN4UW.mjs";
 
 // platforms/hono.ts
 var telemetry = {

package/index.d.mts

@@ -1,5 +1,5 @@
-import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-B_E1VAK6.mjs';
-export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-B_E1VAK6.mjs';
+import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-CekOpKvz.mjs';
+export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-CekOpKvz.mjs';
 import { FlowControl, PublishRequest, HTTPMethods, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 
@@ -183,6 +183,13 @@ type StepLogGroup = {
      */
     steps: {
         messageId: string;
+        /**
+         * name of the step being run.
+         *
+         * only available when the SDK reported it while the step was failing
+         * (via the `Upstash-Error-Step-Name` response header).
+         */
+        stepName?: string;
         state: "STEP_PROGRESS" | "STEP_RETRY" | "STEP_FAILED" | "STEP_CANCELED";
         /**
          * retries
@@ -247,6 +254,7 @@ type FailureFunctionLog = {
      * Status code of the response from the failure function
      */
     responseStatus?: number;
+    nextDeliveryTime?: number;
 };
 type WorkflowRunLog = {
     /**
@@ -317,9 +325,18 @@ type WorkflowRunLog = {
      */
     dlqId?: string;
     /**
-     * Label of the workflow run
+     * Label of the workflow run.
+     *
+     * @deprecated Use `labels` instead. When a run has multiple labels, this
+     *   field only contains the first one.
      */
     label?: string;
+    /**
+     * Labels attached to the workflow run.
+     *
+     * A run can have multiple labels when triggered with `label: string[]`.
+     */
+    labels?: string[];
 };
 type WorkflowRunLogs = {
     cursor: string;
@@ -403,8 +420,11 @@ type TriggerOptions = {
      * Label to apply to the workflow run.
      *
      * Can be used to filter the workflow run logs.
+     *
+     * Pass an array to attach multiple labels to a single workflow run; they are
+     * sent as a comma-separated value in the `Upstash-Label` header.
      */
-    label?: string;
+    label?: string | string[];
     /**
      * By default, Workflow SDK sends telemetry about SDK version, framework or runtime.
      *
@@ -526,7 +546,14 @@ type UniversalFilterFields = {
     fromDate?: Date | number;
     toDate?: Date | number;
     callerIp?: string;
-    label?: string;
+    /**
+     * Filter by label.
+     *
+     * Pass an array to match runs that have any of the given labels (OR semantics).
+     * For example, with runs labelled `[label_1, label_2]` and `[label_2, label_3]`,
+     * filtering by `[label_1, label_2]` returns both.
+     */
+    label?: string | string[];
     flowControlKey?: string;
 };
 /** Workflow-specific filter fields for DLQ and bulk endpoints. */
@@ -664,11 +691,20 @@ type DLQMessage = {
      */
     failureCallbackInfo?: FailureCallbackInfo;
     /**
-     * label passed when triggering workflow
+     * Label passed when triggering the workflow run.
+     *
+     * @deprecated Use `labels` instead. When a run has multiple labels, this
+     *   field only contains the first one.
      */
     label?: string;
+    /**
+     * Labels attached to the workflow run.
+     *
+     * A run can have multiple labels when triggered with `label: string[]`.
+     */
+    labels?: string[];
 };
-type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label">;
+type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label" | "labels">;
 declare class DLQ {
     private client;
     constructor(client: Client$1);

package/index.d.ts

@@ -1,5 +1,5 @@
-import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-B_E1VAK6.js';
-export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-B_E1VAK6.js';
+import { S as StepType, R as RawStep, W as WorkflowMiddleware, a as WorkflowClient, b as WorkflowReceiver, c as RouteFunction, d as WorkflowServeOptions, T as Telemetry, N as NotifyResponse, e as Waiter } from './types-CekOpKvz.js';
+export { A as AsyncStepFunction, C as CallResponse, f as CallSettings, D as DetailedFinishCondition, g as Duration, E as ExclusiveValidationOptions, F as FailureFunctionPayload, h as FinishCondition, H as HeaderParams, I as InvokableWorkflow, i as InvokeStepResponse, j as InvokeWorkflowRequest, L as LazyInvokeStepParams, k as NotifyStepResponse, P as ParallelCallState, Q as QStashClientExtraConfig, l as RequiredExceptFields, m as Step, n as StepFunction, o as StepTypes, p as SyncStepFunction, q as WaitEventOptions, r as WaitRequest, s as WaitStepResponse, t as WorkflowAbort, u as WorkflowContext, v as WorkflowError, w as WorkflowNonRetryableError, x as WorkflowRetryAfterError } from './types-CekOpKvz.js';
 import { FlowControl, PublishRequest, HTTPMethods, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 
@@ -183,6 +183,13 @@ type StepLogGroup = {
      */
     steps: {
         messageId: string;
+        /**
+         * name of the step being run.
+         *
+         * only available when the SDK reported it while the step was failing
+         * (via the `Upstash-Error-Step-Name` response header).
+         */
+        stepName?: string;
         state: "STEP_PROGRESS" | "STEP_RETRY" | "STEP_FAILED" | "STEP_CANCELED";
         /**
          * retries
@@ -247,6 +254,7 @@ type FailureFunctionLog = {
      * Status code of the response from the failure function
      */
     responseStatus?: number;
+    nextDeliveryTime?: number;
 };
 type WorkflowRunLog = {
     /**
@@ -317,9 +325,18 @@ type WorkflowRunLog = {
      */
     dlqId?: string;
     /**
-     * Label of the workflow run
+     * Label of the workflow run.
+     *
+     * @deprecated Use `labels` instead. When a run has multiple labels, this
+     *   field only contains the first one.
      */
     label?: string;
+    /**
+     * Labels attached to the workflow run.
+     *
+     * A run can have multiple labels when triggered with `label: string[]`.
+     */
+    labels?: string[];
 };
 type WorkflowRunLogs = {
     cursor: string;
@@ -403,8 +420,11 @@ type TriggerOptions = {
      * Label to apply to the workflow run.
      *
      * Can be used to filter the workflow run logs.
+     *
+     * Pass an array to attach multiple labels to a single workflow run; they are
+     * sent as a comma-separated value in the `Upstash-Label` header.
      */
-    label?: string;
+    label?: string | string[];
     /**
      * By default, Workflow SDK sends telemetry about SDK version, framework or runtime.
      *
@@ -526,7 +546,14 @@ type UniversalFilterFields = {
     fromDate?: Date | number;
     toDate?: Date | number;
     callerIp?: string;
-    label?: string;
+    /**
+     * Filter by label.
+     *
+     * Pass an array to match runs that have any of the given labels (OR semantics).
+     * For example, with runs labelled `[label_1, label_2]` and `[label_2, label_3]`,
+     * filtering by `[label_1, label_2]` returns both.
+     */
+    label?: string | string[];
     flowControlKey?: string;
 };
 /** Workflow-specific filter fields for DLQ and bulk endpoints. */
@@ -664,11 +691,20 @@ type DLQMessage = {
      */
     failureCallbackInfo?: FailureCallbackInfo;
     /**
-     * label passed when triggering workflow
+     * Label passed when triggering the workflow run.
+     *
+     * @deprecated Use `labels` instead. When a run has multiple labels, this
+     *   field only contains the first one.
      */
     label?: string;
+    /**
+     * Labels attached to the workflow run.
+     *
+     * A run can have multiple labels when triggered with `label: string[]`.
+     */
+    labels?: string[];
 };
-type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label">;
+type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label" | "labels">;
 declare class DLQ {
     private client;
     constructor(client: Client$1);

package/index.js

@@ -110,6 +110,22 @@ var formatWorkflowError = (error) => {
     message: `An error occured while executing workflow: '${typeof error === "string" ? error : JSON.stringify(error)}'`
   };
 };
+var attachStepNameToError = (error, stepName) => {
+  if (typeof error !== "object" || error === null) return;
+  if ("errorStepName" in error) return;
+  if (!Object.isExtensible(error)) return;
+  try {
+    error.errorStepName = stepName;
+  } catch {
+  }
+};
+var getStepNameFromError = (error) => {
+  if (typeof error === "object" && error !== null) {
+    const stepName = error.errorStepName;
+    return typeof stepName === "string" ? stepName : void 0;
+  }
+  return void 0;
+};
 function getConstructorName(obj) {
   if (obj === null || obj === void 0) {
     return null;
@@ -270,12 +286,13 @@ var WORKFLOW_RETRIED_HEADER = "Upstash-Retried";
 var WORKFLOW_LABEL_HEADER = "Upstash-Label";
 var WORKFLOW_UNKOWN_SDK_VERSION_HEADER = "Upstash-Workflow-Unknown-Sdk";
 var WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER = "upstash-workflow-trigger-by-sdk";
+var WORKFLOW_ERROR_STEP_NAME_HEADER = "Upstash-Error-Step-Name";
 var WORKFLOW_PROTOCOL_VERSION = "1";
 var WORKFLOW_PROTOCOL_VERSION_HEADER = "Upstash-Workflow-Sdk-Version";
 var DEFAULT_CONTENT_TYPE = "application/json";
 var NO_CONCURRENCY = 1;
 var DEFAULT_RETRIES = 3;
-var VERSION = "v1.2.1";
+var VERSION = "v1.3.2";
 var SDK_TELEMETRY = `@upstash/workflow@${VERSION}`;
 var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
@@ -290,6 +307,31 @@ var import_qstash4 = require("@upstash/qstash");
 // src/utils.ts
 var NANOID_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";
 var NANOID_LENGTH = 21;
+var RESOURCE_NAME_PATTERN = /^[a-zA-Z0-9\-_.]+$/;
+function validateLabel(label) {
+  if (label === void 0) return;
+  const labels = Array.isArray(label) ? label : [label];
+  if (labels.length === 0) {
+    throw new WorkflowNonRetryableError("Invalid label: label array must not be empty.");
+  }
+  for (const value of labels) {
+    if (!RESOURCE_NAME_PATTERN.test(value)) {
+      throw new WorkflowNonRetryableError(
+        `Invalid label "${value}": must be alphanumeric, hyphen, underscore, or period.`
+      );
+    }
+  }
+}
+function serializeLabel(label) {
+  return Array.isArray(label) ? label.join(",") : label;
+}
+function validateFlowControl(flowControl) {
+  if (flowControl?.key !== void 0 && !RESOURCE_NAME_PATTERN.test(flowControl.key)) {
+    throw new WorkflowNonRetryableError(
+      `Invalid flow control key "${flowControl.key}": must be alphanumeric, hyphen, underscore, or period.`
+    );
+  }
+}
 function getRandomInt() {
   return Math.floor(Math.random() * NANOID_CHARS.length);
 }
@@ -825,8 +867,8 @@ var triggerFirstInvocation = async (params) => {
       if (unknownSdk) {
         headers[WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER] = "true";
       }
-      if (workflowContext.label) {
-        headers[WORKFLOW_LABEL_HEADER] = workflowContext.label;
+      if (workflowContext.labels.length > 0) {
+        headers[WORKFLOW_LABEL_HEADER] = serializeLabel(workflowContext.labels);
       }
       const body = typeof workflowContext.requestPayload === "string" ? workflowContext.requestPayload : JSON.stringify(workflowContext.requestPayload);
       return {
@@ -1628,8 +1670,9 @@ var LazyInvokeStep = class extends BaseLazyStep {
     });
     triggerHeaders["Upstash-Workflow-Invoke"] = "true";
     if (label) {
-      triggerHeaders[WORKFLOW_LABEL_HEADER] = label;
-      triggerHeaders[`upstash-forward-${WORKFLOW_LABEL_HEADER}`] = label;
+      const labelHeader = serializeLabel(label);
+      triggerHeaders[WORKFLOW_LABEL_HEADER] = labelHeader;
+      triggerHeaders[`upstash-forward-${WORKFLOW_LABEL_HEADER}`] = labelHeader;
     }
     return { headers: triggerHeaders, contentType };
   }
@@ -1972,7 +2015,13 @@ var submitSingleStep = async ({
   await dispatchLifecycle("beforeExecution", {
     stepName: lazyStep.stepName
   });
-  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
+  let resultStep;
+  try {
+    resultStep = await lazyStep.getResultStep(concurrency, stepId);
+  } catch (error) {
+    attachStepNameToError(error, lazyStep.stepName);
+    throw error;
+  }
   const { headers } = lazyStep.getHeaders({
     context,
     step: resultStep,
@@ -2195,9 +2244,11 @@ var AutoExecutor = class _AutoExecutor {
           if (isInstanceOf(error, WorkflowAbort) || isInstanceOf(error, import_qstash5.QstashError) && error.status === 400 || isInstanceOf(error, import_qstash5.QstashError) && error.status === 412) {
             throw error;
           }
-          throw new WorkflowError(
+          const wrappedError = new WorkflowError(
             `Error submitting steps to QStash in partial parallel step execution: ${error}`
           );
+          attachStepNameToError(wrappedError, parallelSteps[stepIndex].stepName);
+          throw wrappedError;
         }
         break;
       }
@@ -2703,9 +2754,10 @@ var WorkflowContext = class {
    */
   env;
   /**
-   * Label to apply to the workflow run.
+   * Labels attached to the workflow run.
    *
-   * Can be used to filter the workflow run logs.
+   * Can be used to filter the workflow run logs. A run can have multiple
+   * labels when triggered with `label: string[]`.
    *
    * Can be set by passing a `label` parameter when triggering the workflow
    * with `client.trigger`:
@@ -2713,11 +2765,20 @@ var WorkflowContext = class {
    * ```ts
    * await client.trigger({
    *   url: "https://workflow-endpoint.com",
-   *   label: "my-label"
+   *   label: ["label-1", "label-2"]
    * });
    * ```
    */
-  label;
+  labels;
+  /**
+   * Label of the workflow run.
+   *
+   * @deprecated Use `labels` instead. When a run has multiple labels, this
+   *   only returns the first one.
+   */
+  get label() {
+    return this.labels[0];
+  }
   /**
    * Number of times QStash has retried delivering the current request.
    *
@@ -2748,7 +2809,7 @@ var WorkflowContext = class {
     this.headers = headers;
     this.requestPayload = initialPayload;
     this.env = env ?? {};
-    this.label = label;
+    this.labels = label === void 0 ? [] : Array.isArray(label) ? label : label ? label.split(",") : [];
     this.retried = retried ?? 0;
     const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
     middlewareManagerInstance.assignContext(this);
@@ -2829,8 +2890,10 @@ var WorkflowContext = class {
     await this.addStep(new LazySleepUntilStep(this, stepName, time));
   }
   async call(stepName, settings) {
+    validateFlowControl(settings.flowControl);
     let callStep;
     if ("workflow" in settings) {
+      validateLabel(settings.label);
       const url = getNewUrlFromWorkflowId(this.url, settings.workflow.workflowId);
       const stringBody = typeof settings.body === "string" ? settings.body : settings.body === void 0 ? void 0 : JSON.stringify(settings.body);
       callStep = new LazyCallStep({
@@ -2938,6 +3001,8 @@ var WorkflowContext = class {
     );
   }
   async invoke(stepName, settings) {
+    validateLabel(settings.label);
+    validateFlowControl(settings.flowControl);
     return await this.addStep(
       new LazyInvokeStep(this, stepName, settings)
     );
@@ -3023,7 +3088,7 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       url: context.url,
       initialPayload: context.requestPayload,
       env: context.env,
-      label: context.label,
+      label: context.labels,
       retried: context.retried
     });
     try {
@@ -3861,10 +3926,12 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
       await middlewareManager.dispatchDebug("onError", {
         error: isInstanceOf(error, Error) ? error : new Error(formattedError.message)
       });
+      const stepName = getStepNameFromError(error)?.replace(/[\u0000-\u001F\u007F]+/g, " ").trim();
       return new Response(JSON.stringify(formattedError), {
         status: 500,
         headers: {
-          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
+          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
+          ...stepName ? { [WORKFLOW_ERROR_STEP_NAME_HEADER]: stepName } : {}
         }
       });
     }
@@ -4111,13 +4178,15 @@ var Client4 = class {
     const isBatchInput = Array.isArray(params);
     const options = isBatchInput ? params : [params];
     const invocations = options.map((option) => {
+      validateLabel(option.label);
+      validateFlowControl(option.flowControl);
       const failureUrl = option.failureUrl ?? option.url;
       const finalWorkflowRunId = getWorkflowRunId(option.workflowRunId);
       const context = new WorkflowContext({
         qstashClient: this.client,
         headers: new Headers({
           ...option.headers ?? {},
-          ...option.label ? { [WORKFLOW_LABEL_HEADER]: option.label } : {}
+          ...option.label ? { [WORKFLOW_LABEL_HEADER]: serializeLabel(option.label) } : {}
         }),
         initialPayload: option.body,
         steps: [],

package/index.mjs

@@ -15,9 +15,12 @@ import {
   makeNotifyRequest,
   normalizeCursor,
   prepareFlowControl,
+  serializeLabel,
   serve,
-  triggerFirstInvocation
-} from "./chunk-G24J5PCC.mjs";
+  triggerFirstInvocation,
+  validateFlowControl,
+  validateLabel
+} from "./chunk-ICDNN4UW.mjs";
 
 // src/client/index.ts
 import { Client as QStashClient } from "@upstash/qstash";
@@ -248,13 +251,15 @@ var Client = class {
     const isBatchInput = Array.isArray(params);
     const options = isBatchInput ? params : [params];
     const invocations = options.map((option) => {
+      validateLabel(option.label);
+      validateFlowControl(option.flowControl);
       const failureUrl = option.failureUrl ?? option.url;
       const finalWorkflowRunId = getWorkflowRunId(option.workflowRunId);
       const context = new WorkflowContext({
         qstashClient: this.client,
         headers: new Headers({
           ...option.headers ?? {},
-          ...option.label ? { [WORKFLOW_LABEL_HEADER]: option.label } : {}
+          ...option.label ? { [WORKFLOW_LABEL_HEADER]: serializeLabel(option.label) } : {}
         }),
         initialPayload: option.body,
         steps: [],