Skip to content

Cache static files until they change, and trim what pages wait for - #331

Open
r0ny123 wants to merge 16 commits into
ref/integrate-all-20261025from
perf/web-guidance
Open

r0ny123 wants to merge 16 commits into
ref/integrate-all-20261025from
perf/web-guidance

Conversation

@r0ny123

@r0ny123 r0ny123 commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Based on ref/integrate-all-20261025, the build of all open PRs (#316's comment has the order), so the diff here is this change alone. Part of #63's thread. One of a set of PRs from a review of the front end against the modern-web-guidance performance guides; the others are #328, #330 and the forms, keyboard, semantics, colour, layout and tooltips PRs.

Measured with Playwright and Chromium against the captured corpus, as medians, throttled to 150 ms latency, 1.6 Mbit/s and 4× CPU unless noted.

Change.

  • 4c79eea: static files are cached until they change.
    • Before: Flask answers /static/ with no-cache and an ETag, so a second page revalidated every file. On /explore/samples after /explore/families, 16 of 16 static requests went to the server and came back 304, five of them render-blocking CSS.
    • Versions: url_for('static', …) now adds ?v=<12 hex of the file's sha256> (mcritweb/static_cache.py). The digest is recomputed when a file's size or mtime changes, so a git pull and restart, or an edit under flask run, changes the URL.
    • Lifetimes: a URL carrying the current digest gets public, max-age=31536000, immutable; any other /static/ URL gets an hour.
    • Unversioned files: those another static file names by a relative URL cannot carry a version. That covers the Font Awesome subset's fonts, trace_CFG/cfg_style.css's images, and dagre-d3.min.js, which the layout worker imports. They get the hour without immutable. The font preload and the CFG pages' dagre tag stay unversioned for the same reason, so that each is fetched once (NAMED_BY_STATIC_FILES).
    • What stays revalidated: diagrams and the manual's screenshots keep no-cache.
    • Compression: compression.py now also sends Vary: Accept-Encoding on a compressible response it does not gzip, so a shared cache keeping the file for a year cannot hand the plain copy to everyone.
    • Measured: 0 of 16 requests now reach the server. Warm first paint went 550 → 454 ms on a phone and 660 → 516 ms on desktop (18 runs).
  • 6ce066c: /help's first screenshot, its largest paint, is fetched with fetchpriority="high", Medium → High. The gain is small. Both arms were served through page.route, 15 runs, network throttling only: 616 → 604 ms on a phone and 760 → 696 ms on desktop. At 4× CPU it is lost in noise.
  • 6e64f8f: the Fraunhofer logo, hidden below 992 px, is loading="lazy". No request at 390 and 820 px (2.3 KB before); it still loads at 1100 px and wider.
  • dd8a36a: the icon-font preload carries media="(min-width: 992px)" on /help, /analyze/query, /data/submit, /data/import and /data/export. On a phone those pages draw icons only in the collapsed navbar, so the 6 KB font fetched at High priority went unused.
    • Measured at 390 px, 11 runs: first paint 500 → 448 ms, largest paint 556 → 496 ms.
    • A family's page and the statistics page keep the preload at every width: their rows and warnings draw icons, which the corpus just happens to leave empty.
    • base.html's comment and testIconPreload.py now say which pages the preload does not pay for.
  • a7aa92e: the cross compare no longer links jquery-ui.css, 36 KB of which one rule matched. .ui-sortable-handle { touch-action: none; } moves to style.css. Render-blocking CSS went 30.1 → 21.4 KB, and first paint 660 → 588 ms on a phone (9 runs, network throttling only). Drag-to-reorder still works (testDeferredJqueryBrowser.py).
  • c090390: while its tab is hidden, the job page clears its poll timer and stops its clock. When the tab is shown again it polls and ticks at once; a page loaded in a background tab waits to be shown. In 10 s hidden at refresh=1 there were 9 polls and 10 clock writes before, 0 and 0 after.
  • 5d42904: the function page's code panel is drawn from the graph at once, without waiting for every block's PicBlockHash lookup.
    • Each block with a lookup shows >>> Matches: looking up..., which the answer replaces in place, so nothing below it moves. A failed lookup removes the line, and an answer for a graph since replaced is dropped, as before.
    • The edit is marked // mcritweb: in trace_CFG/main.js.
    • Measured on function 945, 51 lookups with 80 ms added to each, 23 runs: the panel appears at 2.71 s instead of 3.46 s.
    • priority: 'low' on those fetches is left out, because testFunctionPages.py checks the exact fetch(...) call.
  • 3fa175c: AGENTS.md describes the code panel and the job poll as they are now.
  • 86e9ce8: the static view sends style.css, theme-dark.css, navbar.css and signin.css without their comments, which were two thirds of style.css's 15 KB gzipped, and a stylesheet is what a page's first paint waits for.
    • /*! comments are kept, and strings and url(...) are left alone.
    • The stripped body is kept per file and made again when the file changes. The ETag, gzip, 304 answers and cache lifetimes are those of any other static file; vendored stylesheets are sent as they are.
  • Each change above has its CHANGELOG entry.

Since review was requested.

  • e3be8dd. The live-search test's helper closes its region at the later("...live_search.js") call, and matched the bare URL only. Static URLs carry ?v= now, so the region was never closed; the pattern accepts the query.
  • d249875. The code panel and static caching browser tests passed string predicates to wait_for_function, which Playwright evaluates with eval. A strict script-src refuses that, so they would time out under the content security policy. All six predicates are arrow functions.
  • c42bd4e. The same secret-key race fix as Follow-ups from the batch E review: read-only database, backup command, key file without hard links, upper-case job ids #322: without hard links the key is staged and renamed into place under a lock on the instance folder, so workers cannot end up with different keys.
  • e412c41. A few // comments in the inline scripts of job_overview.html and table/column_table.html went to the browser with every copy of the page. They are Jinja comments now, which are dropped on rendering. testInlineScriptComments.py keeps the count: no template may send more comment lines in its inline scripts than it did before.
  • 3b22eea. A rendered page carried every indent and blank line of its templates and the comment lines of its inline scripts, 1.5 KB of what a result page weighs gzipped. The first round trip of a slow connection carries about 14.6 KB, and a result page is 14 to 18 KB gzipped.
    • thin_pages.py runs on every response that is a page, before it is gzipped. A run of white space that holds a line break becomes the line break, which a browser shows as the same one space.
    • pre, textarea, style, code, comments and everything inside a tag are kept. An inline script loses its indentation, blank lines and comment-only lines, unless a line of it may be part of a value.
    • ADR-0022 records it and revisits the whitespace half of ADR-0004, whose arithmetic was the whole page load rather than the first round trip.
    • MCRITWEB_THIN_PAGES = False in instance/config.py sends the page as the templates write it.
  • 84c9e4f. Every signed-in page but the upload forms carried the drop overlay's dialog, its upload form, the form's Dropzone options and the family type-ahead's tag: about 1.7 KB of each page gzipped, and 1.9 KB of a result page.
    • base.html now leaves a hidden slot. upload_form.js fetches the overlay from the new data.drop_overlay view (signed in, visitor and up; no-store; the CSRF token masked per answer) on the first drag that carries a file, alongside Dropzone, and wires it as the upload pages' form is wired.
    • The fragment holds no script, so it works under Harden the response headers, the session cookie and what templates write into scripts #330's nonce policy. The Dropzone options are JSON built by drop_overlay_options() from the settings flask-dropzone reads, and a test compares them key by key with the query page's. The family type-ahead is loaded only where the page has not queued it.
    • A file let go while the overlay is on its way is now kept and put in the zone. Before, nothing took it and the browser opened it in place of the page.
    • ADR-0023 records it. No new file is queued on any page.
    • Gzipped sizes on this branch, as a contributor: / 5694 → 3926 bytes, the result page 12742 → 10814, /explore/samples 9931 → 8149, /data/export 5222 → 3488. The query and submit pages are unchanged.
    • First drag under a slow profile (150 ms round trips, 1.6 Mbps, CPU ×4): the dialog opened 951–1111 ms after the first dragover, against 1075–1190 ms before.
  • 80bbe17. The overlay's ids are checked against each page that has a slot for it, as they were checked with every page that carried the form.
  • On the build of all PRs, the sample result page weighed 17.1 KB gzipped with every PR in. With the comment and script changes of this PR and the others it was back at 14.1 KB, the base's weight, and with 84c9e4f's fetched overlay it is 11.9 KB, comfortably inside the first round trip.

Tests. Each fix has a test that fails on the base:

  • testStaticCaching.py (new, 26 tests) checks every static URL on 10 pages, the lifetimes, diagrams and screenshots, both Vary paths and a changed file's new version. Its guard test fails if a file named from CSS or importScripts() is ever versioned.
  • testStaticCachingBrowser.py (new) checks that the second page comes from cache and that the font and dagre are fetched once.
  • testManual.py, testPageAssets.py, testIconPreload.py, testDeferredJqueryBrowser.py, testJobOverviewBrowser.py and testJobDurationBrowser.py are extended.
  • testNarrowViewportBrowser.py and testFunctionPageCodePanelBrowser.py are new.
  • testStaticStylesheets.py and testStaticStylesheetsBrowser.py are new (86e9ce8).
  • testThinPages.py compares a thinned and a whole page as a browser builds them, and testThinPagesBrowser.py as Chromium lays them out, on every page of the accessibility checks and a dozen of them (3b22eea). Both are new.
  • testInlineScriptComments.py is new (e412c41).
  • testSecretKeyRace.py replaces the test that pinned the old create-then-lock order with two that pin the new one (c42bd4e).
  • testLiveSearch.py is changed by e3be8dd.
  • testDropOverlay.py is new (84c9e4f, 80bbe17; 47 tests): no overlay form, options or ids on six signed-in pages; the view's access, no-store, no script, options equal to the query page's, and a fresh valid token; the upload pages unchanged; no id collisions.
  • testDropOverlayBrowser.py is new (84c9e4f; 8 Chromium tests with real drags): the overlay is built and shown once; a file dropped before Dropzone is in is kept and uploaded with the right fields; the type-ahead works in the built form; a second drag; leaving and re-entering; Escape and close; no layout shift and no focus taken; an ended session builds nothing and the next drag tries again.
  • testAssetDiet.py, testAutocompleteEscaping.py, testDeferredJqueryBrowser.py, testExplorePageCalls.py and routePolicy.py follow the fetched overlay.

14 existing test files compared static URLs exactly and now drop the version first. The non-browser modules around the change pass (1172), as do the browser modules (474), and ruff is clean.

Lighthouse. Accessibility, Best Practices and SEO are 100 on the 12 affected pages, mobile and desktop, and CLS is 0. Desktop Performance is 99-100 on this branch. On a quiet machine, on the build of all PRs with this one in, desktop is 100 on every page, and mobile Performance is 100 on every page but the upload pages (Dropzone's run, as on the base) and one headless paint artifact; with 84c9e4f, interleaved runs before and after score 100 in every run on /, the result page, /explore/samples and /data/export. The figures are in the merge-order comment on #316.

For the other PRs of the set.

Flask sent every /static/ file with Cache-Control: no-cache, so each page
asked for all of them again: on /explore/samples after /explore/families,
16 requests and 16 304s, five of them stylesheets the first paint waits
for.

url_for('static') now adds v, a digest of the file's content taken again
whenever its size or mtime changes, so a git pull and restart or an edit
under flask run changes the URL. A URL carrying the file's current digest
is sent with public, max-age=31536000, immutable; any other /static/ URL
with public, max-age=3600. The files another static file names by a
relative URL (the icon fonts, the CFG stylesheet's images, the dagre
bundle the layout worker imports) get no v, so that the font preload and
the CFG page's dagre script ask for the URL the stylesheet and the worker
ask for and nothing is fetched twice. Diagrams and the manual's
screenshots are untouched and stay revalidated.

The compression layer now sends Vary: Accept-Encoding on a compressible
response it does not gzip as well, so that a shared cache keeping the
file for a year does not serve that copy to every client.

Tests that matched static URLs exactly read them without the version.
The first screenshot is /help's largest paint at both widths, and the
browser asked for it at Medium priority while the logo went at High.
manual.render() now gives it fetchpriority="high", as the
modern-web-guidance image priority guide asks of a page's largest image;
the rest stay lazy.
The logo in the navbar is d-none d-lg-block, so it has no box on a
phone or tablet, and it was requested there on every page view all the
same (2.3 KB on the wire, the dark variant more). With loading="lazy"
Chromium no longer asks for it at 390 or 820 px and still loads it at
1100 and 1350 px, where it is in view. It is never the largest paint,
and its width and height keep its box.
The page linked the whole jQuery UI theme, 375 rules and 36 KB (8 KB on
the wire), as a render-blocking stylesheet, and exactly one of its rules
matches anything there: touch-action: none on the sortable list's
handles. That rule is now at the end of style.css and the link is gone.
The vendored file stays.
base.html preloaded the solid face on every signed-in page, on the
premise that those pages draw icons in their content at every width.
The manual and the query, submit, import and export forms draw solid
icons only in the navbar, which collapses below 992px, so on a phone
the 6 KB went out at High priority before the first paint and nothing
used it. Without it their first paint at 390x844 came 52 ms sooner and
their largest paint 44 ms sooner (medians over the five pages, 9 runs
each, at 1.6 Mbit/s and 150 ms round trips).

Those five templates now set icons_only_in_the_navbar, which gives the
preload media="(min-width: 992px)": on a desktop the navbar's help
icon still has the font in time, and on a phone the font is fetched
when the menu is opened. The family and statistics pages keep the
preload at every width: their sample rows and maintenance warnings draw
solid icons, though the captured corpus leaves both lists empty. The
comment in base.html and the premise in testIconPreload.py say so.
A running job's overview polled data.job_status every refresh interval
and its elapsed-time clock rewrote its cell every second, whether or not
anyone could see the tab. The poll is re-armed from the fetch callback,
so the browser's intensive throttling of background timers does not
slow it: a job watched from a background tab cost a status read per
interval for as long as the tab stayed open.

The poll now clears its timer when the tab is hidden, makes no new one
from a poll that answers while hidden, and polls at once when the tab
is shown again; a page loaded in a background tab waits to be shown.
The clock stops its interval while hidden and, counting from the load
time, ticks at once when shown. In 10 s hidden at refresh=1: 9 polls
and 10 clock writes before, none after (5 runs).
getCodefromGraph() in the main.js fork looks up the matches of every
block with a picblockhash and drew the code panel in a Promise.all over
all of them, so the code waited for the slowest of up to one lookup per
block. On function 945 (51 lookups), with 80 ms added to every request,
the panel appeared 3.46 s after navigation.

The panel is now drawn as soon as the blocks are read from the graph.
A block with a lookup starts with a ">>> Matches: looking up..." line,
which its answer replaces in place, so the lines below do not move; a
failed lookup removes it and leaves the block as before. An answer for
a graph that initialize() has since replaced is still dropped. Same
measurement: the panel appears at 2.71 s (medians of 23 runs).
The main.js note said getCodefromGraph() renders the code panel once
every lookup has settled, through Promise.all. It now draws the panel at
once and fills in each block's match line as its lookup answers; the
note says so, names testFunctionPageCodePanelBrowser.py, and says that
main_duo.js's uncalled copy still waits for its lookups. The note on the
job page's polling says it stops while the tab is hidden and polls at
once when the tab is shown.
The helper that cuts out a live-search region looks for the closing
later("...live_search.js") call, and matched the bare URL only. Static URLs
carry a ?v= version now, so the region was never closed. The pattern accepts the query.
The code panel and static caching browser tests passed string predicates to
wait_for_function. Playwright evaluates a string with eval, which a strict
script-src refuses, so they would time out under the content security policy.
All six predicates are arrow functions now.
style.css and theme-dark.css carry the reasons for their rules as comments, and a
stylesheet is what a page's first paint waits for: on the merged branches
style.css was 15 KB gzipped, two thirds of it comments. The static view now
sends style.css, theme-dark.css, navbar.css and signin.css with their comments
removed, keeping /*! comments and leaving strings and url(...) alone. The
stripped body is kept per file and made again when the file changes; the ETag,
gzip, 304 answers and cache lifetimes are those of any other static file.
Without hard links the key was written into a file created with O_EXCL,
empty until filled. A worker that opened that file in the gap could
replace it and find the creator's key still written into the file it
had displaced; a third worker that had opened the displaced file before
the replacement then read the loser's key and used it, while everyone
else used the winner's. One round in about 1600 ended that way.

The staged key, complete and private from mkstemp, is now renamed into
place under a lock on the instance folder, looking at the key file again
once the lock is held. No key file is opened for writing any more, and
none is ever visible unfinished.

The test that pinned the old create-then-lock order is replaced by two
that pin the new one.
A few // comments inside inline scripts of templates went to the browser with
every copy of the page, where a Jinja comment says the same to whoever reads the
template and is dropped on rendering. They are Jinja comments now.

A ratchet test keeps the count: no template may send more comment lines in its
inline scripts than it did before.
A rendered page carried every indent and blank line of its templates and the
comment lines of its inline scripts, about a quarter of a result page's bytes and
1.5 KB of what it weighs gzipped. The first round trip of a slow connection
carries about 14.6 KB, and a result page is 14 to 18 KB gzipped, so that is
whether the page can be painted from the first flight.

thin_pages.py runs on every response that is a page, before it is gzipped. A run
of white space that holds a line break becomes the line break, which a browser
shows as the same one space; pre, textarea, style, code, comments and everything
inside a tag are kept (the unique-blocks page shows its YARA rules in a code
styled white-space: pre, and a test fails if a template asks any other element to
keep its white space); an inline script loses its indentation, blank lines and
comment-only lines unless a line of it may be part of a value. ADR-0022 revisits
the whitespace half of ADR-0004, whose arithmetic was the whole page load rather
than the first round trip.

Two tests check that it is the same page: the thinned and the whole page are
compared as a browser builds them, and as Chromium lays them out, on every page
of the accessibility checks and a dozen of them.
r0ny123 added a commit that referenced this pull request Oct 26, 2026
The test held the request for show_apitoken.js by its bare path. With #331's
static versioning the URL ends in ?v=<digest>, the route never matched and the
test failed on the build of all PRs. The pattern now allows a query.
Every signed-in page but the upload forms carried the drop overlay's
dialog, its upload form, the form's Dropzone options and the family
type-ahead's tag, about 1.7 KB of each page gzipped and 1.9 KB of a
result page, for the moment a file is dragged over it.

base.html leaves a hidden slot instead, and upload_form.js fetches the
overlay from the new data.drop_overlay on the first drag that carries a
file, alongside Dropzone, and wires it as the upload pages' form is
wired. The overlay holds no script, so that it works under a nonce
policy: its options are JSON built from the settings flask-dropzone
reads, and the family type-ahead is loaded only where the page has not
queued it already. A file let go while the overlay is on its way is now
kept and put in the zone; nothing took it before, and the browser
opened it in place of the page or dropped it.
The overlay's form used to be checked for duplicate ids with every page
that carried it. Fetched and put in the page on the first drag, it is
now checked against each page that has a slot for it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant