Edison Jwa
01a4a9ed28
Add purpose, architecture, and public API summary to each crate README following chanora_resolver pattern. Update verification master plan with new evidence sources and entry/exit criteria.
chanora_prefetch
Server-address prefetch cache and policy. Owns speculative server-resolution warming so that when the user presses Connect, a fresh DNS/SRV result may already be available, reducing perceived join latency.
Architecture
Cache model
ServerPrefetchCache holds at most one entry — the latest prefetched resolution. A generation counter prevents stale async completions from overwriting newer results. TTL is 120 seconds.
Flow
- Flutter typing triggers
prefetch_server(host)via the bridge. ServerPrefetcher::prefetch()normalizes the host, bumps the generation, and spawns a fire-and-forget tokio task that callschanora_resolver::ChanoraResolver::resolve_client_address().- On success, the result is stored if its generation is still current.
- When
chanora_core::connect()is called, it checksfresh_match(host). If a fresh (non-expired) entry matches, it's used as theresolved_addressinConnectConfig, bypassing a second DNS round trip.
Generation guard
If the user types another host while the first prefetch is in flight, the generation advances. The slower completion is discarded because its generation no longer matches. The most recent entry always wins.
Public API Summary
Types
| Type | Role |
|---|---|
ServerPrefetcher |
Public API: schedule prefetches, query fresh matches |
ServerPrefetchError |
ResolverInit, Resolution, InvalidSocketAddress |
Key methods on ServerPrefetcher
new()— construct with empty cacheprefetch(host)— schedule a fire-and-forget resolution (async). Only reports synchronous setup failures; DNS failures are logged.fresh_match(host)→Option<SocketAddr>— return a cached address if it matches and is within TTL (async)
Test-only methods (behind cfg(test) or feature = "test-support")
begin_for_test(host)— bump generationstore_success_for_test(generation, host, addr, instant)— inject a resultlatest_generation_for_test()— read current generationfail_next_prefetch_setup_for_test(error)— inject a setup failure
Design notes
- Blank/whitespace-only hosts are silently skipped.
- Hosts are normalized to lowercase trimmed strings before matching.
- A fresh entry remains usable while a newer prefetch is in flight; stale completions are rejected by the generation guard.