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
127 changes: 127 additions & 0 deletions .github/workflows/published-command-keys.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
name: Published command keys

# Installed signal/update command-key cohort (durable-workflow/.github#216)
# against the published native Server image, by digest. The published job
# runs the released CLI binary; the source job runs this checkout's build
# and expects the request-ID exit codes (9 conflict, 10 ambiguous).

on:
pull_request:
paths:
- '.github/workflows/published-command-keys.yml'
- 'scripts/acceptance/command-keys/published_cohort.py'
- 'rust/src/error.rs'
- 'rust/src/commands/workflow_message.rs'
workflow_dispatch:

permissions:
contents: read

env:
SERVER_INDEX: sha256:30ccaf2cea6810a92915a9eb389f1a63ea870818a74c9cc1a321379b07b2d25c
SERVER_SOURCE: 2d1244be4611e1bc4aa4f0d856c708bed17937b4
SERVER_VERSION: 3.13.0
CLI_VERSION: 2.10.0
CLI_SHA256: dfd1d0417c5767c95a30b25296558b90e4ad12e7319487449b303076a2fd0a58
PROXY_SOURCE: 117118c83093822469b3824ba9587ff4068ed29f
HELPER_SOURCE: 6280877bd8e4ebf5db0ff523239c4246230571db

jobs:
cohort:
name: ${{ matrix.cli }} CLI, ${{ matrix.phase }} cells
if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-24.04
timeout-minutes: 40
strategy:
fail-fast: false
matrix:
cli: [published, source]
phase: [modern, legacy]
defaults:
run:
shell: bash --noprofile --norc -e -o pipefail {0}
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
persist-credentials: false
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: '3.13'
- name: Bootstrap verified dependency trust
uses: durable-workflow/.github/.github/actions/bootstrap-patched-pip@75587fc33ff40c34f32ef777293dad56bb6f48c7 # clean-trust
with:
clients: pip,python,cargo,curl,git
- name: Download the accepted shared inputs
run: |
umask 077
inputs="$RUNNER_TEMP/command-key-inputs"
mkdir -m 700 "$inputs"
echo "INPUTS=$inputs" >> "$GITHUB_ENV"
fetch() { curl --fail --silent --show-error --location --proto '=https' --max-time 60 --max-filesize "$3" "$1" --output "$inputs/$2"; }

Check warning on line 60 in .github/workflows/published-command-keys.yml

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Assign this positional parameter to a local variable.

See more on https://sonarcloud.io/project/issues?id=durable-workflow_cli&issues=AaHybD6XmkJ8I5bThVNM&open=AaHybD6XmkJ8I5bThVNM&pullRequest=167

Check warning on line 60 in .github/workflows/published-command-keys.yml

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Assign this positional parameter to a local variable.

See more on https://sonarcloud.io/project/issues?id=durable-workflow_cli&issues=AaHybD6XmkJ8I5bThVNN&open=AaHybD6XmkJ8I5bThVNN&pullRequest=167

Check warning on line 60 in .github/workflows/published-command-keys.yml

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Assign this positional parameter to a local variable.

