Skip to content

MST/2 reader: conditional requests and the spec 13 §6 link metrics (with separate phase timings) #59

Description

@Ivanbeethoven

Context

The MST/2 client is functionally complete for reads (resolve → hydrate → pin →
mount) but it is blind in two ways that matter operationally:

  1. 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.
  2. 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

  1. 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.
  2. 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.
  3. Phase timings reported separately: T_mount, T_first_useful,
    T_metadata_complete, T_content_complete, T_durable_complete.
  4. 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions