Skip to content

Commit 9e77bc8

Browse files
authored
Merge pull request #318 from durable-workflow/sdk-python/release-2.17.2
Release Python SDK 2.17.2 query receipts and byte-result fix
2 parents bf0ce18 + 36237a6 commit 9e77bc8

11 files changed

Lines changed: 657 additions & 10 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"schema": "sdk-python.reviewed-release/v1",
3+
"version": "2.17.2",
4+
"source_commit": "885395866fa54786adb3cffa7ead9dbf0419e90a",
5+
"source_tree": "cb7fb96110cecf1911989eab3924863d65ce2ea4",
6+
"run_id": 43449487744,
7+
"run_attempt": 1,
8+
"artifact_id": 14049382780,
9+
"artifact_sha256": "9b2eb18707378b9d33965692332e4d34bec683836ee3b06b7fc1c5bb445018d8",
10+
"files": {
11+
"durable_workflow-2.17.2-py3-none-any.whl": "7dc77d3882fa5cbddbeaee6a4cc63b05285e280523c8ea40dc31e03cc12a40bc",
12+
"durable_workflow-2.17.2.tar.gz": "76feb6ce60eb92710c718ece3fe63bb9bfb3b1cafc7fa0dbdce0a9e0b8321956"
13+
}
14+
}

