Skip to content

feat(workflows): Add workflow versioning patch support #799

@WhitWaldo

Description

@WhitWaldo

Summary

Implement patch-based workflow versioning in the Dapr JS SDK, allowing developers to make backward-compatible changes to running workflow definitions without breaking in-flight instances.

Background

When a workflow definition is modified after instances are already running, replaying the history of those instances against the new code can produce non-determinism errors. Patch-based versioning solves this by allowing developers to branch logic based on whether an instance was started before or after a change.

This is sometimes called "version gates" — a mechanism to say "if this instance has already passed this point in execution, use the old logic; otherwise, use the new logic."

Proposed API

// In WorkflowContext:

/**
 * Returns true if the current instance should execute the new code path
 * identified by `patchName`. Returns false for instances that were started
 * before this patch was introduced (to preserve replay compatibility).
 */
isPatched(patchName: string): boolean;

Usage Example

function* myWorkflow(ctx: WorkflowContext, input: OrderInput) {
  // Original logic:
  const result = yield ctx.callActivity(processOrder, input);

  // Added later — new validation step. Old in-flight instances skip this.
  if (ctx.isPatched("add-validation-step")) {
    yield ctx.callActivity(validateOrder, result);
  }

  yield ctx.callActivity(shipOrder, result);
}

Acceptance Criteria

  • WorkflowContext.isPatchEnabled(patchName: string): boolean is implemented
  • In-flight instances that have never seen the patch name return false
  • New instances or instances that haven't yet reached the patch point return true
  • The patch is recorded in the orchestration history so subsequent replays are deterministic
  • Unit and e2e tests cover both old-instance and new-instance paths
  • Documentation with usage examples

Metadata

Metadata

Assignees

No one assigned
    No fields configured for Feature.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions