From bfce07534ddfa1fbe93f4893a303af0c097ba2a2 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:07:22 +0000 Subject: [PATCH] Prepare native 3.10.0 dispatch summary release --- docker-compose.published.yml | 2 +- docs/releases/3.10.0.md | 108 +++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/releases/3.10.0.md diff --git a/docker-compose.published.yml b/docker-compose.published.yml index 0f20cd119..3fc46dedf 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.9.2} +x-server-image: &server-image ${DW_SERVER_IMAGE:-durableworkflow/server:3.10.0} services: server: diff --git a/docs/releases/3.10.0.md b/docs/releases/3.10.0.md new file mode 100644 index 000000000..cff7ba02d --- /dev/null +++ b/docs/releases/3.10.0.md @@ -0,0 +1,108 @@ +# Durable Workflow Server 3.10.0 (native) + +Server 3.10.0 adds durable schedule dispatch summaries to list and describe +responses. A schedule page can distinguish its last dispatch outcome from the +execution status of the latest workflow without describing every schedule. +This release retains the command-key, receipt, completion-limit and observation +ownership corrections from 3.9.2. Its immutable images are +`durableworkflow/server:3.10.0` and `ghcr.io/durable-workflow/server:3.10.0`; +the published Compose default selects 3.10.0. Rolling aliases move separately +after published-image qualification. + +## Upgrade and rollback + +This release requires an explicit additive schema upgrade from 3.9.x: + +| Backend | Schema step | +| --- | --- | +| SQLite | 13 → 14 | +| PostgreSQL | 14 → 15 | +| MariaDB | 14 → 15 | +| MySQL | 15 → 16 | + +Stop every Server replica, keep the database running, and back up the database +and external-payload storage. Select the new immutable image and run that +image's `schema-upgrade` once before restarting every replica on the same +version. Check readiness, reported version and worker registration. Startup +does not upgrade an old schema automatically. Earlier versions also require +the intervening schema steps. + +The new nullable schedule column does not backfill dispatch authority from +legacy action arrays. Existing schedules remain unavailable until an owning +transition records a valid summary. MySQL and MariaDB upgrades resume after +interruption; SQLite and PostgreSQL apply their step transactionally. +Rollback to an older binary requires restoring the pre-upgrade database and +storage backup. Do not run an older binary against the newer schema. + +For a single-node Compose deployment, stop Server while leaving MySQL running: + +```bash +docker compose --env-file durable-workflow.prod.env \ + -f docker-compose.published.yml stop server +``` + +After backing up MySQL and `server_storage`, set `DW_SERVER_IMAGE` to the +3.10.0 image in the environment file, pull it, and upgrade once: + +```bash +docker compose --env-file durable-workflow.prod.env \ + -f docker-compose.published.yml pull server +docker compose --env-file durable-workflow.prod.env \ + -f docker-compose.published.yml run --rm --no-deps server schema-upgrade +docker compose --env-file durable-workflow.prod.env \ + -f docker-compose.published.yml up -d --wait +``` + +From 3.9.x on MySQL, the upgrade reports `from_schema_version:15`, +`schema_version:16`, `status:upgraded`; a repeat reports `status:current`. +Then verify `/api/ready`, `/api/cluster/info` version `3.10.0`, and worker +registration. For several replicas, stop every replica before upgrading and +restart every one on the same version. The matching chart is published after +native qualification; follow its actual versioned upgrade notes rather than +assuming a chart version from this Server version. + +Worker protocol `1.20` and control plane version `2` remain unchanged. + +## Schedule dispatch summaries + +List items and describe responses include `dispatch_summary` version 1, with +`state`, `last_outcome` and `buffered_actions_count`. Its states distinguish +known recorded authority, a newly created schedule that has never fired, and +unavailable legacy or invalid authority. An empty list cannot establish +support. Older producers omit the field. + +Known outcomes are `started`, `buffered`, `skipped` or `failed`. They retain an +outcome ID, UTC recording time with six fractional digits, complete reason and +the applicable workflow/run identities. The current buffer count is separate +from the last outcome. A later buffer drain can leave the recorded buffered +outcome alongside a count of zero. The latest workflow's execution status is +also separate: a Started dispatch can point to a workflow that later Failed. + +Each summary is bounded to 4096 serialized UTF-8 bytes. A transition that +cannot record the complete contract stores unavailable authority without +truncating the reason or changing the underlying scheduling operation. +Absent, null, partial or unsupported data is not v1 authority. A valid +unavailable summary overrides older legacy evidence; a later describe owns +its complete summary and must not be merged field by field with an older +list result. + +Owning schedule transitions update the summary atomically with their durable +effects, including buffer count changes. The list reads a bounded scalar in +its page query and does not scan legacy action arrays or issue per-row +describe calls. See the [schedule API reference](../server-reference.md#schedules) +for the exact contract. Consumer support should inspect the complete field +rather than infer it from a Server version. + +## Retained boundaries + +The [3.9.2 command-key and receipt contract](3.9.2.md#command-keys-and-receipts) +and bounded completion-refusal delivery remain unchanged. This release grants +no additional external-payload, continuation-command or draining-upload +authority. Cloud physical mapping/adoption, installed client command-key +cohorts and the MariaDB re-registration pool-timeout investigation remain +separate. Server 3.9.0 stays held. + +Publication, exact-image corpus, all four published Compose cells, scans, +protected rolling aliases and final Release must qualify this new schema +image. Waterline's published summary/request-budget/visible-refresh acceptance +follows that exact producer tuple; source merge alone is not consumer proof.