diff --git a/docker-compose.published.yml b/docker-compose.published.yml index dfed35932..6834a3d1a 100644 --- a/docker-compose.published.yml +++ b/docker-compose.published.yml @@ -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: diff --git a/docs/releases/3.15.0.md b/docs/releases/3.15.0.md new file mode 100644 index 000000000..90130c00b --- /dev/null +++ b/docs/releases/3.15.0.md @@ -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::`, 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).