See more on https://sonarcloud.io/project/issues?id=durable-workflow_cli&issues=AaHybD6XmkJ8I5bThVNL&open=AaHybD6XmkJ8I5bThVNL&pullRequest=167
fetch "https://raw.githubusercontent.com/durable-workflow/.github/$PROXY_SOURCE/conformance/command-keys/committed_response_loss.py" committed_response_loss.py 65536
fetch "https://raw.githubusercontent.com/durable-workflow/sdk-rust/$HELPER_SOURCE/scripts/acceptance/command-keys/sqlite_legacy.py" sqlite_legacy.py 131072
fetch "https://raw.githubusercontent.com/durable-workflow/sdk-rust/$HELPER_SOURCE/scripts/acceptance/command-keys/command-key-legacy-v1-vectors.json" command-key-legacy-v1-vectors.json 131072
# The cohort verifies each file against its accepted SHA256 before use.
- name: Download the published CLI
if: matrix.cli == 'published'
run: |
curl --fail --silent --show-error --location --proto '=https' --max-time 120 --max-filesize 67108864 \
"https://github.com/durable-workflow/cli/releases/download/$CLI_VERSION/dw-linux-x86_64" --output "$INPUTS/dw"
echo "$CLI_SHA256 $INPUTS/dw" | sha256sum -c -
{
echo "CLI_BINARY=$INPUTS/dw"
echo "CLI_BINARY_SHA256=$CLI_SHA256"
echo "TYPED_EXIT="
} >> "$GITHUB_ENV"
- name: Install Rust 1.99
if: matrix.cli == 'source'
uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
with:
toolchain: 1.99.0
- name: Build this checkout's CLI
if: matrix.cli == 'source'
working-directory: rust
run: |
cargo build --locked
cp target/debug/dw "$INPUTS/dw"
{
echo "CLI_BINARY=$INPUTS/dw"
echo "CLI_BINARY_SHA256=$(sha256sum "$INPUTS/dw" | cut -d' ' -f1)"
echo "TYPED_EXIT=--typed-exit-codes"
} >> "$GITHUB_ENV"
- name: Pull the published Server by digest
run: docker pull "ghcr.io/durable-workflow/server@$SERVER_INDEX"
- name: Run the ${{ matrix.phase }} cells
run: |
# TYPED_EXIT is empty for the published CLI.
# shellcheck disable=SC2086
timeout --kill-after=30s 15m python3 -I scripts/acceptance/command-keys/published_cohort.py \
--phase "${{ matrix.phase }}" $TYPED_EXIT \
--cli "$CLI_BINARY" --cli-sha256 "$CLI_BINARY_SHA256" --inputs "$INPUTS" \
--server-index "$SERVER_INDEX" --server-source "$SERVER_SOURCE" --server-version "$SERVER_VERSION" \
--work-dir "$RUNNER_TEMP/cohort" --container-prefix "cli-command-keys-$GITHUB_RUN_ID" \
--owner "$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" | tee command-key-result.json
python3 -I -c 'import json,sys; r=json.loads(open("command-key-result.json").read().splitlines()[-1]); print("::notice::", r["phase"], r["outcome"], r["checks"], "checks; cleanup", r["cleanup"]); sys.exit(r["outcome"] != "pass")'
{
echo "### ${{ matrix.cli }} CLI, ${{ matrix.phase }} cells"
echo '```json'
tail -n 1 command-key-result.json
echo '```'
} >> "$GITHUB_STEP_SUMMARY"
- name: Remove any container this run created
if: always()
run: |
ids="$(docker ps --all --quiet --filter "label=durable-workflow.cli-command-keys=$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT")"
if [ -n "$ids" ]; then docker rm --force --volumes $ids; fi
test -z "$(docker ps --all --quiet --filter "label=durable-workflow.cli-command-keys=$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT")"
- name: Keep the sanitized observations
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: command-keys-${{ matrix.cli }}-${{ matrix.phase }}
path: |
command-key-result.json
${{ runner.temp }}/cohort/checks.json
${{ runner.temp }}/cohort/invocations.json
retention-days: 7
if-no-files-found: warn
41 changes: 24 additions & 17 deletions docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -538,22 +538,27 @@ Explicit empty or whitespace-only keys are refused before POST. Keys contain
truncation or case conversion. The key is shown safely in human output and
preserved exactly in JSON/JSONL, including after a timeout or network failure.

After a lost response the admission outcome is unknown. Inspect workflow
history and command receipts before retrying; a key alone does not establish
retry safety. Rely on the complete retained-admission and canonical-intent
guarantee only when the Server advertises that published capability. Ordinary
request-key storage and partial update receipt lookup do not supply the full
signal/update guarantee. No currently qualified published Server tuple
advertises that complete capability.

When the Server reports receipt metadata, `retained: true` identifies an
original receipt and `intent_verified` reports whether its intent was
verified. Preserve its original status and exact target. A qualified
retained-admission contract may refuse a different typed intent with HTTP 409
and `reason: request_id_conflict`; the response identifies the retained
command and conflict parts. Legacy receipts with unverified intent never
authorize a new command. Deduplicated admission does not make external effects
exactly once.
After a lost response the admission outcome is unknown. The CLI sends each
signal or update once and never resends it; the key it used is printed, and is
in the JSON error envelope's `request_id`. On a Server that advertises
`capabilities.command_request_keys` (native Server 3.9.2 and later), the key is
a durable command key on the workflow instance: repeat the same command with
the same `--request-id`, name, input and `--run-id` and the Server returns the
original receipt (`retained: true`, `intent_verified: true`) without recording
a second command. On other Servers, inspect workflow history and command
receipts before retrying; a key alone does not establish retry safety.

The same key with a different name, input or run target is refused with HTTP
409 `reason: request_id_conflict`, and the CLI exits `9`
(`REQUEST_ID_CONFLICT`). The response identifies the retained command and the
conflicting parts. A key that matches more than one retained command is refused
with HTTP 409 `reason: request_id_ambiguous` and exits `10`
(`REQUEST_ID_AMBIGUOUS`); nothing is recorded and no receipt is selected.
Neither refusal records anything. A legacy receipt, admitted before the Server
recorded command intent, reads back with `retained: true` and
`intent_verified: false`: the Server returned it without comparing the retried
command with it, and the human output says so. It never authorizes a new
command. Deduplicated admission does not make external effects exactly once.

