Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .github/release-candidates/2.20.0.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"schema": "sdk-python.reviewed-release/v1",
"version": "2.20.0",
"source_commit": "d5e6e63a9ccf49343bb032000576098c95e08960",
"source_tree": "cfdd443d98dcca187338107b983c4813c4b06533",
"run_id": 44583674899,
"run_attempt": 1,
"artifact_id": 14559796844,
"artifact_sha256": "18620e7c696359d0642acecd466512f1ed430154262ae099be95903a335a2a6e",
"files": {
"durable_workflow-2.20.0-py3-none-any.whl": "e97aae2f3895165dd97817f0abc29ead23d48b81e228d3fa7491ef01cc293989",
"durable_workflow-2.20.0.tar.gz": "50e9c0ddc840f4af6fe8de759f761a5d5108dc83fcfc793075b57ca09123e8c7"
}
}
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ jobs:
id: retry-candidate
env:
GH_TOKEN: ${{ github.token }}
run: python .github/scripts/promote_release.py resolve --version 2.19.1
run: python .github/scripts/promote_release.py resolve --version 2.20.0
- name: Download the approved candidate handoff
if: inputs.retry_cap_artifact_source == 'candidate'
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
Expand All @@ -110,7 +110,7 @@ jobs:
archive: false
- name: Verify candidate archive and distribution bytes
if: inputs.retry_cap_artifact_source == 'candidate'
run: python .github/scripts/promote_release.py extract --version 2.19.1
run: python .github/scripts/promote_release.py extract --version 2.20.0
- name: Bootstrap patched pip trust
uses: durable-workflow/.github/.github/actions/bootstrap-patched-pip@75587fc33ff40c34f32ef777293dad56bb6f48c7 # clean-trust
with:
Expand Down
8 changes: 6 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [2.20.0] - 2026-11-19

Both additions need **native Server 3.15.0 or later**, the first Server release that advertises `capabilities.signal_with_start` and the `signal_external_workflow` worker command. Each is discovered from the Server's capabilities and refused before anything is sent on an older Server, so the SDK's supported Server baselines are unchanged and every other feature keeps working on older Servers. Worker protocol (1.20) and control-plane (2) versions are unchanged.

### Added

