diff --git a/docker-compose.published.yml b/docker-compose.published.yml index ab5050819..f7a137057 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.16.0} +x-server-image: &server-image ${DW_SERVER_IMAGE:-durableworkflow/server:3.17.0} services: server: diff --git a/docs/releases/3.17.0.md b/docs/releases/3.17.0.md new file mode 100644 index 000000000..d895ea740 --- /dev/null +++ b/docs/releases/3.17.0.md @@ -0,0 +1,85 @@ +# Durable Workflow Server 3.17.0 (native) + +Server 3.17.0 sends far fewer response bytes: JSON answers are compressed by +default, and workers can opt out of receiving the same server capabilities in +every answer. Its immutable images are `durableworkflow/server:3.17.0` and +`ghcr.io/durable-workflow/server:3.17.0`; the published Compose default selects +3.17.0. Rolling aliases move separately after published-image qualification. + +**Upgrade:** a drop-in replacement for 3.16.x. There is no schema change and no +`schema-upgrade` step; rolling back to 3.16.0 is an ordinary image rollback. +From 3.15.x or earlier, run the [3.16.0 schema step](3.16.0.md#upgrade-and-rollback) +first. Worker protocol and control-plane versions are unchanged. + +## Behavior changes to review + +- Response compression is now on by default. A client whose request allows it + in `Accept-Encoding` receives JSON answers of 1024 bytes or more gzip- or + deflate-encoded, with `Content-Encoding` and `Vary: Accept-Encoding` set. + HTTP clients that send `Accept-Encoding` normally decode transparently. A + client that sends `Accept-Encoding` but reads the raw body must decode it, or + stop sending the header. +- `DW_COMPRESSION_ENABLED` (legacy `WORKFLOW_SERVER_COMPRESSION_ENABLED`) used + to be accepted and ignored; it is now honoured. A deployment that already sets + it to `false` keeps answers uncompressed. +- Cluster info now reports `capabilities.response_compression` as + `["gzip", "deflate"]` instead of `[]` while compression is enabled. + +## Smaller worker and client responses + +In a lab run of the standard one-activity workflow, responses fell from about +385 KB to about 18 KB per workflow with the matching PHP SDK. + +### Response compression + +Native now follows PHP Server's `CompressResponse` (#1261): + +- JSON answers of 1024 bytes or more are gzip-encoded, or deflate-encoded + (zlib format, RFC 1950), when the request's `Accept-Encoding` allows it. +- gzip wins at equal weight, `*` stands for both, `q=0` refuses an encoding, + an answer that already has a `Content-Encoding` is left alone, and + `Vary: Accept-Encoding` is added. +- Bodies over 256 KB are encoded on a blocking thread, so a large answer never + stalls the runtime's async workers. Streamed answers, and in-memory answers + over 64 MB, pass through unchanged. +- Behind Cloudflare (Cloud Dev and similar tunnels) the edge always asks the + origin for gzip, so existing clients benefit without any change. +- `DW_COMPRESSION_ENABLED` defaults to `true`. Set it to `false` to turn + compression off, for example when a reverse proxy already compresses. +- Cluster info advertises `capabilities.response_compression: + ["gzip", "deflate"]` when compression is enabled and `[]` when it is + disabled, as PHP Server does. + +### Opt-in server capabilities digest + +A new request header, `X-Durable-Workflow-Server-Capabilities-Digest`, lets a +worker stop receiving the ~17 KB `server_capabilities` object in every worker +answer, including the second copy inside a carried poll (#1262). + +- The worker sends `X-Durable-Workflow-Server-Capabilities-Digest: |none` + on worker-plane requests. +- When the header names the current digest, each copy of the capabilities is + replaced by the digest string. +- Otherwise each copy is sent in full with a `digest` member the worker keeps. +- Every opted-in answer also carries the current digest in the same response + header. The digest is `sha256:` followed by the lowercase hex SHA-256 of the + capabilities' compact JSON. +- A digest string always names the digest that request sent, so a worker + resolves it against what it captured when it sent that request. This is safe + across rolling deploys. +- Workers that don't send the header get exactly the same bytes as before. + Servers that don't support it ignore it, so a worker that sends it works + against older releases too. +- The digest layer runs inside compression, so the smaller body is still + encoded. + +See the [server capabilities digest contract](../contracts/server-capabilities-digest.md). +PHP SDK support ships separately. + +## Unchanged + +Worker protocol `1.20`, control-plane version `2`, the 3.16.0 schema, codec and +command shapes, and the HTTP API apart from response encoding are unchanged. +There are no new capabilities; `response_compression` changes value as described +above. The PHP Server remains 2.11.8, retired and unpatched; see the +[retirement/security notice](../security/retired-php-server-2026-11-13.md).