`workflow:update-outcome` reads an update that was sent earlier by its update
ID, with one `GET /api/workflows/{workflow_id}/updates/{update_id}`, and never
Expand Down Expand Up @@ -802,13 +807,15 @@ from there:
|------|------|---------|
| 0 | `SUCCESS` | Operation completed successfully. |
| 1 | `FAILURE` | Generic failure — command ran but did not succeed. |
| 2 | `INVALID` | Invalid usage — bad arguments, unknown options, or local validation. Also returned for HTTP 4xx responses that are not covered below (e.g. 400, 422). |
| 2 | `INVALID` | Invalid usage — bad arguments, unknown options, or local validation. Also returned for HTTP 4xx responses that are not covered below (e.g. 400, 422, and a `409` other than a request-ID refusal). |
| 3 | `NETWORK` | Could not reach the server (connection refused, DNS failure, TLS handshake failure, transport error). |
| 4 | `AUTH` | Authentication or authorization failure. Returned for HTTP `401` and `403`. |
| 5 | `NOT_FOUND` | Resource not found. Returned for HTTP `404`. |
| 6 | `SERVER` | Server error. Returned for HTTP `5xx`. |
| 7 | `TIMEOUT` | Request timed out before the server responded. Also returned for HTTP `408`. |
| 8 | `COMPATIBILITY` | Compatibility failure. The CLI/server protocol window cannot be used safely, so the command refused before the requested operation. |
| 9 | `REQUEST_ID_CONFLICT` | HTTP `409` with reason `request_id_conflict`. The signal or update's `--request-id` already names a retained command with a different name, input or run target. Nothing was recorded. Repeat the original command unchanged to read its receipt, or use a new `--request-id`. |
| 10 | `REQUEST_ID_AMBIGUOUS` | HTTP `409` with reason `request_id_ambiguous`. The `--request-id` matches more than one retained command, so the Server recorded nothing and selected no receipt. Retrying it unchanged fails the same way. |

Example:

