Skip to content

Cut worker and result response bytes: capabilities digest, history-free completed result (#352) - #354

Merged
rmcdaniel merged 3 commits into
mainfrom
general/352-egress-digest-result
Nov 20, 2026
Merged

rmcdaniel merged 3 commits into
mainfrom
general/352-egress-digest-result

Conversation

@rmcdaniel

@rmcdaniel rmcdaniel commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Items 1–3 of #352 (item 4 is #353). Needs no Server change. With durable-workflow/server#1261 (compression) and durable-workflow/server#1262 (capabilities digest), both merged and shipping in 3.17.0, this brings the Python SDK in line with durable-workflow/sdk-php#446.

Changes

Capabilities digest (src/durable_workflow/_capabilities_digest.py, contract docs/contracts/server-capabilities-digest.md on server main):

  • Opt-in header: worker-plane requests (_request(..., worker=True)) send X-Durable-Workflow-Server-Capabilities-Digest: <digest>|none. Discovery and control-plane requests do not.
  • Per-request resolution: the (digest, capabilities) pair is captured when a request is sent, and that request's answer is resolved against it. This covers success bodies, error bodies and negotiated poll envelopes, at the top level and up to three levels deep, as PHP does.
  • Learning: a tagged copy (one with a digest member) is learned for later requests, and the member is stripped before callers see it. A digest string that names neither the captured pair nor a tagged copy in the same answer raises the new ServerCapabilitiesDigestError.
  • Rolling deploy: a request in flight under D1 that overlaps an answer learning D2 still restores the D1 object.
  • No aliasing: callers get copies, so they never mutate the held pair.
  • Compatibility: older Servers ignore the header and answer in full.

History-free result: for a completed run, get_result returns the output that describe_workflow already decoded from the status read's output_envelope, when the status read names the same run. It then skips the history read. The history path stays for failed, cancelled, terminated and timed-out runs, for a status read without output_envelope, and for a handle pinned to a different run. WorkflowExecution gains a private, non-init, non-compared flag that records whether output came from the envelope.

gzip and a bound on decoded bodies: httpx decodes gzip transparently, so a small compressed answer could inflate without limit. A response hook now wraps each body stream and counts the bytes it decodes to, inflating at most 1 MiB at a time.

  • Past Client(max_response_body_bytes=...) (128 MiB by default, also on the sync client), it raises the new ResponseBodyTooLarge, which is not retried, before httpx decodes past the bound.
  • The client now asks only for gzip. Any other response Content-Encoding is refused.
  • Tests (tests/test_response_body_limit.py):
    • a 64 MiB gzip bomb of about 64 KiB is refused within the first chunks, not retried, and its stream is closed
    • an identity body over the limit is refused
    • bodies within the limit decode normally
    • an unrequested encoding is refused
    • the default bound is 128 MiB and is validated

Tests

tests/test_capabilities_digest.py:

  • Digest unit tests:
    • the header is none until a tagged copy is learned
    • the digest member is stripped
    • nested restore works three levels deep, but not deeper
    • a digest string resolves against a tagged copy in the same answer
    • an unknown digest raises
    • a differing full object is kept as it is
    • the held pair cannot be mutated through an answer
  • Through Client._request with a mock server that elides like server#1262:
    • opt-in on worker requests only
    • error bodies are restored
    • the rolling-deploy overlap (D1 in flight, D2 learned, late D1 answer restored, next request sends D2)
    • poll envelopes are restored
  • Result:
    • completed: a single status read, no history read
    • fallback to history when there is no envelope or the run differs
    • failed runs still read history and raise WorkflowFailed
  • gzip is advertised.

Locally (Python 3.14, httpx 0.28.1), pytest tests/ -m "not integration" gives 7794 passed and 3 skipped, and ruff, mypy and the regression-corpus guard are clean.

Measurement

Setup:

  • Workload: DW Standard Workflow v1, meaning one start, one activity and one completion, with 1 KiB payloads. 10 sequential workflows.
  • Server: one native Server from server main 43ad8d8f (3.17.0-main43ad8d8f, with server#1261 and server#1262), on SQLite, capped at 1 CPU / 1 GiB, with default compression on.
  • Clients: the same Python interpreter and the same script (lab4 /home/lab4/fleet/tmp/general-egress-py/scripts/measure.py). It counts wire bytes per response with httpx hooks. The first 3 s of worker start-up (registration, first tagged copy) are excluded from both runs.
Response bytes per workflow SDK main 0d5283c this branch change
worker 41,933 5,597 −87%
caller 6,382 4,591 −28% (no history GET)
total 48,315 10,188 −79%

Where the worker savings come from: with the digest, each worker answer carries the 73-byte digest string in place of the ~16.9 KB capabilities object. For example, a workflow-task completion drops from 11,025 to 676 bytes, and the activity renew-lease answer from 5,676 to 876. Several answers are now small enough that the Server no longer compresses them.

Earlier baseline: for comparison with #352, the same workflow on stock 3.15.0 without compression moved 193,799 bytes per workflow.

🤖 Generated with Claude Code

…ee result (#352)

Worker-plane requests opt in to the server capabilities digest
(durable-workflow/server#1262): they send
X-Durable-Workflow-Server-Capabilities-Digest with the digest held when
the request is sent (or "none"), and the answer, success or error body
and negotiated poll envelopes included, is resolved against that
captured pair up to three levels deep. A tagged full copy is learned for
later requests and its digest member stripped; an unknown digest raises
ServerCapabilitiesDigestError. A request in flight across a rolling
deploy restores the object it was sent with.

get_result returns a completed run's output from the status read's
output_envelope when it names the same run, skipping the history read;
non-success outcomes and envelope-less answers keep the history path.

gzip needs no change: httpx advertises and decodes it (test added).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@rmcdaniel rmcdaniel added enhancement New feature or request agent:general labels Nov 20, 2026
httpx decodes gzip transparently, so a small compressed answer could
inflate without limit (a reviewer expanded 1.5 MB of gzip to 3.2 GB in
other SDKs). A response hook wraps each body stream and counts the bytes
it decodes to, inflating at most 1 MiB at a time, and raises the new
ResponseBodyTooLarge (not retried) before httpx decodes past the bound.
Configurable with Client(max_response_body_bytes=...), also on the sync
client. The client now asks only for gzip; another response
Content-Encoding is refused.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Keep both error additions: ResponseBodyTooLarge and
ServerCapabilitiesDigestError beside main's ActivityWorkerLost (and its
ActivityLeaseAuthorityLost alias).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@sonarqubecloud

Copy link
Copy Markdown

@rmcdaniel
rmcdaniel merged commit 8aa941a into main Nov 20, 2026
25 checks passed
rmcdaniel added a commit that referenced this pull request Nov 20, 2026
Keeps both: this branch's transient retries, committed-completion rule
and outage logs, and main's decoded response cap and continue-as-new
result. Only CHANGELOG.md conflicted; both entries are kept.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent:general enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant