edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(prefetch): update rename implementation plan

Browse Source
This commit is contained in:
Edison Jwa
2026-06-02 13:34:12 +09:00
parent 92c09aece3
commit d19501ec66
1 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md
+30 -30
View File
@@ -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<std::net::SocketAddr, Cor
Add this import near the other crate imports:
```rust
use chanora_server_prefetch::ServerPrefetcher;
use chanora_prefetch::ServerPrefetcher;
```
- [ ] **Step 3: Replace the session field and constructor initialization**
@@ -478,7 +478,7 @@ connect_config_without_prefetched_resolution_clears_only_resolved_address
connect_config_preparation_keeps_prefetched_address_out_of_stored_config
```
Replace any direct access to `session.resolution_prefetch` with calls to public test-support methods on `ServerPrefetcher`. In `crates/chanora_server_prefetch/src/lib.rs`, keep these methods gated with `#[cfg(any(test, feature = "test-support"))]`:
Replace any direct access to `session.resolution_prefetch` with calls to public test-support methods on `ServerPrefetcher`. In `crates/chanora_prefetch/src/lib.rs`, keep these methods gated with `#[cfg(any(test, feature = "test-support"))]`:
```rust
#[cfg(any(test, feature = "test-support"))]
@@ -502,7 +502,7 @@ Enable the feature for `chanora_core` tests by adding this dev-dependency in `co
```toml
[dev-dependencies]
chanora_server_prefetch = { path = "../../crates/chanora_server_prefetch", features = ["test-support"] }
chanora_prefetch = { path = "../../crates/chanora_prefetch", features = ["test-support"] }
```
Then core test setup should look like:
@@ -524,7 +524,7 @@ Expected: all core lib tests pass.
- [ ] **Step 7: Commit Task 2**
```bash
git add Cargo.toml Cargo.lock core/chanora_core/Cargo.toml core/chanora_core/src/lib.rs crates/chanora_server_prefetch
git add Cargo.toml Cargo.lock core/chanora_core/Cargo.toml core/chanora_core/src/lib.rs crates/chanora_prefetch
git commit -m "refactor(core): use server prefetch crate"
```
@@ -538,7 +538,7 @@ git commit -m "refactor(core): use server prefetch crate"
- [ ] **Step 1: Remove core tests moved to the prefetch crate**
Delete these tests from `core/chanora_core/src/lib.rs` because they now belong in `chanora_server_prefetch`:
Delete these tests from `core/chanora_core/src/lib.rs` because they now belong in `chanora_prefetch`:
```rust
resolution_prefetch_cache_returns_fresh_exact_match
@@ -564,7 +564,7 @@ Expected: no diff. If there is a diff, revert only accidental protocol edits by
- [ ] **Step 3: Run combined Rust tests**
Run: `cargo test -p chanora_server_prefetch -p chanora_core -p chanora_protocol --lib`
Run: `cargo test -p chanora_prefetch -p chanora_core -p chanora_protocol --lib`
Expected: all tests pass.
@@ -584,7 +584,7 @@ git commit -m "test(core): keep prefetch tests at crate boundary"
- [ ] **Step 1: Run full focused Rust verification**
Run: `cargo test -p chanora_resolver -p chanora_server_prefetch -p chanora_protocol -p chanora_core --lib`
Run: `cargo test -p chanora_resolver -p chanora_prefetch -p chanora_protocol -p chanora_core --lib`
Expected: all tests pass.
@@ -684,6 +684,6 @@ Expected: only unrelated untracked `config.json` remains, unless the user has ad
## Self-Review
- Spec coverage: the plan adds `chanora_server_prefetch`, moves cache policy and resolver-backed warming there, keeps core as trust boundary, preserves Flutter/protocol behavior, and includes Android connect smoke verification.
- Spec coverage: the plan adds `chanora_prefetch`, moves cache policy and resolver-backed warming there, keeps core as trust boundary, preserves Flutter/protocol behavior, and includes Android connect smoke verification.
- Placeholder scan: no `TBD`, `TODO`, or unspecified edge handling remains.
- Type consistency: the plan uses `ServerPrefetcher`, `ServerPrefetchError`, `prefetch`, and `fresh_match` consistently across crate and core tasks.