Files

T

Edison Jwa 01a4a9ed28 docs: add README files to 9 crates and update verification plan (TODO-030,036)

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.

2026-06-11 11:09:12 +09:00

2.3 KiB

Raw Permalink Blame History

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 calls chanora_resolver::ChanoraResolver::resolve_client_address().
On success, the result is stored if its generation is still current.
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.

2.3 KiB Raw Permalink Blame History