‎.github/scripts/promote_release.py‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
#!/usr/bin/env python3
2+
"""Promote the exact reviewed build-only distributions before PyPI upload."""
3+
4+
from __future__ import annotations
5+
6+
import argparse
7+
import hashlib
8+
import json
9+
import os
10+
import re
11+
import subprocess
12+
import tarfile
13+
from pathlib import Path, PurePosixPath
14+
15+
REPOSITORY = "durable-workflow/sdk-python"
16+
MAX_FILE_BYTES = 64 * 1024 * 1024
17+
SHA = re.compile(r"[0-9a-f]{40}")
18+
DIGEST = re.compile(r"[0-9a-f]{64}")
19+
KEYS = {"schema", "version", "source_commit", "source_tree", "run_id", "run_attempt",
20+
"artifact_id", "artifact_sha256", "files"}
21+
22+
23+
def unique_object(pairs: list[tuple[str, object]]) -> dict:
24+
result = {}
25+
for key, value in pairs:
26+
if key in result:
27+
raise ValueError("release approval contains a duplicate member")
28+
result[key] = value
29+
return result
30+
31+
32+
def distribution_names(version: str) -> set[str]:
33+
if re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version) is None:
34+
raise ValueError("release version must be exact stable SemVer")
35+
return {f"durable_workflow-{version}-py3-none-any.whl", f"durable_workflow-{version}.tar.gz"}
36+
37+
38+
def require_digest(value: object) -> None:
39+
if not isinstance(value, str) or DIGEST.fullmatch(value) is None:
40+
raise ValueError("release approval requires exact artifact digests")
41+
42+
43+
def validate_descriptor(approval: dict, version: str) -> None:
44+
if (not isinstance(approval, dict) or set(approval) != KEYS
45+
or approval["schema"] != "sdk-python.reviewed-release/v1" or approval["version"] != version):
46+
raise ValueError("release approval schema or version mismatch")
47+
for key in ("source_commit", "source_tree"):
48+
if not isinstance(approval[key], str) or SHA.fullmatch(approval[key]) is None:
49+
raise ValueError("release approval requires exact source identities")
50+
for key in ("run_id", "run_attempt", "artifact_id"):
51+
if type(approval[key]) is not int or approval[key] <= 0:
52+
raise ValueError("release approval requires positive numeric producer identities")
53+
files = approval["files"]
54+
expected = distribution_names(version)
55+
if not isinstance(files, dict) or set(files) != expected:
56+
raise ValueError("release approval must name exactly the wheel and sdist")
57+
for value in (approval["artifact_sha256"], *files.values()):
58+
require_digest(value)
59+
60+
61+
def load_approval(root: Path, version: str) -> dict:
62+
distribution_names(version)
63+
name = f".github/release-candidates/{version}.json"
64+
path = root / name
65+
if path.is_symlink() or not path.is_file() or path.stat().st_size > 65536:
66+
raise ValueError("release approval must be a bounded regular file")
67+
approval = json.loads(path.read_text(), object_pairs_hook=unique_object)
68+
validate_descriptor(approval, version)
69+
source = approval["source_commit"]
70+
if SHA.fullmatch(source) is None:
71+
raise ValueError("reviewed source must be an exact commit")
72+
directory = str(root.resolve())
73+
subprocess.run(["git", "-C", directory, "merge-base", "--is-ancestor", "--", source, "HEAD"], check=True)
74+
tree = subprocess.check_output(
75+
["git", "-C", directory, "rev-parse", "--verify", "--end-of-options", f"{source}^{{tree}}"], text=True,
76+
).strip()
77+
if tree != approval["source_tree"]:
78+
raise ValueError("reviewed source tree mismatch")
79+
# The approval cannot be embedded in its own reviewed source commit.
80+
# Every executable/configuration/package change must precede the build.
81+
changed = subprocess.check_output(
82+
["git", "-C", directory, "diff", "--no-ext-diff", "--no-textconv", "--no-renames",
83+
"--name-status", source, "HEAD", "--"], text=True,
84+
).strip()
85+
if changed != f"A\t{name}":
86+
raise ValueError("publication source differs from reviewed source beyond its approval file")
87+
return approval
88+
89+
90+
def verify_authority(approval: dict, run: dict, artifact: dict, repository_id: int) -> None:
91+
repository = {"id": repository_id, "full_name": REPOSITORY}
92+
if (run.get("id") != approval["run_id"] or run.get("run_attempt") != approval["run_attempt"]
93+
or run.get("head_sha") != approval["source_commit"] or run.get("event") != "workflow_dispatch"
94+
or run.get("path") != ".github/workflows/publish.yml" or run.get("status") != "completed"
95+
or run.get("conclusion") != "success"
96+
or any(run.get(key, {}).get(field) != value
97+
for key in ("repository", "head_repository") for field, value in repository.items())):
98+
raise ValueError("reviewed build run authority mismatch")
99+
producer = artifact.get("workflow_run", {})
100+
if (artifact.get("id") != approval["artifact_id"] or artifact.get("name") != "dist-handoff.tar"
101+
or artifact.get("expired") is not False
102+
or artifact.get("digest") != "sha256:" + approval["artifact_sha256"]
103+
or type(artifact.get("size_in_bytes")) is not int
104+
or not 0 < artifact["size_in_bytes"] <= 2 * MAX_FILE_BYTES + 65536
105+
or producer.get("id") != approval["run_id"]
106+
or producer.get("head_sha") != approval["source_commit"]
107+
or producer.get("repository_id") != repository_id
108+
or producer.get("head_repository_id") != repository_id):
109+
raise ValueError("reviewed artifact authority mismatch")
110+
111+
112+
def api(path: str) -> dict:
113+
result = subprocess.check_output(["gh", "api", f"repos/{REPOSITORY}/{path}"])
114+
if len(result) > 1048576:
115+
raise ValueError("producer metadata exceeds its bound")
116+
return json.loads(result)
117+
118+
119+
def file_sha256(path: Path) -> str:
120+
digest = hashlib.sha256()
121+
with path.open("rb") as handle:
122+
for chunk in iter(lambda: handle.read(1048576), b""):
123+
digest.update(chunk)
124+
return digest.hexdigest()
125+
126+
127+
def extract_reviewed(approval: dict, incoming: Path, dist: Path) -> None:
128+
archive = incoming / "dist-handoff.tar"
129+
if (incoming.is_symlink() or not incoming.is_dir() or set(incoming.iterdir()) != {archive}
130+
or archive.is_symlink() or not archive.is_file()
131+
or archive.stat().st_size > 2 * MAX_FILE_BYTES + 65536
132+
or file_sha256(archive) != approval["artifact_sha256"]):
133+
raise ValueError("downloaded producer artifact differs from reviewed bytes")
134+
contents = {}
135+
with tarfile.open(archive, mode="r:") as handle:
136+
for member in handle:
137+
if member.name in (".", "./") and member.isdir() and member.size == 0:
138+
continue
139+
name = PurePosixPath(member.name)
140+
if (name.is_absolute() or len(name.parts) != 1 or "\\" in member.name
141+
or name.name not in approval["files"] or name.name in contents
142+
or not member.isreg() or member.mode != 0o644 or not 0 < member.size <= MAX_FILE_BYTES):
143+
raise ValueError("producer artifact has unexpected, duplicate or unsafe members")
144+
with handle.extractfile(member) as stream:
145+
data = stream.read(MAX_FILE_BYTES + 1)
146+
if len(data) != member.size or hashlib.sha256(data).hexdigest() != approval["files"][name.name]:
147+
raise ValueError("distribution differs from reviewed bytes")
148+
contents[name.name] = data
149+
if set(contents) != set(approval["files"]):
150+
raise ValueError("producer artifact does not contain both reviewed distributions")
151+
# Validate everything before creating output; never extract archive paths.
152+
dist.mkdir()
153+
for name in sorted(distribution_names(approval["version"])):
154+
descriptor = os.open(dist / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o644)
155+
with os.fdopen(descriptor, "wb") as output:
156+
output.write(contents[name])
157+
158+
159+
def main() -> None:
160+
parser = argparse.ArgumentParser(description=__doc__)
161+
parser.add_argument("operation", choices=("resolve", "extract"))
162+
parser.add_argument("--version", required=True)
163+
args = parser.parse_args()
164+
approval = load_approval(Path.cwd(), args.version)
165+
if args.operation == "resolve":
166+
verify_authority(approval, api(f"actions/runs/{approval['run_id']}"),
167+
api(f"actions/artifacts/{approval['artifact_id']}"), int(os.environ["GITHUB_REPOSITORY_ID"]))
168+
with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
169+
output.write(f"run-id={approval['run_id']}\nartifact-id={approval['artifact_id']}\n")
170+
for name in sorted(distribution_names(args.version)):
171+
kind = "wheel" if name.endswith(".whl") else "sdist"
172+
output.write(f"{kind}-sha256={approval['files'][name]}\n")
173+
else:
174+
extract_reviewed(approval, Path(".release-candidate"), Path("dist"))
175+
176+
177+
if __name__ == "__main__":
178+
main()

