feat(app): one session slot for every mutation flow, not just updates

`PlanSlot` held a `Box<UpdateFlow>`, and `claim`/`park` were typed to it. S5 needs
to park an `UninstallFlow` between the guard and the removal, and S6 a
`RollbackFlow` between the preview and the restore, so the slot has to hold all
three.

All three variants land now rather than one per slice. Widening it again in S6
means revisiting `claim`, `park` and every match a second time, and the enum is
the cheap half of the work.

Rejected: `Box<dyn MutationFlow>`. The three flows do not share a signature —
only `UpdateFlow` decides, only `UninstallFlow` has `names`, only `RollbackFlow`
produces a preview — so the trait would be a pile of methods returning `Option`
and every caller would still be matching on which one it really had. The typed
claims (`claim_update`, `claim_uninstall`, `claim_rollback`) make asking for the
wrong flow a compile error at the call site and a named error at runtime:
"expected update session, found uninstall" points at the frontend's sequencing,
where a bare "no plan in progress" sends the reader somewhere else. A refused
session is parked back, not dropped — a mis-ordered call must not cost the user
the dialog they were reading.

`RollbackFlow` gains `cancel_handle`/`cancel`, which `UninstallFlow` has had
since it was written. The token was already threaded into its `ProgressSink`; it
simply had no way out, so a GUI rollback would have been uncancellable — and a
restore is a two-phase install of a whole snapshot, which is exactly when a user
reaches for Stop.

`plan_cancel` becomes `async -> Wire<bool>`, because stopping now touches the
slot as well as the token: a session that is merely parked has no process to
kill and is discarded, since leaving it refuses the next plan on behalf of a
preview nobody is looking at. An async command taking a borrowed `State<'_, _>`
must return a `Result` for Tauri's glue to name the lifetime. The TS wrapper is
unchanged — Tauri unwraps `Ok`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent 05b8132088
commit 1c17f6483d
3 files changed
+232 -23

No files matched your search

