From 3d1e13bbbb76140787d99fdca87d46443f2e6a6a Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 4 Aug 2026 18:57:19 +0700 Subject: [PATCH] feat(app): hold the name index in memory, and warm it on demand MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit S4's exit criterion is < 50 ms per keystroke measured in the app. **`NameIndex::load` costs 613 ms on the real 858k-project index** — measured before writing any of this — which is twelve times the whole budget. SP-3 had already ruled out the alternative: scanning SQLite per keystroke measured 218 ms. So the index is loaded once and held, and the only real question was when to pay for it. On demand, with `IndexSlot` as the honest account of it. A user who never opens Search never pays; one who does gets the field immediately with a note. Typing two or three characters takes about as long as the load, so the note is rarely seen — but `index_search` must **never** wait for it, which is what a state rather than an `Option` behind a lock enforces. `index_refresh` invalidates the slot, or a refresh reports thousands of new projects that search cannot find. `ready: false` is a state on the result, not an error. "You have never refreshed the index" is an action the user can take; an error row would say something went wrong instead. Empty `hits` and "not loaded yet" are different answers, and conflating them would tell someone their package does not exist for 613 ms. **`index::metadata` and `index::refresh` now take the app-data directory, not a `&Store`** — the same fix as `UpdateFlow::start`, for the same reason, and this is the second time it has come up: `Store` is `Send` but not `Sync`, so a future holding one is not `Send` and cannot be returned from a Tauri command. It also stops `refresh` holding a SQLite handle open across a multi-second PyPI download, which was wrong independently of whether it compiled. The no-snake_case-in-any-schema test earned its keep again: `RefreshReport` went onto the wire with `wire_bytes` and `elapsed_ms` and was rejected. Verified by running afterwards — a real `index refresh` fetched 864,083 projects in 4.5 s and printed camelCase. Co-Authored-By: Claude Opus 5 --- crates/pipdock-cli/src/run.rs | 6 +- crates/pipdock-cli/tests/golden.rs | 2 + .../snapshots/golden__schema-Freshness.snap | 26 +++++ .../golden__schema-RefreshReport.snap | 35 +++++++ .../golden__schema-unknown-type.snap | 2 +- crates/pipdock-core/src/index/mod.rs | 21 ++-- crates/pipdock-core/src/plan/mod.rs | 4 + src-tauri/src/commands.rs | 95 +++++++++++++++++++ src-tauri/src/lib.rs | 3 + src-tauri/src/state.rs | 90 ++++++++++++++++++ ui/src/ipc/generated.ts | 16 ++++ ui/src/ipc/index.ts | 35 +++++++ 12 files changed, 324 insertions(+), 11 deletions(-) create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Freshness.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-RefreshReport.snap diff --git a/crates/pipdock-cli/src/run.rs b/crates/pipdock-cli/src/run.rs index 0eacc34..353bfcc 100644 --- a/crates/pipdock-cli/src/run.rs +++ b/crates/pipdock-cli/src/run.rs @@ -953,12 +953,11 @@ fn confirm_text(question: &str) -> bool { /// `PD-NET-010` when the index cannot be fetched. The previous index stays in place and remains /// searchable — a failed refresh must not cost the user the index they already had. pub async fn index_refresh(opts: &GlobalOpts) -> Result { - let store = Store::open(&app_data_dir())?; if !opts.quiet { eprintln!("fetching {} …", index::SIMPLE_INDEX_URL); } - let report = index::refresh(&store, jiff::Timestamp::now()).await?; + let report = index::refresh(&app_data_dir(), jiff::Timestamp::now()).await?; if opts.json { println!( @@ -1037,9 +1036,8 @@ pub async fn search(opts: &GlobalOpts, query: &str, limit: usize) -> Result Result { - let store = Store::open(&app_data_dir())?; let name = PkgName::parse(pkg)?; - let (meta, freshness) = index::metadata(&store, &name, jiff::Timestamp::now()).await?; + let (meta, freshness) = index::metadata(&app_data_dir(), &name, jiff::Timestamp::now()).await?; if opts.json { println!( diff --git a/crates/pipdock-cli/tests/golden.rs b/crates/pipdock-cli/tests/golden.rs index 628f8a2..b70ccbe 100644 --- a/crates/pipdock-cli/tests/golden.rs +++ b/crates/pipdock-cli/tests/golden.rs @@ -43,6 +43,8 @@ const SCHEMA_TYPES: &[&str] = &[ "SnapshotMeta", "Hit", "PackageMeta", + "Freshness", + "RefreshReport", "ProgressEvent", "FlowStep", "Decision", diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Freshness.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Freshness.snap new file mode 100644 index 0000000..dd9cc0b --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Freshness.snap @@ -0,0 +1,26 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "How fresh a metadata answer is, so the UI can badge it (UI-SPEC §7).", + "oneOf": [ + { + "const": "fresh", + "description": "Fetched just now.", + "type": "string" + }, + { + "const": "cached", + "description": "Served from cache, still inside the TTL.", + "type": "string" + }, + { + "const": "stale", + "description": "Served from cache because the network was unreachable. The UI shows an offline badge and\nthe cached-at time rather than an error, because search itself still works.", + "type": "string" + } + ], + "title": "Freshness" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-RefreshReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-RefreshReport.snap new file mode 100644 index 0000000..7f621c0 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-RefreshReport.snap @@ -0,0 +1,35 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "What a refresh did.", + "properties": { + "elapsedMs": { + "description": "How long the whole refresh took.", + "format": "uint64", + "minimum": 0, + "type": "integer" + }, + "projects": { + "description": "Projects ingested.", + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "wireBytes": { + "description": "Bytes received on the wire.", + "format": "uint", + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "projects", + "wireBytes", + "elapsedMs" + ], + "title": "RefreshReport", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap index 981ef85..94c0579 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap @@ -2,4 +2,4 @@ source: crates/pipdock-cli/tests/golden.rs expression: "stderr_of(&[\"schema\", \"NoSuchType\"])" --- -error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, Hit, PackageMeta, ProgressEvent, FlowStep, Decision, Intent, Code +error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, Hit, PackageMeta, Freshness, RefreshReport, ProgressEvent, FlowStep, Decision, Intent, Code diff --git a/crates/pipdock-core/src/index/mod.rs b/crates/pipdock-core/src/index/mod.rs index 516a459..adfb018 100644 --- a/crates/pipdock-core/src/index/mod.rs +++ b/crates/pipdock-core/src/index/mod.rs @@ -255,6 +255,7 @@ impl NameIndex { /// What a refresh did. #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, schemars::JsonSchema)] +#[serde(rename_all = "camelCase")] pub struct RefreshReport { /// Projects ingested. pub projects: usize, @@ -273,7 +274,7 @@ pub struct RefreshReport { /// # Errors /// `PD-NET-010` when the fetch or ingest fails. The previous index is left in place and stays /// searchable, because a failed refresh must not cost the user the index they already had. -pub async fn refresh(store: &Store, now: jiff::Timestamp) -> Result { +pub async fn refresh(app_data: &std::path::Path, now: jiff::Timestamp) -> Result { let started = std::time::Instant::now(); let client = http_client()?; @@ -319,7 +320,11 @@ pub async fn refresh(store: &Store, now: jiff::Timestamp) -> Result Result<(PackageMeta, Freshness)> { - if let Some((meta, fetched_at)) = cached_metadata(store, name)? { + // The store is opened for each synchronous stretch and dropped before the network call, never + // held across it. `Store` wraps a `rusqlite::Connection` and is `Send` but not `Sync`, so a + // future holding one is not `Send` and cannot be returned from a Tauri command — and holding a + // database handle open across a PyPI round trip would be wrong even where it compiled. + if let Some((meta, fetched_at)) = cached_metadata(&Store::open(app_data)?, name)? { let age_ms = now .as_millisecond() .saturating_sub(fetched_at.as_millisecond()); @@ -437,7 +446,7 @@ pub async fn metadata( match fetch_metadata(name).await { Ok(meta) => { let payload = serde_json::to_string(&meta).unwrap_or_default(); - store + Store::open(app_data)? .conn() .execute( "INSERT INTO meta_cache (normalized, payload, fetched_at) VALUES (?1, ?2, ?3) @@ -452,7 +461,7 @@ pub async fn metadata( } // Offline with a stale entry is better than offline with nothing: ARCHITECTURE §5 says // the metadata panel shows a cached/offline badge rather than failing. - Err(e) => match cached_metadata(store, name)? { + Err(e) => match cached_metadata(&Store::open(app_data)?, name)? { Some((meta, _)) => Ok((meta, Freshness::Stale)), None => Err(e), }, diff --git a/crates/pipdock-core/src/plan/mod.rs b/crates/pipdock-core/src/plan/mod.rs index 4905bc4..8f3d32a 100644 --- a/crates/pipdock-core/src/plan/mod.rs +++ b/crates/pipdock-core/src/plan/mod.rs @@ -272,6 +272,8 @@ pub fn json_schema(type_name: &str) -> Result { "SnapshotMeta" => crate::snapshot::Meta, "Hit" => crate::index::Hit, "PackageMeta" => crate::index::PackageMeta, + "Freshness" => crate::index::Freshness, + "RefreshReport" => crate::index::RefreshReport, "ProgressEvent" => crate::engine::ProgressEvent, "FlowStep" => crate::flow::FlowStep, "Decision" => Decision, @@ -296,6 +298,8 @@ pub const SCHEMA_TYPES: &[&str] = &[ "SnapshotMeta", "Hit", "PackageMeta", + "Freshness", + "RefreshReport", "ProgressEvent", "FlowStep", "Decision", diff --git a/src-tauri/src/commands.rs b/src-tauri/src/commands.rs index da81437..bc64f41 100644 --- a/src-tauri/src/commands.rs +++ b/src-tauri/src/commands.rs @@ -12,6 +12,7 @@ use pipdock_core::engine; use pipdock_core::envs::{self, ScanProgress}; use pipdock_core::errors::Code; use pipdock_core::flow; +use pipdock_core::index::{self, NameIndex}; use pipdock_core::model::EnvSource; use pipdock_core::pins::{self, Pin}; use pipdock_core::plan::{Decision, ExecutionSummary}; @@ -240,6 +241,100 @@ pub async fn pin_remove( Ok(pins::remove(&store, &env_hash, &name)?) } +/// What `index_search` returns. +/// +/// A struct rather than a bare `Hit[]` because "no results" and "the index is not loaded yet" are +/// different answers and the screen must say different things about them. Conflating them would +/// tell a user their package does not exist during the 613 ms it takes to load 858k names. +#[derive(serde::Serialize)] +#[serde(rename_all = "camelCase")] +pub struct SearchResults { + /// Matches, best first. Empty when `ready` is false. + pub hits: Vec, + /// False while the index is still loading. + pub ready: bool, + /// Set when the index could not be loaded at all — usually "never refreshed". + #[serde(skip_serializing_if = "Option::is_none")] + pub unavailable: Option, +} + +/// Fuzzy search over the local name index. +/// +/// **Never blocks on the load.** SP-3 measured scanning SQLite at 218 ms per keystroke against a +/// 50 ms budget, so the index is held in memory — and loading it costs 613 ms on the real 858k +/// index, which is why a search that arrives first is answered `ready: false` rather than queued +/// behind it. The load is kicked off here so the screen does not have to coordinate; calling this +/// on every keystroke is safe. +/// +/// # Errors +/// Never as a whole — an index that cannot be loaded is reported in `unavailable`, because +/// "refresh the index" is an action, not a failure. +#[tauri::command] +pub async fn index_search( + state: tauri::State<'_, AppState>, + query: String, + limit: usize, +) -> Wire { + if let Some(hits) = state.search_index(&query, limit) { + return Ok(SearchResults { + hits, + ready: true, + unavailable: None, + }); + } + + if state.begin_index_load() { + let loaded = { + let store = state.store.lock().await; + NameIndex::load(&store) + }; + state.finish_index_load(loaded); + // The load that this keystroke paid for is done, so answer from it rather than making the + // user press another key. + if let Some(hits) = state.search_index(&query, limit) { + return Ok(SearchResults { + hits, + ready: true, + unavailable: None, + }); + } + } + + Ok(SearchResults { + hits: Vec::new(), + ready: false, + unavailable: state.index_failure(), + }) +} + +/// Cached PyPI metadata for the details panel, with how fresh it is. +/// +/// # Errors +/// `PD-PKG-002` when the name is malformed or PyPI does not know it; `PD-NET-001` when it is +/// neither cached nor reachable. +#[tauri::command] +pub async fn pkg_metadata( + state: tauri::State<'_, AppState>, + pkg: String, +) -> Wire<(index::PackageMeta, index::Freshness)> { + let name = PkgName::parse(&pkg)?; + // Takes the directory, not a `Store`: `index::metadata` opens one for each synchronous stretch + // and drops it before the PyPI call, so its future stays `Send`. + Ok(index::metadata(&state.app_data, &name, jiff::Timestamp::now()).await?) +} + +/// Re-download the PEP 691 name index. +/// +/// # Errors +/// `PD-NET-010` when the index cannot be fetched; the previously cached index stays searchable. +#[tauri::command] +pub async fn index_refresh(state: tauri::State<'_, AppState>) -> Wire { + let report = index::refresh(&state.app_data, jiff::Timestamp::now()).await?; + // Otherwise a refresh reports thousands of new projects and search cannot find any of them. + state.invalidate_index(); + Ok(report) +} + /// What `plan_execute` returns: the summary, plus the snapshot it took first. /// /// The snapshot id is not in `ExecutionSummary` because the CLI prints it *before* execution diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index fedbed5..8c6f90a 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -44,6 +44,9 @@ pub fn run() { commands::plan_decide, commands::plan_execute, commands::plan_cancel, + commands::index_search, + commands::index_refresh, + commands::pkg_metadata, commands::settings_get, commands::settings_set, commands::legal_consent_get, diff --git a/src-tauri/src/state.rs b/src-tauri/src/state.rs index e35222a..34d3087 100644 --- a/src-tauri/src/state.rs +++ b/src-tauri/src/state.rs @@ -17,6 +17,7 @@ use std::path::PathBuf; use pipdock_core::errors::{Code, PdError, Result}; use pipdock_core::flow::UpdateFlow; +use pipdock_core::index::NameIndex; use pipdock_core::store::Store; use tokio_util::sync::CancellationToken; @@ -46,12 +47,41 @@ impl PlanSlot { } } +/// How far the in-memory name index has got. +/// +/// **Measured on the real 858k-project index: `NameIndex::load` costs 613 ms** — twelve times the +/// entire per-keystroke budget, and SP-3 had already ruled out the alternative (scanning SQLite +/// per keystroke measured 218 ms against 50 ms). So it is loaded once and held, and the only +/// question was when to pay for it. +/// +/// The answer is on demand, with this state as the honest account of it: a user who never opens +/// Search never pays, and one who does gets the field immediately with a note rather than a +/// frozen window. Typing two or three characters takes about as long as the load, so in practice +/// the note is rarely seen — but `index_search` must **never** wait for it, which is what having +/// a state rather than an `Option` and a lock enforces. +pub enum IndexSlot { + /// Not asked for yet. + Cold, + /// A load is running. Searches answer `Warming` rather than blocking. + Warming, + /// Ready to search. + Ready(Box), + /// The load failed — most often because the index has never been refreshed. + Failed(String), +} + /// Everything a command may need that outlives one call. pub struct AppState { /// `%LOCALAPPDATA%\PipDock`. pub app_data: PathBuf, /// Settings, pins, recents and the package index. pub store: tokio::sync::Mutex, + /// The 858k-name search index, once something has asked for it. + /// + /// A `std::sync::Mutex` rather than tokio's: it is only ever held to read or replace the slot, + /// 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, /// The plan being driven across several IPC calls. pub plan: tokio::sync::Mutex, /// The token for whatever engine work is in flight. @@ -73,11 +103,71 @@ impl AppState { Ok(Self { app_data, store: tokio::sync::Mutex::new(store), + index: std::sync::Mutex::new(IndexSlot::Cold), plan: tokio::sync::Mutex::new(PlanSlot::Idle), cancel: std::sync::Mutex::new(None), }) } + /// Claim the index slot for a load, if one is not already done or running. + /// + /// Returns `true` when the caller is now responsible for loading. Idempotent, so calling it on + /// every Search render is harmless — which is what lets the screen ask without coordinating. + pub fn begin_index_load(&self) -> bool { + let Ok(mut slot) = self.index.lock() else { + return false; + }; + if matches!(*slot, IndexSlot::Cold | IndexSlot::Failed(_)) { + *slot = IndexSlot::Warming; + return true; + } + false + } + + /// Publish the result of a load. + pub fn finish_index_load(&self, loaded: pipdock_core::Result) { + if let Ok(mut slot) = self.index.lock() { + *slot = match loaded { + Ok(index) => IndexSlot::Ready(Box::new(index)), + Err(e) => IndexSlot::Failed(e.message), + }; + } + } + + /// Search, without ever waiting for a load. + /// + /// `None` means "not ready" — the caller reports that as a state rather than an error, because + /// warming is not a failure and a spinner that says so is better than a stall. + pub fn search_index(&self, query: &str, limit: usize) -> Option> { + let slot = self.index.lock().ok()?; + match &*slot { + IndexSlot::Ready(index) => Some(index.search(query, limit)), + IndexSlot::Cold | IndexSlot::Warming | IndexSlot::Failed(_) => None, + } + } + + /// Why the index could not be loaded, when that is the state it is in. + /// + /// Reported as a state on the search result rather than as a command error: "the index has + /// never been refreshed" is an action the user can take, and an error row would tell them + /// something went wrong instead. + pub fn index_failure(&self) -> Option { + match &*self.index.lock().ok()? { + IndexSlot::Failed(why) => Some(why.clone()), + IndexSlot::Cold | IndexSlot::Warming | IndexSlot::Ready(_) => None, + } + } + + /// Drop the loaded index, so the next search reloads it. + /// + /// Called after `index_refresh`: leaving the old names in memory would mean a refresh that + /// reports thousands of new projects and a search that cannot find any of them. + pub fn invalidate_index(&self) { + if let Ok(mut slot) = self.index.lock() { + *slot = IndexSlot::Cold; + } + } + /// Claim the plan slot for engine work, returning whatever flow was waiting there. /// /// # Errors diff --git a/ui/src/ipc/generated.ts b/ui/src/ipc/generated.ts index 61715a9..1c82ee9 100644 --- a/ui/src/ipc/generated.ts +++ b/ui/src/ipc/generated.ts @@ -211,6 +211,12 @@ export type FlowStep = | { report: ResolutionReport; step: 'roundsExhausted' } | { reason: NothingReason; step: 'nothing' }; +/** How fresh a metadata answer is, so the UI can badge it (UI-SPEC §7). */ +export type Freshness = + | 'fresh' + | 'cached' + | 'stale'; + /** * What the uninstall guard found. * @@ -399,6 +405,16 @@ export interface PyEnv { source: EnvSource; } +/** What a refresh did. */ +export interface RefreshReport { + /** How long the whole refresh took. */ + elapsedMs: number; + /** Projects ingested. */ + projects: number; + /** Bytes received on the wire. */ + wireBytes: number; +} + /** * The normalized dry-run result. * diff --git a/ui/src/ipc/index.ts b/ui/src/ipc/index.ts index 9e4f8b7..c5e3d25 100644 --- a/ui/src/ipc/index.ts +++ b/ui/src/ipc/index.ts @@ -17,15 +17,19 @@ import { listen, type UnlistenFn } from '@tauri-apps/api/event' import type { Decision, Dist, + Freshness, + Hit, EngineId, EnvSource, ExecutionSummary, FlowStep, Intent, OutdatedDist, + PackageMeta, Pin, ProgressEvent, PyEnv, + RefreshReport, SnapshotMeta, } from './generated' @@ -183,6 +187,37 @@ export const pinAdd = (envHash: string, pin: Pin): Promise => export const pinRemove = (envHash: string, pkg: string): Promise => invoke('pin_remove', { envHash, pkg }) +/** + * What `indexSearch` resolves to. + * + * `ready` is separate from an empty `hits` because "no such package" and "the index is still + * loading" are different answers. Loading 858k names costs ~613 ms, and telling someone their + * package does not exist for that long would be a lie. + */ +export interface SearchResults { + hits: Hit[] + ready: boolean + /** Set when the index cannot be loaded at all — usually "never refreshed". */ + unavailable?: string +} + +/** + * Fuzzy search the local name index. Safe to call on every keystroke. + * + * Never blocks on the index load: a search that arrives first comes back `ready: false` and the + * screen says so. SP-3 ruled out the alternative — scanning SQLite per keystroke measured 218 ms + * against a 50 ms budget. + */ +export const indexSearch = (query: string, limit: number): Promise => + invoke('index_search', { query, limit }) + +/** Cached PyPI metadata for the details panel, with how fresh it is. */ +export const pkgMetadata = (pkg: string): Promise<[PackageMeta, Freshness]> => + invoke('pkg_metadata', { pkg }) + +/** Re-download the PEP 691 name index. The previous index stays searchable if this fails. */ +export const indexRefresh = (): Promise => invoke('index_refresh') + /** What `planExecute` resolves to: the summary, and the snapshot taken before anything ran. */ export interface ExecutionOutcome { summary: ExecutionSummary