‎.github/workflows/publish.yml‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ on:
1111
workflow_dispatch:
1212
inputs:
1313
release_tag:
14-
description: 'Existing immutable SDK release tag; empty permits a build-only run'
14+
description: 'Existing immutable tag for publication; build-only runs use the selected source commit'
1515
required: false
1616
type: string
1717
default: ''
@@ -41,6 +41,9 @@ concurrency:
4141
jobs:
4242
build:
4343
runs-on: ubuntu-latest
44+
permissions:
45+
contents: read
46+
actions: read
4447
outputs:
4548
artifact-digest: ${{ steps.privileged-handoff.outputs.artifact-digest }}
4649
artifact-id: ${{ steps.privileged-handoff.outputs.artifact-id }}
@@ -54,8 +57,8 @@ jobs:
5457
with:
5558
fetch-depth: 0
5659
ref: >-
57-
${{ github.event_name == 'workflow_dispatch' && inputs.release_tag != ''
58-
&& format('refs/tags/{0}', inputs.release_tag) || github.ref }}
60+
${{ github.event_name == 'workflow_dispatch' && inputs.publish && inputs.release_tag != ''
61+
&& format('refs/tags/{0}', inputs.release_tag) || github.sha }}
5962
6063
- name: Resolve exact release identity
6164
id: release_source
@@ -95,18 +98,45 @@ jobs:
9598
fi
9699
fi
97100
else
101+
test "$head_commit" = "$GITHUB_SHA"
98102
REQUESTED_TAG="$package_version"
99103
fi
100104
{
101105
printf 'tag=%s\n' "$REQUESTED_TAG"
102106
printf 'commit=%s\n' "$head_commit"
103107
printf 'base_commit=%s\n' "$base_commit"
108+
printf 'publish=%s\n' "$PUBLISH_REQUESTED"
104109
} >> "$GITHUB_OUTPUT"
105110
106111
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
107112
with:
108113
python-version: "3.12"
109114

