feat(app): hold the name index in memory, and warm it on demand

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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-05 18:50:23 +07:00
1 parent 02c8d13d59
commit 3d1e13bbbb
12 files changed
+324 -11

No files matched your search

+2 -4
View File
@@ -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<Exit> {
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<Exit
/// `PD-PKG-002` when PyPI does not know the name; `PD-NET-001` when it is neither cached nor
/// reachable.
pub async fn info(opts: &GlobalOpts, pkg: &str) -> Result<Exit> {
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!(
+2
View File
@@ -43,6 +43,8 @@ const SCHEMA_TYPES: &[&str] = &[
"SnapshotMeta",
"Hit",
"PackageMeta",
"Freshness",
"RefreshReport",
"ProgressEvent",
"FlowStep",
"Decision",
@@ -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"
}
@@ -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"
}
@@ -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
+15 -6
View File
@@ -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<RefreshReport> {
pub async fn refresh(app_data: &std::path::Path, now: jiff::Timestamp) -> Result<RefreshReport> {
let started = std::time::Instant::now();
let client = http_client()?;
@@ -319,7 +320,11 @@ pub async fn refresh(store: &Store, now: jiff::Timestamp) -> Result<RefreshRepor
.map(|name| (crate::model::normalize_name(name), name.to_owned()))
.collect();
ingest(store, &rows)?;
// Opened only now, after the download: the ingest is synchronous, so the handle never spans an
// await. Holding one open across a multi-second PyPI transfer would block every other command
// that wanted the store, for no benefit.
let store = Store::open(app_data)?;
ingest(&store, &rows)?;
store.set(KEY_LAST_REFRESH, &now.to_string())?;
Ok(RefreshReport {
@@ -421,11 +426,15 @@ pub enum Freshness {
/// `PD-NET-001` when the package is not cached **and** the network is unreachable; `PD-PKG-002`
/// when PyPI does not know the name.
pub async fn metadata(
store: &Store,
app_data: &std::path::Path,
name: &PkgName,
now: jiff::Timestamp,
) -> 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),
},
+4
View File
@@ -272,6 +272,8 @@ pub fn json_schema(type_name: &str) -> Result<serde_json::Value> {
"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",
+95
View File
@@ -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<index::Hit>,
/// 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<String>,
}
/// 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<SearchResults> {
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<index::RefreshReport> {
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
+3
View File
@@ -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,
+90
View File
@@ -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<NameIndex>` 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<NameIndex>),
/// 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<Store>,
/// 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<IndexSlot>,
/// The plan being driven across several IPC calls.
pub plan: tokio::sync::Mutex<PlanSlot>,
/// 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<NameIndex>) {
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<Vec<pipdock_core::index::Hit>> {
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<String> {
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
+16
View File
@@ -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.
*
+35
View File
@@ -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<void> =>
export const pinRemove = (envHash: string, pkg: string): Promise<boolean> =>
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<SearchResults> =>
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<RefreshReport> => invoke('index_refresh')
/** What `planExecute` resolves to: the summary, and the snapshot taken before anything ran. */
export interface ExecutionOutcome {
summary: ExecutionSummary