24 KiB
test_expiry_window
Type: Harness API (may include self-tests). Source contract: test_expiry_window.h.
Use when
An overlay samples product behavior at a cutoff derived from a served
expiry: a temporary link's or free code's Copy/Share that must refuse inside
the product's share cutoff before the served expiry, a frozen Share that must
close at its own deadline, a renderer with its own deadline, a natural-expiry
wait, or a clock resynchronization. Test::FreezeExpiryWindow binds a
positive served expiry to the exact live owner, generation and link, with its
receipt and a fresh server-clock reading, and freezes one immutable window
per output. Test::ExpiryBoundaryWatch polls that window to its boundary, and
Test::PlanExpirySample re-validates the premise before an action. Every
premise refuses by name before anything can be scheduled.
The module reads no product state: the overlay supplies both sides. For animation frames use test_animation_clock; for paint timing, test_post_paint; for a server rate deadline on fixture writes, test_fixture_transaction.
Preconditions and limits
- Two sources, never copied into each other.
Test::ExpiryObservationis the oracle side, recorded where the served value arrives (an RPC reply hook):owner,generation,link,servedExpires(unixtime seconds) andreceipt = Test::ReadServerClock().Test::ExpiryReadingis the product side, read at each use through the product's own typed seam:owner, the caller's currentgeneration,link,productExpiresand a freshclock = Test::ReadServerClock(). A validation compares a product value with a served one; filling the reading from the observation compares a field with itself (an earlier overlay's clock-update control passed as0==0; see failure diagnosis). A caller without a typed product seam cannot freeze a window. - No default satisfies validation. Every number is a
std::optional, the owner aQPointer<QObject>and the link aQString, and absence refuses before any equality, so two absent values (whichstd::optionalcompares equal) or two zeros never establish a premise. - The owner is the exact object holding the served value (the box), not an
output the product closes at its cutoff (a Share box). Identity is the
QPointer: it is null once that object is destroyed, and a new object at the same address never revives it. Main thread only. - Feed
productExpiresfrom a value the product holds until the link changes (the box's current link expiry), not a frozen copy it clears at its own cutoff. The product's monotonic deadline (for exampleLinkExpiry::deadlineinpeer_qr_box.cpp, a receipt-basedcrl::now()time) is never an input: the oracle stays independent of it. generationis the caller's counter, for example the count of served responses. Any present value, 0 included, is explicit; onlystd::nulloptis absent.- Links compare exactly and are never printed: details read
same,otherorabsent.ExpiryWindowArgs::labelis public text naming the window, never a link or a secret. - Times are server-shifted wall milliseconds since the epoch.
Test::ReadServerClock()addsbase::unixtime's whole-second shift, taken asbase::unixtime::now()minustime(nullptr)(the clock that shift is added to), to oneQDateTime::currentMSecsSinceEpoch()read, so Qt's millisecond rounding or tick granularity never moves a reading by a second. It reads the shift between two equaltime(nullptr)reads, up to three times when that second rolls over, and is absent if it never settles. Its fraction comes from the local clock, a resynchronization moves it by whole seconds, and it is never a product countdown display value. The module never callsbase::unixtime::update(). - A window's cutoff is
servedExpires * 1000 - cutoffLead. ChoosecutoffLeadas the earliest moment the product may react: 3000 for the product'skShareCutoff; a few hundred ms for a natural expiry the product acts on at the expiry itself, with a watch offset past it. Freezing requires the fresh clock to be at leastminimumAheadms before the cutoff (inclusive) and strictly before it, so actions above the cutoff have time. - No rows of its own: callers
Test::Checkthedetailstext. Numbers are ordinary integers; it is not a helper converted toTest::RequestTelemetryNumbers(). - The overlay's
untilpolls on the runner's 50 ms tick, so a boundary is observed up to one tick late (more on a busy event loop), andlateMsreports it. The stage timeout andTDESKTOP_TEST_WATCHDOGmust cover the whole wait.
Minimal use
An overlay sketch against the real API; no translation unit compiles it (the
self-test compiles the API over literal values). box, url and expires
stand for the reply hook's values, and CurrentReading() for the overlay's
typed product seam plus Test::ReadServerClock().
struct Timing {
Test::ExpiryObservation served;
std::shared_ptr<Test::ExpiryBoundaryWatch> share;
uint64 generation = 0;
QString gate;
};
const auto timing = std::make_shared<Timing>();
// Reply hook, where the served response arrives:
timing->served = {
.owner = box,
.generation = ++timing->generation,
.link = url,
.servedExpires = expires,
.receipt = Test::ReadServerClock(),
};
runner->add({
.name = u"share expiry window: freeze"_q,
.then = [=] {
const auto freeze = Test::FreezeExpiryWindow({
.label = u"share"_q,
.cutoffLead = crl::time(3000),
.minimumAhead = crl::time(4000),
}, timing->served, CurrentReading());
Test::Check(
freeze.frozen(),
u"fixture gate: share expiry window frozen"_q,
freeze.details);
timing->share = std::make_shared<Test::ExpiryBoundaryWatch>(
freeze,
crl::time(60));
if (!freeze.frozen()) {
timing->gate = u"fixture gate: share expiry premise refused"_q;
}
},
});
runner->addGated([=] { return timing->gate; }, [&] {
runner->add({
.name = u"share expiry window: boundary"_q,
.until = [=] {
return timing->share->poll(CurrentReading())
!= Test::ExpiryWatchState::Waiting;
},
.then = [=] {
const auto reached = (timing->share->state()
== Test::ExpiryWatchState::Reached);
Test::Check(
reached,
u"fixture gate: share premise held to the boundary"_q,
timing->share->details());
if (!reached) {
timing->gate = u"fixture gate: share boundary refused"_q;
return;
}
// Product assertions at the boundary.
},
.timeout = crl::time(90000),
});
});
A refused freeze sets the gate, so the boundary stage and every later stage
of the group are N/A instead of waiting on a refused premise
(gated groups). An action
above the cutoff first calls
Test::PlanExpirySample(*timing->share->window(), CurrentReading()) and
requires accepted() and an untilCutoffMs margin that covers the action.
A second output (a render, a natural-expiry wait) gets its own window and
watch; a refreshed served value freezes a new window, and existing windows
never change.
Readings and refusals
Three pure readings, each with a named refusal and a one-line details that
the caller prints on both verdicts:
Test::ExpiryFreezefromFreezeExpiryWindow(args, observation, current):windowis non-null exactly whenrefusalisnone, andfrozen()requires both. The window exposeslabel(),owner()(null once the owner is destroyed),generation(),link(),servedExpires(),receiptServerMs(),frozenServerMs(),cutoffLead()andcutoffServerMs().Test::ExpiryPlanfromPlanExpirySample(window, current):untilCutoffMsis present only on acceptance (accepted()), and iscutoffServerMs()minus the reading's clock. It may be at or below zero past the cutoff, so an action above the cutoff requires its own margin. A refused plan has no value, so nothing can be scheduled from it.Test::ExpiryBoundaryWatch:poll(current)returns the state (Waiting,Reached,Refused).refusal()isnoneunless the state isRefused, so decide bystate().window()is null when the watch was built from a refused freeze;boundaryServerMs()(cutoff plus offset) is present when a window exists;untilBoundaryMs()only while Waiting, from the last poll's clock; thenreachedServerMs(),polls(),confirmations()anddetails().
A frozen window proves that at the freeze reading the observed owner was
live and was the product's current owner, both generations and links were
present and equal, the served expiry and the receipt were present and
positive, the product's own expiry was present, positive and equal to the
served one, and the clock was positive and far enough before the cutoff. A
Reached watch adds that every poll before the cutoff (before the boundary,
for a negative offset) re-confirmed that premise, at least one did, and the
owner stayed the window's to the boundary. Neither proves product behavior
at the cutoff: that is the caller's sample. Every result defaults to
not-evaluated, which never accepts. A refusal is never a product PASS or
FAIL: it is a fixture gate, and the measurement it guarded is undecided.
| Name | Meaning | Where |
|---|---|---|
none |
Accepted. | Freeze, plan, watch. |
not-evaluated |
The default of every ExpiryFreeze and ExpiryPlan; never accepts. |
A default result; a watch built from one. |
owner-not-live |
The observed owner (freeze) or the window's owner (plan, watch) was never recorded or is destroyed. | Freeze, plan, watch at every poll. |
wrong-owner |
The reading's owner is another object or null. | Freeze, plan, watch at every poll. |
generation-absent |
Either side has none; a window always has one, so in a plan or a watch it is the reading's. | Freeze, plan, watch before stop. |
obsolete-generation |
The reading's generation differs. | Freeze, plan, watch before stop. |
link-absent |
Either side is empty; in a plan or a watch, the reading's. | Freeze, plan, watch before stop. |
wrong-link |
The reading's link differs. | Freeze, plan, watch before stop. |
served-expiry-absent |
The observation has no served expiry. | Freeze. |
served-expiry-not-positive |
The served expiry is 0 or negative. | Freeze. |
receipt-absent |
The observation has no receipt clock. | Freeze. |
receipt-not-positive |
The receipt clock is 0 or negative. | Freeze. |
product-expiry-absent |
The reading has no product expiry. | Freeze, plan, watch before stop. |
product-expiry-not-positive |
The product expiry is 0 or negative. | Freeze, plan, watch before stop. |
product-expiry-differs |
The product's value is not the served one (the window's, in a plan or a watch). | Freeze, plan, watch before stop. |
clock-absent |
The reading's fresh clock is absent. | Freeze, plan, watch at every poll. |
clock-not-positive |
The reading's fresh clock is 0 or negative. | Freeze, plan, watch at every poll. |
cutoff-not-ahead |
The fresh clock is not at least minimumAhead and strictly before the cutoff. |
Freeze. |
boundary-unconfirmed |
The watch reached stop before any poll confirmed the full premise. |
Watch. |
A watch built from a refused freeze is Refused at construction by that freeze's name, so every freeze-only name can also be a watch's.
First refusal, in order:
- Freeze: owner (
owner-not-live, thenwrong-owner), generation (generation-absent, thenobsolete-generation), link (link-absent, thenwrong-link), served expiry (absent, not positive), receipt (absent, not positive), product expiry (absent, not positive, differs from served), clock (absent, not positive), thencutoff-not-ahead. So a served and a product expiry both absent refuseserved-expiry-absent, both 0 refuseserved-expiry-not-positive, and a receipt and a clock both 0 refusereceipt-not-positive. - Plan:
owner-not-live,wrong-owner,generation-absent,obsolete-generation,link-absent,wrong-link, product expiry (absent, not positive, differs from the window's served expiry), clock (absent, not positive). The served expiry and the receipt are the window's, validated once at freeze. - Watch poll: the clock (absent, not positive) first; then strictly before
stopthe plan's order; at or paststop,boundary-unconfirmedwhen no poll confirmed, thenowner-not-live,wrong-owner.
The boundary rule
A watch's boundary is the cutoff plus its offset; stop is the earlier of
the cutoff and the boundary.
- Built from a freeze that is not
frozen(), the watch starts Refused with that freeze's refusal (not-evaluatedwhen it readsnone), a null window and zero polls: there is nothing to wait on. - Reached and Refused are final: a later poll changes and counts nothing.
Every other poll counts in
polls()and refuses an absent or non-positive clock. - Strictly before
stop,PlanExpirySamplemust accept, or the watch refuses with its refusal. Each acceptance counts inconfirmations(), is kept asconfirmedServerMs, and setsuntilBoundaryMsto the boundary minus this reading. - At or past
stop, zero confirmations refusesboundary-unconfirmed; otherwise only the owner is validated (owner-not-live,wrong-owner), so a destruction or replacement during the wait never transfers. Generation, link and product expiry are not refused there: from its cutoff the product may close the frozen Share, clear its frozen expiry or replace the link, and that reaction is what the caller samples at the boundary. - Strictly before the boundary the watch stays Waiting with
untilBoundaryMsthe boundary minus this reading; at or past it, Reached withreachedServerMsthis reading anduntilBoundaryMscleared. - Every poll recomputes from its own reading, so a clock resynchronization in
either direction moves the boundary in wall time and never changes the
window. A negative offset samples before the cutoff:
stopis then the boundary, and the full premise is validated up to it.
Details formats
Each is one line, wrapped here. A freeze:
window=<label> refusal=<name> owner=<live:Class|not-live>
current=<same|other|absent> generation=<n|none>/<n|none>
link=<same|other|absent> served=<n|none> receiptServerMs=<n|none>
product=<n|none> clockServerMs=<n|none> cutoffLead=<ms>
minimumAhead=<ms> cutoffServerMs=<n|none> untilCutoffMs=<n|none>
The generations are the observation's and the reading's. A not-positive
value prints as its number, so served=0 is visible; cutoffServerMs is
printed only from a positive served expiry, and untilCutoffMs only from it
and a positive clock. A plan:
window=<label> refusal=<name> owner=<live:Class|not-live>
current=<same|other|absent> generation=<window>/<n|none>
link=<same|other|absent> served=<window> product=<n|none>
clockServerMs=<n|none> cutoffServerMs=<n> untilCutoffMs=<n|none>
A watch:
window=<label|none> state=<waiting|reached|refused> refusal=<name>
offset=<ms> cutoffServerMs=<n|none> boundaryServerMs=<n|none>
polls=<n> confirmations=<n> confirmedServerMs=<n|none>
untilBoundaryMs=<n|none> reachedServerMs=<n|none> lateMs=<n|none>
premise=[<premise>]
lateMs is the reached reading minus the boundary. The premise is the last
poll's plan details before stop, or
owner=<live:Class|not-live> current=<same|other|absent> clockServerMs=<n|none>
for a poll at or past it or with a refused clock; it is empty before the
first poll.
Lifetime and cleanup
The module has no timers, rows, subscriptions, onFinish registration or
product state, and owns nothing but its values. A window holds its owner
weakly (QPointer) and is shared as std::shared_ptr<const ExpiryWindow>; a
watch keeps that pointer. Release watches with the scenario state. Nothing
needs restoring, and base::unixtime is never changed.
Verification
Test::AppendExpiryWindowSelfTest(runner), called after
runner->waitEvent(u"launch_finished"_q), appends nine then-only stages
named expiry window self-test: <leg>. They run synchronously over literal
caller-owned identities and deadlines and plain QObject owners: no
session, network, account, widget, fixture secret, server fixture mutation
or QR surface. Only the last leg reads the real clock, and nothing calls
base::unixtime::update(). An account-free --portable-root sandbox (an
empty <dir>/test_TelegramForcePortable) is enough. Every refusal is
observed through pure readings and asserted as a passing Check whose details
carry it; a finish release frees the owners. Expected:
SCENARIO_RESULT: PASS (failures: 0) with no FAIL and no N/A row. The legs,
each with its control and falsifier:
- arm: a fixture gate on three live distinct owners; one distinct non-empty
name for every refusal; defaults that never accept (an empty
ExpiryFreezeandExpiryPlan, a freeze from an empty observation and reading refusingowner-not-livewith no window, a watch from an empty freeze Refusednot-evaluatedwith a null window and zero polls, still so after a poll). Falsifier: an accepting default, or a missing or duplicate name. - positive observation: a current positive observation freezes a window
whose fields are the observation's, the receipt keeps its sub-second
fraction, a plan at the freeze reading has the expected
untilCutoffMs, and a watch polled at the freeze reading, one ms before the cutoff, at the cutoff and at the boundary reads Waiting, Waiting, Waiting, Reached with two confirmations (the poll at the cutoff is not one) andlateMs=0. The details readlink=sameand never the link text. Controls: a product expiry one second off refusesproduct-expiry-differs, and an absent served or product expiry refuses by its own name. Falsifier: a freeze comparing the served field with itself, or a dropped receipt fraction. - freeze refusals: table rows for every freeze name: each owner null, each
generation absent, each link empty (and both of each), another owner,
generation or link, every expiry, receipt and clock absent and zero (a
served expiry also -1), a differing product expiry, the both-absent and
both-zero expiry pairs, a receipt and a clock both 0, and
cutoff-not-aheadone ms insideminimumAhead, at and past the cutoff, and withminimumAhead0 at the cutoff. Controls in the same table freeze at the inclusiveminimumAheadedge and, withminimumAhead0, one ms before the cutoff. Every refused freeze has no window, and a watch from it is Refused by the same name with zero polls and nountilBoundaryMs, before and after a poll. Falsifier: avalue_or(0)-style comparison freezes the both-absent and both-zero rows; a wrong name; a Waiting watch. - plan refusals: reading mutations against a frozen window refuse
wrong-owner(another owner, null),generation-absent,obsolete-generation,link-absent,wrong-link, the three product names and the two clock names, each withoutuntilCutoffMs. A fresh watch's first poll with the same reading is Refused by the same name with zero confirmations, and a later poll at the boundary leaves it Refused with one poll. Falsifier: anyuntilCutoffMsoruntilBoundaryMson a refusal row. - simultaneous windows: Share, natural (same owner and link, lead 0) and
render (another owner, generation and link) windows coexist; refreshing the
render source freezes a second render window while the three snapshots
stay unchanged with pairwise distinct cutoffs. The old render window
refuses
obsolete-generationagainst the new generation and the new one accepts; interleaved Share and render watches polled over one clock sequence each reach only at its own boundary. Falsifier: a changed snapshot, or one watch reaching at the other's boundary. - destruction and replacement: an owner destroyed and rebuilt at the same
address (control: the address is equal) leaves the window's
owner()null. Planning, re-freezing from the kept observation and polling two watches (one before the cutoff, one inside the reaction window) refuseowner-not-liveand stay Refused. Another live owner refuseswrong-owner; a new generation on the same owner refusesobsolete-generationon the old window and freezes a new one while the old keeps its generation. Falsifier: raw-pointer identity accepts the same-address object. - boundary: an absent product expiry one ms before the cutoff refuses
product-expiry-absent; from the cutoff to the boundary an absent product expiry, another link and a new generation (the product's reaction) stay Waiting, then Reached, with one confirmation; another owner inside that window refuseswrong-owner; a watch first polled at the cutoff or past the boundary refusesboundary-unconfirmed; a late poll reaches withlateMs=2500and the freeze reading asconfirmedServerMs; a -500 ms offset reaches at exactly its boundary and validates the full premise up to it; a poll after Reached changes nothing. Falsifier: re-validating the product in the reaction window refuses those rows, skipping validation before the cutoff accepts the one-ms-before row, and an unbound owner reaches with another owner. - resynchronization: forward (+5 s) and backward (-3 s) clock jumps
recompute
untilBoundaryMsfrom each reading, while the window keeps its served expiry, link, generation and cutoff; the clock-update check that once compared0==0becomes an accepted plan whose product expiry is the positive served one. After a jump, an absent or zero clock, another link and a product expiry rebased on the shifted clock refuseclock-absent,clock-not-positive,wrong-linkandproduct-expiry-differs. Two polls 300 ms apart in one server second differ inuntilBoundaryMsby exactly 300 while the whole-second countdown a product would display,(untilCutoffMs + 999) / 1000, is the same for both. Falsifier: a cached first delay, an accepted absent or zero clock, a moved link, a rebased product expiry or a display-rounded reading. - real server clock: first the composition over literal reads, with
base::unixtime::now()7 s ahead oftime(nullptr): a mid-second Qt read, one rounded up into the next second (Unix rounds to the nearest ms) and one a tick behindtime(nullptr)(Windows) each keep their milliseconds and add exactly 7000. Then oneTest::ReadServerClock()between twoQDateTime::currentMSecsSinceEpoch()reads is present, positive and within[before + 1000 * shift, after + 1000 * shift], whereshiftis read independently (base::unixtime::now()minustime(nullptr), between two equalnow()reads). The details print every value and the reading's% 1000fraction on both verdicts. Read-only. Falsifier: taking the local second from Qt's milliseconds is 1000 ms off in the rounded and the lagging rows, and a wrong shift sign is 14000 off; on the real clock, a reading that drops or rounds its fraction falls outside the bracket unless the local reads sit on a whole second (about one run in a thousand), and so do a unit error and a wrong shift sign while the shift is nonzero; an absent or non-positive reading or an unsettled shift fails the same Check.
Compile-time immutability proofs: static_asserts in the translation unit
state that ExpiryWindow is neither copy-constructible nor copy-assignable
and that ExpiryFreeze::window is a std::shared_ptr<const ExpiryWindow>;
the window's constructor is private, so only FreezeExpiryWindow makes one.
Each falsifier above fails a Check in the same run. Proposed, not part of the
self-test, and executed only when a reviewer doubts the in-process
falsifiers: one disposable mutation build whose absence checks compare
value_or(0) and whose served check accepts 0, expected to FAIL the
both-absent and both-zero rows. Record executed results in the change's
evidence, and say when the mutation was only proposed.
Related guidance
Runner gated groups; test_probe (a reading that cannot discriminate refuses); test_fixture_transaction (the nearest harness API with a deadline and an injected clock); failure diagnosis.