+17
View File
@@ -612,6 +612,23 @@ impl RollbackFlow {
)
.await
}
/// A handle that stops this flow's execution.
///
/// The same contract as [`UpdateFlow::cancel_handle`] and [`UninstallFlow::cancel_handle`],
/// and the token has been threaded into this flow's `ProgressSink` since it was written — it
/// simply had no way out, so a GUI rollback could not be stopped. A restore is a two-phase
/// install of a whole snapshot's worth of packages, which is precisely the operation a user
/// reaches for Stop during.
#[must_use]
pub fn cancel_handle(&self) -> CancellationToken {
self.cancel.clone()
}
/// Stop this flow. Idempotent.
pub fn cancel(&self) {
self.cancel.cancel();
}
}
/// The proof that DATA-FLOW §9.2 was satisfied, or the refusal.
+20 -13
View File
@@ -21,7 +21,7 @@ use pipdock_core::{PdError, PkgName, PyEnv};
use tauri::Emitter as _;
use tokio_util::sync::CancellationToken;
use crate::state::AppState;
use crate::state::{AppState, Session};
/// The error shape `ui/src/ipc` declares.
#[derive(Debug, serde::Serialize)]
@@ -383,7 +383,7 @@ pub async fn plan_resolve(
match flow::UpdateFlow::start(env, engine, &intent, &env_pins).await {
Ok((flow, step)) => {
state.park(Box::new(flow)).await;
state.park(Session::Update(Box::new(flow))).await;
Ok(step)
}
Err(e) => {
@@ -404,7 +404,7 @@ pub async fn plan_decide(
state: tauri::State<'_, AppState>,
decisions: std::collections::BTreeMap<String, Decision>,
) -> Wire<flow::FlowStep> {
let mut flow = state.claim_one().await?;
let mut flow = state.claim_update().await?;
let parsed = decisions
.into_iter()
@@ -416,14 +416,14 @@ pub async fn plan_decide(
Err(e) => {
// The flow is still good — only the argument was bad, so park it rather than losing
// the preview the user is looking at.
state.park(flow).await;
state.park(Session::Update(flow)).await;
return Err(e.into());
}
};
match flow.decide(&parsed).await {
Ok(step) => {
state.park(flow).await;
state.park(Session::Update(flow)).await;
Ok(step)
}
Err(e) => {
@@ -447,7 +447,7 @@ pub async fn plan_execute(
app: tauri::AppHandle,
state: tauri::State<'_, AppState>,
) -> Wire<ExecutionOutcome> {
let mut flow = state.claim_one().await?;
let mut flow = state.claim_update().await?;
state.set_cancel(Some(flow.cancel_handle()));
let snapshot = match flow
@@ -481,16 +481,23 @@ pub async fn plan_execute(
})
}
/// Stop the plan that is running (DATA-FLOW §3: allowed while resolving or executing).
/// Stop the plan, whichever half of it is on screen (DATA-FLOW §3: allowed while resolving or
/// executing).
///
/// Returns whether anything was actually in flight, so the UI can tell "stopped it" from "there
/// was nothing to stop" rather than guessing.
/// Returns whether anything was actually there, so the UI can tell "stopped it" from "there was
/// nothing to stop" rather than guessing. A session that is merely *parked* — a preview, a guard
/// dialog — counts, and is discarded: it has no process to kill, and leaving it behind refuses
/// the next plan on behalf of something nobody is looking at.
///
/// Never fails: cancelling something that already finished is not an error, and making it one
/// would mean the UI has to race the thing it is trying to stop.
/// # Errors
/// Never, in practice. An `async` command taking a borrowed `tauri::State<'_, _>` has to return a
/// `Result` for Tauri's generated glue to name the lifetime, so the signature says so even though
/// no path produces one. It became `async` when stopping grew to touch the slot as well as the
/// token — cancelling something that already finished is not an error, and making it one would
/// mean the UI has to race the thing it is trying to stop.
#[tauri::command]
pub fn plan_cancel(state: tauri::State<'_, AppState>) -> bool {
state.cancel_current()
pub async fn plan_cancel(state: tauri::State<'_, AppState>) -> Wire<bool> {
Ok(state.stop().await)
}
/// Read the stored settings.
+195 -10
View File
@@ -22,11 +22,72 @@
use std::path::PathBuf;
use pipdock_core::errors::{Code, PdError, Result};
use pipdock_core::flow::UpdateFlow;
use pipdock_core::flow::{RollbackFlow, UninstallFlow, UpdateFlow};
use pipdock_core::index::NameIndex;
use pipdock_core::store::Store;
use tokio_util::sync::CancellationToken;
/// Which mutation a parked session is part-way through.
///
/// Separate from [`Session`] so a mismatch can be *reported* — "expected an update, found an
/// uninstall" names a real bug in the caller, where a bare "no plan in progress" would send
/// whoever reads it looking in the wrong place.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionKind {
/// An update or an install: `UpdateFlow`, the only one with a decision loop.
Update,
/// A removal: `UninstallFlow`.
Uninstall,
/// A restore: `RollbackFlow`.
Rollback,
}
impl SessionKind {
/// The wire name, for error messages. Never localized (I18N §2).
const fn as_str(self) -> &'static str {
match self {
Self::Update => "update",
Self::Uninstall => "uninstall",
Self::Rollback => "rollback",
}
}
}
/// The mutation flow the slot is holding between two IPC calls.
///
/// All three variants exist from the moment the slot stops being `UpdateFlow`-shaped, rather than
/// arriving one per slice. The alternative — widen it again for S6 — means revisiting `claim`,
/// `park` and every match a second time, and the enum is the cheap half of the work.
///
/// Rejected: `Box<dyn MutationFlow>`. The three flows do not share a signature — only `UpdateFlow`
/// decides, only `UninstallFlow` has `names`, only `RollbackFlow` produces a preview — so the
/// trait would be a pile of methods returning `Option`, and every caller would still be matching
/// on which one it really had.
pub enum Session {
/// `plan_resolve` → `plan_decide`* → `plan_execute`.
Update(Box<UpdateFlow>),
/// `uninstall_guard` → `uninstall_execute`.
Uninstall(Box<UninstallFlow>),
/// `snapshot_rollback_preview` → `snapshot_rollback`.
Rollback(Box<RollbackFlow>),
/// Test-only, so the slot protocol can be exercised without an interpreter to probe.
#[cfg(test)]
Fake(SessionKind),
}
impl Session {
/// Which flow this is.
pub const fn kind(&self) -> SessionKind {
match *self {
Self::Update(_) => SessionKind::Update,
Self::Uninstall(_) => SessionKind::Uninstall,
Self::Rollback(_) => SessionKind::Rollback,
#[cfg(test)]
Self::Fake(kind) => kind,
}
}
}
/// Where the one plan this session may have has got to.
///
/// One at a time, deliberately. Two concurrent plans would interleave engine commands against a
@@ -158,6 +219,80 @@ impl<T> Sessions<T> {
None => false,
}
}
/// Stop whatever the session is doing, whichever half of it that is.
///
/// Two states both count as "there was something to stop", and only one of them is a running
/// process. Engine work in flight is cancelled through the token. A session merely *parked* —
/// a preview on screen, a guard the user is reading — has no process to kill and is discarded
/// instead, because leaving it there means the next plan is refused by a flow nobody is
/// looking at any more.
pub async fn stop(&self) -> bool {
let mut slot = self.slot.lock().await;
if slot.is_busy() {
drop(slot);
return self.cancel_current();
}
let was_parked = matches!(*slot, PlanSlot::Ready(_));
*slot = PlanSlot::Idle;
drop(slot);
self.set_cancel(None);
was_parked
}
}
impl Sessions<Session> {
/// Claim a parked [`Session::Update`].
///
/// # Errors
/// `PD-RES-003` when a plan is in flight, `PD-INT-001` when nothing is parked or the parked
/// session is a different flow.
pub async fn claim_update(&self) -> Result<Box<UpdateFlow>> {
match self.claim_one().await? {
Session::Update(flow) => Ok(flow),
other => Err(self.wrong_kind(SessionKind::Update, other).await),
}
}
/// Claim a parked [`Session::Uninstall`].
///
/// # Errors
/// As [`Self::claim_update`].
pub async fn claim_uninstall(&self) -> Result<Box<UninstallFlow>> {
match self.claim_one().await? {
Session::Uninstall(flow) => Ok(flow),
other => Err(self.wrong_kind(SessionKind::Uninstall, other).await),
}
}
/// Claim a parked [`Session::Rollback`].
///
/// # Errors
/// As [`Self::claim_update`].
pub async fn claim_rollback(&self) -> Result<Box<RollbackFlow>> {
match self.claim_one().await? {
Session::Rollback(flow) => Ok(flow),
other => Err(self.wrong_kind(SessionKind::Rollback, other).await),
}
}
/// Put back a session the caller could not use, and say what was wrong.
///
/// Parking rather than dropping: the session is intact and its owner may still come back for
/// it. A command asking for the wrong kind is a bug in the frontend's sequencing, and losing
/// the user's preview to it would turn a mis-ordered call into lost work.
async fn wrong_kind(&self, want: SessionKind, found: Session) -> PdError {
let found_kind = found.kind();
self.park(found).await;
PdError::new(
Code::IntUnexpected,
format!(
"expected {} session, found {}",
want.as_str(),
found_kind.as_str()
),
)
}
}
/// A second plan was asked for while one is running.
@@ -212,8 +347,8 @@ pub struct AppState {
/// never across an await, and a search that had to await a lock would be a search that can be
/// queued behind the 613 ms load — the exact thing this design exists to prevent.
pub index: std::sync::Mutex<IndexSlot>,
/// The plan being driven across several IPC calls.
pub sessions: Sessions<Box<UpdateFlow>>,
/// The mutation being driven across several IPC calls.
pub sessions: Sessions<Session>,
}
impl AppState {
@@ -295,21 +430,21 @@ impl AppState {
///
/// # Errors
/// `PD-RES-003` when a plan is already in flight.
pub async fn claim(&self) -> Result<Option<Box<UpdateFlow>>> {
pub async fn claim(&self) -> Result<Option<Session>> {
self.sessions.claim().await
}
/// See [`Sessions::claim_one`].
/// See [`Sessions::claim_update`].
///
/// # Errors
/// `PD-RES-003` when a plan is in flight; `PD-INT-001` when there is nothing parked.
pub async fn claim_one(&self) -> Result<Box<UpdateFlow>> {
self.sessions.claim_one().await
/// `PD-RES-003` when a plan is in flight; `PD-INT-001` when nothing of that kind is parked.
pub async fn claim_update(&self) -> Result<Box<UpdateFlow>> {
self.sessions.claim_update().await
}
/// See [`Sessions::park`].
pub async fn park(&self, flow: Box<UpdateFlow>) {
self.sessions.park(flow).await;
pub async fn park(&self, session: Session) {
self.sessions.park(session).await;
}
/// See [`Sessions::release`].
@@ -326,6 +461,11 @@ impl AppState {
pub fn cancel_current(&self) -> bool {
self.sessions.cancel_current()
}
/// See [`Sessions::stop`].
pub async fn stop(&self) -> bool {
self.sessions.stop().await
}
}
#[cfg(test)]
@@ -397,6 +537,51 @@ mod tests {
);
}
#[tokio::test]
async fn asking_for_the_wrong_kind_gives_it_back() {
let s: Sessions<Session> = Sessions::default();
s.park(Session::Fake(SessionKind::Uninstall)).await;
let wrong = s.claim_update().await;
let err = wrong.err().expect("an uninstall is not an update");
assert_eq!(err.code, Code::IntUnexpected);
assert!(
err.message
.contains("expected update session, found uninstall"),
"the message must name both kinds, not just say 'no plan': {}",
err.message
);
// Parked, not dropped: a command asking out of order is a frontend sequencing bug, and
// losing the user's guard dialog to it would turn a mis-ordered call into lost work.
let still_there = s.claim().await.expect("slot is free");
assert_eq!(
still_there.map(|x| x.kind()),
Some(SessionKind::Uninstall),
"the refused session must survive the refusal"
);
}
#[tokio::test]
async fn stop_discards_a_parked_session_and_cancels_a_running_one() {
let s: Sessions<Session> = Sessions::default();
assert!(!s.stop().await, "nothing to stop");
// Parked: no process exists, so stopping means letting go. Leaving it would refuse the
// next plan on behalf of a preview nobody is looking at.
s.park(Session::Fake(SessionKind::Update)).await;
assert!(s.stop().await);
assert!(s.claim().await.expect("free").is_none());
// Busy: there is a child process, and the token is the only thing that reaches it.
let token = CancellationToken::new();
s.park(Session::Fake(SessionKind::Update)).await;
let _running = s.claim_one().await.expect("parked");
s.set_cancel(Some(token.clone()));
assert!(s.stop().await);
assert!(token.is_cancelled());
}
#[tokio::test]
async fn cancel_reaches_a_session_the_slot_no_longer_owns() {
let s = sessions();