refReplicaWindow property

  1. @visibleForTesting
Duration refReplicaWindow
getter/setter pair

How long a landed write out-ranks a ref read that contradicts it.

GitHub serves ref reads from replicas and promises no read-after-write consistency, so for a short time after a save the ref can still name the commit the save replaced. Inside this window that answer is treated as stale; outside it, the ref is believed again — which is what keeps a genuine force-push rewind from being pinned out of sight forever.

Measured, 2026-09-17, against a live repository over 85 write cycles (wonecodeprpc13_replica_lag_live_test.dart, which re-measures this on every live run). Each figure is the elapsed time at which a read was issued that came back truthful, so a round trip to api.github.com is excluded rather than counted as lag:

  • p50, p90, p99 — 0 ms. A read issued the instant the write was accepted was almost always already truthful.
  • 2 of 85 writes were answered stale at all.
  • The whole observed tail was under one second (293 ms and 902 ms).
  • A second client, on its own connection, saw the same rates and the same tail — so the lag is a property of the service at that moment and not of which replica a connection is pinned to.

Measured again under load, 2026-09-29, because those 85 cycles were all taken in a repository nothing else was writing to, and the defect the window exists for was met while several writers were. Four runs of 85 cycles each, the same day, in one repository — three in a row, and a fourth quiet one some hours later:

concurrent writers their commits stale at all max
0 — 0 of 85 0 ms
2 102 0 of 85 0 ms
4 154 0 of 85 0 ms
0 — 0 of 85 0 ms

The second client's arm matched in all four (one read at 1 ms in the first three, and one in the fourth). No writer was refused, so the load ran for the whole of each measurement. The writers committed to branches of their own; the timed branch has one writer by construction, since the authority covers our own write.

What that settles and what it does not. Load in the repository did not produce a tail: 256 concurrent commits moved nothing. It does not show that load cannot lengthen a tail, because on that day there was no tail to lengthen — the quiet arms saw none either. Across all 425 measured cycles the longest read-back remains the 902 ms of the first run, so the floor stands where it was and the window stays at ten seconds.

The distribution does not, by itself, set the number, and that is the substantive finding: it gives a floor, and the rest is the shape of the costs. Too short and an earlier defect returns — a head silently retracted, which is a correctness bug — and 425 writes are a sample, not a bound on what the service does. Too long costs remarkably little, because _authoritative refuses exactly two answers: the commit our own write superseded, and "no branch" after our own create. A rewind is therefore hidden only when the force-push lands precisely back on the commit we just replaced, and only from the client that made that write.

So the band is comfortably past a sub-second tail, comfortably inside the shortest poll interval a sync loop uses, one minute — the upper bound being what makes "a rewind is noticed on the next poll" true. Ten seconds is eleven times the measured tail and a sixth of that interval. Both bounds are asserted: the floor by a live measurement, the ceiling by a test that needs no network.

Implementation

@visibleForTesting
Duration refReplicaWindow = const Duration(seconds: 10);