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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-17 00:55:27 +07:00
1 parent 7e6ad52b4f
commit f9984fa4fb
6 files changed
+457 -18

No files matched your search

+14 -4
View File
@@ -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<Exit> {
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 {
+11
View File
@@ -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<StepResult>;
/// 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::ProbeResult> {
crate::envs::probe(&env.interpreter, env.source).await
}
}
/// What one resolve is given besides the request itself.
+42 -10
View File
@@ -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<Pin>,
cancel: CancellationToken,
clock: fn() -> jiff::Timestamp,
}
impl UpdateFlow {
@@ -189,6 +213,7 @@ impl UpdateFlow {
engine: Box<dyn Engine>,
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<dyn Engine>,
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::<Result<_>>()?;
// 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<dyn Engine>,
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));
+1
View File
@@ -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");
+370
View File
@@ -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<String>,
}
/// The environment and index a [`Scripted`] engine answers from.
#[derive(Default)]
struct World {
installed: BTreeMap<String, Installed>,
/// The newest release the index offers, per package.
latest: BTreeMap<String, String>,
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<InstallSet>,
}
#[derive(Clone, Default)]
struct Scripted(Arc<Mutex<World>>);
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<String> {
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<Vec<Dist>> {
Ok(self.probe(&env()).await?.dists)
}
async fn list_outdated(&self, _env: &PyEnv) -> Result<Vec<OutdatedDist>> {
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<ResolutionReport> {
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<StepResult> {
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<StepResult> {
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<CheckReport> {
Ok(CheckReport {
ok: true,
findings: Vec::new(),
error: None,
})
}
async fn freeze(&self, _env: &PyEnv) -> Result<String> {
Ok(self
.world()
.installed
.iter()
.map(|(name, i)| format!("{name}=={}\n", i.version))
.collect())
}
async fn upgrade_pip(&self, _env: &PyEnv) -> Result<StepResult> {
Err(PdError::new(Code::IntUnexpected, "not scripted"))
}
async fn probe(&self, env: &PyEnv) -> Result<ProbeResult> {
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");
}
+19 -4
View File
@@ -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)