mirror of
https://github.com/nexu-io/open-design.git
synced 2026-10-27 09:51:12 +01:00
06e0fd7259
* fix(web): page recovery no longer withdraws a valid touchpoint lease (OPEND-3363)
`online`, `pageshow` and `visibilitychange` were all bound to the destructive
`wake()`, which calls `revoke()` synchronously — before the revalidation it
starts has produced any evidence. Switching Wi-Fi, waking from sleep or tabbing
back therefore unmounted a campaign the server had authorized, and the user saw
it vanish and (sometimes) reappear.
The loss could also be permanent. An emptied lease makes `abandonAttempt`'s
`!lease.current` branch true, so the first failed revalidation dropped the saved
`revalidationLease` too; the retry that succeeded came back `{kind:"retain"}`
with nothing left to restore. The impression was already recorded, so the
activity never showed again for that session.
The three recovery events now take the non-destructive shape `focus` already
had, named `resume`: a lease still inside the window the server granted keeps
its mount and revalidates in the background, a lapsed lease falls through to
`wake`, and a hidden page cancels only the request in flight. `armExpiry` still
retires every lease on the server's own deadline, and a 410 withdrawal still
closes at once.
Deliberate behavior-contract change. Three existing cases pinned the old
destructive semantics and are rewritten here with the opposite outcome:
- `withdraws old authority synchronously on wake and rejects a timed-out
revalidation` → `keeps an unexpired visible decision mounted while an online
revalidation is pending`
- `still withdraws display and authority on actual page hiding` → `fences a
hidden page without withdrawing the lease it was granted`
- `fences the old modal action until recovery mounts a fresh decision` → `keeps
the mounted modal action authorized across focus and online recovery`
The badge case additionally drops from three refreshes to two: `online` now
joins the revalidation `focus` already has in flight instead of tearing it down
and re-requesting.
Every new case asserts inside the pending revalidation window, not on the
settled state — the blind spot the four network edge cases this week shared.
* feat(web): let a production touchpoint hold the authority the server grants (OPEND-3366)
`resolveAuthorizationDeadline` takes the minimum of the server's
authorization, the activity's `endsAt` and a local cap. With A3 removing the
sixty-second clamp on `authorizationExpiresAt`, that local cap became the
binding term: a five-minute `MAX_LEASE_MS` truncated every long authorization
back to five minutes, so a client that lost the network went blank in the
middle of an activity that was still running.
The cap now lives once, as `PRODUCTION_MAX_LEASE_MS`, at the longest interval a
timer can name — a backstop against a server clock that grants past the
activity, not a policy. `endsAt` governs, which is what the server means.
`armExpiry` already segments the wait with `Math.min(remaining, MAX_TIMER_MS)`
and is unchanged.
All three production placements (Modal, Badge, Hover) had their own copy of the
five-minute constant, which is exactly how two of them could keep a short lease
after the third was fixed. They now share the one exported value, and a test
reads all three sources to keep it that way.
Depends on OPEND-3363: before it, page recovery emptied the lease before any
failure was evaluated, so a long authorization had nothing to protect.
* feat(daemon): assemble touchpoint content locally instead of re-downloading it (OPEND-3371)
A production decision refresh re-downloaded the whole content package every 30
seconds, although the bytes almost never change. B4 lets a caller say which
content it already holds and get a `contentOmitted` reply, but taking that
benefit in the browser would need a new desktop package — every already-shipped
prerelease would keep paying full price. Putting it in the daemon means the
client does not change at all and existing installs benefit immediately.
The daemon now carries `heldContentId` / `heldContentLocale` on its own behalf,
and puts the omitted `content` back from a local store before answering the
browser. Two layers: blobs addressed by their own digest, so the four
placements of one activity share `shared.js` / `theme.css` once; and one
assembly record per (placementKey, locale) naming the manifest, the entry and
the path → digest map. The root is derived from `RUNTIME_DATA_DIR`, so two
namespaces get two stores and neither can see the other's.
The proxy could stay a pure `source.pipe(dest)` only as long as nobody had to
read the body; this route now buffers and rebuilds the JSON. Everything else —
the Test runtime, the events endpoint, any production request the daemon holds
no content for — keeps the verbatim streaming path.
Two properties carry the design, and each has a named case:
- A daemon holding nothing sends today's request and returns today's response
byte for byte, with no `contentOmitted` anywhere. Published clients guard on
`if (!next.content?.id) return clear`, so breaking this makes campaigns
disappear.
- Nothing behind the daemon may cost the campaign. A miss, a corrupted blob, a
digest that stopped describing its bytes, an unwritable data directory, a
Vela that ignores the parameters — each falls back to exactly today's full
request. A trimmed reply that cannot be rebuilt is re-asked once, without
held content, and that retry can never trim again.
The cache holds no opinion about WHICH activity to show: the server re-decides
that every request, so a stale cache cannot pin a withdrawn activity, and a new
one is still visible within one poll.
Measured on a realistic package (real minified JS/CSS as content bytes):
638.8 KB raw / 190.1 KB gzip for the full response against 0.7 KB raw /
0.4 KB gzip for the trimmed one — the steady-state WAN body is under a
kilobyte per refresh regardless of how large the activity is.
* test(web): pin what a rotating touchpoint decision id costs the client (OPEND-3369)
The server-side measurement can only show that `touchpointDecisionId` differs
per request (120 distinct ids in an hour of polling). Whether that costs
anything is decided on the client, in the lease key: `refresh` bumps
`generation` whenever the key changes, and the mount effects are keyed on
`generation`, so a rotating id is a full teardown and re-mount per poll.
Every existing lifecycle case uses `key: "same"`, so this path had never been
observed. Two pairs of cases observe it now, at both seams:
- `useTouchpointLifecycle`: a rotating key over 120 polls produces 120
generation bumps and a new decision object each time; the same hour with a
stable key produces zero.
- `ProductionCampaignModal`: the same hour produces 121 distinct
`opend-touchpoint` elements and 121 `mount` calls with a rotating id, against
one element and one mount with a stable one.
Tests only; no behavior change. This confirms the client-side benefit claimed
for B3 — 120 remounts an hour become none once the id is stable.
* fix(web): take the one-shot credential out of the touchpoint lease key (OPEND-3374)
All three production placements put `touchpointDecisionId` in their lease key. A
changed key is `++generation`, which is a full teardown: shadow DOM rebuilt,
Blob URLs re-created, entry animation replayed, scroll lock released and
re-taken. But that id is not content identity — it is a credential the server
re-issues whenever its own sixty-second row lapses.
OPEND-3369 stabilised the id and removed the every-thirty-seconds version of
this churn. It did not remove the cause. The credential lives 60s and the client
polls every 30s, so missing two polls — a Wi-Fi switch, a tunnel, a closed lid —
expires the row; on recovery the server INSERTs a new one and the campaign
flickers. That moved the remount from "on a timer, for everyone" to "whenever
the network wobbles", which is the same population the recovery-lifecycle P1 was
about.
The key now answers only the question it exists to answer — same content, same
person, same deployment — through one shared `touchpointContentIdentity`, so the
three placements cannot drift apart.
Hover needed arguing rather than deleting, and the argument came out differently
than expected. Its key carried the ENTRY's content id plus BOTH credentials; the
layer's content id was never in it, so the layer's identity rode on its
credential. Whether a deployment always gives both placements the same
`content.id` is a server-side property this side cannot verify, and this repo's
own hover fixtures assume it does not (each placement gets its own version). So
the layer's content version is now named explicitly. The red test for it —
`still remounts the pair when only the layer's content version changes` — fails
on the previous key by showing the layer still rendering the replaced content.
Retaining the previous decision object means the client presents a credential
the server has expired. Both uses of it are asserted here rather than assumed:
`still clears on a 410 whose receipt echoes the stale decision id the client
kept` covers OPEND-3372, and `reports the stale decision id on a click after the
credential rotated` covers OPEND-3364. Without those two, this change would
become a revocation failure or lost attribution.
Deliberate contract change. The three OPEND-3369 observation cases measured the
cost of a rotating id and are rewritten with the opposite outcome:
- `rebuilds the mounted host on every poll when only the decision id changes` →
`keeps one mounted host for a whole hour of rotating decision ids` (121 hosts
and 121 mounts become 1 and 1)
- `keeps one mounted host for a whole hour when the decision id is stable` keeps
its result and loses its role as a contrast — the two now agree, which is the
point
- the hook-level `remounts once per poll when the decision id rotates ...` is
re-framed as `... when the lease key rotates ...`: the hook never knew about
decision ids, and which inputs change a key is now decided in the placements
OPEND-3369 is not undone — its write-side saving stands on its own and this
returns it to being purely that.
* fix(web): judge a set-aside lease by its own window, not by an empty screen (OPEND-3376)
**The ticket asked for `revalidationLease` to be deleted as unreachable. It is
not unreachable, so this takes the alternative the ticket names instead: fix
`abandonAttempt`'s criterion. See below — this needs a decision.**
The reachability argument was: `wake()` has one call site, `resume`'s `else`
branch, which runs only when the lease is missing or lapsed; so `wake()` can
only ever set aside a lease that is already expired; and the restore branch
requires the set-aside lease to still be valid; so the two are mutually
exclusive.
Every step is true except the last. It needs "expired" to be a property that,
once true, stays true. It is not. `elapsed()` is `max(monotonic, wall)`, so a
wall clock that steps FORWARD makes a live lease read as expired — `resume`
then takes the `wake` branch — and a correction BACK makes it read as live
again. NTP steps, VM resume and dual-boot clocks all do this, and this module
already takes wall-clock skew seriously enough to have a case for it.
Verified with a throwaway probe against this branch's HEAD: step the clock an
hour forward, dispatch `online`, step it back, resolve `{kind:"retain"}` — the
restore branch fires and the campaign comes back. Deleting the mechanism would
therefore have been a silent behavior change, not a no-op.
So the P1 hazard is repaired where it actually lives. `abandonAttempt` decided
whether a failure may end display by asking whether there is an ACTIVE lease,
treating "none" as "expired". `wake` empties `lease.current` before it
revalidates, so the next failure met that branch, spent the set-aside lease too,
and the retry that finally succeeded came back `{kind:"retain"}` with nothing
left to restore — gone for the session. The criterion now judges whichever lease
is still recoverable by its own window.
This is stronger than the deletion would have been. The deletion's safety rested
on `wake()` keeping exactly one call site, which nothing enforced; adding one
back would have reopened the loss. After this, a new `wake()` call site cannot
cause permanent loss at all, because the short-circuit that caused it is gone.
Red first: `no single failure can discard display authority that is still
recoverable` drives the clock excursion, fails one revalidation inside the
set-aside lease's own window, and asserts the retry restores display. It fails
on HEAD and passes here. All 42 pre-existing lifecycle assertions are untouched
and still pass, so nothing was bent to fit.
What is NOT delivered: `revalidationLease` still exists, and so does the
three-state lease machine the ticket wanted reduced to two. Whether to keep the
restore branch (it un-does a spurious withdrawal caused by a bad clock) or drop
it and accept one remount plus up to a 30s gap in that case is a product call,
not one to make inside a "delete dead code" ticket.
* refactor(web): a lease carries content identity, not authorization timing (OPEND-3377)
Since OPEND-3374 a matching key retains the previous decision object, which is
the point — consumers depend on `decision`, so a new reference would re-mount.
But the retained object is the whole response DTO, and three of its fields
describe something that does not survive being retained: `serverTime`, `endsAt`
and `authorizationExpiresAt` are whatever some earlier response happened to
carry. How long display may last comes from the lease's own `validForMs`, taken
fresh every time.
Nothing reads the stale copies today. That is a fact about who has written the
consumers so far, not about the code: the day someone adds `decision.endsAt` to
a countdown they read an end time the operator has already moved, and nothing
fails to tell them. Same species as OPEND-3376 — correct, but resting on an
invariant nothing enforces.
Option (a) from the ticket. `touchpointLeaseValue` drops the three fields and
`TouchpointLeaseValue<T>` says so in the type, and the value really does not
carry them, so a consumer that casts past the type still finds nothing. One
named helper, three placements, matching `touchpointContentIdentity` and
`PRODUCTION_MAX_LEASE_MS`. (b) was rejected because `never`-typed fields still
read as present and still invite `as`.
Chosen for the reason the ticket gives: it states the boundary rather than
patching a symptom. A lease carries a STABLE content identity, which decides
whether to re-mount, and a FRESH authorization window, which decides how long
display may last; these are different things and no longer share a DTO.
The type system then found the rest by itself. `dispatchProductionCampaignAction`
declared it took a whole `Decision` while reading only static actions and
identity — it already receives the window separately as `expiresAt` — and
Hover's `matches` did the same. Both are narrowed; no call site changed.
Evidence for the acceptance bar: adding
`console.log("activity ends at", decision.endsAt)` to the Modal's mount effect
produces
src/components/ProductionCampaignModal.tsx(375,46): error TS2339:
Property 'endsAt' does not exist on type 'AuthorizedDecision'.
Three type-level assertions in the suite keep that true without needing a human
to re-run the experiment: each `@ts-expect-error` is itself checked, so if a
field came back TypeScript would report the directive as unused and `pnpm
typecheck` would fail.
Pure narrowing. Every pre-existing assertion in the lifecycle suite and in all
three placement suites is untouched and still passes, including OPEND-3374's
retained-credential cases, and the web suite is green.
* test(web): pin that a receiptless 410 withdraws display (OPEND-3375)
Vela now answers a request carrying an `activeDecisionId` for a deployment that
has been taken down with `410 production_runtime_withdrawn` and no receipt,
shaped byte for byte like a rollout withdrawal that cannot name one. The client
half of that was explicitly outside its authorization.
The client already handles it correctly, and this locks that in rather than
changing it: the receipt parse is what decides, so any 410 that does not yield
all four fields becomes `http_410`, and `http_410` is the one detail that sets
`touchpointWithdrawal` — the single flag `withdrawsDisplay` reads, and the only
failure permitted to end a lease the server already granted. Every other failure
is transport noise the lease rides out, which since OPEND-3363 it really does
ride out, so a 410 quietly reclassified as noise would now mean a withdrawn
campaign stays on screen for the rest of its lease.
Two cases, and neither goes red first — they are regression locks, not fixes:
- the loader, over the withdrawal body, the rollout body it mimics, a null
receipt and an empty body, asserting `http_410` + `touchpointWithdrawal`
- the Modal end to end through the real loader and lifecycle: a withdrawn
deployment closes the dialog on the next poll, and a later 200 does not bring
it back
* fix(web): a clock step must not re-mount a campaign that never left the screen (OPEND-3378)
Audit of every consumer of `elapsed()` under the non-monotonicity found in
OPEND-3376: `max(monotonic, wall)` rises and falls again when a wall clock steps
FORWARD and is corrected BACK. Ten call sites; nine acceptable, one not. The
verdicts are in the report; the reasoning that survives in code is on `elapsed`
itself, whose old one-line comment ("a forward jump can only shorten it") is
what made the shape sound monotonic in the first place.
The one that had to change is `same`, which decides renewal against re-mount.
It asked whether the previous lease was still inside its window, and a forward
step makes a perfectly live lease answer no. The response arriving during the
step is then a new presentation: `++generation`, rebuilt host, rebuilt Blob
URLs, replayed entry animation — the flicker OPEND-3374 removed, re-entering
through the clock. A3 made leases run for the whole activity, so the window a
step can land in went from a minute to days.
It is also not defensible on its own terms. Nothing evaluates `elapsed` until
something asks, so a step alone tears nothing down (verified by probe): the
campaign is still mounted and still authorized when the poll lands, and there is
no withdrawal for that re-mount to correspond to.
So the question is asked only where it means something: a lease being RESUMED
from `revalidationLease` must still prove it is inside its window, because its
display really was withdrawn. A lease that is still `lease.current` renews. A
mounted lease that has genuinely lapsed is not reachable here — `armExpiry`
retires it, which empties `lease.current`.
Red first: `a clock step forward does not re-mount a campaign that is still on
screen`. It fails on HEAD with `expected 3 to be 2` — one generation too many.
Deliberately NOT changed: `elapsed` itself. The monotonic term stops a clock set
back from granting time; the wall term stops a sleeping device from freezing the
lease, because `performance.now()` pauses across sleep on some platforms. Each
closes a cheat the other does not, so making it purely monotonic or purely
wall-clock would be a regression, and the fix belongs at the call sites that
care about the direction of the error.
Every pre-existing assertion is untouched, including OPEND-3376's
`no single failure can discard display authority that is still recoverable`.
* fix(web): drop the visibility fence whose premise OPEND-3363 removed
#8269 and OPEND-3363 are each correct and together reproduce the P1 they were
both written to remove: a campaign that vanishes on a tab switch.
#8269 added a `visibilitychange` fence releasing the open presentation whenever
the page goes hidden. Its own comment states the premise — "A hidden page ...
withdraws the lease and takes this modal down with it" — which was true when it
was written. OPEND-3363 removed exactly that: hiding now cancels only the
request in flight and leaves the lease, and the modal, alone.
So the fence released a presentation that had not ended. The campaign stayed on
screen with nothing recorded as presenting it, and the poll arriving on return
took `!continuesOpenPresentation && wasDisplayed(...)` with
`openPresentation.current` already null — the `{kind: "clear"}` branch — and
closed the host.
Reproduced before touching anything, on the rebased branch:
keeps a displayed campaign through a tab switch now that hiding no longer
withdraws it
→ TestingLibraryElementError: Unable to find an accessible element with the
role "dialog"
and the failure is on RETURN, not on hide: the modal survives being hidden, so
this is the interaction and not a regression in either change alone.
The fence is removed. What it protected is still protected, by the presentation's
own deadline: it is anchored to the authorization that opened it, so a sleep long
enough to lapse the lease also lapses the presentation, and the offer arriving on
wake is correctly read as a new one. That is asserted rather than argued.
Everything else from #8269 is kept, including the parts this branch was behind
on: campaign hosts confined to the home view, `onError` releasing the
presentation only for a real withdrawal, the `revokesActive` refactor, and
`touchpointWithdrawsDisplay`.
Deliberate contract change. #8269's `does not re-present a displayed campaign
after the page is hidden and shown again` asserted that hiding takes the modal
down, which OPEND-3363 made false. It is rewritten as `does not re-present a
displayed campaign after a sleep outlasts its authorization` — the property it
was actually protecting — with a sleep long enough to be a real one.
* fix(daemon): repair a damaged content blob instead of keeping it forever
`remember` skipped any blob file that already existed. The name is the
digest, so a present file "should" hold exactly those bytes -- but a file
damaged after it was written keeps its name, and `remember` is the only
moment the daemon ever holds the correct bytes for it again. Every other
round it is answering from a trimmed reply that carries no content at all.
The result was a closed loop with no exit and no signal: `held` sees the
files exist and offers the version, Vela trims its reply to ~1KB,
reassembly fails on the digest, the fallback refetches the full ~270KB,
and `remember` declines to overwrite. That placement then pays a trimmed
ask plus a full ask on every single poll -- strictly worse than running
with no cache at all -- and nothing in this module logs or counts it.
Writing unconditionally costs nothing in steady state, because `remember`
only runs on a response that was not trimmed. The rewrite is atomic and
idempotent, so the loop now closes after exactly one round.
The existing HTTP case pinned the defect as expected behaviour: it ran a
single round and asserted two upstream calls. It now runs one round
further and asserts the second round is back to one conditional ask.
* fix(daemon): make a blob's digest a statement about the file itself
`readVerifiedBlob` hashed a decode of the stored file and then returned
the file. Those are not the same bytes. Node's base64 decoder drops every
character outside the alphabet -- anywhere in the input, not only after
the padding -- so anything appended to or injected into a stored blob was
invisible to the digest while still being handed back and forwarded to
the browser.
The handover notes called this harmless on the grounds that the browser
decodes the same way. It does not. `atob` is WHATWG forgiving-base64: it
strips ASCII whitespace and throws `InvalidCharacterError` on anything
else. So the daemon reports a verified package, skips the fallback it
keeps for exactly this case, and the browser refuses to mount it. With
the blob-repair fix this placement would still self-heal in one round;
before that fix the pair was permanent, silent, and invisible to every
integrity check on both sides.
Blobs now store the bytes their digest names and are re-encoded to base64
on the way out, so `sha256(file) === digest` is an exact claim about
everything the cache returns. Modules already worked this way; the two
layers now share one invariant.
Two consequences, both deliberate:
- blobs written by an earlier build no longer match their digest. They
are repaired on the next full response, which is why the blob-repair
fix has to land first -- without it every one of them would be
stranded and cost double forever.
- a rebuilt response now carries Node's canonical base64. It stays
byte-identical to the original only while upstream sends canonical
base64 too, which Vela does today. The warm/cold equality case is the
assertion that will fail if that ever stops being true.
The cache fixture's shared resource was exactly 24 bytes, so its base64
form had no padding and appended garbage folded into the decode and broke
the digest by accident -- the new cases would have passed against the old
code for the wrong reason. It is 25 bytes now.
* fix(daemon): bind reassembly to the version it was negotiated for
`reassemble` took only the cache key, so it reread the record from disk
and rebuilt from whatever that record said at that moment. The record is
mutable: a concurrent full response for the same placement replaces it.
When it did, the daemon spliced the new campaign's content into a reply
the server had framed for the old one -- and nothing downstream could
tell. The browser verifies that the content is internally consistent, and
it is; both halves are. So it renders campaign Y's creative and reports
its impressions against campaign X's decision id. Billing and attribution
cross silently, on a path where every integrity check passes.
The pair this attempt offered upstream is now an argument, and
`recordStillHolds` is the invariant: a reply trimmed against one version
may only ever be rebuilt against that version. A record that has moved on
returns null, which the existing fallback already handles by re-asking in
full.
The locale it compares is the one the daemon OFFERED, not the one it
asked for. Vela resolves a placement locale through [requested, base
language, en-US], so a zh-CN request is legitimately answered and cached
as en-US, and `held` reports that faithfully. Comparing the requested
locale would strand every placement the server answers through a
fallback, which is why a case now pins that too.
Dropping the upstream request on abort ships with it, because the two are
one defect in practice. This proxy had no cancellation at all, while the
AMR proxy a few hundred lines up has had it all along. The browser's
per-attempt budget is 15s and this proxy's is 30s, so every attempt the
browser gives up on stayed alive here for up to fifteen more seconds:
still downloading, still buffering, and still writing the assembly record
that a later, live request was about to rebuild from. `res.headersSent`
does not catch it, because an attempt aborted before a byte went out has
sent no headers. That is what turns the race above from a one-round-trip
window into a fifteen-second one, which is why fixing only the first half
would leave reviewers with the wrong idea of how wide it is.
The fake Vela can now be taken over by a case that needs to control when
a reply lands, not only what it says. It still may not bypass the server's
own rule -- content is omitted only for a caller that already holds
exactly the version being served -- so the crossing above is produced the
way production would produce it: by promoting a campaign mid-flight.
* fix(daemon): put a ceiling back on buffering and decompression
Before content assembly this route forwarded production decisions as a
stream, so its memory was bounded by the socket. Reading the body to
assemble it gave that up and replaced it with nothing: `size` was tracked
only to size the final `Buffer.concat`, and the three `zlib.*Sync` calls
ran without `maxOutputLength`, which leaves the limit at
`buffer.kMaxLength` -- effectively none. Measured on this Node: a 199KB
gzip response allocates 200MB in 51ms, a ratio of about 1000:1. The 2MiB
check people point at runs four allocations later, inside the cache, long
after the damage is done.
Two things make this worse than it looks for a daemon. The decompressors
are synchronous, so an oversized body does not merely consume memory, it
holds the event loop of a privileged local process while it expands. And
this is not an edge route: it is the steady-state poll every placement
makes twice a minute.
Both limits now derive from one number. `MAX_CONTENT_BYTES` -- the budget
the web host already enforces on a content package -- is exported, and
the proxy allows four times it, which covers base64's 4/3 inflation plus
the manifest and metadata wrapped around the resources. A body past that
cannot be assembled into anything the browser would accept, so buffering
it buys nothing.
Past the ceiling the route degrades to streaming rather than refusing:
the caller still gets its answer, in one WAN fetch, framed exactly as
upstream framed it. That is the behaviour this route had before, and it
is what the pre-existing `passThrough` path does for every other request.
* chore(daemon): escape the key separator so the file is not binary to git
`keyName` separated the placement key from the locale with a literal NUL
byte written straight into the template string. Git classifies a file
containing NUL as binary, so this one showed up in the pull request as
`+0/-0` and `Binary files differ`. It is the 11KB module the whole
content-assembly feature lives in, and no reviewer on GitHub could open
it -- which is exactly where the defects fixed earlier in this branch
were sitting.
`\u0000` is the same character. Nothing about the hash, the file names on
disk or any stored record changes; only git's guess about the file type
does.
* fix(web): stop the timer limit binding the production lease again
`PRODUCTION_MAX_LEASE_MS` exists to catch a server clock that grants past
the activity it is granting for. Giving it `MAX_TIMER_MS` answered a
different question -- what one `setTimeout` can name -- and so made it the
binding term in `resolveAuthorizationDeadline` for every schedule longer
than ~24.9 days.
That is the same defect OPEND-3366 was written to remove, one tier up. The
five-minute value truncated every longer authorization to five minutes;
`MAX_TIMER_MS` truncates every schedule longer than ~24.9 days. `armExpiry`
has segmented long waits since this landed, so the timer's reach was never
the lease's problem to borrow.
It is reachable. The server validates only `endsAt > startsAt` and a future
`startsAt` -- there is no maximum schedule length anywhere in the write
path -- and its own production-runtime fixtures assert multi-year windows
are handed back unshortened. A device that misses every poll for 24.9 days
(a lid closed over a long trip, then opened offline) wakes to a truncated
lease, `wake` treats the offer as a new presentation, and the recorded
device impression retires it. That campaign never shows on that device
again.
The docblock made the same mistake in prose, and said so confidently: "At
the longest interval a timer can name it stops binding, and `endsAt`
governs". True below 24.9 days, false above it, and it is the sentence that
would have let the next reader repeat this. Rewritten to keep the two
bounds apart -- one timer segment versus one authorization -- and to record
both times the constant was given the wrong one.
Ten years, not `Infinity` and not a dropped term: skew is exactly what
`endsAt` cannot catch, because `validForMs` is `deadline - serverTime` and
`endsAt` is what the lag is measured against. Not one year either, for the
same reason five minutes failed -- the team's own fixtures schedule past it.
* test(web): give the sleep case a control that can tell absence apart
Both assertions in "does not re-present a displayed campaign after a sleep
outlasts its authorization" are absences. An absence is also what a
lifecycle that never came back looks like, so the case could not
distinguish the device impression closing a live offer from no offer
arriving at all -- and a `wake` that stopped waking would have left it
fully green.
Verified by construction: with `resume`'s lapsed-lease branch stubbed to
return instead of calling `wake`, both `toBeNull()` assertions still pass
and only the new control fails.
The control drops the impression and wakes once more through the same
event and the same advance, so the impression is the only difference
between presenting and not.
* test(web): cover the two background-recovery cases A5 had no test for
A5 (screen sleep / backgrounding) was carried as unverified because
`document.hidden` cannot be forced inside a real Electron renderer. That is
true of Electron and not of this suite, which has been forging it all along
with `vi.spyOn(document, "hidden", "get")`. Two of its four cases had no
coverage at all.
Short side, at the modal. The existing tab-switch case toggles visibility
on the real clock with nothing in between, so it cannot tell "the lease was
left alone" from "nothing had time to lapse". The new case is hidden for
forty-five seconds of a sixty-second authorization: a poll tick falls
inside the spell, and the lease is still the server's to renew on return.
It asserts the same dialog node, the same `opend-touchpoint` host, and zero
requests while hidden.
Long side, at the hook. Nothing covered a lease lapsing WHILE the page is
hidden. `armExpiry` does not consult `document.hidden`, so the grant
retires on the server's deadline whether anyone is watching or not, and the
return has nothing left to revalidate: it must go through `wake`, exactly
once. `generation` is asserted as changed rather than as a number, because
this path steps it three times and pinning the count would pin the route
instead of the outcome.
Both were checked by breaking what they claim to hold:
- visibilitychange bound back to `wake` (pre-OPEND-3363) -> the modal case
fails on the first assertion after hiding.
- `refresh` no longer fencing a hidden page -> the modal case fails on the
zero-requests assertion.
- `armExpiry` consulting `document.hidden` -> the hook case fails on
`current` being null.
- `resume` no longer waking a lapsed lease -> the hook case fails on the
single `load`.
Recorded for the next reader: reverting OPEND-3378 does NOT red the modal
case. The lease is still inside its window at the moment of return, so
`same` holds either way; 3378 needs a clock step forward, which is already
covered by "a clock step forward does not re-mount a campaign that is still
on screen".
What is left for a human is one platform fact, not product logic: whether
an Electron renderer flips `document.hidden` on sleep, occlusion and
minimise at all. Recovery does not depend on that event firing -- the
expiry timer ignores it, the thirty-second poll runs regardless, and focus,
online and pageshow share the same handler -- so the worst case is one poll
interval of delay rather than a wrong branch.
* docs(web): scope the OPEND-3377 stripping claim to production
"They do not survive into the lease" reads as a property of
`useTouchpointLifecycle`. It is a property of `touchpointLeaseValue`, and
the hook has a fourth consumer that does not apply it: `TestCampaignModal`
retains whole decisions with `serverTime`, `endsAt` and
`authorizationExpiresAt` intact, and reads across polls from the object it
retained.
That is the right call there -- the Test channel exists to show an operator
what the schedule is doing, its authorization is capped at sixty seconds
and every round recomputes from a fresh `serverTime`, so nothing it holds
can be stale by more than one poll -- and this change does not touch it.
What it does is stop the note reading as a repository-wide invariant when
the source scan behind it only visits the three production files. Left
unqualified, the next reader adding a consumer would believe a guarantee
nothing is enforcing.
* test(web): stop waiting for a real animation frame on a fake clock
The device impression is recorded inside a `requestAnimationFrame`, and
`requestAnimationFrame` was not in either case's `toFake` list. So the frame
stayed on the REAL clock while the case advanced only the fake one, and
`expect(localStorage.getItem(marker())).toBe("1")` after a fixed
`advanceTimersByTimeAsync(16)` was really asking whether enough WALL time
had happened to pass inside the awaits. On an idle machine it had; under
load it had not.
Measured, 12 busy cores against one file, six runs per arm:
- "keeps the same host through a background spell" (mine) 3/8 red
- "does not re-present ... after a sleep outlasts" 3/8 red
with every one of my commits reverted -- this one arrived with
the #8269 rewrite and was already failing before I touched the file
- after this change 0/29 red
Both now go through one helper that advances in small steps until the
marker lands. Each step yields to the real microtask queue, which is what
lets `verifyWebTouchpoint`'s real crypto finish; the frame it then requests
fires on fake time. Ablation, same load: the stepping alone is what carries
it (6/6 green); faking frames alone is strictly worse than before (6/6 red),
because a single fixed advance can run out before the frame is even asked
for. Frames are faked anyway, so the mechanism the case waits on belongs to
the clock the case controls, instead of to the wall.
"keeps the displayed campaign on screen when a poll fails and its retry
recovers" -- the case CI reported, and the A1 watchman from #8269 -- is not
touched. It sets the marker by hand precisely because of this, and it was
green in all 14 runs with my commits reverted. It has a weaker form of the
same fragility, noted for a follow-up: it reads
`document.querySelector("opend-touchpoint")`, which the host satisfies
synchronously, so nothing in it waits for the mount that sets
`openPresentation`. Starve that crypto long enough and the recovering poll
finds no open presentation, reads the impression it set by hand, and clears
the host. That is how it can fail, and it is not this PR's to change.
* fix(web): stop bounding production display authority by a lease duration
`resolveAuthorizationDeadline` took `serverTime + PRODUCTION_MAX_LEASE_MS` in
its minimum, so the ten-year value truncated every longer grant. The server's
own production-runtime fixtures run 2020-01-01 to 2100-01-01, so the premise
that no operator's schedule could reach it was false when it was written:
after ten years offline the client would withdraw a campaign the server still
authorizes, which is OPEND-3366 again at a larger threshold.
The term is removed rather than widened. Three times it was filled with a
number that answered a different question -- five minutes (the poll interval),
`MAX_TIMER_MS` (one timer's reach), ten years (a guess at "far enough") -- and
each became the binding answer to this one. Every fill was defended as a skew
backstop, but a duration cap only ever sees the SUM of the skew and the
schedule, so no value can bound one without binding the other: a value small
enough to catch a month of skew truncates every multi-year campaign. There is
no fourth value to try.
Skew is carried instead by the terms that survive it. `authorizationExpiresAt`
stays in the minimum, so a clock-derived credential window cancels the offset
exactly; `endsAt <= serverTime` still refuses an activity already over on the
server's clock; and a successful poll replaces `validForMs` outright, so an
inflated window is only ever spent by a client that cannot reach the server
for the whole of it. The residue -- a server clock wrong by a month
over-displays by a month, an error the size of the skew and not of the lease
-- is recorded as accepted, together with why comparing `serverTime` against
the device's `Date.now()` is not the fix.
The one maximum left is the Test runtime's sixty-second contract, now named
`TEST_MAX_AUTHORIZATION_MS` and a rejection threshold only; it cannot shorten
anything. The regression matrix gains the server fixture's own 2100-01-01
window, and the three-placement guard now asserts production passes no
maximum at all.
* test(web): wait for the mount behind the impression, not for a hand-written marker
`keeps the displayed campaign on screen when a poll fails and its retry
recovers` wrote the device-impression marker itself, to get past a frame its
`toFake` list had left on the real clock. That manufactures a state the
product cannot produce: `openPresentation` is assigned when `mountTouchpoint`
resolves and the marker only in the frame after it, so "impression recorded,
nothing open" exists in the case and nowhere else -- and it is exactly the
`{kind:"clear"}` branch of the load callback. Whenever the real SHA-256 behind
the mount had not finished inside the case's fixed ten-millisecond advance,
the recovering poll therefore tore down the very host the case then asserted
on, which is the `expected null not to be null` this went red with.
This is an existing weakness in the case, not one this branch introduced.
Starving the digest reproduces it identically on 1c4751266d, before the
lease-cap change; and the value that change removed never bound this fixture,
whose `authorizationExpiresAt` of `serverTime + 60s` was the minimum's
binding term under the old ten-year cap and stays so without it.
The case now fakes frames through `IMPRESSION_TIMERS` and waits through
`advanceToRecordedImpression`, like the two siblings beside it. That wait is a
real mount barrier, because nothing can write the marker until the
presentation is open. Nothing is relaxed to get there: this case guards the
blocking defect from the OPEND-3363 acceptance report, and reverting the
`onError` guard it exists to protect still turns it red.
`advanceToRecordedImpression` also stops spending fake time on a wait that is
really about the real queue. A step used to buy exactly one turn of it, so a
machine slow at the crypto ran out of steps while fake milliseconds were still
plentiful; each step now yields the real queue before advancing its frame.
Against a deliberately starved digest the case used to break at forty turns
and now survives four hundred, and when it does give up it names the wait that
failed instead of leaving an unexplained null host behind.
* feat(cms): keep a cached activity on screen while the runtime is unreachable
OPEND-3436. A client that cannot reach the CMS runtime went blank sixty
seconds later — the length of the authorization window it happened to be
holding — and then spent the outage retrying a request that could not
succeed. Restarting lost the activity entirely, because the daemon's
content store held the bytes of a package but nothing about WHEN it was
authorized to show them.
The daemon now owns persistence and the clock. Its assembly records carry
the server's own startsAt/endsAt/serverTime/authorizationExpiresAt, the
activity/deployment/content identity, and the decision envelope, scoped by
(environment, account) so one account's packages are unreachable from
another's session. When the runtime cannot be reached it rebuilds the last
decision it stored, re-times it, and answers 200 with `offlineReplay` — the
same body the browser already parses, with two fields rewritten:
`serverTime` becomes the daemon's estimate of now, and
`authorizationExpiresAt` becomes `endsAt`. That second rewrite is the
ticket's product ruling: offline display lasts to the last known END of the
activity, not to the short authorization it was issued.
Elapsed time is measured so it can only increase — an in-process monotonic
reading, and a persisted high-water mark that survives a restart — so
winding the system clock back cannot buy display time. A record whose
window has closed is deleted on the next read, along with the bytes no
surviving record still references; the blob pool is shared by digest, so
reclaiming without asking the survivors first would break every other
activity built from the same component. A 410 deletes only when all four
fields of its receipt name this record. A 404, a timeout and a 5xx delete
nothing.
The browser reads one field and changes two behaviours: a failure that
means the runtime was not reached suspends the poll and the backoff chain,
and recovery becomes one deduplicated revalidation per reconnection —
however many of online/focus/pageshow/visibilitychange that fires. The
window still ends on its own timer with no network involved, and a lease
that lapsed while the device slept is retired before anything is
revalidated, so waking does not flash an activity that is over.
The opt-in is off by default. The Test channel shares this hook, its job is
to keep asking, and there is no cached content behind it to fall back on.
Scope note: three existing regression tests recovered from an outage on the
next poll tick and now dispatch the `online` event a real reconnection
fires. What they guard — no remount across the outage — is unchanged.
* fix(web): keep asking while a 5xx holds the offline fallback
OPEND-3436 stands the poll down on the first failure that means the
runtime was not reached, and leaves recovery to `online`, `focus`,
`pageshow` and `visibilitychange`. That bargain holds for exactly one of
the two failures it covers.
When the device's own network broke, its repair fires `online`. When the
server answered 5xx, nothing broke at the device end at all: the request
crossed a healthy network and came back with an answer, `navigator.onLine`
stayed true throughout, and a user who simply leaves the app open on the
page the activity appears on fires none of the other three either. No
event anywhere says the server is healthy again, so a client that went
quiet on a 5xx stays quiet for the whole cached window while fully online.
What that costs is the ticket's own product bargain. A revocation is only
delivered in the answer to a request this client makes, so a client that
has stopped asking cannot be told an activity was pulled -- it keeps
showing it. A shortened schedule and a newly published activity are lost
the same way.
So a fallback held by a 5xx now keeps one request every
SERVER_FAULT_HEARTBEAT_MS. The interval is fixed rather than backed off
because its job is not "recover early" but "bound how late a withdrawal
can land": the longest a pulled activity can stay up is the longest this
client will go without asking, and only a fixed number answers the
question an operator actually asks. It goes through `revalidateOnce`, so
a heartbeat landing beside a reconnection is still one request, and a
heartbeat that fails starts no retry chain -- it just waits for the next
bound. One success returns it to the ordinary 30s poll.
A transport failure gets none of this, and a red guard pins that: a
device with no network answers every request the same way and its
recovery is already announced.
* test(web): wait for the menu the click schedules, not the tree before it
`pickHomeTemplate` read `home-hero-template-menu` with a synchronous
`getByTestId` on the statement after `fireEvent.click`. The click only
schedules the open state; the menu is not in the DOM until React commits,
so the helper passed only while that render happened to win the tick.
On `main` alone it wins every time. Merged with this branch — which mounts
the campaign placements into HomeView — the same tick carries more work and
the read starts losing: measured 0/6 failures on `main`, 1/6 on the merge
that CI actually builds, surfacing as `HomeView.example-dismiss` failing on
a testid that file never mentions.
`findByTestId` waits for the commit the click asked for. The read is what
was wrong, not the timing it happened to get.
* fix(web): arm the heartbeat on the path production actually takes
The heartbeat added in the previous commit could not fire in production.
It armed from `abandonAttempt`, which only runs when a request REJECTS,
and an unreachable runtime never reaches this browser as a rejection: the
daemon absorbs it, rebuilds the decision from its own cache and answers
HTTP 200 with an `offlineReplay` marker. The loader then collapsed that
marker to `offline: true`, so the lifecycle stood its poll down and armed
nothing. Every heartbeat test passed by mocking a rejection the real
stack does not produce.
That left the exact hole the heartbeat was written to close, and left it
on the likelier path. Both of the daemon's reasons -- `upstream_unavailable`
for a runtime 5xx, `upstream_unreachable` for its own DNS, connect or
timeout failure -- happen entirely behind the daemon, over a
browser-to-daemon connection that never broke. `navigator.onLine` stays
true so `online` cannot fire, and a user sitting on the page fires no
`focus`, `pageshow` or `visibilitychange` either. With no request on a
clock, a withdrawn activity stays on screen until the replayed `endsAt`,
which the daemon re-times to the whole remaining window and which a real
schedule may set years out.
So the marker is carried up whole instead of flattened, and the lifecycle
takes a recovery POLICY rather than a flag: "stop asking" and "nothing
will tell you when to start again" are different facts, and merging them
is what hid this. `productionTouchpointRecovery` maps reason to policy in
one exhaustive switch, so a third reason added upstream cannot inherit an
answer nobody ruled on.
The guard is unchanged and still green: a failure of the browser's own
transport is announced by `online` and gets no heartbeat.
Pinned by an integration case that drives the real loader -- daemon 200
replay in, 410 withdrawal out, and not one browser event in between.
* fix(daemon): decide what a status licenses before degrading to streaming
A decision body that outgrows MAX_BUFFERED_DECISION_BYTES makes the proxy
give up assembly and become a pipe. Becoming a pipe sends headers, and
sending headers retires the status block in the `end` handler — so the
size of a body was silently deciding what its status meant.
Two consequences, both reproduced by the specs added here:
- an oversized 410 never called `forgetWithdrawn`, so the browser cleared
the screen while the stored package survived its own withdrawal and
stayed eligible to replay the next time the runtime was unreachable;
- an oversized 5xx was forwarded instead of answered from cache, which is
the outage this route exists to survive.
Neither decision needs the bytes. `settleOversizedStatus` runs before the
degrade: a 410 reclaims and a transient 5xx replays, and a body this size
is by construction one no revocation receipt can be read out of — which
`touchpointWithdrawalReclaims` already rules is the whole deployment being
withdrawn. Once the cache has answered, the remainder has no reader, so it
is dropped rather than buffered back over the ceiling.
* test(daemon): pin that a 410 reclaims when its body expands past the decode ceiling
The streaming ceiling had a hole; this is the same rule one ceiling further
in. A body small on the wire but oversized once expanded leaves `decoded`
null, and the status block must still run — it precedes the unparseable-body
bail-out, and nothing stated that order.
Verified the guard can fail: moving the `!decoded` return above the status
block (one site) turns exactly this spec red.
* fix(daemon): make a damaged record a miss, and make a wound-back clock still pass
Two ways the persisted cache could break the fail-closed guarantee it states.
`parseAssembly` validated every scalar it reads but not `envelope`, which
`rebuild` dereferences with `Object.entries`. A record that is valid JSON of
the current version with `envelope: null` therefore threw — from inside the
proxy's upstream `error`/5xx handlers, where nothing catches it, so cache
corruption could take the daemon down in place of the documented cache miss.
Validating it here keeps "damaged record" and "miss" the same outcome.
The high-water mark survives a restart, but on its own it cannot MEASURE
time while the wall clock sits behind it: `max` pins `now` to the mark,
`elapsed` stops growing, and an activity keeps its authority for as long as
the clock stays wound back. The defect is not that the mark is too high — it
is that the mark does not move. Anchoring it to this process's monotonic
reading makes the wait count, per key so one placement's mark is never
evidence about another's.
This keeps `does not let a backwards system clock extend the window` green
rather than reversing it: the ruling that observed time cannot be
un-observed stands, and is now paired with time that continues to be
observed.
Both specs were verified to fail without their fix: removing the `envelope`
guard throws `TypeError: Cannot convert undefined or null to object`, and
removing the anchor replays an activity 25 hours past its `endsAt`. The
other 16 specs stayed green through each ablation.
* test(daemon): pin that the clock residual is bounded by downtime, not by the rollback
The monotonic anchor cannot recover time the daemon was not running, so a
rollback straddling downtime still buys display time. How MUCH is the whole
question, and it was being argued rather than measured.
This fixture measures it: one hour of downtime plus a twenty-four hour
rollback costs exactly one hour of over-display — the activity ends after
twenty-four hours of UPTIME, not twenty-four hours past the rollback.
Verified it can fail: removing the anchor lets the same activity survive the
final assertion.
* fix(daemon): refuse offline replay after an uncertain clock restart
Do not restore cached display authority when startup local time is behind the persisted observation. Fresh server responses establish a new per-record monotonic anchor, preserving consistently offset clocks and in-process rollback handling.
---------
Co-authored-by: lefarcen <935902669@qq.com>
Co-authored-by: lefarcen <ontf116@gmail.com>