115+
- name: Resolve the reviewed build-only artifact
116+
if: steps.release_source.outputs.publish == 'true'
117+
id: candidate
118+
env:
119+
GH_TOKEN: ${{ github.token }}
120+
RELEASE_VERSION: ${{ steps.release_source.outputs.tag }}
121+
run: python .github/scripts/promote_release.py resolve --version "$RELEASE_VERSION"
122+
123+
- name: Download the exact reviewed distributions
124+
if: steps.release_source.outputs.publish == 'true'
125+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
126+
with:
127+
artifact-ids: ${{ steps.candidate.outputs.artifact-id }}
128+
run-id: ${{ steps.candidate.outputs.run-id }}
129+
github-token: ${{ github.token }}
130+
repository: ${{ github.repository }}
131+
path: .release-candidate
132+
archive: false
133+
134+
- name: Verify reviewed bytes before extracting distributions
135+
if: steps.release_source.outputs.publish == 'true'
136+
env:
137+
RELEASE_VERSION: ${{ steps.release_source.outputs.tag }}
138+
run: python .github/scripts/promote_release.py extract --version "$RELEASE_VERSION"
139+
110140
- name: Bootstrap patched pip trust
111141
uses: durable-workflow/.github/.github/actions/bootstrap-patched-pip@75587fc33ff40c34f32ef777293dad56bb6f48c7 # clean-trust
112142
with:
@@ -117,6 +147,7 @@ jobs:
117147
pip install --only-binary :all: build==1.6.1 twine==7.0.0
118148
119149
- name: Build package
150+
if: steps.release_source.outputs.publish != 'true'
120151
run: python -m build
121152

122153
- name: Compare built release metadata with the exact source commit
@@ -137,7 +168,28 @@ jobs:
137168
path: dist/
138169