Expand Down
87 changes: 87 additions & 0 deletions rust/parity/cases.json
Original file line number Diff line number Diff line change
Expand Up @@ -15596,6 +15596,93 @@
},
"reference": "php-main"
},
{
"name": "workflow signal request id ambiguous JSON",
"argv": [
"workflow:signal",
"chk-42",
"approve",
"--server={mock}",
"--request-id=approve-1",
"--json"
],
"mock": [],
"mock_routes": {
"/api/workflows/chk-42/signal/approve": {
"method": "POST",
"status": 409,
"headers": {
"X-Durable-Workflow-Control-Plane-Version": "2"
},
"body": {
"message": "The request_id matches more than one retained command.",
"reason": "request_id_ambiguous",
"retained": true,
"intent_verified": false,
"retryable": false
}
}
},
"reference": "php-main"
},
{
"name": "workflow signal request id ambiguous human",
"argv": [
"workflow:signal",
"chk-42",
"approve",
"--server={mock}",
"--request-id=approve-1"
],
"mock": [],
"mock_routes": {
"/api/workflows/chk-42/signal/approve": {
"method": "POST",
"status": 409,
"headers": {
"X-Durable-Workflow-Control-Plane-Version": "2"
},
"body": {
"message": "The request_id matches more than one retained command.",
"reason": "request_id_ambiguous",
"retained": true,
"intent_verified": false,
"retryable": false
}
}
},
"reference": "php-main"
},
{
"name": "workflow update request id ambiguous JSON",
"argv": [
"workflow:update",
"chk-42",
"quota.adjust",
"--server={mock}",
"--request-id=approve-1",
"--wait=completed",
"--json"
],
"mock": [],
"mock_routes": {
"/api/workflows/chk-42/update/quota.adjust": {
"method": "POST",
"status": 409,
"headers": {
"X-Durable-Workflow-Control-Plane-Version": "2"
},
"body": {
"message": "The request_id matches more than one retained command.",
"reason": "request_id_ambiguous",
"retained": true,
"intent_verified": false,
"retryable": false
}
}
},
"reference": "php-main"
},
{
"name": "workflow update server error JSON",
"argv": [
Expand Down
11 changes: 10 additions & 1 deletion rust/src/commands/workflow_message.rs
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,18 @@ fn receipt_lines(result: &Value) {
));
}
if let Some(Value::Bool(verified)) = result.get("intent_verified") {
// A legacy receipt is retained without a recorded intent, so the
// Server returned it without comparing this command to it.
let legacy = !*verified && result.get("retained") == Some(&Value::Bool(true));
formatter::writeln_out(&format!(
" Intent Verified: {}",
if *verified { "yes" } else { "no" }
if *verified {
"yes"
} else if legacy {
"no (legacy receipt; the Server did not compare this command's intent with it)"
} else {
"no"
}
));
}
}
Expand Down
49 changes: 49 additions & 0 deletions rust/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ pub mod exit {
pub const SERVER: i32 = 6;
pub const TIMEOUT: i32 = 7;
pub const COMPATIBILITY: i32 = 8;
/// HTTP 409 `request_id_conflict`: the command key already names a
/// retained command with a different intent. Nothing was recorded.
pub const REQUEST_ID_CONFLICT: i32 = 9;
/// HTTP 409 `request_id_ambiguous`: the command key matches more than one
/// retained command. Nothing was recorded and no receipt was selected.
pub const REQUEST_ID_AMBIGUOUS: i32 = 10;

pub fn from_http_status(status: u16) -> i32 {
match status {
Expand Down Expand Up @@ -62,6 +68,16 @@ impl CliError {
CliError::Invalid(_) => exit::INVALID,
CliError::Network(_) => exit::NETWORK,
CliError::Timeout(_) => exit::TIMEOUT,
CliError::Http { status: 409, .. }
if self.reason() == Some(REQUEST_ID_CONFLICT_REASON) =>
{
exit::REQUEST_ID_CONFLICT
}
CliError::Http { status: 409, .. }
if self.reason() == Some(REQUEST_ID_AMBIGUOUS_REASON) =>
{
exit::REQUEST_ID_AMBIGUOUS
}
CliError::Http { status, .. } => exit::from_http_status(*status),
CliError::Compatibility(_) => exit::COMPATIBILITY,
CliError::Failure(_) => exit::FAILURE,
Expand Down Expand Up @@ -183,6 +199,10 @@ impl ErrorContext<'_> {
/// different command.
const REQUEST_ID_CONFLICT_REASON: &str = "request_id_conflict";

/// The Server's refusal reason for a request ID that matches more than one
/// retained command, so no receipt can be selected.
const REQUEST_ID_AMBIGUOUS_REASON: &str = "request_id_ambiguous";

/// 2.x `errorRecommendations()`: the error's next step, then, for a keyed
/// command whose outcome is unknown, the inspect-before-retry warning.
pub fn recommendations(error: &CliError, context: &ErrorContext) -> Vec<Value> {
Expand Down Expand Up @@ -267,6 +287,20 @@ fn base_recommendations(error: &CliError, context: &ErrorContext) -> Vec<Value>
),
})];
}
if error.reason() == Some(REQUEST_ID_AMBIGUOUS_REASON) {
let empty = Map::new();
let body = body.as_ref().unwrap_or(&empty);
let request_id = scalar_text(body.get("request_id"))
.or_else(|| context.request_id.clone())
.unwrap_or_else(|| "given".into());
return vec![json!({
"id": "request_id.ambiguous",
"severity": "error",
"message": format!(
"Request id [{request_id}] matches more than one retained command, so the Server recorded nothing and selected no receipt. Retrying it unchanged fails the same way. Inspect workflow history to see which commands were admitted, and pass a new --request-id to record a new command.",
),
})];
}
}
// A failed update read later is final, not a request to fix and retry.
if context.command == "workflow:update-outcome"
Expand Down Expand Up @@ -663,6 +697,21 @@ mod tests {
assert_eq!(exit::from_http_status(503), exit::SERVER);
}

#[test]
fn request_id_refusals_have_their_own_exit_codes() {
let conflict = CliError::from_http(409, r#"{"reason":"request_id_conflict"}"#);
assert_eq!(conflict.exit_code(), exit::REQUEST_ID_CONFLICT);
assert_eq!(exit::REQUEST_ID_CONFLICT, 9);
let ambiguous = CliError::from_http(409, r#"{"reason":"request_id_ambiguous"}"#);
assert_eq!(ambiguous.exit_code(), exit::REQUEST_ID_AMBIGUOUS);
assert_eq!(exit::REQUEST_ID_AMBIGUOUS, 10);
// Only the Server's 409 refusal is typed; other statuses keep their category.
let other = CliError::from_http(422, r#"{"reason":"request_id_conflict"}"#);
assert_eq!(other.exit_code(), exit::INVALID);
let closed = CliError::from_http(409, r#"{"reason":"run_not_active"}"#);
assert_eq!(closed.exit_code(), exit::INVALID);
}

#[test]
fn refusal_without_message_keeps_reason_and_server_response() {
let error = CliError::from_http(
Expand Down
Loading
Loading