Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
fbdbd64
Add native open-run version usage query and endpoint
rmcdaniel Nov 14, 2026
dc4ca75
Bind version-usage fixtures and cover live tenant paging
rmcdaniel Nov 14, 2026
0771e6d
Preserve existing workflow IDs with a distinct version usage route
rmcdaniel Nov 14, 2026
1a77d08
Accept repeated version decisions with valid evolving ranges
rmcdaniel Nov 14, 2026
f365e96
Authenticate usage cursors and recognize native start admission history
rmcdaniel Nov 14, 2026
9b63024
Keep unsupported initial history formats explicitly unavailable
rmcdaniel Nov 14, 2026
32928fa
Keep legal escaped query values within the signed cursor budget
rmcdaniel Nov 14, 2026
e83e4cb
Apply exact identity collation throughout usage queries
rmcdaniel Nov 14, 2026
b8ccffb
Reject malformed and repeated native admission prefixes
rmcdaniel Nov 14, 2026
6e99c52
Keep unsupported history and missing owners visible as unknown
rmcdaniel Nov 14, 2026
33c4a8d
Verify the advertised version usage capability and final shared contract
rmcdaniel Nov 14, 2026
c37dc69
Record version usage in the strict native capability corpus
rmcdaniel Nov 14, 2026
cb4e29f
Validate paired reused-marker provenance before classifying usage
rmcdaniel Nov 14, 2026
c1ebf5a
Pin version usage to the shared reuse provenance contract
rmcdaniel Nov 14, 2026
1e927ee
Merge remote-tracking branch 'origin/main' into feat/server-220-versi…
rmcdaniel Nov 14, 2026
f944e74
Generate fresh cursor signing keys in authentication controls
rmcdaniel Nov 14, 2026
e1729e2
Keep malformed-prefix fixture identity within the stored column bound
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
48 changes: 48 additions & 0 deletions docs/workflow-version-usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Open-run version usage

`GET /api/workflow-version-usage` reports which open runs retain an older
version-marker decision for one workflow type and change point. Discover support
by requiring `capabilities.workflow_version_usage` to be exactly `true` on
`GET /api/cluster/info`. A missing capability or unsuccessful request is not an
empty cohort. Published Server versions without this capability do not serve
this contract.

Use an operator or admin token, the existing control-plane version header, and
the selected namespace. Required query parameters are exact `workflow_type`
(1–255 UTF-8 bytes), exact `change_id` (1–1024 bytes), and signed 32-bit
`min_version`, the proposed minimum supported version. Optional `state` is
`legacy`, `current`, or `unknown`; `limit` is 1–200 (default 50). Continue with
only the returned opaque `cursor` and the same identity/classification filters.
Invalid or mismatched cursors return HTTP 422, rather than restarting a page.
Native namespace echo is always the selected string, including `default`.

A valid retained marker below `min_version` is `legacy`; a value at or above it
is `current`. Missing markers remain `unknown/marker_absent`, even for runs with
a current code fingerprint. Pruned, incomplete or unsupported history remains
`unknown/history_unavailable`. Malformed ranges, integer fields or conflicting
decisions remain `unknown/history_invalid`. More than 1,000 inspected marker
events in one run also makes its history unavailable. The query reads no
application arguments, results, memo or external payload objects.

Reused markers must carry both `reused_from_run_id` and `reused_recorded_at`,
or neither. The source ID must be nonempty, exact and at most 255 UTF-8 bytes,
without surrounding whitespace or control characters. The clock must be a valid
explicit-offset RFC3339 timestamp (`Z` or `+/-HH:MM`), with optional fractional
seconds of at most nine digits. Malformed pairs remain `history_invalid`, even
on a different change ID. Reading these fields never rewrites retained strings
or establishes SDK replay-clock qualification.

`counts` includes the entire bounded open-run cohort before the optional state
filter. `runs` is ordered by ascending run ID. The first page fixes the greatest
participating ID as `through_run_id`; continuations retain that upper bound and
advance strictly after the last returned ID. Each response's counts and records
share one read-only database snapshot. Between pages, closures and marker
recording can change counts and membership. A newly matching state behind a
cursor requires a fresh traversal. This live view is not a deployment fence and
never authorizes branch removal; unknowns must stay visible while admissions
are drained or fenced through the operator's rollout process.

