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
2 changes: 1 addition & 1 deletion docker-compose.published.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ name: durable-workflow-server
# release whose default names another image). Set DW_SERVER_IMAGE to run
# any other native image, by tag or digest; pin a digest for production
# change control.
x-server-image: &server-image ${DW_SERVER_IMAGE:-durableworkflow/server:3.14.0}
x-server-image: &server-image ${DW_SERVER_IMAGE:-durableworkflow/server:3.15.0}

services:
server:
Expand Down
144 changes: 144 additions & 0 deletions docs/releases/3.15.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# Durable Workflow Server 3.15.0 (native)

Server 3.15.0 adds atomic signal-with-start, lets workflow code signal another
workflow durably, and decides failed-run redrive by Workflow 2.33.0's rules.
Its immutable images are `durableworkflow/server:3.15.0` and
`ghcr.io/durable-workflow/server:3.15.0`; the published Compose default selects
3.15.0. Rolling aliases move separately after published-image qualification.

**Upgrade:** a drop-in replacement for 3.14.x. There is no schema change and no
`schema-upgrade` step; rolling back to 3.14.0 is an ordinary image rollback.
From 3.13.x or earlier, run the [3.14.0 schema step](3.14.0.md#upgrade-and-rollback)
first. Worker protocol and control-plane versions are unchanged.

## Behavior changes to review

- An HTTP signal or signal-with-start whose `request_id` starts with
`workflow-signal:` is now refused with `422 request_id_reserved` before
anything is read or written. That prefix is reserved for signals sent by
workflow code (see [Signal another workflow](#signal-another-workflow-from-workflow-code)).
Updates are unaffected.
- A worker holding a workflow task can now signal any workflow in that task's
namespace through the new `signal_external_workflow` command, without the
operator or admin role an HTTP signal needs. Keep a workflow that other
workflows' code must not signal in a separate namespace.
- Failed runs that native refused to redrive with `unsupported_history`,
`unexpected_start` or `unrecorded_failure_boundary` are now decided by
Workflow 2.33.0's rules. Most notably, a run whose failed activity exhausted
its retries can now be redriven, and describe's `can_redrive` reports it.
Runs that still cannot be redriven get Core's specific reason (see
[Redrive](#redrive-follows-workflow-2330)).

## Atomic signal-with-start

`POST /api/workflows/{workflow_id}/signal-with-start/{signal_name}` starts the
workflow or reuses its open run and admits one signal on that run in one
transaction. Discover it through `capabilities.signal_with_start`. The body is
a start request plus `signal_input`, an optional `request_id` and
`closed_run_policy`; `duplicate_policy` defaults to `use-existing`.

| Current state of the instance | Result |
| --- | --- |
| No instance | A new run starts and the signal joins it. `201`, `start_outcome: "started_new"`. |
| Open run (after continue-as-new, the newest run) | The signal joins that run. `202`, `start_outcome: "returned_existing_active"`. With `duplicate_policy: "fail"`, `409 instance_already_started`. |
| Closed run, `closed_run_policy: "reject"` (default) | `409 run_not_active`. The closed run is never reopened. |
| Closed run, `closed_run_policy: "start_new_run"` | A fresh run numbered after the closed one starts and the signal joins it. `201`, with `closed_run_id`. |

The namespace, durable workflow type and an explicit `task_queue` must match
an open run (`workflow_id_reserved_in_namespace`, `workflow_type_conflict`,
`task_queue_conflict`). Every refusal writes nothing: no run starts, no signal
is recorded and no key is reserved. A blank signal name is
`422 invalid_signal_name`.

`request_id` is the signal's durable command key on the instance and binds the
signal name, typed signal arguments and workflow type. A matching retry
returns the original start and signal receipts with `retained: true`, even
after the run closed or continued; a retry that changes only the start half
also returns the original receipts. A different name, arguments or workflow
type, or a key a plain signal already used, is `409 request_id_conflict`
naming the part. The route requires the operator or admin role.

Native deliberately differs from embedded `WorkflowStub::signalWithStart`
(Workflow 2.33.0): it refuses a closed run unless `closed_run_policy` is
`start_new_run`, also accepts `duplicate_policy: "fail"`, and refuses a key
with no recorded signal-with-start intent. Published PHP has no such route
(native divergence `signal-with-start-intake`). See
[Signal-with-start](../server-reference.md#signal-with-start) (#1133, #1249).

## Signal another workflow from workflow code

The new worker command `signal_external_workflow` (`workflow_id`, optional
`run_id`, `signal_name` and an Avro `arguments` envelope) signals another
workflow in the sender's namespace. Discover it through
`capabilities.signal_external_workflow` in cluster info and worker
`server_capabilities`; it is listed in `supported_workflow_task_commands`.

The completion that carries the command records `ExternalSignalRequested` on
the sender, admits the signal on the target in the same transaction, and
records exactly one resolution at the same sequence:
`ExternalSignalDelivered`, or `ExternalSignalFailed` with `outcome`
`target_not_found` (`instance_not_found`, `run_not_found`), `target_closed`
(`run_not_active`, `historical_run`) or `rejected` (`unknown_signal`,
`invalid_signal_arguments`, `structural_limit_exceeded`,
`runtime_reserved_signal`, `self_target`, `request_id_conflict`). A failed
outcome is a recorded result, not a task failure. Replay reads the recorded
outcome and never sends the signal again.

A delivered signal leaves the same records on the target as an HTTP signal,
with `source: workflow` and a workflow command context naming the sending run
and sequence. Each delivery is keyed on the target as
`workflow-signal:<sender run>:<sequence>`, which is why HTTP callers can no
longer use that prefix. The command takes the next authored sequence and gives
the sender one new workflow task to read the outcome (none when the same
completion closes the sender).

`workflow_id` and `run_id` are 1 to 191 characters. `signal_name` follows an
HTTP signal's name rules (not empty, at most 255 bytes, no control characters)
and must also be non-blank and at most 191 characters. Other fields or a
non-Avro `arguments` envelope are refused with 422 before anything is written.
The command is refused at a cancellation-scope checkpoint and during
cancellation cleanup.

Published PHP and embedded Workflow 2.33.0 have no such command (native
divergence `signal-external-workflow-command`). An SDK must check the
capability before submitting it. See the
[signal-external contract](../contracts/signal-external-workflow.md) (#1134,
#1251).

## Redrive follows Workflow 2.33.0

Native redrive, and describe's `can_redrive` and `redrive_blocked_reason`, now
decide a failed run by embedded Workflow 2.33.0's `FailedRunRedrivePlan`,
`ActivityRetryHistory` and `FailedRunRedriveEligibility`:

- A retried activity step is accepted when its attempts form Core's lineage: a
completed one is reused, a failed one is resumed. An invalid lineage refuses
as `invalid_activity_retry_history`.
- A start adopted under `use-existing` and `MessageCursorAdvanced` are not
steps.
- Signal waits, updates and child calls are validated with Core's reasons. A
valid one is a step no service SDK replays yet, so a worker-sourced run
refuses as `service_redrive_history_not_qualified`, as Core does in service
mode. Rejected updates, and updates closed when the run failed, do not block
redrive.
- `workflow_code` and `structural_limit` failure boundaries are read as Core
reads them; an unchanged definition refuses as
`workflow_code_failure_requires_corrected_definition`.
- A reused activity result needs its `payload_codec`. An Avro result that does
not decode refuses as `unavailable_activity_result`.

The successor writer and the redrive response shape are unchanged. Native
offers no `allow_definition_change`, refuses unqualified steps on runs that are
not worker-sourced too, decodes only Avro payloads, and has no per-run message
rows to move (native divergence `redrive-core-2.33-rules`). See the
[checkpoint](../rust-server-port-checkpoints/2026-11-19-redrive-core-2.33.md)
(#980, #1250).

## Unchanged

Worker protocol `1.20`, control-plane version `2`, the 3.14.0 schema, codec and
existing command shapes, and the HTTP signal, update and start routes (apart
from the reserved `request_id` prefix) are unchanged. New capabilities are
`signal_with_start` and `signal_external_workflow`. The PHP Server remains
2.11.8, retired and unpatched; see the
[retirement/security notice](../security/retired-php-server-2026-11-13.md).
Loading