Skip to content

Show legacy and unknown workflow version usage #158

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
rmcdaniel wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Show legacy and unknown workflow version usage #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d07cea
Draft workflow version-usage command for open runs
rmcdaniel Nov 14, 2026
dc06274
Test version usage transport and adopt the nonconflicting route
rmcdaniel Nov 14, 2026
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
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,23 @@ dw workflow:history <workflow-id> <run-id>
dw service-call:describe <endpoint> <service> <operation> <call-id> --json
```

## Version branch usage

Before retiring a version branch, inspect the open runs for its workflow type
and change ID:

```bash
dw workflow:version-usage shipment carrier-api --min-version=2 --namespace=orders
dw workflow:version-usage shipment carrier-api --min-version=2 --state=unknown --json
```

This requires a Server advertising `workflow_version_usage`. Counts include all
legacy, current and unknown runs before filtering and paging. A missing marker
or unavailable history stays unknown. The command reads one live page; pass its
opaque `next_cursor` with the same query to continue. JSON and JSONL preserve the
whole page, including counts. Drain or fence admissions and restart the query
before making a branch-removal decision.

## Automation Contract

All read and mutating commands support machine-readable output. Use
Expand Down
200 changes: 200 additions & 0 deletions rust/parity/catalog-additions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1709,6 +1709,206 @@
}
},
"rust_only": true
},
{
"name": "workflow:version-usage",
"description": "Show live legacy, current and unknown version usage across open runs",
"synopsis": "workflow:version-usage [-s|--server [SERVER]] [--namespace NAMESPACE] [--token [TOKEN]] [--tls-verify TLS-VERIFY] [--env ENV] [--output OUTPUT] [--min-version MIN-VERSION] [--state STATE] [--limit LIMIT] [--cursor CURSOR] [--json] [--] <workflow-type> <change-id>",
"aliases": [],
"hidden": false,
"help": "Read one live, namespace-scoped page of open runs for a workflow type and\nchange ID. --min-version is required: decisions below that proposed minimum\nare legacy; decisions at or above it are current. Use 1 for a patched() branch.\nNo marker, pruned/incomplete history or invalid decisions remain unknown.\nUnknown is never zero usage or a current decision.\n\nCounts cover all states before --state and paging. --cursor is opaque and\nbound to the exact namespace/type/change/minimum/state query. The first page\nsets an upper run-ID bound. New admissions beyond that bound stay excluded;\nclosures and new decisions can still change counts/state between pages.\nRestart after draining or fencing admissions before retiring a branch.\n\nRequires literal capabilities.workflow_version_usage=true from the Server.\nWithout it, dw exits 8 before the version-usage request. Unsupported routes,\nstorage failures and invalid/inconsistent responses are errors, never empty\nsuccessful counts. This command never runs workflow code or changes markers.\n\n--limit is 1..200 (default 50). --state is legacy, current or unknown.\nJSON and JSONL retain one complete page, including counts and continuation;\nJSONL does not discard the envelope when no runs match the selected state.\n\n<comment>Examples:</comment>\n\n <info>dw workflow:version-usage shipment carrier-api --min-version=2 --namespace=orders</info>\n <info>dw workflow:version-usage shipment carrier-api --min-version=2 --state=unknown --json</info>\n <info>dw workflow:version-usage shipment carrier-api --min-version=2 --limit=20 --cursor=OPAQUE --json</info>",
"definition": {
"arguments": {
"workflow-type": {
"name": "workflow-type",
"is_required": true,
"is_array": false,
"description": "Exact workflow type (at most 255 UTF-8 bytes)",
"default": null
},
"change-id": {
"name": "change-id",
"is_required": true,
"is_array": false,
"description": "Exact version change ID (at most 1024 UTF-8 bytes)",
"default": null
}
},
"options": {
"server": {
"name": "--server",
"shortcut": "-s",
"accept_value": true,
"is_value_required": false,
"is_multiple": false,
"description": "Server URL",
"default": null
},
"namespace": {
"name": "--namespace",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Target namespace",
"default": null
},
"token": {
"name": "--token",
"shortcut": "",
"accept_value": true,
"is_value_required": false,
"is_multiple": false,
"description": "Auth token",
"default": null
},
"tls-verify": {
"name": "--tls-verify",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Verify TLS certificates (true/false). Defaults to $DURABLE_WORKFLOW_TLS_VERIFY, then the selected profile, then true.",
"default": null
},
"env": {
"name": "--env",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Named dw environment to use (overrides $DW_ENV and any env set via `dw env:use`). Hard-fails when the profile does not exist.",
"default": null
},
"output": {
"name": "--output",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Output format: table, json, or one complete page per line (jsonl)",
"default": "table"
},
"min-version": {
"name": "--min-version",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Required proposed minimum supported version (signed 32-bit integer)",
"default": null
},
"state": {
"name": "--state",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Filter returned runs by legacy, current, or unknown; counts retain all states",
"default": null
},
"limit": {
"name": "--limit",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Runs per page (1..200)",
"default": "50"
},
"cursor": {
"name": "--cursor",
"shortcut": "",
"accept_value": true,
"is_value_required": true,
"is_multiple": false,
"description": "Opaque continuation bound to this exact query",
"default": null
},
"json": {
"name": "--json",
"shortcut": "",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Output the command response as JSON (alias for --output=json)",
"default": false
},
"help": {
"name": "--help",
"shortcut": "-h",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Display help for the given command. When no command is given display help for the <info>list</info> command",
"default": false
},
"silent": {
"name": "--silent",
"shortcut": "",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Do not output any message",
"default": false
},
"quiet": {
"name": "--quiet",
"shortcut": "-q",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Only errors are displayed. All other output is suppressed",
"default": false
},
"verbose": {
"name": "--verbose",
"shortcut": "-v|-vv|-vvv",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug",
"default": false
},
"version": {
"name": "--version",
"shortcut": "-V",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Display this application version",
"default": false
},
"ansi": {
"name": "--ansi",
"shortcut": "",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Force (or disable --no-ansi) ANSI output",
"default": null
},
"no-ansi": {
"name": "--no-ansi",
"shortcut": "",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Negate the \"--ansi\" option",
"default": null
},
"no-interaction": {
"name": "--no-interaction",
"shortcut": "-n",
"accept_value": false,
"is_value_required": false,
"is_multiple": false,
"description": "Do not ask any interactive question",
"default": false
}
}
},
"rust_only": true
}
]
}
2 changes: 1 addition & 1 deletion rust/parity/test_parity.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ class RustOnlyCommandTest(unittest.TestCase):
def test_the_catalog_marks_the_batch_activity_dispatch_and_update_outcome_commands_rust_only(self):
self.assertEqual(["batch:cancel", "batch:resume", "batch:show", "batch:signal", "batch:update",
"task-queue:activity-dispatch", "task-queue:pause-activities",
"task-queue:resume-activities", "workflow:update-outcome"],
"task-queue:resume-activities", "workflow:update-outcome", "workflow:version-usage"],
parity.rust_only_commands())

def test_rust_only_help_is_skipped_but_2x_help_is_kept(self):
Expand Down
Loading
Loading