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.16.0}
x-server-image: &server-image ${DW_SERVER_IMAGE:-durableworkflow/server:3.17.0}

services:
server:
Expand Down
85 changes: 85 additions & 0 deletions docs/releases/3.17.0.md
Original file line number Diff line number Diff line change
@@ -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: <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).
Loading