139170
- name: Package the privileged PyPI handoff as one immutable file
140-
run: tar -cf dist-handoff.tar -C dist .
171+
env:
172+
PROMOTE_REVIEWED: ${{ steps.release_source.outputs.publish }}
173+
RELEASE_VERSION: ${{ steps.release_source.outputs.tag }}
174+
REVIEWED_WHEEL_SHA256: ${{ steps.candidate.outputs.wheel-sha256 }}
175+
REVIEWED_SDIST_SHA256: ${{ steps.candidate.outputs.sdist-sha256 }}
176+
run: |
177+
set -euo pipefail
178+
if [ "$PROMOTE_REVIEWED" = true ]; then
179+
[[ "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
180+
[[ "$REVIEWED_WHEEL_SHA256" =~ ^[0-9a-f]{64}$ ]]
181+
[[ "$REVIEWED_SDIST_SHA256" =~ ^[0-9a-f]{64}$ ]]
182+
shopt -s dotglob nullglob
183+
files=(dist/*)
184+
test "${#files[@]}" -eq 2
185+
wheel="dist/durable_workflow-${RELEASE_VERSION}-py3-none-any.whl"
186+
sdist="dist/durable_workflow-${RELEASE_VERSION}.tar.gz"
187+
test -f "$wheel" && test ! -L "$wheel"
188+
test -f "$sdist" && test ! -L "$sdist"
189+
printf '%s %s\n%s %s\n' \
190+
"$REVIEWED_WHEEL_SHA256" "$wheel" "$REVIEWED_SDIST_SHA256" "$sdist" | sha256sum --check --strict -
191+
fi
192+
tar -cf dist-handoff.tar -C dist .
141193
142194
- name: Bind the privileged PyPI handoff identity and digest
143195
id: privileged-handoff

‎CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
66

77
## [Unreleased]
88

9+
## [2.17.2] - 2026-11-13
10+
11+
### Fixed
12+
13+
- The query client guide, SDK reference and API docstring now document the Server receipt returned by `Client.query_workflow()`, `WorkflowHandle.query()` and the synchronous client. Read `receipt["result"]` for the decoded handler value, including a successful `None`. Runtime behavior is unchanged. (#316, #317)
14+
- Query workers return valid Avro values containing bytes without also trying to serialize those bytes as plain JSON. The authoritative `result_envelope` is unchanged; JSON-compatible results retain their optional plain projection. (#319)
15+
916
### Changed
1017

1118
- Replay refuses explicit `parallel_group_policy` histories before constructing application state until a qualified policy consumer is enabled. Absent-policy histories retain their wait, failure-selection and clock behavior. Explicit propagation is being prepared behind disabled worker admission. (#307)
1219

1320
### Added
1421

15-
- Timeout cleanup interruption (workflow#863, workflow#1129). `CancellationContext.from_dict()` reads the context's optional top-level `cause`: absent or `"cancellation"` is an ordinary cancellation, `"timeout"` marks a timeout-cleanup request (the run passed its work deadline and is now in cleanup), and any other value raises `ValueError`. The context carries no other timeout fields: its existing `cleanup_deadline_at` is the cleanup deadline, and the timeout kind and work deadline stay on the `WorkflowTimeoutCleanupStarted` event. `cause` and `is_timeout` are readable on the context, and `to_dict()` writes `cause` back exactly as received, including an explicit `"cancellation"`, leaving ordinary contexts byte-identical. A timeout request is raised at the authored call as the new experimental `WorkflowTimeoutCleanupRequested`, a subclass of `WorkflowCancelled`, so existing `except WorkflowCancelled:` handlers, such as saga compensation, run on timeout too. It stays `BaseException`-rooted and is not an `asyncio.CancelledError`. Test `cause`, the cross-SDK discriminator, to tell the two apart. `cause` is never inherited: a child cancelled under a timeout request, scoped or not, receives an ordinary cancellation without `cause`.
22+
- Experimental timeout-cleanup parser/exception preparation (workflow#863, workflow#1129, server#1201). This patch advertises no timeout-cleanup capability and does not qualify producer delivery or enable timeout cleanup. `CancellationContext.from_dict()` reads the context's optional top-level `cause`: absent or `"cancellation"` is an ordinary cancellation, `"timeout"` marks a timeout-cleanup request (the run passed its work deadline and is now in cleanup), and any other value raises `ValueError`. The context carries no other timeout fields: its existing `cleanup_deadline_at` is the cleanup deadline, and the timeout kind and work deadline stay on the `WorkflowTimeoutCleanupStarted` event. `cause` and `is_timeout` are readable on the context, and `to_dict()` writes `cause` back exactly as received, including an explicit `"cancellation"`, leaving ordinary contexts byte-identical. A timeout request is raised at the authored call as the new experimental `WorkflowTimeoutCleanupRequested`, a subclass of `WorkflowCancelled`, so existing `except WorkflowCancelled:` handlers, such as saga compensation, run on timeout too. It stays `BaseException`-rooted and is not an `asyncio.CancelledError`. Test `cause`, the cross-SDK discriminator, to tell the two apart. `cause` is never inherited: a child cancelled under a timeout request, scoped or not, receives an ordinary cancellation without `cause`.
1623

1724
## [2.17.1] - 2026-11-13
1825

‎CONTRIBUTING.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,29 @@ Existing evidence is append-only; protocol evolution adds a new fixture with a
2020
```bash
2121
python scripts/ci/validate-regression-corpus.py --base-ref <target>
2222
```
23+
24+
## Reviewed package publication
25+
26+
Build a release candidate without publishing:
27+
28+
```bash
29+
gh workflow run publish.yml --ref <release-branch> -f publish=false
30+
```
31+
32+
Before tagging, obtain Security review of that run's exact wheel and sdist and
33+
qualify the installed candidate against the selected published Server. Record
34+
the reviewed producer in `.github/release-candidates/<version>.json`, using the
35+
closed `sdk-python.reviewed-release/v1` schema checked by
36+
`.github/scripts/promote_release.py`: version, source commit/tree, run ID and
37+
attempt, raw `dist-handoff.tar` artifact ID/SHA256, and the wheel/sdist filename
38+
to SHA256 map. The approval file itself receives normal PR/Security review.
39+
40+
The final tag may differ from the reviewed build's source only by adding that
41+
approval file. Any other source or workflow change requires a new build and
42+
review. Tagged publication checks the successful same-repository producer and
43+
promotes its exact distribution bytes through the existing protected handoff;
44+
it does not rebuild them. After package checks and smoke execution, the handoff
45+
step rechecks both files against digests captured before that execution.
46+
Missing, expired, changed or unreviewed artifacts
47+
refuse publication before upload. Finish registry installation and stable
48+
portal readback after publication.

‎pyproject.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "durable-workflow"
7-
version = "2.17.1"
7+
version = "2.17.2"
88
description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
99
readme = "README.md"
1010
requires-python = ">=3.10"
@@ -79,8 +79,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
7979
durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
8080

8181
[tool.durable-workflow]
82-
product-train = "2.17.1"
83-
registry-version = "2.17.1"
82+
product-train = "2.17.2"
83+
registry-version = "2.17.2"
8484
supported-server-versions = "2.8.0"
8585
supported-server-release-baselines = { "2" = "2.8.0", "3" = "3.0.0" }
8686
worker-protocol-version = "1.20"

0 commit comments

Comments
 (0)