- `Client.signal_with_start()` (and the sync client's) starts a workflow or reuses its open run and records one signal on it in a single Server transaction, so the run cannot close between a separate start and signal (durable-workflow/.github#222, server#1133). It needs a Server that advertises `capabilities.signal_with_start` (native Server) and raises `RuntimeCapabilityUnsupported` before sending otherwise. An open run, including the newest run after continue-as-new, is reused with its input and deadlines unchanged (`start_outcome == "returned_existing_active"`); `duplicate_policy="fail"` refuses it. A closed run is refused with `run_not_active` unless `closed_run_policy="start_new_run"`, which starts a fresh run after it. `request_id` is the signal's command key (generated as `sdk-python-signal-with-start-<uuid>` when omitted): a retry returns the original receipt, even after the run closed. Every refusal raises the new `SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and nothing was written.
- `Client.signal_with_start()` (and the sync client's) starts a workflow or reuses its open run and records one signal on it in a single Server transaction, so the run cannot close between a separate start and signal (durable-workflow/.github#222, server#1133). It needs a Server that advertises `capabilities.signal_with_start` (native Server 3.15.0 or later) and raises `RuntimeCapabilityUnsupported` before sending otherwise. An open run, including the newest run after continue-as-new, is reused with its input and deadlines unchanged (`start_outcome == "returned_existing_active"`); `duplicate_policy="fail"` refuses it. A closed run is refused with `run_not_active` unless `closed_run_policy="start_new_run"`, which starts a fresh run after it. `request_id` is the signal's command key (generated as `sdk-python-signal-with-start-<uuid>` when omitted): a retry returns the original receipt, even after the run closed. Every refusal raises the new `SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and nothing was written.
- Workflow code can signal another workflow durably with `ctx.signal_external_workflow(workflow_id, signal_name, args=None, *, run_id=None)` (durable-workflow/.github#223, durable-workflow/server#1134). Yielding it sends the `signal_external_workflow` command and resumes with an `ExternalSignalResult` (`outcome`, `reason`, `target_run_id`, `target_command_id`, `target_signal_id`, `retained`, `delivered`). A missing, closed or refusing target is a returned outcome (`target_not_found`, `target_closed` or `rejected` with the Server's reason), not an exception, because the Server records it as a result and workflow code decides what to do. Arguments travel as an inline Avro payload envelope, like child workflow arguments. A signal name the Server would refuse (blank, a control character below U+0020 or U+007F, more than 191 characters or more than 255 UTF-8 bytes) raises the new `InvalidSignalName` (a `ValueError` with `reason`) in workflow code when the command is created, so nothing is sent and the task does not fail with a 422. The command is yielded on its own; a parallel group or selection member is refused.
- **Replay safety:** replay matches `ExternalSignalRequested` at the command's sequence and returns the outcome from the following `ExternalSignalDelivered` or `ExternalSignalFailed`. A recorded signal is never sent again, including on a cold replacement worker and while its outcome is not yet recorded. A different target, run, signal name or arguments at that sequence raises `NonDeterministicReplayError`. Existing histories are unchanged.
- **Server requirement:** the Worker submits the command only when the Server advertises `signal_external_workflow` in `worker_protocol.server_capabilities` (and lists it in `supported_workflow_task_commands` when that list is present). Otherwise it fails the workflow task with `signal_external_workflow_unavailable` before submitting, so the signal is never sent outside history.
- **Server requirement:** native Server 3.15.0 or later. The Worker submits the command only when the Server advertises `signal_external_workflow` in `worker_protocol.server_capabilities` (and lists it in `supported_workflow_task_commands` when that list is present). Otherwise it fails the workflow task with `signal_external_workflow_unavailable` before submitting, so the signal is never sent outside history.

## [2.19.1] - 2026-11-18

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ another workflow durably. The yield resumes with an `ExternalSignalResult`
whose `outcome` is `delivered`, `target_not_found`, `target_closed` or
`rejected`. Undelivered signals are returned values, not exceptions. The
signal is recorded once in history and replay never sends it again. It needs
a Server that advertises `signal_external_workflow`.
native Server 3.15.0 or later, which advertises `signal_external_workflow`.

Yield a list for deterministic parallel composition. Lists may nest and may
mix activity, child-workflow, and timer commands; the resolved value has the
Expand Down
23 changes: 22 additions & 1 deletion docs/sdk-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -799,6 +799,18 @@ dispatch-rate limits, so automation can detect whether local worker slots,
queue caps, namespace caps, or downstream dispatch budget groups are
constraining throughput.

## Signal-with-start

`Client.signal_with_start(workflow_id, signal_name, *, workflow_type=...,
task_queue=..., input=..., signal_args=...)` (and the sync client's) starts the workflow or reuses its open run and records one
signal on that run in a single Server transaction, so the run cannot close
between a separate start and signal. It needs native Server 3.15.0 or later,
which advertises `capabilities.signal_with_start`; against an older Server it
raises `RuntimeCapabilityUnsupported` before sending anything. Refusals raise
`SignalWithStartFailed` (a `SignalFailed`) with the Server's `reason`, and
nothing is written. See the method docstring for `duplicate_policy`,
`closed_run_policy` and `request_id` retries.

## Signal another workflow

Workflow code can signal another workflow in its namespace with
Expand Down Expand Up @@ -842,7 +854,7 @@ needs delivery.

Yield the command on its own: it cannot be a member of a parallel group or a
durable selection. The connected Server must advertise
`signal_external_workflow` (native Server, server#1134). Against a Server that
`signal_external_workflow` (native Server 3.15.0 or later, server#1134). Against a Server that
does not, the Worker fails the workflow task with
`signal_external_workflow_unavailable` before submitting anything, so the
signal is never sent outside history and the workflow is not failed.
Expand Down Expand Up @@ -1613,6 +1625,15 @@ The top-level server `version` is build identity only. The worker checks these
protocol manifests at startup and fails closed when compatibility is missing,
unknown, or undiscoverable.

Some features need a newer Server than the SDK's supported baseline. They are
discovered from the Server's capabilities and refused before anything is sent
when the Server does not advertise them, so the rest of the SDK keeps working:

| Feature | Needs |
| --- | --- |
| `Client.signal_with_start()` | native Server 3.15.0 or later (`capabilities.signal_with_start`) |
| `ctx.signal_external_workflow()` | native Server 3.15.0 or later (`signal_external_workflow` worker command) |

Carriers and support tooling can validate `auth_composition_contract` with
`parse_auth_composition_contract()` before resolving connection, namespace,
token, TLS, profile, and redacted effective-configuration diagnostics.
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "durable-workflow"
version = "2.19.1"
version = "2.20.0"
description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
readme = "README.md"
requires-python = ">=3.10"
Expand Down Expand Up @@ -79,8 +79,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"

[tool.durable-workflow]
product-train = "2.19.1"
registry-version = "2.19.1"
product-train = "2.20.0"
registry-version = "2.20.0"
supported-server-versions = "2.8.0"
supported-server-release-baselines = { "2" = "2.8.0", "3" = "3.0.0" }
worker-protocol-version = "1.20"
Expand Down
2 changes: 1 addition & 1 deletion scripts/ci/activity-retry-cap.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
The retry-cap case qualifies the exact reviewed 2.19.1 wheel on the published
The retry-cap case qualifies the exact reviewed 2.20.0 wheel on the published
Server/Python tuple in `tests/fixtures/published-retry-cap.json`. It uses the
existing internal two-container profile, complete hash lock, captured no-site
entry, before/after installed inventory and independent ID/label cleanup.
Expand Down
2 changes: 1 addition & 1 deletion scripts/ci/activity_acceptance_release.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

from scripts.ci.activity_acceptance_entry import captured_file

VERSION = "2.19.1"
VERSION = "2.20.0"
WHEEL = f"durable_workflow-{VERSION}-py3-none-any.whl"
SDIST = f"durable_workflow-{VERSION}.tar.gz"

Expand Down
10 changes: 5 additions & 5 deletions tests/fixtures/published-retry-cap.json
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
{
"schema": "sdk-python.published-activity-acceptance/v1",
"sdk_version": "2.19.1",
"server_image": "ghcr.io/durable-workflow/server@sha256:30ccaf2cea6810a92915a9eb389f1a63ea870818a74c9cc1a321379b07b2d25c",
"server_source": "2d1244be4611e1bc4aa4f0d856c708bed17937b4",
"server_amd64_manifest": "sha256:6cdcb909b1ca46d10410d7f659fcbd292dbf02be0c337d989b886153c0f3ee56",
"server_qualification": "https://github.com/durable-workflow/server/releases/tag/3.13.0",
"sdk_version": "2.20.0",
"server_image": "ghcr.io/durable-workflow/server@sha256:f7f84884ff178e36b6536237f9f31eb006ed050feac3028106af736bc01d19de",
"server_source": "fdb6c4f63d0e1923b4b93a253699fc12d064bb10",
"server_amd64_manifest": "sha256:0d0db083943ab6d56ba66010f2fea1fe1dbebbede60b87f7bde2d5f9cd28e709",
"server_qualification": "https://github.com/durable-workflow/server/releases/tag/3.15.0",
"python_image": "docker.io/library/python@sha256:935c3c5b12357a7e10caa9c1e6ca5692344d97cf229832ef584be2cec9fc03df",
"python_amd64_manifest": "sha256:0f086103b026048cc50cb5da25ec435c023c5241a83fc44daea593377abc61c4",
"python_version": "3.12.16"
Expand Down
2 changes: 1 addition & 1 deletion tests/test_activity_retry_cap_cell.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ def approval(digest="a" * 64):

def test_effective_lock_adds_only_the_approved_sdk_to_the_fixed_dependencies():
result, digest = release.lock(b"pytest==1 --hash=sha256:" + b"c" * 64 + b"\n", approval())
assert result.endswith(f"durable-workflow==2.19.1 --hash=sha256:{digest}\n".encode())
assert result.endswith(f"durable-workflow==2.20.0 --hash=sha256:{digest}\n".encode())
assert result.count(b"durable-workflow") == 1


Expand Down
Loading