From 39cb251ab8639eccf77fd988ff110133309082be Mon Sep 17 00:00:00 2001 From: Ruben Fiszel Date: Wed, 18 Nov 2026 15:06:18 +0100 Subject: [PATCH] feat: get an approval step's detail by flow run id and step id (#12521) * feat: get an approval step's detail by flow run id and step id Co-Authored-By: Claude Opus 5.5 * fix: gate approval step detail like the worker and reach it from run scopes Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- backend/windmill-api-auth/src/scopes.rs | 6 +- backend/windmill-api/openapi.yaml | 131 +++++++++ backend/windmill-api/src/jobs.rs | 371 ++++++++++++++++++++++++ 3 files changed, 506 insertions(+), 2 deletions(-) diff --git a/backend/windmill-api-auth/src/scopes.rs b/backend/windmill-api-auth/src/scopes.rs index dbeda33871..bb73e9728e 100644 --- a/backend/windmill-api-auth/src/scopes.rs +++ b/backend/windmill-api-auth/src/scopes.rs @@ -347,7 +347,7 @@ fn extract_domain_from_route( /// exports) and credential minting (`job_view_token`) are deliberately absent — those are /// `jobs:read`. Keep by-id read routes here in sync as they are added, or a run token /// loses the ability to follow its own run through them. -const RUN_WHITELISTED_GET_PATHS: [&'static str; 32] = [ +const RUN_WHITELISTED_GET_PATHS: [&'static str; 33] = [ "jobs_u/get_flow/", "jobs_u/get_root_job_id/", "jobs_u/get/", @@ -375,6 +375,7 @@ const RUN_WHITELISTED_GET_PATHS: [&'static str; 32] = [ "jobs/flow/user_states/", "jobs/job_signature/", "jobs/wac_approval_urls/", + "jobs/flow/approval_step_detail/", "jobs/completed/get/", "jobs/completed/get_result/", "jobs/completed/get_result_maybe/", @@ -572,7 +573,7 @@ fn resource_metadata_route_allowed(suffix: &str) -> bool { /// a direct `require_job_within_read_scope`. `jobs/result_by_id/` is absent because it /// resolves a node up through the enclosing flows, past the job the check admitted. /// A route added here without that check serves a path-scoped token every job. -const READ_PATH_SCOPED_BY_ID_PATHS: [&'static str; 25] = [ +const READ_PATH_SCOPED_BY_ID_PATHS: [&'static str; 26] = [ "jobs_u/get/", "jobs_u/get_logs/", "jobs_u/get_completed_logs_tail/", @@ -591,6 +592,7 @@ const READ_PATH_SCOPED_BY_ID_PATHS: [&'static str; 25] = [ "jobs_u/get_log_file/", "jobs_u/get_flow/", "jobs_u/flow/approval_info/", + "jobs/flow/approval_step_detail/", "jobs/run_progress/", "jobs/flow/user_states/", "jobs/completed/get/", diff --git a/backend/windmill-api/openapi.yaml b/backend/windmill-api/openapi.yaml index 6b812b4cd7..ccd2f296e9 100644 --- a/backend/windmill-api/openapi.yaml +++ b/backend/windmill-api/openapi.yaml @@ -13199,6 +13199,137 @@ paths: application/json: schema: {} + /w/{workspace}/jobs/flow/approval_step_detail/{job_id}/{step_id}: + get: + summary: get the approval detail of one step of a flow run + description: > + Get the approval state of an approval (suspend) step of a flow run, by the + flow run id and the step id, in a single query: where the step stands, its + approval settings, the approvals received and, while it waits, whether the + caller can approve. Only the run's own steps are searched: for a step inside + a branch or loop, pass the id of the branch's or iteration's run. + operationId: getApprovalStepDetail + tags: + - job + parameters: + - $ref: "#/components/parameters/WorkspaceId" + - name: job_id + in: path + required: true + description: id of the flow run + schema: + type: string + format: uuid + - name: step_id + in: path + required: true + description: id of the approval step in the flow + schema: + type: string + responses: + "200": + description: approval step detail + content: + application/json: + schema: + type: object + required: + - flow_id + - step_id + - status + - required_events + - hide_cancel + - continue_on_disapprove_timeout + - skin + - approvals + properties: + flow_id: + type: string + format: uuid + step_id: + type: string + status: + type: string + enum: [not_reached, skipped, failed, waiting, resumed, not_resumed] + description: > + not_reached: the step's own script has not finished yet. + failed: the step failed before asking for approval. + waiting: the run is suspended on this step. + resumed: the run moved past this step. + not_resumed: the run ended while waiting (denied, timed out or cancelled). + step_job: + type: string + format: uuid + description: the job of the approval step, once it ran + step_summary: + type: string + required_events: + type: integer + description: number of approvals required to resume + timeout: + type: integer + description: seconds the run waits for approvals + suspended_until: + type: string + format: date-time + description: when the wait times out, while waiting + form_schema: + description: form schema for the approval step + hide_cancel: + type: boolean + continue_on_disapprove_timeout: + type: boolean + skin: + type: string + enum: [detailed, minimal] + approval_conditions: + type: object + properties: + user_auth_required: + type: boolean + user_groups_required: + type: array + items: + type: string + self_approval_disabled: + type: boolean + required: + - user_auth_required + - user_groups_required + - self_approval_disabled + can_approve: + type: boolean + description: whether the caller can approve, set only while waiting + description: + description: description returned by the approval step's script + default_args: + description: default form values returned by the approval step's script + enums: + description: form enums returned by the approval step's script + approvals: + type: array + description: > + approvals received. approved, value and created_at are known only + while the run is live; a finished run keeps approver names alone. + items: + type: object + required: + - resume_id + - approver + properties: + resume_id: + type: integer + approver: + type: string + approved: + type: boolean + value: {} + created_at: + type: string + format: date-time + error: + description: the run's error, when status is not_resumed + /w/{workspace}/jobs/job_view_token/{id}: get: summary: mint a read-only share token for a job diff --git a/backend/windmill-api/src/jobs.rs b/backend/windmill-api/src/jobs.rs index e63416ddbc..7b70acce62 100644 --- a/backend/windmill-api/src/jobs.rs +++ b/backend/windmill-api/src/jobs.rs @@ -396,6 +396,10 @@ pub fn workspaced_service() -> Router { "/result_by_id/{job_id}/{node_id}", get(get_result_by_id).layer(cors.clone()), ) + .route( + "/flow/approval_step_detail/{job_id}/{step_id}", + get(get_approval_step_detail), + ) .route( "/job_view_token/{id}", get(get_job_view_token).layer(cors.clone()), @@ -5698,6 +5702,325 @@ async fn get_approval_info( })) } +#[derive(Serialize, Debug, PartialEq)] +#[serde(rename_all = "snake_case")] +enum ApprovalStepStatus { + /// The step has not finished running its own script yet. + NotReached, + Skipped, + /// The step failed before asking for approval. + Failed, + Waiting, + Resumed, + /// The run ended while waiting: denied, timed out or cancelled. + NotResumed, +} + +#[derive(Serialize)] +struct StepApproval { + resume_id: u16, + approver: String, + /// Known only while the run is live: a finished run keeps approver names alone. + #[serde(skip_serializing_if = "Option::is_none")] + approved: Option, + #[serde(skip_serializing_if = "Option::is_none")] + value: Option, + #[serde(skip_serializing_if = "Option::is_none")] + created_at: Option>, +} + +#[derive(Serialize)] +struct ApprovalStepDetail { + flow_id: Uuid, + step_id: String, + status: ApprovalStepStatus, + #[serde(skip_serializing_if = "Option::is_none")] + step_job: Option, + #[serde(skip_serializing_if = "Option::is_none")] + step_summary: Option, + required_events: u32, + #[serde(skip_serializing_if = "Option::is_none")] + timeout: Option, + #[serde(skip_serializing_if = "Option::is_none")] + suspended_until: Option>, + #[serde(skip_serializing_if = "Option::is_none")] + form_schema: Option, + hide_cancel: bool, + continue_on_disapprove_timeout: bool, + skin: ApprovalSkin, + #[serde(skip_serializing_if = "Option::is_none")] + approval_conditions: Option, + #[serde(skip_serializing_if = "Option::is_none")] + can_approve: Option, + #[serde(skip_serializing_if = "Option::is_none")] + description: Option, + #[serde(skip_serializing_if = "Option::is_none")] + default_args: Option, + #[serde(skip_serializing_if = "Option::is_none")] + enums: Option, + approvals: Vec, + #[serde(skip_serializing_if = "Option::is_none")] + error: Option, +} + +/// Where an approval step stands, from its status module and the one after it: while an +/// approval is pending, the step after holds `WaitingForEvents` with the approval step's job. +fn approval_step_status( + module: Option<&FlowStatusModule>, + next_module: Option<&FlowStatusModule>, + running: bool, + continue_on_disapprove_timeout: bool, + flow_error: Option<&serde_json::Value>, +) -> ApprovalStepStatus { + let canceled = flow_error + .and_then(|e| e.get("name")) + .is_some_and(|n| n == "Canceled"); + match module { + None + | Some(FlowStatusModule::WaitingForPriorSteps { .. }) + // Held by an approval of the step before it. + | Some(FlowStatusModule::WaitingForEvents { .. }) + | Some(FlowStatusModule::WaitingForExecutor { .. }) + | Some(FlowStatusModule::InProgress { .. }) => ApprovalStepStatus::NotReached, + Some(FlowStatusModule::Failure { .. }) => ApprovalStepStatus::Failed, + Some(FlowStatusModule::Success { skipped: true, .. }) => ApprovalStepStatus::Skipped, + Some(FlowStatusModule::Success { job, approvers, .. }) => match next_module { + Some(FlowStatusModule::WaitingForEvents { job: waiting_on, .. }) + if waiting_on == job => + { + if running { + ApprovalStepStatus::Waiting + } else { + ApprovalStepStatus::NotResumed + } + } + // The worker has yet to pick up the step after it and suspend the run. + None | Some(FlowStatusModule::WaitingForPriorSteps { .. }) if running => { + ApprovalStepStatus::Waiting + } + // A denial or timeout that does not continue, or a cancel, fails the step after it + // without running it. The worker records approvers only when it moves on, and a + // step that continues on a timeout moves on with none: its next step can still + // fail unrun, on a branch predicate. + Some(FlowStatusModule::Failure { job: next_job, .. }) + if next_job.is_nil() + && approvers.is_empty() + && (!continue_on_disapprove_timeout || canceled) => + { + ApprovalStepStatus::NotResumed + } + _ => ApprovalStepStatus::Resumed, + }, + } +} + +/// The approval state of one step of a flow run, read in a single query. Only the run's own +/// modules are searched: a step nested in a branch or loop is a module of that branch's or +/// iteration's job, which is the id to pass for it. +async fn get_approval_step_detail( + OptViewToken(view_token): OptViewToken, + authed: ApiAuthed, + Extension(db): Extension, + Extension(user_db): Extension, + Path((w_id, flow_id, step_id)): Path<(String, Uuid, String)>, +) -> error::Result> { + #[derive(sqlx::FromRow)] + struct Row { + created_by: String, + runnable_path: Option, + permissioned_as_email: String, + running: bool, + module: Option, + next_module: Option, + module_def: Option, + is_last_module: bool, + run_approval_conditions: Option, + suspend_until: Option>, + flow_error: Option, + step_result: Option, + resumes: serde_json::Value, + } + // `v2_job_status` holds the status of a live run only; a finished one's is on + // `v2_job_completed`. Resumes addressed to the run itself + // count toward any of its approval steps, as the worker counts them. + let row = sqlx::query_as::<_, Row>( + "SELECT j.created_by, j.runnable_path, j.permissioned_as_email, + s.id IS NOT NULL AS running, + m.module, m.next_module, + jsonb_path_query_first( + COALESCE(j.raw_flow, fv.value, fn.flow), + '$.modules[*] ? (@.id == $id)', + jsonb_build_object('id', $3::text) + ) AS module_def, + COALESCE( + COALESCE(j.raw_flow, fv.value, fn.flow)->'modules'->-1->>'id' = $3, + false + ) AS is_last_module, + s.flow_status->'approval_conditions' AS run_approval_conditions, + q.suspend_until, + c.result->'error' AS flow_error, + sj.result AS step_result, + COALESCE(( + SELECT jsonb_agg(jsonb_build_object( + 'resume_id', r.resume_id, 'approver', r.approver, + 'approved', r.approved, 'value', r.value, 'created_at', r.created_at + ) ORDER BY r.created_at) + FROM resume_job r + WHERE r.flow = j.id AND (r.job = j.id OR r.job = m.step_job) + ), '[]'::jsonb) AS resumes + FROM v2_job j + LEFT JOIN v2_job_status s ON s.id = j.id + LEFT JOIN v2_job_completed c ON c.id = j.id + LEFT JOIN v2_job_queue q ON q.id = j.id + LEFT JOIN flow_version fv + ON j.raw_flow IS NULL AND j.kind = 'flow' AND fv.id = j.runnable_id + LEFT JOIN flow_node fn + ON j.raw_flow IS NULL AND j.kind = 'flownode' AND fn.id = j.runnable_id + LEFT JOIN LATERAL ( + SELECT e.module, + COALESCE(s.flow_status, c.flow_status)->'modules'->(e.idx::int) AS next_module, + -- A step held by the approval before it carries that approval's job. + CASE WHEN e.module->>'type' <> 'WaitingForEvents' + THEN (e.module->>'job')::uuid END AS step_job + FROM jsonb_array_elements(COALESCE(s.flow_status, c.flow_status)->'modules') + WITH ORDINALITY AS e(module, idx) + WHERE e.module->>'id' = $3 + LIMIT 1 + ) m ON true + LEFT JOIN v2_job_completed sj + ON sj.id = m.step_job AND sj.workspace_id = j.workspace_id + WHERE j.id = $1 AND j.workspace_id = $2", + ) + .bind(&flow_id) + .bind(&w_id) + .bind(&step_id) + .fetch_optional(&db) + .await? + .ok_or_else(|| Error::NotFound(format!("Job {flow_id} not found")))?; + + require_job_read_access( + &db, + &user_db, + &authed, + &w_id, + &flow_id, + &row.created_by, + view_token.as_deref(), + ) + .await?; + + let not_found = || { + Error::NotFound(format!( + "Step {step_id} is not a step of flow run {flow_id}. A step inside a branch or \ + loop belongs to the branch's or iteration's run: pass that run's id instead." + )) + }; + let module_def: FlowModule = row + .module_def + .and_then(|v| serde_json::from_value(v).ok()) + .ok_or_else(not_found)?; + // The worker holds a run only after a step with a positive `required_events` that has a + // step after it (`needs_resume`); the last step's suspend settings never stop the run. + let suspend = module_def + .suspend + .as_ref() + .filter(|s| s.required_events.unwrap_or(0) > 0 && !row.is_last_module) + .ok_or_else(|| { + Error::BadRequest(format!("Step {step_id} is not an approval (suspend) step")) + })?; + let module: Option = row.module.and_then(|v| serde_json::from_value(v).ok()); + let next_module: Option = + row.next_module.and_then(|v| serde_json::from_value(v).ok()); + + let step_job = module + .as_ref() + .filter(|m| !matches!(m, FlowStatusModule::WaitingForEvents { .. })) + .and_then(|m| m.job()); + let status = approval_step_status( + module.as_ref(), + next_module.as_ref(), + row.running, + suspend.continue_on_disapprove_timeout.unwrap_or(false), + row.flow_error.as_ref(), + ); + + let live_resumes: Vec = + serde_json::from_value::>(row.resumes) + .unwrap_or_default() + .into_iter() + .map(|r| StepApproval { + // Truncated as the worker records it on the finished step, so both agree. + resume_id: r.get("resume_id").and_then(|v| v.as_i64()).unwrap_or(0) as u16, + approver: r + .get("approver") + .and_then(|v| v.as_str()) + .unwrap_or("anonymous") + .to_string(), + approved: r.get("approved").and_then(|v| v.as_bool()), + value: r.get("value").cloned(), + created_at: r + .get("created_at") + .and_then(|v| serde_json::from_value(v.clone()).ok()), + }) + .collect(); + let approvals = if !live_resumes.is_empty() { + live_resumes + } else if let Some(FlowStatusModule::Success { approvers, .. }) = &module { + approvers + .iter() + .map(|a| StepApproval { + resume_id: a.resume_id, + approver: a.approver.clone(), + approved: None, + value: None, + created_at: None, + }) + .collect() + } else { + vec![] + }; + + let waiting = status == ApprovalStepStatus::Waiting; + let approval_conditions = row + .run_approval_conditions + .filter(|_| waiting) + .and_then(|v| serde_json::from_value::(v).ok()) + .or_else(|| approval_conditions_from_settings(suspend)); + let can_approve = waiting.then(|| { + can_approve_step( + &Some(authed.clone()), + &approval_conditions, + row.runnable_path.as_deref(), + &row.permissioned_as_email, + ) + }); + let step_result_field = |k: &str| row.step_result.as_ref().and_then(|r| r.get(k).cloned()); + + Ok(Json(ApprovalStepDetail { + flow_id, + step_id, + step_job, + step_summary: module_def.summary.clone().filter(|s| !s.trim().is_empty()), + required_events: suspend.required_events.unwrap_or_default(), + timeout: suspend.timeout, + suspended_until: row.suspend_until.filter(|_| waiting), + form_schema: suspend.resume_form.clone(), + hide_cancel: suspend.hide_cancel.unwrap_or(false), + continue_on_disapprove_timeout: suspend.continue_on_disapprove_timeout.unwrap_or(false), + skin: suspend.skin.unwrap_or_default(), + approval_conditions, + can_approve, + description: step_result_field("description"), + default_args: step_result_field("default_args"), + enums: step_result_field("enums"), + approvals, + error: row + .flow_error + .filter(|_| status == ApprovalStepStatus::NotResumed), + status, + })) +} + // --- End new approval system endpoints --- pub async fn resume_suspended_job( @@ -12966,6 +13289,54 @@ async fn get_otel_traces( Ok(Json(traces)) } +#[cfg(test)] +mod approval_step_status_tests { + use super::*; + + fn m(v: serde_json::Value) -> FlowStatusModule { + serde_json::from_value(v).unwrap() + } + + #[test] + fn denial_is_not_read_as_resumed() { + let job = "01a1eedb-e408-980c-2af6-e9ac192dc70f"; + let approval = + m(serde_json::json!({"type": "Success", "id": "a", "job": job, "skipped": false})); + let waiting = + m(serde_json::json!({"type": "WaitingForEvents", "id": "b", "job": job, "count": 1})); + let next_failed = m(serde_json::json!({"type": "Failure", "id": "b", "job": Uuid::nil()})); + let next_ran = m( + serde_json::json!({"type": "Success", "id": "b", "job": Uuid::new_v4(), "skipped": false}), + ); + let approved = m(serde_json::json!({"type": "Success", "id": "a", "job": job, + "skipped": false, "approvers": [{"resume_id": 1, "approver": "admin"}]})); + + let status = + |next, running| approval_step_status(Some(&approval), next, running, false, None); + assert_eq!(status(Some(&waiting), true), ApprovalStepStatus::Waiting); + assert_eq!( + status(Some(&waiting), false), + ApprovalStepStatus::NotResumed + ); + // Denied or cancelled while waiting. + assert_eq!( + status(Some(&next_failed), false), + ApprovalStepStatus::NotResumed + ); + assert_eq!(status(Some(&next_ran), false), ApprovalStepStatus::Resumed); + // Approved, then the step after failed before running. + assert_eq!( + approval_step_status(Some(&approved), Some(&next_failed), false, false, None), + ApprovalStepStatus::Resumed + ); + // Timed out and continued, then the step after failed before running. + assert_eq!( + approval_step_status(Some(&approval), Some(&next_failed), false, true, None), + ApprovalStepStatus::Resumed + ); + } +} + #[cfg(test)] mod approval_view_gate_tests { use super::*;