@upstash/workflow 1.3.3 → 1.4.0-rc

package/nextjs.js

@@ -29,6 +29,9 @@ __export(nextjs_exports, {
 });
 module.exports = __toCommonJS(nextjs_exports);
 
+// src/serve/index.ts
+var import_qstash12 = require("@upstash/qstash");
+
 // src/client/utils.ts
 var import_qstash2 = require("@upstash/qstash");
 
@@ -217,6 +220,14 @@ var WORKFLOW_CREATED_AT_HEADER = "Upstash-Workflow-CreatedAt";
 var WORKFLOW_FAILURE_HEADER = "Upstash-Workflow-Is-Failure";
 var WORKFLOW_FAILURE_CALLBACK_HEADER = "Upstash-Workflow-Failure-Callback";
 var WORKFLOW_FEATURE_HEADER = "Upstash-Feature-Set";
+var WORKFLOW_FEATURE_SET = "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig";
+var WORKFLOW_STEP_CONFIG_CALL_TYPE = "stepConfig";
+var WORKFLOW_STEP_CONFIG_HEADER = "Upstash-Workflow-Step-Config";
+var FLOW_CONTROL_KEY_HEADER = "Upstash-Flow-Control-Key";
+var FLOW_CONTROL_VALUE_HEADER = "Upstash-Flow-Control-Value";
+var RETRIES_HEADER = "Upstash-Retries";
+var RETRY_DELAY_HEADER = "Upstash-Retry-Delay";
+var WORKFLOW_STEP_CONFIG_FEATURE = "WF_StepConfig";
 var WORKFLOW_INVOKE_COUNT_HEADER = "Upstash-Workflow-Invoke-Count";
 var WORKFLOW_RETRIED_HEADER = "Upstash-Retried";
 var WORKFLOW_LABEL_HEADER = "Upstash-Label";
@@ -234,102 +245,6 @@ var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
 var TELEMETRY_HEADER_RUNTIME = "Upstash-Telemetry-Runtime";
 
-// src/context/auto-executor.ts
-var import_qstash5 = require("@upstash/qstash");
-
-// src/qstash/headers.ts
-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);
-}
-function nanoid(length = NANOID_LENGTH) {
-  return Array.from({ length }).map(() => NANOID_CHARS[getRandomInt()]).join("");
-}
-function getWorkflowRunId(id) {
-  return `wfr_${id ?? nanoid()}`;
-}
-function decodeBase64(base64) {
-  const binString = atob(base64);
-  try {
-    const intArray = Uint8Array.from(binString, (m) => m.codePointAt(0));
-    return new TextDecoder().decode(intArray);
-  } catch (error) {
-    console.warn(
-      `Upstash Qstash: Failed while decoding base64 "${base64}". Decoding with atob and returning it instead. ${error}`
-    );
-    return binString;
-  }
-}
-function getUserIdFromToken(qstashClient) {
-  try {
-    const token = qstashClient.token;
-    const decodedToken = decodeBase64(token);
-    const tokenPayload = JSON.parse(decodedToken);
-    const userId = tokenPayload.UserID;
-    if (!userId) {
-      throw new WorkflowError("QStash token payload does not contain userId");
-    }
-    return userId;
-  } catch (error) {
-    throw new WorkflowError(
-      `Failed to decode QStash token while running create webhook step: ${error.message}`
-    );
-  }
-}
-function getQStashUrl(qstashClient) {
-  try {
-    const requester = qstashClient.http;
-    const baseUrl = requester.baseUrl;
-    if (!baseUrl) {
-      throw new WorkflowError("QStash client does not have a baseUrl");
-    }
-    return baseUrl;
-  } catch (error) {
-    throw new WorkflowError(`Failed to get QStash URL from client: ${error.message}`);
-  }
-}
-function getEventId() {
-  return `evt_${nanoid(15)}`;
-}
-function stringifyBody(body) {
-  if (body === void 0) {
-    return void 0;
-  }
-  if (typeof body === "string") {
-    return body;
-  }
-  return JSON.stringify(body);
-}
-
 // node_modules/neverthrow/dist/index.es.js
 var defaultErrorConfig = {
   withStackTrace: false
@@ -745,6 +660,102 @@ var Err = class {
 };
 var fromThrowable = Result.fromThrowable;
 
+// src/context/auto-executor.ts
+var import_qstash5 = require("@upstash/qstash");
+
+// src/qstash/headers.ts
+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);
+}
+function nanoid(length = NANOID_LENGTH) {
+  return Array.from({ length }).map(() => NANOID_CHARS[getRandomInt()]).join("");
+}
+function getWorkflowRunId(id) {
+  return `wfr_${id ?? nanoid()}`;
+}
+function decodeBase64(base64) {
+  const binString = atob(base64);
+  try {
+    const intArray = Uint8Array.from(binString, (m) => m.codePointAt(0));
+    return new TextDecoder().decode(intArray);
+  } catch (error) {
+    console.warn(
+      `Upstash Qstash: Failed while decoding base64 "${base64}". Decoding with atob and returning it instead. ${error}`
+    );
+    return binString;
+  }
+}
+function getUserIdFromToken(qstashClient) {
+  try {
+    const token = qstashClient.token;
+    const decodedToken = decodeBase64(token);
+    const tokenPayload = JSON.parse(decodedToken);
+    const userId = tokenPayload.UserID;
+    if (!userId) {
+      throw new WorkflowError("QStash token payload does not contain userId");
+    }
+    return userId;
+  } catch (error) {
+    throw new WorkflowError(
+      `Failed to decode QStash token while running create webhook step: ${error.message}`
+    );
+  }
+}
+function getQStashUrl(qstashClient) {
+  try {
+    const requester = qstashClient.http;
+    const baseUrl = requester.baseUrl;
+    if (!baseUrl) {
+      throw new WorkflowError("QStash client does not have a baseUrl");
+    }
+    return baseUrl;
+  } catch (error) {
+    throw new WorkflowError(`Failed to get QStash URL from client: ${error.message}`);
+  }
+}
+function getEventId() {
+  return `evt_${nanoid(15)}`;
+}
+function stringifyBody(body) {
+  if (body === void 0) {
+    return void 0;
+  }
+  if (typeof body === "string") {
+    return body;
+  }
+  return JSON.stringify(body);
+}
+
 // src/types.ts
 var StepTypes = [
   "Initial",
@@ -850,6 +861,10 @@ var triggerFirstInvocation = async (params) => {
     return err(error_);
   }
 };
