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.
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 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
|
|
|
|
1. Flutter typing triggers `prefetch_server(host)` via the bridge.
|
|
2. `ServerPrefetcher::prefetch()` normalizes the host, bumps the generation, and spawns a fire-and-forget tokio task that calls `chanora_resolver::ChanoraResolver::resolve_client_address()`.
|
|
3. On success, the result is stored if its generation is still current.
|
|
4. When `chanora_core::connect()` is called, it checks `fresh_match(host)`. If a fresh (non-expired) entry matches, it's used as the `resolved_address` in `ConnectConfig`, 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 cache
|
|
- `prefetch(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 generation
|
|
- `store_success_for_test(generation, host, addr, instant)` — inject a result
|
|
- `latest_generation_for_test()` — read current generation
|
|
- `fail_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.
|