diff --git a/docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md b/docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md index 7e3359a..ebbcf4a 100644 --- a/docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md +++ b/docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md @@ -2,9 +2,9 @@ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -**Goal:** Move server-resolution prefetch policy from `chanora_core` into a focused crate named `chanora_server_prefetch` without changing Flutter APIs, resolver behavior, protocol dialing behavior, or Android connect UX. +**Goal:** Move server-resolution prefetch policy from `chanora_core` into a focused crate named `chanora_prefetch` without changing Flutter APIs, resolver behavior, protocol dialing behavior, or Android connect UX. -**Architecture:** Add `crates/chanora_server_prefetch` as a workspace member. The new crate owns normalization, single-entry TTL cache, generation rejection, resolver-backed async warming, and fresh exact-match lookup. `chanora_core` keeps the trust boundary for `ConnectConfig.resolved_address`, using the prefetcher only to populate one-time dial config while keeping stored/reconnect config sanitized. +**Architecture:** Add `crates/chanora_prefetch` as a workspace member. The new crate owns normalization, single-entry TTL cache, generation rejection, resolver-backed async warming, and fresh exact-match lookup. `chanora_core` keeps the trust boundary for `ConnectConfig.resolved_address`, using the prefetcher only to populate one-time dial config while keeping stored/reconnect config sanitized. **Tech Stack:** Rust workspace, `tokio`, `tracing`, `thiserror`, `chanora_resolver`, `chanora_core`, `chanora_protocol`, Flutter Android smoke via ADB. @@ -12,28 +12,28 @@ ## File Structure -- Create `crates/chanora_server_prefetch/Cargo.toml`: package metadata and dependencies. -- Create `crates/chanora_server_prefetch/src/lib.rs`: public `ServerPrefetcher`, public `ServerPrefetchError`, internal cache entry/state, resolver-backed prefetch logic, and unit tests. -- Modify `Cargo.toml`: add `crates/chanora_server_prefetch` to workspace members and update the workspace layout comment. -- Modify `core/chanora_core/Cargo.toml`: replace the direct `chanora_resolver` dependency with `chanora_server_prefetch`. +- Create `crates/chanora_prefetch/Cargo.toml`: package metadata and dependencies. +- Create `crates/chanora_prefetch/src/lib.rs`: public `ServerPrefetcher`, public `ServerPrefetchError`, internal cache entry/state, resolver-backed prefetch logic, and unit tests. +- Modify `Cargo.toml`: add `crates/chanora_prefetch` to workspace members and update the workspace layout comment. +- Modify `core/chanora_core/Cargo.toml`: replace the direct `chanora_resolver` dependency with `chanora_prefetch`. - Modify `core/chanora_core/src/lib.rs`: remove private prefetch cache/resolver helpers, add `ServerPrefetcher`, delegate `prefetch_server_resolution`, and keep connect config sanitization tests. - Modify `Cargo.lock`: generated by `cargo test`/`cargo check` after adding the crate. --- -### Task 1: Add `chanora_server_prefetch` Crate With Cache Policy Tests +### Task 1: Add `chanora_prefetch` Crate With Cache Policy Tests **Files:** - Modify: `Cargo.toml` -- Create: `crates/chanora_server_prefetch/Cargo.toml` -- Create: `crates/chanora_server_prefetch/src/lib.rs` +- Create: `crates/chanora_prefetch/Cargo.toml` +- Create: `crates/chanora_prefetch/src/lib.rs` - [ ] **Step 1: Add the workspace member and package files** In top-level `Cargo.toml`, update the layout comment and members: ```toml -# crates/chanora_server_prefetch — server-resolution prefetch cache/policy +# crates/chanora_prefetch — server-resolution prefetch cache/policy # crates/chanora_bridge/ — Flutter/Rust typed DTOs + glue ``` @@ -45,17 +45,17 @@ members = [ "crates/chanora_audio", "crates/chanora_storage", "crates/chanora_diagnostics", - "crates/chanora_server_prefetch", + "crates/chanora_prefetch", "crates/chanora_bridge", "crates/chanora_resolver", ] ``` -Create `crates/chanora_server_prefetch/Cargo.toml`: +Create `crates/chanora_prefetch/Cargo.toml`: ```toml [package] -name = "chanora_server_prefetch" +name = "chanora_prefetch" description = "Chanora — server-address prefetch cache and policy built on chanora_resolver." version.workspace = true edition.workspace = true @@ -75,7 +75,7 @@ tokio = { version = "1", features = ["sync", "rt", "macros"] } test-support = [] ``` -Create `crates/chanora_server_prefetch/src/lib.rs` with the initial crate implementation and tests: +Create `crates/chanora_prefetch/src/lib.rs` with the initial crate implementation and tests: ```rust //! Server-address prefetch cache and policy for Chanora. @@ -189,13 +189,13 @@ impl ServerPrefetcher { }; let cache = self.cache.clone(); tokio::spawn(async move { - info!(target: "chanora_server_prefetch", host = %normalized, "resolution prefetch started"); + info!(target: "chanora_prefetch", host = %normalized, "resolution prefetch started"); let result = resolve_socket(&normalized).await; let mut guard = cache.lock().await; match result { Ok(addr) => { info!( - target: "chanora_server_prefetch", + target: "chanora_prefetch", host = %normalized, resolved = %addr, "resolution prefetch result" @@ -204,7 +204,7 @@ impl ServerPrefetcher { } Err(err) => { warn!( - target: "chanora_server_prefetch", + target: "chanora_prefetch", host = %normalized, error = %err, "resolution prefetch failed" @@ -224,7 +224,7 @@ impl ServerPrefetcher { match resolved { Some(addr) => { info!( - target: "chanora_server_prefetch", + target: "chanora_prefetch", host = %host, resolved = %addr, "connect using prefetched resolution" @@ -232,7 +232,7 @@ impl ServerPrefetcher { Some(addr) } None => { - info!(target: "chanora_server_prefetch", host = %host, "connect prefetch miss or stale"); + info!(target: "chanora_prefetch", host = %host, "connect prefetch miss or stale"); None } } @@ -350,14 +350,14 @@ mod tests { - [ ] **Step 2: Run new crate tests** -Run: `cargo test -p chanora_server_prefetch --lib` +Run: `cargo test -p chanora_prefetch --lib` Expected: the new crate compiles and all 5 tests pass. - [ ] **Step 3: Commit Task 1** ```bash -git add Cargo.toml Cargo.lock crates/chanora_server_prefetch +git add Cargo.toml Cargo.lock crates/chanora_prefetch git commit -m "feat(prefetch): add server prefetch crate" ``` @@ -380,7 +380,7 @@ chanora_resolver = { path = "../../crates/chanora_resolver" } with: ```toml -chanora_server_prefetch = { path = "../../crates/chanora_server_prefetch" } +chanora_prefetch = { path = "../../crates/chanora_prefetch" } ``` - [ ] **Step 2: Remove private prefetch cache implementation from core** @@ -406,7 +406,7 @@ async fn resolve_prefetch_socket(host: &str) -> Result