+var flushPendingStep = async (workflowContext) => {
+  const { executor } = workflowContext;
+  return await executor.submitPendingStep();
+};
 var triggerRouteFunction = async ({
   onCleanup,
   onStep,
@@ -1057,8 +1072,29 @@ If you want to disable QStash Verification, you should clear env variables QSTAS
 var BaseLazyStep = class _BaseLazyStep {
   stepName;
   context;
-  constructor(context, stepName) {
+  /**
+   * step-level settings (flow control, retries etc.) which override the
+   * settings the workflow run was triggered with, for this step only.
+   */
+  stepSettings;
+  /**
+   * whether this step's result can be submitted after the route function
+   * has moved on, instead of right away.
+   *
+   * Enabled for steps whose `getResultStep` produces the final `out` —
+   * which is not the same as "needs no server round trip":
+   * `LazyCreateWebhookStep` builds its result in `getBody` and returns
+   * `out: undefined` from `getResultStep`, so deferring it would hand
+   * `undefined` to the route function.
+   *
+   * Deferring lets the route function continue and reveal the next step,
+   * so that step's settings can ride on this step's submission instead
+   * of needing a step config request of their own.
+   */
+  supportsDeferredSubmission = false;
+  constructor(context, stepName, stepSettings) {
     this.context = context;
+    this.stepSettings = stepSettings;
     if (!stepName) {
       throw new WorkflowError(
         "A workflow step name cannot be undefined or an empty string. Please provide a name for your workflow step."
@@ -1122,7 +1158,13 @@ var BaseLazyStep = class _BaseLazyStep {
     step.out = JSON.stringify(step.out);
     return JSON.stringify(step);
   }
-  getHeaders({ context, telemetry, invokeCount, step }) {
+  getHeaders({
+    context,
+    telemetry,
+    invokeCount,
+    step,
+    stepSettings
+  }) {
     return getHeaders({
       initHeaderValue: "false",
       workflowConfig: {
@@ -1135,7 +1177,8 @@ var BaseLazyStep = class _BaseLazyStep {
       stepInfo: {
         step,
         lazyStep: this
-      }
+      },
+      stepSettings
     });
   }
   async submitStep({ context, body, headers }) {
@@ -1153,8 +1196,9 @@ var LazyFunctionStep = class extends BaseLazyStep {
   stepFunction;
   stepType = "Run";
   allowUndefinedOut = true;
-  constructor(context, stepName, stepFunction) {
-    super(context, stepName);
+  supportsDeferredSubmission = true;
+  constructor(context, stepName, stepFunction, stepSettings) {
+    super(context, stepName, stepSettings);
     this.stepFunction = stepFunction;
   }
   getPlanStep(concurrent, targetStep) {
@@ -1184,6 +1228,7 @@ var LazySleepStep = class extends BaseLazyStep {
   sleep;
   stepType = "SleepFor";
   allowUndefinedOut = true;
+  supportsDeferredSubmission = true;
   constructor(context, stepName, sleep) {
     super(context, stepName);
     this.sleep = sleep;
@@ -1223,6 +1268,7 @@ var LazySleepUntilStep = class extends BaseLazyStep {
   sleepUntil;
   stepType = "SleepUntil";
   allowUndefinedOut = true;
+  supportsDeferredSubmission = true;
   constructor(context, stepName, sleepUntil) {
     super(context, stepName);
     this.sleepUntil = sleepUntil;
@@ -1715,6 +1761,7 @@ var WorkflowHeaders = class {
   invokeCount;
   initHeaderValue;
   stepInfo;
+  stepSettings;
   headers;
   /**
    * @param params workflow header parameters
@@ -1724,17 +1771,20 @@ var WorkflowHeaders = class {
     workflowConfig,
     invokeCount,
     initHeaderValue,
-    stepInfo
+    stepInfo,
+    stepSettings
   }) {
     this.userHeaders = userHeaders;
     this.workflowConfig = workflowConfig;
     this.invokeCount = invokeCount;
     this.initHeaderValue = initHeaderValue;
     this.stepInfo = stepInfo;
+    this.stepSettings = stepSettings;
     this.headers = {
       rawHeaders: {},
       workflowHeaders: {},
-      failureHeaders: {}
+      failureHeaders: {},
+      stepSettingsHeaders: {}
     };
   }
   getHeaders() {
@@ -1745,6 +1795,7 @@ var WorkflowHeaders = class {
     this.addUserHeaders();
     this.addInvokeCount();
     this.addFailureUrl();
+    this.addStepSettings();
     const contentType = this.addContentType();
     return this.prefixHeaders(contentType);
   }
@@ -1754,7 +1805,7 @@ var WorkflowHeaders = class {
       [WORKFLOW_INIT_HEADER]: this.initHeaderValue,
       [WORKFLOW_ID_HEADER]: this.workflowConfig.workflowRunId,
       [WORKFLOW_URL_HEADER]: this.workflowConfig.workflowUrl,
-      [WORKFLOW_FEATURE_HEADER]: "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig",
+      [WORKFLOW_FEATURE_HEADER]: WORKFLOW_FEATURE_SET,
       [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
       ...this.workflowConfig.telemetry ? getTelemetryHeaders(this.workflowConfig.telemetry) : {}
     };
@@ -1832,7 +1883,7 @@ var WorkflowHeaders = class {
     this.headers.failureHeaders["Workflow-Init"] = "false";
     this.headers.failureHeaders["Workflow-Url"] = this.workflowConfig.workflowUrl;
     this.headers.failureHeaders["Workflow-Calltype"] = "failureCall";
-    this.headers.failureHeaders["Feature-Set"] = "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig";
+    this.headers.failureHeaders["Feature-Set"] = WORKFLOW_FEATURE_SET;
     if (this.workflowConfig.retries !== void 0 && this.workflowConfig.retries !== DEFAULT_RETRIES) {
       this.headers.failureHeaders["Retries"] = this.workflowConfig.retries.toString();
     }
@@ -1840,6 +1891,42 @@ var WorkflowHeaders = class {
       this.headers.failureHeaders["Retry-Delay"] = this.workflowConfig.retryDelay.toString();
     }
   }
+  /**
+   * Applies the step-level settings of a step to the message.
+   *
+   * These headers configure the message itself, so that QStash uses them
+   * instead of the settings the run was triggered with. The delivery of
+   * the message is what executes the step, which is how a step's
+   * settings reach it.
+   *
+   * When any setting is present the feature set is extended with
+   * `WF_StepConfig`, which is what tells QStash to keep them. QStash
+   * reports that back on the delivery as `Upstash-Workflow-Step-Config`.
+   */
+  addStepSettings() {
+    if (!this.stepSettings) {
+      return;
+    }
+    const headers = {};
+    if (this.stepSettings.flowControl) {
+      const { flowControlKey, flowControlValue } = prepareFlowControl(
+        this.stepSettings.flowControl
+      );
+      headers[FLOW_CONTROL_KEY_HEADER] = flowControlKey;
+      headers[FLOW_CONTROL_VALUE_HEADER] = flowControlValue;
+    }
+    if (this.stepSettings.retries !== void 0) {
+      headers[RETRIES_HEADER] = this.stepSettings.retries.toString();
+    }
+    if (this.stepSettings.retryDelay) {
+      headers[RETRY_DELAY_HEADER] = this.stepSettings.retryDelay;
+    }
+    if (Object.keys(headers).length === 0) {
+      return;
+    }
+    headers[WORKFLOW_FEATURE_HEADER] = `${WORKFLOW_FEATURE_SET},${WORKFLOW_STEP_CONFIG_FEATURE}`;
+    this.headers.stepSettingsHeaders = headers;
+  }
   addContentType() {
     if (this.workflowConfig.useJSONContent) {
       this.headers.rawHeaders["content-type"] = "application/json";
@@ -1853,14 +1940,17 @@ var WorkflowHeaders = class {
     return contentType;
   }
   prefixHeaders(contentType) {
-    const { rawHeaders, workflowHeaders, failureHeaders } = this.headers;
+    const { rawHeaders, workflowHeaders, failureHeaders, stepSettingsHeaders } = this.headers;
     const isCall = this.stepInfo?.lazyStep.stepType === "Call";
     return {
       headers: {
         ...rawHeaders,
         ...addPrefixToHeaders(workflowHeaders, isCall ? "Upstash-Callback-" : "Upstash-"),
         ...addPrefixToHeaders(failureHeaders, "Upstash-Failure-Callback-"),
-        ...isCall ? addPrefixToHeaders(failureHeaders, "Upstash-Callback-Failure-Callback-") : {}
+        ...isCall ? addPrefixToHeaders(failureHeaders, "Upstash-Callback-Failure-Callback-") : {},
+        // last, so they override the run's settings above. Never
+        // prefixed: they configure this message, not its callback.
+        ...stepSettingsHeaders
       },
       contentType
     };
@@ -1911,7 +2001,7 @@ var submitParallelSteps = async ({
     info: `Submitting ${planSteps.length} parallel steps.`
   });
   const result = await context.qstashClient.batch(
-    planSteps.map((planStep) => {
+    planSteps.map((planStep, index) => {
       const { headers } = getHeaders({
         initHeaderValue: "false",
         workflowConfig: {
@@ -1919,7 +2009,8 @@ var submitParallelSteps = async ({
           workflowUrl: context.url,
           telemetry
         },
-        invokeCount
+        invokeCount,
+        stepSettings: steps[index].stepSettings
       });
       return {
         headers,
@@ -1938,31 +2029,38 @@ var submitParallelSteps = async ({
   }
   throw new WorkflowAbort(planSteps[0].stepName, planSteps[0]);
 };
-var submitSingleStep = async ({
-  context,
+var executeStep = async ({
   lazyStep,
   stepId,
-  invokeCount,
   concurrency,
-  telemetry,
-  dispatchDebug,
   dispatchLifecycle
 }) => {
   await dispatchLifecycle("beforeExecution", {
     stepName: lazyStep.stepName
   });
-  let resultStep;
   try {
-    resultStep = await lazyStep.getResultStep(concurrency, stepId);
+    return await lazyStep.getResultStep(concurrency, stepId);
   } catch (error) {
     attachStepNameToError(error, lazyStep.stepName);
     throw error;
   }
+};
+var submitStepResult = async ({
+  context,
+  lazyStep,
+  resultStep,
+  invokeCount,
+  concurrency,
+  telemetry,
+  dispatchDebug,
+  nextStepSettings
+}) => {
   const { headers } = lazyStep.getHeaders({
     context,
     step: resultStep,
     invokeCount,
-    telemetry
+    telemetry,
+    stepSettings: nextStepSettings
   });
   const body = lazyStep.getBody({
     context,
@@ -1987,6 +2085,138 @@ var submitSingleStep = async ({
   }
   return resultStep;
 };
+var publishStepConfigRequest = async ({
+  context,
+  lazyStep,
+  targetStep,
+  invokeCount,
+  telemetry,
+  dispatchDebug
+}) => {
+  const { headers } = getHeaders({
+    initHeaderValue: "false",
+    workflowConfig: {
+      workflowRunId: context.workflowRunId,
+      workflowUrl: context.url,
+      telemetry
+    },
+    invokeCount,
+    stepSettings: lazyStep.stepSettings
+  });
+  await dispatchDebug("onInfo", {
+    info: `Step "${lazyStep.stepName}" (${targetStep}) has step-level settings which the current delivery does not carry. Requesting a delivery which does.`
+  });
+  const result = await context.qstashClient.publishJSON({
+    headers: {
+      ...headers,
+      "Upstash-Workflow-CallType": WORKFLOW_STEP_CONFIG_CALL_TYPE
+    },
+    method: "POST",
+    body: { targetStep, invokeCount },
+    url: context.url,
+    contentBasedDeduplication: true
+  });
+  if (result?.deduplicated) {
+    await dispatchDebug("onWarning", {
+      warning: `A step config request for step "${lazyStep.stepName}" (${targetStep}) was already published and this one was deduplicated. Expected when the delivery which published it is being retried; otherwise the run stops here.`
+    });
+  } else if (result?.messageId) {
+    await dispatchDebug("onInfo", {
+      info: `Requested a delivery under the settings of step "${lazyStep.stepName}" with messageId: ${result.messageId}.`
+    });
+  }
+};
+
+// src/qstash/step-config.ts
+var DEFAULT_PARALLELISM = 0;
+var DEFAULT_RATE = 0;
+var DEFAULT_PERIOD_SECONDS = 1;
+var SECONDS_PER_UNIT = {
+  s: 1,
+  m: 60,
+  h: 60 * 60,
+  d: 24 * 60 * 60
+};
+var durationToSeconds = (duration) => {
+  if (typeof duration === "number") {
+    return Number.isFinite(duration) ? duration : void 0;
+  }
+  const match = /^(\d+)([smhd])$/.exec(duration.trim());
+  if (match) {
+    return Number(match[1]) * SECONDS_PER_UNIT[match[2]];
+  }
+  const seconds = Number(duration.trim());
+  return Number.isFinite(seconds) ? seconds : void 0;
+};
+var normalizeFlowControl = (flowControl) => {
+  const period = flowControl.period === void 0 ? void 0 : durationToSeconds(flowControl.period);
+  return {
+    key: flowControl.key,
+    parallelism: flowControl.parallelism ?? DEFAULT_PARALLELISM,
+    rate: flowControl.rate ?? flowControl.ratePerSecond ?? DEFAULT_RATE,
+    period: period ?? DEFAULT_PERIOD_SECONDS
+  };
+};
+var parseFlowControlHeaders = (key, value) => {
+  if (!key) {
+    return void 0;
+  }
+  const flowControl = {
+    key,
+    parallelism: DEFAULT_PARALLELISM,
+    rate: DEFAULT_RATE,
+    period: DEFAULT_PERIOD_SECONDS
+  };
+  for (const entry of (value ?? "").split(",")) {
+    const [name, rawValue] = entry.split("=").map((part) => part.trim());
+    if (!name || rawValue === void 0) {
+      continue;
+    }
+    switch (name) {
+      case "parallelism": {
+        flowControl.parallelism = Number(rawValue);
+        break;
+      }
+      case "rate": {
+        flowControl.rate = Number(rawValue);
+        break;
+      }
+      case "period": {
+        flowControl.period = durationToSeconds(rawValue) ?? DEFAULT_PERIOD_SECONDS;
+        break;
+      }
+    }
+  }
+  return flowControl;
+};
+var getEffectiveConfig = (headers) => {
+  const retriesHeader = headers.get(RETRIES_HEADER);
+  return {
+    flowControl: parseFlowControlHeaders(
+      headers.get(FLOW_CONTROL_KEY_HEADER),
+      headers.get(FLOW_CONTROL_VALUE_HEADER)
+    ),
+    retries: retriesHeader === null ? void 0 : Number(retriesHeader),
+    retryDelay: headers.get(RETRY_DELAY_HEADER) ?? void 0,
+    hasStepConfig: headers.get(WORKFLOW_STEP_CONFIG_HEADER) === "true"
+  };
+};
+var describeStepSettingsMismatch = (stepSettings, effectiveConfig) => {
+  if (stepSettings.flowControl) {
+    const wanted = normalizeFlowControl(stepSettings.flowControl);
+    const applied = effectiveConfig.flowControl;
+    if (!applied || applied.key !== wanted.key || applied.parallelism !== wanted.parallelism || applied.rate !== wanted.rate || applied.period !== wanted.period) {
+      return `flow control: expected ${JSON.stringify(wanted)}, delivery has ${JSON.stringify(applied)}`;
+    }
+  }
+  if (stepSettings.retries !== void 0 && effectiveConfig.retries !== void 0 && stepSettings.retries !== effectiveConfig.retries) {
+    return `retries: expected ${stepSettings.retries}, delivery has ${effectiveConfig.retries}`;
+  }
+  if (stepSettings.retryDelay !== void 0 && stepSettings.retryDelay !== effectiveConfig.retryDelay) {
+    return `retry delay: expected '${stepSettings.retryDelay}', delivery has '${effectiveConfig.retryDelay ?? ""}'`;
+  }
+  return void 0;
+};
 
 // src/context/auto-executor.ts
 var AutoExecutor = class _AutoExecutor {
@@ -2003,6 +2233,25 @@ var AutoExecutor = class _AutoExecutor {
   stepCount = 0;
   planStepCount = 0;
   executingStep = false;
+  /**
+   * an executed step whose result hasn't been submitted to QStash yet.
+   *
+   * Set when a step which can produce its result in-process executes. The
+   * submission waits so that the route function can continue and reveal
+   * what comes next: if that is a single step with step-level settings,
+   * the settings ride on this submission and no step config request is
+   * needed, since the delivery of the submission is what executes it.
+   *
+   * Flushed when the next step is reached (see `addStep`) or when the
+   * route function ends (see `flushPendingStep` in `serve`).
+   */
+  pendingStep;
+  /**
+   * configuration QStash applied to the delivery being handled. A step
+   * with step-level settings is settled by comparing its settings against
+   * this.
+   */
+  effectiveConfig;
   /**
    * @param context workflow context
    * @param steps list of steps
@@ -2010,14 +2259,17 @@ var AutoExecutor = class _AutoExecutor {
    * @param dispatchLifecycle lifecycle event dispatcher
    * @param telemetry optional telemetry information
    * @param invokeCount optional invoke count
+   * @param effectiveConfig configuration QStash applied to the delivery
+   *   being handled
    */
-  constructor(context, steps, dispatchDebug, dispatchLifecycle, telemetry, invokeCount) {
+  constructor(context, steps, dispatchDebug, dispatchLifecycle, telemetry, invokeCount, effectiveConfig) {
     this.context = context;
     this.steps = steps;
     this.dispatchDebug = dispatchDebug;
     this.dispatchLifecycle = dispatchLifecycle;
     this.telemetry = telemetry;
     this.invokeCount = invokeCount ?? 0;
+    this.effectiveConfig = effectiveConfig ?? { hasStepConfig: false };
     this.nonPlanStepCount = this.steps.filter((step) => !step.targetStep).length;
   }
   /**
@@ -2052,6 +2304,15 @@ var AutoExecutor = class _AutoExecutor {
     lazyStepList.push(stepInfo);
     const index = this.indexInCurrentList++;
     const requestComplete = this.deferExecution().then(async () => {
+      const submitted = await this.submitPendingStep(
+        lazyStepList.length === 1 ? lazyStepList[0].stepSettings : void 0
+      );
+      if (submitted.isErr()) {
+        throw submitted.error;
+      }
+      if (submitted.value.result === "submitted-step") {
+        throw submitted.value.abort;
+      }
       if (!this.promises.has(lazyStepList)) {
         const promise2 = this.getExecutionPromise(lazyStepList);
         this.promises.set(lazyStepList, promise2);
@@ -2105,18 +2366,100 @@ var AutoExecutor = class _AutoExecutor {
       }
       return parsedOut;
     }
-    const resultStep = await submitSingleStep({
-      context: this.context,
+    const mismatch = lazyStep.stepSettings ? describeStepSettingsMismatch(lazyStep.stepSettings, this.effectiveConfig) : void 0;
+    if (mismatch) {
+      if (!this.effectiveConfig.hasStepConfig) {
+        await publishStepConfigRequest({
+          context: this.context,
+          lazyStep,
+          targetStep: this.stepCount,
+          invokeCount: this.invokeCount,
+          telemetry: this.telemetry,
+          dispatchDebug: this.dispatchDebug
+        });
+        throw new WorkflowAbort(lazyStep.stepName);
+      } else {
+        await this.dispatchDebug("onWarning", {
+          warning: `The step-level settings of step '${lazyStep.stepName}' were published but are not recognized on the delivery which carries them (${mismatch}). Executing the step with the settings of the delivery instead. This is a bug in @upstash/workflow, please report it.`
+        });
+      }
+    }
+    const resultStep = await executeStep({
       lazyStep,
       stepId: this.stepCount,
+      concurrency: NO_CONCURRENCY,
+      dispatchLifecycle: this.dispatchLifecycle
+    });
+    if (lazyStep.supportsDeferredSubmission) {
+      this.pendingStep = { status: "held", lazyStep, resultStep };
+      return lazyStep.parseOut({
+        ...resultStep,
+        out: resultStep.out === void 0 ? void 0 : JSON.stringify(resultStep.out)
+      });
+    }
+    await submitStepResult({
+      context: this.context,
+      lazyStep,
+      resultStep,
       invokeCount: this.invokeCount,
-      concurrency: 1,
+      concurrency: NO_CONCURRENCY,
       telemetry: this.telemetry,
-      dispatchDebug: this.dispatchDebug,
-      dispatchLifecycle: this.dispatchLifecycle
+      dispatchDebug: this.dispatchDebug
     });
     throw new WorkflowAbort(lazyStep.stepName, resultStep);
   }
+  /**
+   * Submits the result of the step being held, if there is one, and
+   * returns the abort the caller has to throw to end the invocation.
+   *
+   * Returns undefined when no step is being held, which is the caller's
+   * signal that there is nothing to end. Throws instead of returning
+   * when the submission itself fails, so that error reaches the caller
+   * rather than an abort claiming the step was submitted.
+   *
+   * Callers which arrive while a submission is already under way (the
+   * steps of a parallel group, added together) wait for that one and get
+   * the same abort, rather than submitting a second time.
+   *
+   * The next step's settings are attached whenever it has any, without
+   * checking them against the current delivery: the executor only knows
+   * the configuration of the delivery in hand, which inside a
+   * delivery is the *previous* step's, so such a check would be wrong
+   * exactly when two steps with settings follow each other.
+   *
+   * @param nextStepSettings step-level settings of the next step
+   * @returns `submitted-step` with the abort which ends this invocation,
+   *   or `no-pending-step` when nothing was held and there is nothing to
+   *   end
+   */
+  async submitPendingStep(nextStepSettings) {
+    if (!this.pendingStep) {
+      return ok({ result: "no-pending-step" });
+    }
+    try {
+      if (this.pendingStep.status === "submitting") {
+        return ok({ result: "submitted-step", abort: await this.pendingStep.submitted });
+      }
+      const { lazyStep, resultStep } = this.pendingStep;
+      const submitted = (async () => {
+        await submitStepResult({
+          context: this.context,
+          lazyStep,
+          resultStep,
+          invokeCount: this.invokeCount,
+          concurrency: NO_CONCURRENCY,
+          telemetry: this.telemetry,
+          dispatchDebug: this.dispatchDebug,
+          nextStepSettings
+        });
+        return new WorkflowAbort(lazyStep.stepName, resultStep);
+      })();
+      this.pendingStep = { status: "submitting", submitted };
+      return ok({ result: "submitted-step", abort: await submitted });
+    } catch (error) {
+      return err(error);
+    }
+  }
   /**
    * Runs steps in parallel.
    *
@@ -2165,15 +2508,20 @@ var AutoExecutor = class _AutoExecutor {
         validateStep(parallelSteps[stepIndex], planStep);
         try {
           const parallelStep = parallelSteps[stepIndex];
-          const resultStep = await submitSingleStep({
-            context: this.context,
+          const resultStep = await executeStep({
             lazyStep: parallelStep,
             stepId: planStep.targetStep,
+            concurrency: parallelSteps.length,
+            dispatchLifecycle: this.dispatchLifecycle
+          });
+          await submitStepResult({
+            context: this.context,
+            lazyStep: parallelStep,
+            resultStep,
             invokeCount: this.invokeCount,
             concurrency: parallelSteps.length,
             telemetry: this.telemetry,
-            dispatchDebug: this.dispatchDebug,
-            dispatchLifecycle: this.dispatchLifecycle
+            dispatchDebug: this.dispatchDebug
           });
           throw new WorkflowAbort(parallelStep.stepName, resultStep);
         } catch (error) {
@@ -2789,6 +3137,46 @@ var WorkflowContext = class {
    * `1` on the first retry, `2` on the second, and so on.
    */
   retried;
+  /**
+   * Configuration QStash applied to the request being handled.
+   *
+   * This is the configuration of *this delivery*, not of the run: it is
+   * the configuration the run was triggered with, except inside the
+   * delivery which executes a step that has step-level settings, where
+   * it is that step's settings. The fields below expose it; the executor
+   * gets it directly rather than reaching through the context.
+   */
+  effectiveConfig;
+  /**
+   * Flow control QStash applied to the request being handled, if any.
+   *
+   * This is the flow control of the request in hand, which is the one the
+   * run was triggered with except inside a step carrying its own.
+   */
+  get flowControl() {
+    return this.effectiveConfig.flowControl;
+  }
+  /**
+   * Retry limit QStash applied to the request being handled, if it
+   * reported one.
+   *
+   * Not to be confused with {@link retried}, which is how many retries
+   * have already happened.
+   *
+   * @see {@link flowControl} for what "the request being handled" means
+   */
+  get retries() {
+    return this.effectiveConfig.retries;
+  }
+  /**
+   * Retry delay expression QStash applied to the request being handled,
+   * if any.
+   *
+   * @see {@link flowControl} for what "the request being handled" means
+   */
+  get retryDelay() {
+    return this.effectiveConfig.retryDelay;
+  }
   constructor({
     qstashClient,
     workflowRunId,
@@ -2802,7 +3190,8 @@ var WorkflowContext = class {
     invokeCount,
     label,
     retried,
-    middlewareManager
+    middlewareManager,
+    effectiveConfig
   }) {
     this.qstashClient = qstashClient;
     this.workflowRunId = workflowRunId;
@@ -2814,6 +3203,7 @@ var WorkflowContext = class {
     this.env = env ?? {};
     this.labels = label === void 0 ? [] : Array.isArray(label) ? label : label ? label.split(",") : [];
     this.retried = retried ?? 0;
+    this.effectiveConfig = effectiveConfig ?? { hasStepConfig: false };
     const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
     middlewareManagerInstance.assignContext(this);
     this.executor = new AutoExecutor(
@@ -2822,7 +3212,8 @@ var WorkflowContext = class {
       middlewareManagerInstance.dispatchDebug.bind(middlewareManagerInstance),
       middlewareManagerInstance.dispatchLifecycle.bind(middlewareManagerInstance),
       telemetry,
-      invokeCount
+      invokeCount,
+      this.effectiveConfig
     );
   }
   /**
@@ -2848,13 +3239,35 @@ var WorkflowContext = class {
    * ])
    * ```
    *
+   * Step-level settings can be passed as a third argument, overriding
+   * the settings the workflow run was triggered with for this step only:
+   *
+   * ```typescript
+   * const result = await context.run(
+   *   "step 1",
+   *   () => {
+   *     return "result"
+   *   },
+   *   {
+   *     flowControl: { key: "custom-key", parallelism: 3 },
+   *     retries: 5,
+   *   }
+   * )
+   * ```
+   *
    * @param stepName name of the step
    * @param stepFunction step function to be executed
+   * @param stepSettings step-level settings for this step
    * @returns result of the step function
    */
-  async run(stepName, stepFunction) {
+  async run(stepName, stepFunction, stepSettings) {
+    if (stepSettings) {
+      validateFlowControl(stepSettings.flowControl);
+    }
     const wrappedStepFunction = (() => this.executor.wrapStep(stepName, stepFunction));
-    return await this.addStep(new LazyFunctionStep(this, stepName, wrappedStepFunction));
+    return await this.addStep(
+      new LazyFunctionStep(this, stepName, wrappedStepFunction, stepSettings)
+    );
   }
   /**
    * Stops the execution for the duration provided.
@@ -3077,7 +3490,7 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
    *
    * @param routeFunction
    */
-  static async tryAuthentication(routeFunction, context) {
+  static async tryAuthentication(routeFunction, context, effectiveConfig) {
     const disabledContext = new _DisabledWorkflowContext({
       qstashClient: new import_qstash10.Client({
         baseUrl: "disabled-client",
@@ -3092,7 +3505,10 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       initialPayload: context.requestPayload,
       env: context.env,
       label: context.labels,
-      retried: context.retried
+      retried: context.retried,
+      // the route function runs for real here until it reaches a step, so
+      // it observes the same configuration as it will on the real context
+      effectiveConfig
     });
     try {
       await routeFunction(disabledContext);
@@ -3309,6 +3725,7 @@ var handleFailure = async ({
     }
     const userHeaders = recreateUserHeaders(request.headers);
     const retried = Number(request.headers.get(WORKFLOW_RETRIED_HEADER) ?? "0");
+    const effectiveConfig = getEffectiveConfig(request.headers);
     const workflowContext = new WorkflowContext({
       qstashClient,
       workflowRunId,
@@ -3322,11 +3739,13 @@ var handleFailure = async ({
       label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0,
       retried,
       workflowRunCreatedAt: workflowCreatedAt,
-      middlewareManager: void 0
+      middlewareManager: void 0,
+      effectiveConfig
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
-      workflowContext
+      workflowContext,
+      effectiveConfig
     );
     if (authCheck.isErr()) {
       await dispatchDebug?.("onError", {
@@ -3418,7 +3837,13 @@ var createRegionalHandler = (environment, receiverConfig, region, clientOptions)
   const client = new import_qstash11.Client({
     ...clientOptions,
     baseUrl: clientEnv.QSTASH_URL,
-    token: clientEnv.QSTASH_TOKEN
+    token: clientEnv.QSTASH_TOKEN,
+    // Mirror the receiver's dev-mode decision so a single QSTASH_DEV=true points
+    // the client at the local dev server too. Without this the QStash Client
+    // re-derives dev mode from its own process.env, which is blind to the
+    // Cloudflare worker `env` binding that actually carries QSTASH_DEV there.
+    // An explicit devMode in the user's client config still wins.
+    devMode: clientOptions?.devMode ?? isQStashDevModeEnabled(environment)
   });
   const receiver = getReceiver(environment, receiverConfig, region);
   return { client, receiver };
@@ -3468,7 +3893,9 @@ var getQStashHandlers = ({
         client: qstashClientOption && "http" in qstashClientOption ? qstashClientOption : new import_qstash11.Client({
           ...qstashClientOption,
           baseUrl: environment.QSTASH_URL,
-          token: environment.QSTASH_TOKEN
+          token: environment.QSTASH_TOKEN,
+          // Mirror the receiver's dev-mode decision (see createRegionalHandler).
+          devMode: qstashClientOption?.devMode ?? isQStashDevModeEnabled(environment)
         }),
         receiver: getReceiver(environment, receiverConfig)
       }
@@ -3808,12 +4235,14 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
     const retried = Number(request.headers.get(WORKFLOW_RETRIED_HEADER) ?? "0");
     const label = request.headers.get(WORKFLOW_LABEL_HEADER) ?? void 0;
     const workflowRunCreatedAt = request.headers.get(WORKFLOW_CREATED_AT_HEADER);
+    const effectiveConfig = getEffectiveConfig(request.headers);
     const workflowContext = new WorkflowContext({
       qstashClient: regionalClient,
       workflowRunId,
       initialPayload: isThirdPartyCallResult(request) ? JSON.parse(rawInitialPayload) : initialPayloadParser(rawInitialPayload),
       headers: recreateUserHeaders(request.headers),
       steps,
+      effectiveConfig,
       url: workflowUrl,
       env,
       telemetry,
@@ -3825,7 +4254,8 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
-      workflowContext
+      workflowContext,
+      effectiveConfig
     );
     if (authCheck.isErr()) {
       throw authCheck.error;
@@ -3862,7 +4292,23 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
           if (steps.length === 1) {
             await middlewareManager.dispatchLifecycle("runStarted", {});
           }
-          return await routeFunction(workflowContext);
+          let outcome;
+          try {
+            outcome = { ran: true, result: await routeFunction(workflowContext) };
+          } catch (error) {
+            outcome = { ran: false, error };
+          }
+          const submitted = await flushPendingStep(workflowContext);
+          if (submitted.isErr()) {
+            throw submitted.error;
+          }
+          if (submitted.value.result === "submitted-step") {
+            throw submitted.value.abort;
+          }
+          if (!outcome.ran) {
+            throw outcome.error;
+          }
+          return outcome.result;
         },
         onCleanup: async (result2) => {
           await middlewareManager.dispatchLifecycle("runCompleted", {
@@ -3943,6 +4389,7 @@ var serveBase = (routeFunction, telemetry, options, internalOptions) => {
 };
 
 // platforms/nextjs.ts
+var import_qstash13 = require("@upstash/qstash");
 var appTelemetry = {
   sdk: SDK_TELEMETRY,
   framework: "nextjs",
@@ -3954,6 +4401,7 @@ var pagesTelemetry = {
   runtime: process.versions.bun ? `bun@${process.versions.bun}/node@${process.version}` : `node@${process.version}`
 };
 var serve = (routeFunction, options) => {
+  void (0, import_qstash13.startDevServer)();
   const { handler: serveHandler } = serveBase(
     routeFunction,
     appTelemetry,
@@ -3986,6 +4434,7 @@ var serveMany = (workflows, options) => {
   };
 };
 var servePagesRouter = (routeFunction, options) => {
+  void (0, import_qstash13.startDevServer)();
   const { handler: serveHandler } = serveBase(routeFunction, pagesTelemetry, options, void 0);
   const handler = async (request_, res) => {
     if (request_.method?.toUpperCase() !== "POST") {