From f9984fa4fbbae20c37b1dbd169c16bc01c38dc90 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Fri, 16 Oct 2026 21:24:46 +0700 Subject: [PATCH] refactor(flow): FlowOptions and an Engine::probe seam Every flow probed through a free function, so nothing `start` decides - the PEP 668 gate, the graph, the drift basis, what reaches the resolver - could be reached by a test without a real interpreter, and the bugs the next commits fix were all there. Engine::probe is a provided method (it is probe.py, not an engine command; no adapter overrides it), and tests/flows.rs drives whole flows against a scripted engine that owns a small, mutable world. FlowOptions carries what the caller decides before a flow starts: the cancellation token and a clock. The token is the caller's because the first resolve runs inside `start`, and a token made there could only be handed out after the resolve it was needed to stop. The GUI registered a token of its own for that window which nothing listened to, so Stop during a first resolve did nothing at all (H13); plan_resolve now hands its token to the flow, and a test proves a hung resolve ends on Stop rather than on its watchdog. Co-Authored-By: Claude Opus 5.5 --- crates/pipdock-cli/src/run.rs | 18 +- crates/pipdock-core/src/engine/mod.rs | 11 + crates/pipdock-core/src/flow/mod.rs | 52 +++- crates/pipdock-core/tests/execution.rs | 1 + crates/pipdock-core/tests/flows.rs | 370 +++++++++++++++++++++++++ src-tauri/src/commands.rs | 23 +- 6 files changed, 457 insertions(+), 18 deletions(-) create mode 100644 crates/pipdock-core/tests/flows.rs diff --git a/crates/pipdock-cli/src/run.rs b/crates/pipdock-cli/src/run.rs index 9ebc4d6..1ea59c5 100644 --- a/crates/pipdock-cli/src/run.rs +++ b/crates/pipdock-cli/src/run.rs @@ -13,7 +13,8 @@ use pipdock_core::engine::{ use pipdock_core::envs::{self, Candidate}; use pipdock_core::errors::{Code, PdError, Result}; use pipdock_core::flow::{ - FlowStep, GuardAck, NothingReason, RollbackFlow, SnapshotPolicy, UninstallFlow, UpdateFlow, + FlowOptions, FlowStep, GuardAck, NothingReason, RollbackFlow, SnapshotPolicy, UninstallFlow, + UpdateFlow, }; use pipdock_core::model::{EngineId, EnvSource, PkgName, PyEnv, StepStatus}; @@ -520,7 +521,14 @@ pub async fn plan_and_run(opts: &GlobalOpts, intent: Intent, dry_run: bool) -> R // Read before the flow starts: `UpdateFlow` takes the pins rather than the store they came // from, so its future stays `Send` for the GUI's sake. let env_pins = pins::list(&store, &envs::env_hash(&env.interpreter))?; - let (mut flow, mut step) = UpdateFlow::start(env, engine_for(opts), &intent, &env_pins).await?; + let (mut flow, mut step) = UpdateFlow::start( + env, + engine_for(opts), + &intent, + &env_pins, + FlowOptions::default(), + ) + .await?; // The flow returns the exclusion as data; the wording is the head's business (I18N §1). if !flow.excluded_pins().is_empty() && !opts.json { @@ -1431,7 +1439,8 @@ pub async fn snapshot_rollback(opts: &GlobalOpts, id: &str) -> Result { let env = select_env(opts).await?; let app_data = app_data_dir(); - let (mut flow, preview) = RollbackFlow::start(env, engine_for(opts), &app_data, id).await?; + let (mut flow, preview) = + RollbackFlow::start(env, engine_for(opts), &app_data, id, FlowOptions::default()).await?; if preview.restore.is_empty() { println!("environment already matches snapshot {}", preview.target.id); @@ -1775,7 +1784,8 @@ pub async fn uninstall(opts: &GlobalOpts, pkgs: &[String], force: bool) -> Resul let env = select_env(opts).await?; let engine = engine_for(opts); - let (mut flow, report) = UninstallFlow::start(env, engine, pkgs).await?; + let (mut flow, report) = + UninstallFlow::start(env, engine, pkgs, FlowOptions::default()).await?; if !report.is_clear() { if opts.json { diff --git a/crates/pipdock-core/src/engine/mod.rs b/crates/pipdock-core/src/engine/mod.rs index 28fe08a..4ebdc31 100644 --- a/crates/pipdock-core/src/engine/mod.rs +++ b/crates/pipdock-core/src/engine/mod.rs @@ -255,6 +255,17 @@ pub trait Engine: Send + Sync { /// Upgrade pip inside `env`. The uv adapter returns an `Unsupported` error — DATA-FLOW §7 /// says pip upkeep is surfaced only when pip is the active engine or present in the env. async fn upgrade_pip(&self, env: &PyEnv) -> Result; + + /// Probe `env`: the interpreter, its marker environment, and every distribution with its + /// requirements. + /// + /// Provided, and no adapter overrides it: this is `probe.py`, not an engine command. It is on + /// the trait so a flow can be driven end to end against a scripted engine — every flow probed + /// through a free function, so none of `start`'s decisions (the PEP 668 gate, the graph, the + /// drift basis) could be tested without a real interpreter, and the bugs in them were not. + async fn probe(&self, env: &PyEnv) -> Result { + crate::envs::probe(&env.interpreter, env.source).await + } } /// What one resolve is given besides the request itself. diff --git a/crates/pipdock-core/src/flow/mod.rs b/crates/pipdock-core/src/flow/mod.rs index db70e22..d4854ce 100644 --- a/crates/pipdock-core/src/flow/mod.rs +++ b/crates/pipdock-core/src/flow/mod.rs @@ -136,6 +136,29 @@ pub enum FlowStep { }, } +/// What the caller decides about a flow before it starts. +#[derive(Debug, Clone)] +pub struct FlowOptions { + /// Stops the flow: its resolve rounds and its execution. + /// + /// **The caller's, not one the flow makes for itself.** The first resolve runs inside + /// `start`, and a token made there could only be handed out once `start` returned — after the + /// resolve it was needed to stop. The GUI registered a token of its own for that window that + /// nothing listened to, so *Stop* during a first resolve did nothing at all (H13). + pub cancel: CancellationToken, + /// What time it is. A function so a test can age a preview without waiting ten minutes. + pub clock: fn() -> jiff::Timestamp, +} + +impl Default for FlowOptions { + fn default() -> Self { + Self { + cancel: CancellationToken::new(), + clock: jiff::Timestamp::now, + } + } +} + /// Whether to take the pre-execution snapshot. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum SnapshotPolicy { @@ -170,6 +193,7 @@ pub struct UpdateFlow { /// Pinned packages kept out of this plan, so the caller can say which and why. excluded_pins: Vec, cancel: CancellationToken, + clock: fn() -> jiff::Timestamp, } impl UpdateFlow { @@ -189,6 +213,7 @@ impl UpdateFlow { engine: Box, intent: &Intent, pins: &[Pin], + opts: FlowOptions, ) -> Result<(Self, FlowStep)> { let env_hash = crate::envs::env_hash(&env.interpreter); @@ -201,7 +226,7 @@ impl UpdateFlow { )); } - let probed = crate::envs::probe(&env.interpreter, env.source).await?; + let probed = engine.probe(&env).await?; // Built against this interpreter so marker-gated requirements are read correctly: without // it a `python_version < "3.11"` branch is reported as a blocker on 3.12 (SP-5 dogfood). let graph = ReverseDeps::for_probe(&probed); @@ -222,7 +247,8 @@ impl UpdateFlow { plan_id, snapshot: SnapshotState::NotTaken, excluded_pins, - cancel: CancellationToken::new(), + cancel: opts.cancel, + clock: opts.clock, }; if flow.req.upgrades.is_empty() && flow.req.installs.is_empty() { @@ -323,7 +349,7 @@ impl UpdateFlow { plan_id: self.plan_id.clone(), }, self.engine.id(), - jiff::Timestamp::now(), + (self.clock)(), )?; let meta = snap.meta.clone(); self.snapshot = SnapshotState::Taken(Box::new(snap)); @@ -347,7 +373,7 @@ impl UpdateFlow { self.report.clone(), self.env_hash.clone(), &self.installed, - jiff::Timestamp::now(), + (self.clock)(), ); plan::execute( @@ -356,7 +382,7 @@ impl UpdateFlow { &accepted, proof, &self.installed, - jiff::Timestamp::now(), + (self.clock)(), sink, ) .await @@ -421,6 +447,7 @@ pub struct UninstallFlow { /// accepted. Returned to the caller as well, because the caller is what renders it. guard: crate::graph::GuardReport, cancel: CancellationToken, + clock: fn() -> jiff::Timestamp, } /// Whether the user has accepted the breakage the guard found (DATA-FLOW §5). @@ -449,6 +476,7 @@ impl UninstallFlow { env: PyEnv, engine: Box, pkgs: &[String], + opts: FlowOptions, ) -> Result<(Self, crate::graph::GuardReport)> { // DATA-FLOW §2's preamble is "all mutating flows", and a removal is one. `UpdateFlow` has // refused these since S1 and this did not, so PipDock would happily strip packages out of @@ -468,7 +496,7 @@ impl UninstallFlow { .collect::>()?; // The graph is built from probe.py, which is the only source carrying requires_dist. - let probed = crate::envs::probe(&env.interpreter, env.source).await?; + let probed = engine.probe(&env).await?; let report = ReverseDeps::for_probe(&probed).guard(&names); let env_hash = crate::envs::env_hash(&env.interpreter); @@ -482,7 +510,8 @@ impl UninstallFlow { plan_id, snapshot: SnapshotState::NotTaken, guard: report.clone(), - cancel: CancellationToken::new(), + cancel: opts.cancel, + clock: opts.clock, }, report, )) @@ -533,7 +562,7 @@ impl UninstallFlow { plan_id: self.plan_id.clone(), }, self.engine.id(), - jiff::Timestamp::now(), + (self.clock)(), )?; let meta = snap.meta.clone(); self.snapshot = SnapshotState::Taken(Box::new(snap)); @@ -625,6 +654,7 @@ pub struct RollbackFlow { /// The state being *replaced*, captured before it is — a rollback is itself reversible. pre: SnapshotState, cancel: CancellationToken, + clock: fn() -> jiff::Timestamp, } impl RollbackFlow { @@ -637,6 +667,7 @@ impl RollbackFlow { engine: Box, app_data: &Path, id: &str, + opts: FlowOptions, ) -> Result<(Self, RollbackPreview)> { let env_hash = crate::envs::env_hash(&env.interpreter); let target = snapshot::load(app_data, &env_hash, id)?; @@ -657,7 +688,8 @@ impl RollbackFlow { target_id: target.meta.id, restore, pre: SnapshotState::NotTaken, - cancel: CancellationToken::new(), + cancel: opts.cancel, + clock: opts.clock, }, preview, )) @@ -676,7 +708,7 @@ impl RollbackFlow { restoring: self.target_id.clone(), }, self.engine.id(), - jiff::Timestamp::now(), + (self.clock)(), )?; let meta = snap.meta.clone(); self.pre = SnapshotState::Taken(Box::new(snap)); diff --git a/crates/pipdock-core/tests/execution.rs b/crates/pipdock-core/tests/execution.rs index fd66a1d..4fce73d 100644 --- a/crates/pipdock-core/tests/execution.rs +++ b/crates/pipdock-core/tests/execution.rs @@ -892,6 +892,7 @@ async fn a_rollback_stops_when_the_token_is_tripped() { Box::new(engine.clone()), &dir, &snap.meta.id, + pipdock_core::flow::FlowOptions::default(), ) .await .expect("start"); diff --git a/crates/pipdock-core/tests/flows.rs b/crates/pipdock-core/tests/flows.rs new file mode 100644 index 0000000..dcfb89c --- /dev/null +++ b/crates/pipdock-core/tests/flows.rs @@ -0,0 +1,370 @@ +//! The flows, driven end to end against a scripted engine. +//! +//! `execution.rs` drives `plan::execute` directly. Everything a flow decides *before* that — the +//! PEP 668 gate, the drift basis, what reaches the resolver, what a forced package releases — sat +//! behind a free-function probe and could not be reached without a real interpreter, and the bugs +//! in it were not found by a test. `Engine::probe` is the seam; this suite is what it is for. +//! +//! The engine here owns a small world — what is installed, what the index offers, whether the +//! interpreter is externally managed — and installs really change it, so a test can move the +//! environment between two calls the way another terminal would. + +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use std::collections::BTreeMap; +use std::sync::{Arc, Mutex, MutexGuard}; + +use async_trait::async_trait; +use pipdock_core::engine::{Engine, GuardAdjust, InstallSet, ProgressSink, ResolveCtx}; +use pipdock_core::envs::ProbeResult; +use pipdock_core::errors::{Code, PdError, Result}; +use pipdock_core::exec::Stop; +use pipdock_core::flow::{ + FlowOptions, FlowStep, Intent, NothingReason, SnapshotPolicy, UpdateFlow, +}; +use pipdock_core::model::{ + CheckReport, Dist, EngineId, EngineInfo, EnvSource, ExecMode, OutdatedDist, PkgName, PyEnv, + StepResult, StepStatus, Version, +}; +use pipdock_core::plan::{Change, ChangeKind, PlanRequest, ResolutionReport}; + +/// One package in the scripted world. +#[derive(Clone)] +struct Installed { + version: String, + requires: Vec, +} + +/// The environment and index a [`Scripted`] engine answers from. +#[derive(Default)] +struct World { + installed: BTreeMap, + /// The newest release the index offers, per package. + latest: BTreeMap, + externally_managed: bool, + /// The resolve blocks until its token is tripped, as a backtracking pip does. + resolve_hangs: bool, + /// Every resolve the flow asked for: the request and what it changed about the guard set. + resolves: Vec<(PlanRequest, GuardAdjust)>, + /// Every install invocation. + installs: Vec, +} + +#[derive(Clone, Default)] +struct Scripted(Arc>); + +impl Scripted { + fn world(&self) -> MutexGuard<'_, World> { + self.0 + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + fn with(self, name: &str, version: &str, requires: &[&str]) -> Self { + self.world().installed.insert( + name.to_owned(), + Installed { + version: version.to_owned(), + requires: requires.iter().map(|r| (*r).to_owned()).collect(), + }, + ); + self + } + + fn offering(self, name: &str, latest: &str) -> Self { + self.world() + .latest + .insert(name.to_owned(), latest.to_owned()); + self + } + + fn version_of(&self, name: &str) -> Option { + self.world().installed.get(name).map(|i| i.version.clone()) + } +} + +fn pkg(name: &str) -> PkgName { + PkgName::parse(name).unwrap() +} + +fn env() -> PyEnv { + PyEnv { + interpreter: "python.exe".into(), + prefix: "prefix".into(), + python_version: "3.12.4".into(), + externally_managed: false, + hidden_user_site: None, + source: EnvSource::Manual, + } +} + +#[async_trait] +impl Engine for Scripted { + fn id(&self) -> EngineId { + EngineId::Pip + } + + async fn info(&self, _env: &PyEnv) -> EngineInfo { + EngineInfo { + id: EngineId::Pip, + version: Some("26.2.1".into()), + available: true, + } + } + + async fn list_installed(&self, _env: &PyEnv) -> Result> { + Ok(self.probe(&env()).await?.dists) + } + + async fn list_outdated(&self, _env: &PyEnv) -> Result> { + let world = self.world(); + Ok(world + .installed + .iter() + .filter_map(|(name, i)| { + let latest = world.latest.get(name)?; + (*latest != i.version).then(|| OutdatedDist { + name: pkg(name), + current: Version(i.version.clone()), + latest: Version(latest.clone()), + }) + }) + .collect()) + } + + async fn resolve( + &self, + _env: &PyEnv, + req: &PlanRequest, + ctx: &ResolveCtx, + ) -> Result { + let hangs = { + let mut world = self.world(); + world.resolves.push((req.clone(), ctx.adjust.clone())); + world.resolve_hangs + }; + if hangs { + ctx.cancel.cancelled().await; + return Err( + PdError::new(Code::IntUnexpected, "cancelled: pip").with_stop(Stop::Cancelled) + ); + } + + // Every upgrade goes to the index's latest; a pin the flow added goes where it says. + let world = self.world(); + let mut changes = Vec::new(); + for name in &req.upgrades { + if ctx.adjust.pins.iter().any(|p| &p.name == name) { + continue; + } + let (Some(from), Some(to)) = ( + world.installed.get(name.as_str()), + world.latest.get(name.as_str()), + ) else { + continue; + }; + changes.push(Change { + name: name.clone(), + from: Some(Version(from.version.clone())), + to: Version(to.clone()), + kind: ChangeKind::Upgrade, + }); + } + for pin in &ctx.adjust.pins { + changes.push(Change { + name: pin.name.clone(), + from: world + .installed + .get(pin.name.as_str()) + .map(|i| Version(i.version.clone())), + to: pin.version.clone(), + kind: ChangeKind::Upgrade, + }); + } + Ok(ResolutionReport { + changes, + ..ResolutionReport::default() + }) + } + + async fn install( + &self, + _env: &PyEnv, + set: &InstallSet, + mode: ExecMode, + _sink: ProgressSink, + ) -> Result { + let mut world = self.world(); + world.installs.push(set.clone()); + for spec in &set.specs { + let requires = world + .installed + .get(spec.name.as_str()) + .map(|i| i.requires.clone()) + .unwrap_or_default(); + world.installed.insert( + spec.name.to_string(), + Installed { + version: spec.version.0.clone(), + requires, + }, + ); + } + let _ = mode; + Ok(StepResult { + pkg: set.specs[0].name.clone(), + from: None, + to: Some(set.specs[0].version.clone()), + status: StepStatus::Ok, + code: None, + stderr_tail: None, + }) + } + + async fn uninstall( + &self, + _env: &PyEnv, + names: &[PkgName], + _sink: ProgressSink, + ) -> Result { + let mut world = self.world(); + for name in names { + world.installed.remove(name.as_str()); + } + Ok(StepResult { + pkg: names[0].clone(), + from: None, + to: None, + status: StepStatus::Ok, + code: None, + stderr_tail: None, + }) + } + + async fn check(&self, _env: &PyEnv) -> Result { + Ok(CheckReport { + ok: true, + findings: Vec::new(), + error: None, + }) + } + + async fn freeze(&self, _env: &PyEnv) -> Result { + Ok(self + .world() + .installed + .iter() + .map(|(name, i)| format!("{name}=={}\n", i.version)) + .collect()) + } + + async fn upgrade_pip(&self, _env: &PyEnv) -> Result { + Err(PdError::new(Code::IntUnexpected, "not scripted")) + } + + async fn probe(&self, env: &PyEnv) -> Result { + let world = self.world(); + Ok(ProbeResult { + env: PyEnv { + externally_managed: world.externally_managed, + ..env.clone() + }, + dists: world + .installed + .iter() + .map(|(name, i)| Dist { + name: pkg(name), + version: Version(i.version.clone()), + requires_dist: i.requires.clone(), + requires_python: None, + size_bytes: None, + }) + .collect(), + markers: BTreeMap::new(), + }) + } +} + +fn update_all() -> Intent { + Intent::Update { + all: true, + pkgs: Vec::new(), + except: Vec::new(), + force_latest: false, + } +} + +/// A scratch app-data directory of this test's own. +fn app_data(tag: &str) -> std::path::PathBuf { + let dir = std::env::temp_dir().join(format!("pd-flows-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + dir +} + +#[tokio::test] +async fn an_update_runs_end_to_end_through_the_seam() { + let engine = Scripted::default() + .with("idna", "3.4", &[]) + .offering("idna", "3.10"); + let (mut flow, step) = UpdateFlow::start( + env(), + Box::new(engine.clone()), + &update_all(), + &[], + FlowOptions::default(), + ) + .await + .expect("start"); + let FlowStep::NeedsConfirm { report } = step else { + panic!("a clean upgrade needs only a confirm: {step:?}"); + }; + assert_eq!(report.changes.len(), 1); + + let dir = app_data("e2e"); + flow.take_snapshot(SnapshotPolicy::Take, &dir) + .await + .expect("snapshot"); + let (tx, _rx) = tokio::sync::mpsc::unbounded_channel(); + let summary = flow.execute(tx).await.expect("execute"); + let _ = std::fs::remove_dir_all(&dir); + + assert_eq!(summary.counts.ok, 1); + assert_eq!(engine.version_of("idna").as_deref(), Some("3.10")); +} + +#[tokio::test] +async fn a_stop_during_the_first_resolve_reaches_the_engine() { + // The first resolve runs inside `start`. The GUI's Stop for that window tripped a token + // nothing listened to, and pip went on backtracking for up to its ten-minute watchdog (H13). + let engine = Scripted::default() + .with("idna", "3.4", &[]) + .offering("idna", "3.10"); + engine.world().resolve_hangs = true; + + let opts = FlowOptions::default(); + let stop = opts.cancel.clone(); + let pressed = tokio::spawn(async move { + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + stop.cancel(); + }); + let started = tokio::time::timeout( + std::time::Duration::from_secs(10), + UpdateFlow::start(env(), Box::new(engine.clone()), &update_all(), &[], opts), + ) + .await + .expect("Stop must end the resolve, not the watchdog") + .expect("a stopped resolve is not an error"); + pressed.await.expect("joined"); + + assert!( + matches!( + started.1, + FlowStep::Nothing { + reason: NothingReason::Cancelled + } + ), + "{:?}", + started.1 + ); + assert!(engine.world().installs.is_empty(), "nothing ran"); +} diff --git a/src-tauri/src/commands.rs b/src-tauri/src/commands.rs index da62b55..33a8d0e 100644 --- a/src-tauri/src/commands.rs +++ b/src-tauri/src/commands.rs @@ -624,8 +624,11 @@ pub async fn plan_resolve( // A bug report carries one run, so the ring starts here rather than at execute. state.log.clear(); + // **This token is the flow's own**, handed in before `start` runs the first resolve. The + // token registered here used to be a fresh one nothing listened to, so *Stop* pressed while + // that resolve ran did nothing (H13). let cancel = CancellationToken::new(); - state.set_cancel(Some(cancel)); + state.set_cancel(Some(cancel.clone())); // Both store reads happen up front and the guard is dropped before any await. `Store` is not // `Sync`, so a future holding one is not `Send` and a Tauri command cannot return it — which @@ -637,7 +640,11 @@ pub async fn plan_resolve( (engine, env_pins) }; - match flow::UpdateFlow::start(env, engine, &intent, &env_pins).await { + let opts = flow::FlowOptions { + cancel, + ..flow::FlowOptions::default() + }; + match flow::UpdateFlow::start(env, engine, &intent, &env_pins, opts).await { Ok((flow, step)) => { // The engine's own output, kept for a report. A resolve emits no progress events, so // without this the commonest thing anyone reports — a plan that would not resolve — @@ -781,7 +788,7 @@ pub async fn uninstall_guard( engine::for_id(settings::load(&store)?.engine) }; - match flow::UninstallFlow::start(env, engine, &pkgs).await { + match flow::UninstallFlow::start(env, engine, &pkgs, flow::FlowOptions::default()).await { Ok((flow, report)) => { state.park(Session::Uninstall(Box::new(flow))).await; Ok(report) @@ -930,7 +937,15 @@ pub async fn snapshot_rollback_preview( engine::for_id(settings::load(&store)?.engine) }; - match flow::RollbackFlow::start(env, engine, &state.app_data, &id).await { + match flow::RollbackFlow::start( + env, + engine, + &state.app_data, + &id, + flow::FlowOptions::default(), + ) + .await + { Ok((rollback, preview)) => { state.park(Session::Rollback(Box::new(rollback))).await; Ok(preview)