The normative fields are in the [shared v1 contract](https://github.com/durable-workflow/workflow/blob/30341b139323c4bf3fa26a34c2c562f88c075bbe/docs/version-usage.md)
and the [control-plane OpenAPI](../resources/platform-protocol-specs/control-plane-api.openapi.yaml).
The endpoint changes no marker producer, history, workflow definition, schema
or replay behavior.
94 changes: 93 additions & 1 deletion resources/platform-protocol-specs/control-plane-api.openapi.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: durable-workflow.v2.control-plane-api
version: "15"
version: "16"
summary: Durable Workflow control-plane HTTP+JSON API
description: >
Normative OpenAPI specification for the standalone Durable Workflow
Expand Down Expand Up @@ -201,6 +201,98 @@ paths:
"201": { $ref: "#/components/responses/ControlPlaneEnvelope" }
"409": { $ref: "#/components/responses/ControlPlaneError" }
"422": { $ref: "#/components/responses/ControlPlaneError" }
/workflow-version-usage:
get:
tags: [workflows]
operationId: getWorkflowVersionUsage
summary: Count and page open runs by retained version-marker decision
description: >
Requires capabilities.workflow_version_usage=true and the authenticated
namespace context. Reads open pending/running/waiting runs of the exact
workflow type and change ID. No marker, unavailable history and invalid
decisions remain unknown; unknown never means zero legacy usage or safe
removal. Counts include all states before the optional state filter.
Each response uses one read-only storage snapshot. Pagination is a live
ascending run-ID keyset, fixed to the first page's through_run_id, not a
durable fleet snapshot or deployment fence. A marker inspection budget
of 1000 per run yields history_unavailable when exceeded.
Reused marker provenance must be a complete source-ID and explicit-offset
RFC3339 clock pair, otherwise history_invalid. Native clocks retain up to
nine fractional digits and retained strings are never rewritten. Arguments,
results and external payloads are not read. The shared v1 contract is
https://github.com/durable-workflow/workflow/blob/30341b139323c4bf3fa26a34c2c562f88c075bbe/docs/version-usage.md.
parameters:
- $ref: "#/components/parameters/ControlPlaneVersionHeader"
- in: query
name: workflow_type
required: true
description: Exact nonempty workflow type, at most 255 UTF-8 bytes.
schema: { type: string, minLength: 1 }
- in: query
name: change_id
required: true
description: Exact nonempty change-point ID, at most 1024 UTF-8 bytes.
schema: { type: string, minLength: 1 }
- in: query
name: min_version
required: true
schema: { type: integer, minimum: -2147483648, maximum: 2147483647 }
- in: query
name: state
schema: { type: string, enum: [legacy, current, unknown] }
- in: query
name: limit
schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
- in: query
name: cursor
description: Opaque namespace/type/change/minimum/state-bound continuation. Invalid or mismatched cursors are errors.
schema: { type: string }
responses:
"200":
description: Open-run version usage v1; no safe-to-remove flag.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [schema_version, namespace, workflow_type, change_id, min_version, state, consistency, through_run_id, counts, runs, limit, returned_count, has_more, next_cursor]
properties:
schema_version: { const: 1 }
namespace: { type: string }
workflow_type: { type: string }
change_id: { type: string }
min_version: { type: integer, minimum: -2147483648, maximum: 2147483647 }
state: { enum: [null, legacy, current, unknown] }
consistency: { const: live }
through_run_id: { type: [string, "null"] }
counts:
type: object
additionalProperties: false
required: [total, legacy, current, unknown]
properties:
total: { type: integer, minimum: 0 }
legacy: { type: integer, minimum: 0 }
current: { type: integer, minimum: 0 }
unknown: { type: integer, minimum: 0 }
runs:
type: array
maxItems: 200
items:
type: object
additionalProperties: false
required: [instance_id, run_id, status, state, recorded_version, unknown_reason]
properties:
instance_id: { type: string }
run_id: { type: string }
status: { enum: [pending, running, waiting] }
state: { enum: [legacy, current, unknown] }
recorded_version: { type: [integer, "null"], minimum: -2147483648, maximum: 2147483647 }
unknown_reason: { enum: [null, marker_absent, history_unavailable, history_invalid] }
limit: { type: integer, minimum: 1, maximum: 200 }
returned_count: { type: integer, minimum: 0, maximum: 200 }
has_more: { type: boolean }
next_cursor: { type: [string, "null"] }
"422": { $ref: "#/components/responses/ControlPlaneError" }
/workflows/import/embedded-v2:
post:
tags: [workflows]
Expand Down
6 changes: 4 additions & 2 deletions rust/src/runtime/cluster_info.rs
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ pub(super) fn capabilities() -> Value {
"schedule_jitter",
"schedule_max_runs",
"search_attributes",
super::version_usage::CAPABILITY,
"history_export",
"continue_as_new",
"child_workflows",
Expand Down Expand Up @@ -217,8 +218,9 @@ mod tests {
}
// PHP's names plus native's child turn, occurrence-id reopen,
// occurrence deadline, update outcome reads, task queue pauses and
// command request keys.
assert_eq!(caps.as_object().unwrap().len(), 62);
// command request keys and open-run version usage.
assert_eq!(caps.as_object().unwrap().len(), 63);
assert_eq!(caps[super::super::version_usage::CAPABILITY], json!(true));
assert_eq!(caps["task_queue_activity_dispatch_pause"], json!(true));
assert_eq!(caps["command_request_keys"], json!(true));
assert_eq!(caps["update_outcome_reads"], json!(true));
Expand Down
5 changes: 4 additions & 1 deletion rust/src/runtime/control_plane.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ use std::collections::HashMap;
pub(super) enum Operation<'a> {
Start,
List,
VersionUsage,
ListRuns,
Describe,
DescribeRun,
Expand Down Expand Up @@ -99,6 +100,7 @@ impl Operation<'_> {
let (operation, required, success): (&str, &[&str], &[&str]) = match self {
Self::Start => ("start", &[], &["workflow_id", "outcome"]),
Self::List => ("list", &[], &[]),
Self::VersionUsage => ("version_usage", &[], &[]),
Self::ListRuns => ("list_runs", &["workflow_id"], &[]),
Self::Describe => ("describe", &["workflow_id"], &[]),
Self::DescribeRun => ("describe_run", &["workflow_id"], &["run_id"]),
Expand Down Expand Up @@ -321,7 +323,7 @@ impl Operation<'_> {
selected_run_not_current configured_workflow_type_invalid v1_projection_read_only \
backend_lock_pressure control_plane_internal_error",
),
Self::List | Self::ListRuns | Self::Describe | Self::Observe | Self::Debug | Self::ImportEmbeddedV2 => return None,
Self::List | Self::VersionUsage | Self::ListRuns | Self::Describe | Self::Observe | Self::Debug | Self::ImportEmbeddedV2 => return None,
})
}
}
Expand All @@ -345,6 +347,7 @@ pub(super) async fn admission_response(request: Request, mut body: Value) -> Val
("POST", ["api", "workflows", _, "query", name])
| ("POST", ["api", "workflows", _, "runs", _, "query", name]) => Operation::Query(name),
("GET", ["api", "workflows"]) => Operation::List,
("GET", ["api", "workflow-version-usage"]) => Operation::VersionUsage,
("GET", ["api", "workflows", _]) => Operation::Describe,
("GET", ["api", "workflows", _, "runs"]) => Operation::ListRuns,
("GET", ["api", "workflows", _, "runs", _]) => Operation::DescribeRun,
Expand Down
7 changes: 7 additions & 0 deletions rust/src/runtime/execution.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1122,6 +1122,13 @@ impl Runtime {
Storage::MySql(store) => store.list_workflows(&filter).await,
}
}
pub(super) async fn version_usage(&self, filter: super::version_usage::Filter) -> Result<Value> {
match &*self.storage {
Storage::Sqlite(store) => store.version_usage(&filter, &self.token).await,
Storage::Postgres(store) => store.version_usage(&filter, &self.token).await,
Storage::MySql(store) => store.version_usage(&filter, &self.token).await,
}
}
pub(crate) async fn update_workflow(
&self,
workflow_id: &str,
Expand Down
10 changes: 10 additions & 0 deletions rust/src/runtime/http.rs
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ pub fn router(runtime: Runtime) -> Router {
delete(delete_search_attribute),
)
.route("/api/workflows", get(list_workflows).post(start))
.route("/api/workflow-version-usage", get(version_usage))
.route("/api/bridge-adapters/webhook/{adapter}", post(bridge_webhook))
.route("/api/workflows/import/embedded-v2", post(import_embedded_v2))
.route("/api/workflows/import/waterline-v1", post(import_waterline_v1))
Expand Down Expand Up @@ -932,6 +933,7 @@ fn namespace_route(path: &str) -> Option<Allowed> {
fn exact_namespace_route(path: &str) -> Option<Allowed> {
Some(match path {
"/api/runtime-credentials" | "/api/schedules" => Allowed::Any,
"/api/workflow-version-usage" => READ,
"/api/workflows" | "/api/activities" | "/api/search-attributes" => READ_WRITE,
// The metrics describe the namespace's own state, read by GET or POST.
"/api/system/metrics" => READ_WRITE,
Expand Down Expand Up @@ -1467,6 +1469,14 @@ async fn list_workflows(
Ok(Json(runtime.list_workflows(query.validate()?).await?))
}

async fn version_usage(
Extension(runtime): Extension<Runtime>,
query: std::result::Result<Query<super::version_usage::Query>, axum::extract::rejection::QueryRejection>,
) -> Result<Json<Value>> {
let Query(query) = query.map_err(|_| super::version_usage::invalid("query", "The version-usage query parameters are invalid."))?;
Ok(Json(runtime.version_usage(query.validate(&runtime.token)?).await?))
}

async fn describe_current(
Extension(runtime): Extension<Runtime>,
Path(workflow_id): Path<String>,
Expand Down
1 change: 1 addition & 0 deletions rust/src/runtime/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,7 @@ mod update_validation;
mod updates;
pub mod upgrade;
mod visibility;
mod version_usage;
mod visibility_query;
mod wait_history;
mod wait_projection;
Expand Down
Loading
Loading