Context
The MST/2 client is functionally complete for reads (resolve → hydrate → pin →
mount) but it is blind in two ways that matter operationally:
- No conditional requests. Every read is unconditional. The server sends a
strong ETag and private, no-cache, no-transform today, and spec 04 §10
requires lease/auth checks to happen before a 304, plus a defined
CURSOR_STALE retry — the client ignores all of it.
- No link metrics. Transport retries and received bytes are counted
(Mst2Client::retry_count, received_bytes, units_fetched), and the
incremental sync reports its three counters — but there is no per-operation
latency, no negative-proof count, no cache hit/miss accounting, no
distinction between bytes that were useful and bytes that were retried.
Spec 13 §6 names the metrics that must exist per link, and §6 requires the
phases T_mount, T_first_useful, T_metadata_complete, T_content_complete,
T_durable_complete to be reported separately — collapsing them into one
"mount time" number hides exactly the failures that matter (a fast mount that
never completes hydration looks better than a slow correct one).
Scope
- Conditional requests (spec 04 §10):
- store the ETag with cached metadata/content and send
If-None-Match;
- treat
304 as "unchanged" only after the lease/permission path was
validated server-side — do not reimplement auth locally as a shortcut;
- handle
CURSOR_STALE by restarting that directory enumeration rather than
silently skipping entries.
- Metrics (spec 13 §6), per operation and aggregated:
lookup/read latency percentiles (p50/p95/p99);
- proven-negative count (a proven absence is a success, not an error);
- metadata cache hit/miss, content cache hit/miss;
- single-flight waiters and how long they waited;
- bytes: useful, hydrated, prefetch, retried — as separate counters;
verify_fail and missing page/chunk counters.
- Phase timings reported separately:
T_mount, T_first_useful,
T_metadata_complete, T_content_complete, T_durable_complete.
- An integrity failure must never be recorded as a fast success — a run that
ends in a verification error must not look better in the metrics than a run
that completed.
Acceptance
- A test where a second identical read produces a conditional request and the
client handles 304 without re-downloading (asserted by bytes received).
- A test where a cursor is invalidated mid-enumeration (
CURSOR_STALE) and the
client restarts the enumeration and still returns the complete, correct set.
- Metrics output for the three paths (small file, large file by range, incremental
sync) showing the counters separated, not summed.
- A test asserting that a
verify_fail run does not publish a T_durable_complete
value (the phase must be missing/errored, not fast).
References
- Spec 04 §10 (caching, conditional requests, retries), spec 13 §6 (metrics)
src/snapshot/client.rs, src/snapshot/reader.rs, src/snapshot/coordinator.rs
Context
The MST/2 client is functionally complete for reads (resolve → hydrate → pin →
mount) but it is blind in two ways that matter operationally:
strong ETag and
private, no-cache, no-transformtoday, and spec 04 §10requires lease/auth checks to happen before a 304, plus a defined
CURSOR_STALEretry — the client ignores all of it.(
Mst2Client::retry_count,received_bytes,units_fetched), and theincremental sync reports its three counters — but there is no per-operation
latency, no negative-proof count, no cache hit/miss accounting, no
distinction between bytes that were useful and bytes that were retried.
Spec 13 §6 names the metrics that must exist per link, and §6 requires the
phases
T_mount,T_first_useful,T_metadata_complete,T_content_complete,T_durable_completeto be reported separately — collapsing them into one"mount time" number hides exactly the failures that matter (a fast mount that
never completes hydration looks better than a slow correct one).
Scope
If-None-Match;304as "unchanged" only after the lease/permission path wasvalidated server-side — do not reimplement auth locally as a shortcut;
CURSOR_STALEby restarting that directory enumeration rather thansilently skipping entries.
lookup/readlatency percentiles (p50/p95/p99);verify_failand missing page/chunk counters.T_mount,T_first_useful,T_metadata_complete,T_content_complete,T_durable_complete.ends in a verification error must not look better in the metrics than a run
that completed.
Acceptance
client handles
304without re-downloading (asserted by bytes received).CURSOR_STALE) and theclient restarts the enumeration and still returns the complete, correct set.
sync) showing the counters separated, not summed.
verify_failrun does not publish aT_durable_completevalue (the phase must be missing/errored, not fast).
References
src/snapshot/client.rs,src/snapshot/reader.rs,src/snapshot/coordinator.rs