@decocms/blocks 8.10.0 → 8.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/v8/cli/index.d.ts +1 -0
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +1 -0
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/run.d.ts +2 -0
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +30 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/v8/cli/index.ts +1 -0
- package/src/v8/cli/run.ts +35 -1
- package/src/v8/cli/skills.ts +91 -0
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Cache keys and what may be stored
|
|
2
|
+
|
|
3
|
+
One rule decides most hit-rate bugs: **the key holds exactly what changes the response, and
|
|
4
|
+
nothing else.** Too little in the key serves the wrong page to someone. Too much splits one page
|
|
5
|
+
into many entries that each miss.
|
|
6
|
+
|
|
7
|
+
## The example's key
|
|
8
|
+
|
|
9
|
+
`cacheKey(url, parts)` in the example worker entry builds a `Request` from:
|
|
10
|
+
|
|
11
|
+
| Part | Where it comes from | Why |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Path and query | `page.url`, minus the hash, `TRACKING_PARAMS` and `__cseg` | The page itself |
|
|
14
|
+
| `payload` | Server functions only, canonicalized (`skuId`, `idsku` dropped from page paths) | The page data the call loads |
|
|
15
|
+
| `__v` | `cacheVersion(cms, __BUILD_HASH__, url)` | A deploy or publish moves every entry |
|
|
16
|
+
| `__seg` | `segmentKey(segmentOf(request))` | Device and the site's own parts |
|
|
17
|
+
| `__a` | `assignmentsKey(page.assignments)` | Which side of each test, which campaigns |
|
|
18
|
+
| `__fetch` | `Sec-Fetch-Dest: empty` on a page URL | A programmatic fetch gets its own entry, as in v7 |
|
|
19
|
+
|
|
20
|
+
Use the same function for lookup, store and purge. Two functions drift, and then a purge
|
|
21
|
+
silently deletes nothing.
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
### 1. Strip tracking parameters, and add yours
|
|
26
|
+
|
|
27
|
+
The example drops `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`,
|
|
28
|
+
`utmi_campaign`, `utmi_page`, `utmi_part`, `fbclid`, `gclid`, `gclsrc`, `dclid`, `msclkid`,
|
|
29
|
+
`twclid`, `li_fat_id`, `mc_cid`, `mc_eid`, `ttclid`, `srsltid` (case-insensitive name match).
|
|
30
|
+
|
|
31
|
+
Check your real traffic for others and add them to `TRACKING_PARAMS`. Common ones not in the list:
|
|
32
|
+
`gad_source` and other `gad_*`, `gbraid`, `wbraid`, `_gl`. A param that is not in the list makes
|
|
33
|
+
every ad click a new entry.
|
|
34
|
+
|
|
35
|
+
Stripping a param from the key is only half the job. The page was rendered with the raw URL. See
|
|
36
|
+
"tracking-param poisoning" in `egress-traps.md` before you trust it.
|
|
37
|
+
|
|
38
|
+
### 2. Never the visitor, always the assignments
|
|
39
|
+
|
|
40
|
+
`page.visitor` must never be in the key: every visitor would miss. `assignmentsKey` is what the
|
|
41
|
+
page renders by. Two visitors on the same side of every test share an entry. More running tests
|
|
42
|
+
mean more entries per URL (up to 2^tests); retire finished tests. `deco-variants` covers the rest.
|
|
43
|
+
|
|
44
|
+
### 3. Segment only by what the content varies by
|
|
45
|
+
|
|
46
|
+
`buildSegment(request)` in the worker entry returns the device plus the site's own parts (a
|
|
47
|
+
region, a sales channel). Each part multiplies the entries per URL.
|
|
48
|
+
|
|
49
|
+
- Add a part only if the HTML differs by it. Ask: would two requests that differ only in this
|
|
50
|
+
part get byte-identical pages? If yes, it does not belong in the key.
|
|
51
|
+
- Region is the usual offender. A part filled from the CDN's geo header on every request splits
|
|
52
|
+
each URL by every region, even when one region sees different content. On VTEX, use the
|
|
53
|
+
regionalization `regionId` the shopper actually has, or move the regional choice to the
|
|
54
|
+
browser and a separate cacheable URL.
|
|
55
|
+
- Device: the example keys every page by device. If a page renders the same HTML for all devices,
|
|
56
|
+
the device split only lowers the hit rate for it.
|
|
57
|
+
- `loggedIn: true` makes the request private: never read from or written to the cache. Detect it
|
|
58
|
+
from the cookie your sign-in flow actually sets. A cookie that every returning visitor carries
|
|
59
|
+
(a checkout or cart cookie) turns most traffic private.
|
|
60
|
+
|
|
61
|
+
### 4. Keep the key stable
|
|
62
|
+
|
|
63
|
+
Order changes must not change the key. `segmentKey` and `assignmentsKey` sort their parts, and the
|
|
64
|
+
example canonicalizes server-function payloads with `JSON.stringify` after a walk. If you add a
|
|
65
|
+
part built from an object, sort its keys first.
|
|
66
|
+
|
|
67
|
+
### 5. Store only clean 200s
|
|
68
|
+
|
|
69
|
+
The example stores a render only if it is a 200, not degraded, not private. Keep all three.
|
|
70
|
+
|
|
71
|
+
- A non-200 (a CMS 404 page through `x-page-status`, a 5xx) is never stored.
|
|
72
|
+
- An empty or partial page that answers 200 is the dangerous one. In v8 a block read returns a
|
|
73
|
+
`[value, error]` result instead of throwing. If a section's loader failed or the upstream returned
|
|
74
|
+
`null`, the page can still render a 200 with an empty grid. Stored, every visitor gets it for the
|
|
75
|
+
whole fresh and stale window.
|
|
76
|
+
- Fix: when a loader the page needs fails or returns nothing, set `x-deco-degraded: true`
|
|
77
|
+
(`DEGRADED_HEADER`). The example then serves a stale copy if it has one, and never stores the
|
|
78
|
+
degraded render. Treat "no products where products are required" as a failure, not as data.
|
|
79
|
+
- Do not add a process-wide "last good" copy on top of the page cache. The stale windows already
|
|
80
|
+
do that, and an extra copy per isolate diverges between isolates and hides real failures.
|
|
81
|
+
|
|
82
|
+
### 6. Private data never shares a URL's entry
|
|
83
|
+
|
|
84
|
+
- Cart, user, wishlist, addresses: server functions that call `markPrivate()`, or answer with
|
|
85
|
+
`Cache-Control: private, no-store`. The example never stores them.
|
|
86
|
+
- Do not write a cookie while rendering a cacheable page. Move the write to a POST handler or a
|
|
87
|
+
private server function. A cookie on the response makes the example bypass, which is safe but
|
|
88
|
+
costs a render every time.
|
|
89
|
+
- Do not strip `Set-Cookie` or override `private` to "fix" the hit rate. The private header is
|
|
90
|
+
usually there because the response depends on the shopper (price table, campaign).
|
|
91
|
+
|
|
92
|
+
## One upstream call per request
|
|
93
|
+
|
|
94
|
+
Several sections often need the same upstream data.
|
|
95
|
+
|
|
96
|
+
- Inside one request, `@decocms/blocks` already runs each block function once per canonical input:
|
|
97
|
+
the resolver keeps one promise per function and inputs, for that request only. Two sections
|
|
98
|
+
that resolve the same loader block with the same props share one call.
|
|
99
|
+
- Block bodies (the content) are fetched once per hash per isolate and shared by concurrent
|
|
100
|
+
requests.
|
|
101
|
+
- Across requests, the example does not coalesce concurrent misses. Two requests that miss the
|
|
102
|
+
same key at once both render. Stale-while-revalidate keeps this rare on hot pages. If a viral
|
|
103
|
+
page's misses hurt the upstream, add a lock in your own `pageCache`; nothing in the framework
|
|
104
|
+
provides one.
|
|
105
|
+
- If you write a helper that calls the upstream directly, dedupe it per request (a `Map` of key to
|
|
106
|
+
promise that drops a rejected promise), never per process.
|
|
107
|
+
|
|
108
|
+
`deco-storefront-performance` covers finding the duplicate calls.
|
|
109
|
+
|
|
110
|
+
## Upstream data cache
|
|
111
|
+
|
|
112
|
+
v8 has no framework loader cache (v7's `createCachedLoader` is gone). An upstream cache is a
|
|
113
|
+
`fetch` you write and pass to the client:
|
|
114
|
+
|
|
115
|
+
- `createVtexClient({ ..., fetch })` from `@decocms/apps-vtex`; the other `@decocms/apps-*` clients
|
|
116
|
+
take a `fetch` option too. They all go through `createInstrumentedFetch` from
|
|
117
|
+
`@decocms/blocks/fetch`.
|
|
118
|
+
- A response your fetch serves from its cache should carry `x-cache: HIT`: the
|
|
119
|
+
`http.client.request.duration` metric then labels it `cached=true`.
|
|
120
|
+
- Key it on everything the response depends on (the VTEX client's docs name `regionId`; also the
|
|
121
|
+
sales channel, locale, price table). Cache only shopper-invariant responses (`deco-apps`).
|
|
122
|
+
- An in-memory cache is per isolate and TTL-only. A long TTL delays every upstream change, deploy
|
|
123
|
+
or not. Keep it to seconds or minutes.
|
|
124
|
+
|
|
125
|
+
## Test the key
|
|
126
|
+
|
|
127
|
+
The example's `worker-entry.test.ts` shows the shape: tracking params share one entry, devices get
|
|
128
|
+
their own, the purge's keys equal the stored keys. Add a case for every part you add to
|
|
129
|
+
`buildSegment`, and one that asserts two visitors in the same test bucket share a key.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Case study: an egress audit on a VTEX storefront
|
|
2
|
+
|
|
3
|
+
A worked example. The site ran on the v1 Fresh/Deno stack, so the code it changed (loader
|
|
4
|
+
`cacheKey` exports, a Redis loader cache, site middleware) does not exist on v8. The lessons do;
|
|
5
|
+
each one ends with where it lives on v8.
|
|
6
|
+
|
|
7
|
+
## Starting point
|
|
8
|
+
|
|
9
|
+
- About 88 GB a week of CDN egress, about 52% cache hit rate.
|
|
10
|
+
- One listing page at 13 MB of HTML was 46% of a day's egress on its own.
|
|
11
|
+
- On a second VTEX storefront audited the same way, the origin was about 41% of a cluster's
|
|
12
|
+
cost, almost all egress.
|
|
13
|
+
|
|
14
|
+
## What happened, in order
|
|
15
|
+
|
|
16
|
+
**1. The broad first cut.** Capped listing size at 48 products, set cache headers per path, took
|
|
17
|
+
tracking params out of the loader cache key, blocked aggressive crawlers (about 26% of bandwidth
|
|
18
|
+
was crawlers stacking filter combinations), redirected URLs with three or more stacked filters to
|
|
19
|
+
the clean path, and fixed layout shift (home desktop CLS from 0.42 to 0.0025).
|
|
20
|
+
|
|
21
|
+
**2. The hit rate dropped, from 52% to 38%.** CDN telemetry showed three causes curl had not:
|
|
22
|
+
top-level category links answered a 307 with no cache headers, so every main-menu click went to
|
|
23
|
+
origin; a static sprite answered `Vary: If-None-Match`, splitting its cache by ETag; listing TTLs
|
|
24
|
+
were too short. The device was also dropped from the listing key, since listings rendered the same
|
|
25
|
+
for every device.
|
|
26
|
+
*v8:* trap 5 (redirects), trap 4 (`Vary`), trap 3 (device split) in `egress-traps.md`.
|
|
27
|
+
|
|
28
|
+
**3. Every returning visitor was private.** The site's middleware bypassed the cache when the
|
|
29
|
+
*request* carried the checkout cookie, which VTEX sets for almost every returning visitor, even
|
|
30
|
+
with an empty cart. Checking the *response* for a new cookie instead fixed it.
|
|
31
|
+
*v8:* `loggedIn` in `buildSegment` must read the sign-in cookie only (`cache-keys.md`, rule 3).
|
|
32
|
+
|
|
33
|
+
**4. Payload trim.** Warm responses still averaged 180 KB compressed, because a HIT serves whatever
|
|
34
|
+
the miss produced. The product graph carried about 32 installment price entries per offer, and each
|
|
35
|
+
color swatch carried a full product.
|
|
36
|
+
|
|
37
|
+
| Page | Before | After |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| Best-sellers listing, raw HTML | 28.7 MB | 2.89 MB (−89.9%) |
|
|
40
|
+
| Same page, `UnitPriceSpecification` count | 63,744 | 585 (−99.1%) |
|
|
41
|
+
| Campaign listing, raw HTML | 5.84 MB | 1.77 MB (−69.7%) |
|
|
42
|
+
|
|
43
|
+
Cards were trimmed to the two price entries they read; the product detail page, the one consumer of
|
|
44
|
+
the full graph, was left alone. The same audit found the CDN's "cache by device type" rule was off,
|
|
45
|
+
so mobile HTML could be served to desktop.
|
|
46
|
+
*v8:* trap 8 and `deco-storefront-performance`.
|
|
47
|
+
|
|
48
|
+
**5. A consolidation, a revert, a re-land.** Three listing sections were merged into one with one
|
|
49
|
+
cached payload, plus a custom "last good copy" and failure backoff on top of the loader cache. The
|
|
50
|
+
upstream search returns `null` instead of throwing for some queries. The merged loader turned that
|
|
51
|
+
into a valid-looking empty result, the cache kept it for 30 minutes, and mobile users saw an empty
|
|
52
|
+
listing. Reverted four hours later. The re-land threw on `null` (errors were not cached), dropped
|
|
53
|
+
the custom layer, and kept the sections separate: an in-request dedupe still gave one upstream
|
|
54
|
+
call per render, and a failure now emptied one section instead of the whole page.
|
|
55
|
+
*v8:* rule 5 (store only clean 200s, `x-deco-degraded`) and single-flight in `cache-keys.md`.
|
|
56
|
+
|
|
57
|
+
**Last: the cache that held one key.** The loader cache had a single 8.4 MB entry. Every cached
|
|
58
|
+
loader gated its key on "anonymous visitor", and the platform's segment cookie marks a visitor as
|
|
59
|
+
not anonymous as soon as it carries any `utm_*` field, so about 99% of real traffic skipped the
|
|
60
|
+
cache. Gating on the fields that change the response (sales channel privacy, campaigns, price
|
|
61
|
+
tables, region) and keying on those fields only fixed it. Probes for 3 listings × 7 visitor
|
|
62
|
+
profiles then asserted that every profile hit the same entry.
|
|
63
|
+
*v8:* rules 1 to 3 in `cache-keys.md`, the fingerprint probe in `perf-guardrails-e2e.md`.
|
|
64
|
+
|
|
65
|
+
## Outcome
|
|
66
|
+
|
|
67
|
+
Projected 25 to 30 GB a week, from about 88: roughly a 65–70% drop, over 11 merged changes and two
|
|
68
|
+
reverts.
|
|
69
|
+
|
|
70
|
+
## Lessons
|
|
71
|
+
|
|
72
|
+
1. A HIT is not the goal. The key must exist for real traffic, the stored body must be small, and
|
|
73
|
+
nothing may split the entry for no reason.
|
|
74
|
+
2. Test the failure path. Most of the regressions were "the upstream returned something odd and
|
|
75
|
+
we cached it".
|
|
76
|
+
3. Do not build a cache on top of a cache. A per-process "last good" copy diverges between
|
|
77
|
+
processes and hides failures.
|
|
78
|
+
4. Check what the CDN actually does. A header that looks right in curl is not proof that the CDN
|
|
79
|
+
caches by it. A diagnostic response header that echoes what the CDN saw found the device rule
|
|
80
|
+
in minutes.
|
|
81
|
+
5. One merged section is one failure domain. Keep sections that can fail separately apart.
|
|
82
|
+
6. Be exact about request cookies vs response cookies when a cookie decides cacheability.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Traps that kill hit rate or raise egress
|
|
2
|
+
|
|
3
|
+
Check them in this order. The first ones make pages uncacheable, and an uncacheable page costs on
|
|
4
|
+
every visit: a 6 MB page served from the cache costs no render, a 150 KB page never cached costs
|
|
5
|
+
one render and one set of upstream calls per view. Later traps also give misleading signals until
|
|
6
|
+
the earlier ones are fixed.
|
|
7
|
+
|
|
8
|
+
Each trap has a symptom, a probe (commands in `verification.md`), and a fix.
|
|
9
|
+
|
|
10
|
+
## 1. The page is never stored
|
|
11
|
+
|
|
12
|
+
**Symptom.** `X-Cache: BYPASS` on every request to a public page. Read `X-Cache-Reason`:
|
|
13
|
+
|
|
14
|
+
| Reason | What to look at |
|
|
15
|
+
|---|---|
|
|
16
|
+
| `private-response` | A `Set-Cookie` on the render (a loader or section writing a cookie), or `Cache-Control: private/no-store` from a route or a server function. Find who sets it. Move cookie writes to a POST handler or private server function. |
|
|
17
|
+
| `private` | `buildSegment` returned `loggedIn: true`. Check which cookie it reads. A cookie every returning visitor has (cart, checkout, session id) makes almost all traffic private. Read the cookie the sign-in flow sets, never "any cookie present". |
|
|
18
|
+
| `status:<code>` | The render was not a 200. A 404 for a real page means routing; a redirect status means the page itself redirects. |
|
|
19
|
+
| `degraded` | A loader failed and the page set `x-deco-degraded`. Fix the upstream, or the condition that sets it. |
|
|
20
|
+
| `profile:<name>` | The URL matched `private` or `none`, or a profile with edge `fresh` 0. Check `pageProfile` for a rule that is too broad. |
|
|
21
|
+
|
|
22
|
+
No `X-Cache` at all on a page means `pageCache` never ran: a preview (draft cookie or
|
|
23
|
+
`?__draft=`), an `Authorization` header, a `HEAD` request, `vite dev`, or your `routes` answered it.
|
|
24
|
+
|
|
25
|
+
## 2. Tracking-param poisoning
|
|
26
|
+
|
|
27
|
+
**Symptom.** One visitor's `gclid` or `utm_*` value shows up in the HTML other visitors get;
|
|
28
|
+
attribution is wrong; or ad traffic misses while plain traffic hits.
|
|
29
|
+
|
|
30
|
+
**Cause.** The key drops tracking params (`cache-keys.md`), but the page was rendered from the raw
|
|
31
|
+
URL. Anything that echoes the URL (canonical or `og:url` built from the request, analytics
|
|
32
|
+
payloads, pagination links, router state embedded in the HTML) carries the value. The example
|
|
33
|
+
stores that render under the clean key, so everyone gets it.
|
|
34
|
+
|
|
35
|
+
Server functions have the same problem one level down: the page path inside `payload` can carry
|
|
36
|
+
tracking params. The example strips only `skuId` and `idsku` from it.
|
|
37
|
+
|
|
38
|
+
**Probe.** Request `?gclid=POISON42` until it is stored, then the clean URL, and grep for
|
|
39
|
+
`POISON42`. It must be 0.
|
|
40
|
+
|
|
41
|
+
**Fix, in order of preference.**
|
|
42
|
+
1. Do not echo the raw query into the page. Build canonical and pagination URLs from the
|
|
43
|
+
parameters the page uses.
|
|
44
|
+
2. In `pageCache`, let a request that carried a tracking param read the clean entry but never
|
|
45
|
+
write it (skip `store`). This was v7's guard; the v8 example does not do it, so add it yourself
|
|
46
|
+
if your pages echo the URL.
|
|
47
|
+
3. Strip tracking params from page paths inside the server-function `payload` in
|
|
48
|
+
`canonicalPayload`, and from any URL the browser builds from `location.search` for a
|
|
49
|
+
client-side fetch.
|
|
50
|
+
|
|
51
|
+
## 3. The key splits for nothing
|
|
52
|
+
|
|
53
|
+
**Symptom.** Hit rate low on pages that are clearly public, with many distinct `X-Cache-Segment`
|
|
54
|
+
or URL variants per path.
|
|
55
|
+
|
|
56
|
+
- **Region.** A `buildSegment` part from the CDN's geo header splits every URL by region. Keep
|
|
57
|
+
only parts the HTML varies by.
|
|
58
|
+
- **Device.** Fine when mobile and desktop HTML differ. Wasteful when they don't.
|
|
59
|
+
- **Unlisted query params.** A new campaign param, a sort default spelled two ways, a crawler that
|
|
60
|
+
stacks filters in random order. Look at the raw URLs behind the misses.
|
|
61
|
+
- **Assignments.** Every running test multiplies entries. Retire finished tests.
|
|
62
|
+
|
|
63
|
+
## 4. `Vary` splits or blocks the cache
|
|
64
|
+
|
|
65
|
+
`Vary` tells every cache in the path to keep one copy per value of each listed request header.
|
|
66
|
+
`Vary: Cookie` or `Vary: User-Agent` on a public page means one copy per visitor or per browser
|
|
67
|
+
build in any cache that honors it. `Vary: If-None-Match` (seen from static-file servers) splits by
|
|
68
|
+
ETag, which defeats a year-long TTL.
|
|
69
|
+
|
|
70
|
+
The example sets `Vary: Accept-Encoding` on the answers it gives from its cache or a fresh store,
|
|
71
|
+
replacing what the app sent. A `BYPASS` answer keeps the app's `Vary`, and so do your `routes`
|
|
72
|
+
answers. The worker sets `Vary: Accept-Encoding` on fingerprinted assets and on `/fonts/`. Any
|
|
73
|
+
other file (a sprite or icon in `public/` without a hash in its name) is not an asset to the worker:
|
|
74
|
+
it goes through `pageCache` like a page. Previews get `Vary: Cookie`, which is correct for them.
|
|
75
|
+
Probe public URLs and static files for any other token.
|
|
76
|
+
|
|
77
|
+
## 5. Redirects
|
|
78
|
+
|
|
79
|
+
CMS redirects are answered by the worker before your `routes` and before `pageCache`. They carry
|
|
80
|
+
no `Cache-Control`, leave with `CDN-Cache-Control: no-store`, and are measured on one
|
|
81
|
+
`http.route`, `redirect`, with `cache` `BYPASS`.
|
|
82
|
+
|
|
83
|
+
Each one is a Worker invocation, not a page render: no commerce upstream is called, and the
|
|
84
|
+
redirects block body is kept per isolate once fetched. That is cheap. It only matters when
|
|
85
|
+
main-navigation links point at a redirecting URL, so every click pays a round trip. Fix the links
|
|
86
|
+
first.
|
|
87
|
+
|
|
88
|
+
If you cache redirects in front of the worker, cache only those that stay on the same host and
|
|
89
|
+
protocol and do not point at themselves. A cached leg of a redirect loop freezes the loop.
|
|
90
|
+
|
|
91
|
+
## 6. Hidden variants rendered in full
|
|
92
|
+
|
|
93
|
+
**Symptom.** The HTML carries N copies of a grid or menu, and CSS or an A/B script shows one.
|
|
94
|
+
`html-anatomy.mjs` lists the same blob N times.
|
|
95
|
+
|
|
96
|
+
**Fix.** Render the active variant on the server. Each other variant is an empty wrapper that
|
|
97
|
+
loads its content through a cacheable GET only when it becomes visible. A `display:none` element
|
|
98
|
+
never intersects, so it never loads. "Render everything, hide with CSS" is acceptable only for
|
|
99
|
+
something as small as a label. `deco-variants` covers variants that stay cacheable.
|
|
100
|
+
|
|
101
|
+
## 7. Calls on every page view that can't be cached, or that create state
|
|
102
|
+
|
|
103
|
+
**Symptom.** Every view fires a POST or a `no-store` GET, or a cookieless visitor gets a new
|
|
104
|
+
upstream cart (`Set-Cookie` for a cart id on a request with no cookies).
|
|
105
|
+
|
|
106
|
+
**Fix.**
|
|
107
|
+
- No cart cookie means no cart: return an empty cart without calling the upstream.
|
|
108
|
+
- Keep that response private anyway (`markPrivate()`): the URL is shared, and an empty cart
|
|
109
|
+
stored for one visitor would be served to a shopper who has items.
|
|
110
|
+
- Don't fire a session or profile POST when there is no auth cookie and nothing to change.
|
|
111
|
+
- Check third-party scripts in the browser's network panel. Some create carts too.
|
|
112
|
+
|
|
113
|
+
## 8. Payload bloat that compression hides
|
|
114
|
+
|
|
115
|
+
**Symptom.** Pages of several MB raw. Compressed size looks fine, but every miss renders and
|
|
116
|
+
transfers it, every client-side navigation fetches its data again, and parse and hydration time
|
|
117
|
+
grow. A cache HIT does not mean a small response.
|
|
118
|
+
|
|
119
|
+
Usual causes, as `html-anatomy.mjs` ranks them:
|
|
120
|
+
- Full product objects in serialized page data when a card needs ten fields. Map to a small card
|
|
121
|
+
model in the loader, before anything is cached or rendered.
|
|
122
|
+
- The same product serialized once per size or color button. Emit it once and reference it by id.
|
|
123
|
+
- Analytics payloads per card (`data-event` attributes). Send the shared part once.
|
|
124
|
+
- One script inlined per component instance. Emit the code once; pass each instance's props.
|
|
125
|
+
|
|
126
|
+
`deco-storefront-performance` has the trimming method and which fields each consumer reads.
|
|
127
|
+
|
|
128
|
+
## 9. Traffic you asked the browser to make
|
|
129
|
+
|
|
130
|
+
- Fetches on mount for UI that is closed (drawers, store locators). Fetch on open.
|
|
131
|
+
- Prefetch or prerender rules your site adds. A hover can download a whole page and its scripts.
|
|
132
|
+
Keep them conservative on dense menus.
|
|
133
|
+
- A page's own data fetched again right after a cached HTML load, with no interaction. Find what
|
|
134
|
+
triggers it before shipping; it doubles the transfer of that page.
|
|
135
|
+
|
|
136
|
+
## 10. Crawlers
|
|
137
|
+
|
|
138
|
+
A crawler stacking filter combinations creates unique URLs that never hit. One measured audit
|
|
139
|
+
found about a quarter of bandwidth came from crawlers. That is a WAF and bot-management job
|
|
140
|
+
(`deco-bot-management`, `deco-cloudflare-waf` in decocms/skills), not a cache key change.
|
|
141
|
+
|
|
142
|
+
## PR review checklist
|
|
143
|
+
|
|
144
|
+
- [ ] A new or changed loader on a cacheable page depends only on props and the URL's real
|
|
145
|
+
params. No request headers other than cookies for private data.
|
|
146
|
+
- [ ] A loader that can fail or return nothing sets `x-deco-degraded`.
|
|
147
|
+
- [ ] No cookie written while rendering a cacheable page.
|
|
148
|
+
- [ ] `buildSegment` adds only parts the HTML varies by. `loggedIn` reads the sign-in cookie.
|
|
149
|
+
- [ ] No raw query string echoed into the HTML.
|
|
150
|
+
- [ ] Variant UI: only the active variant rendered on the server.
|
|
151
|
+
- [ ] New per-view request: a cacheable GET, and it creates no state for anonymous visitors.
|
|
152
|
+
- [ ] `html-anatomy.mjs` before and after on the heaviest page: nothing repeated N times.
|
|
153
|
+
- [ ] Changed key: lookup, store and purge still use the same function; tests updated.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Next.js: the same rules on @decocms/nextjs
|
|
2
|
+
|
|
3
|
+
`@decocms/nextjs` caches nothing either. Caching is Next's own (ISR, the full route cache) and
|
|
4
|
+
whatever CDN sits in front. The binding's job is to make that safe: a cached page must never be a
|
|
5
|
+
preview, and must never be keyed on the visitor. The setup itself is in `deco-nextjs-site`.
|
|
6
|
+
|
|
7
|
+
## What `@decocms/nextjs/proxy` does
|
|
8
|
+
|
|
9
|
+
`draftProxy(proxyCms, options)` is the whole flow for a site without a proxy of its own. A site
|
|
10
|
+
with one calls `decideDraft`, `decideVisitor`, `decideAssignments`, the `*RequestHeaders` helpers
|
|
11
|
+
and `applyDraft` / `applyVisitor` itself.
|
|
12
|
+
|
|
13
|
+
| Request | What happens | Cache effect |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| Any draft signal (`?__draft=`, `off` included, or the draft cookie) | Rewritten onto the dynamic draft route (`/_draft/<path>`, mounted as `app/%5Fdraft/...`) | Never cached. `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie`, `X-Robots-Tag: noindex, nofollow` |
|
|
16
|
+
| A published CMS page, with `options.assignments(request)` true | Rewritten onto `/_assignments/<assignments>/<path>` (`rewriteToAssignmentsRoute`) | Next keeps one cached page per set of assignments. The visitor id is never in the path |
|
|
17
|
+
| Anything else | Forwarded with `x-deco-version`, `x-deco-visitor`, `x-deco-assignments` | Your route decides |
|
|
18
|
+
|
|
19
|
+
On the assignments route the page builds its client with `assignedClient(cms, segment)` from
|
|
20
|
+
`@decocms/nextjs/server`, which reads no request, so Next can cache it:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
export const revalidate = 600;
|
|
24
|
+
export async function generateStaticParams() {
|
|
25
|
+
return [];
|
|
26
|
+
}
|
|
27
|
+
export default async function Page({ params }) {
|
|
28
|
+
const { assignments, path } = await params;
|
|
29
|
+
const client = await assignedClient(cms, assignments);
|
|
30
|
+
if (!client) notFound();
|
|
31
|
+
// …
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
With `revalidate = 600`, a page can be about ten minutes stale; the first request after that
|
|
36
|
+
still gets the old page while Next renders again.
|
|
37
|
+
|
|
38
|
+
## The visitor URL vs the cached route
|
|
39
|
+
|
|
40
|
+
When the content has saved tests or campaigns, the proxy marks the response to the URL the visitor
|
|
41
|
+
asked for `Cache-Control: private, no-cache`. Next caches the rewritten route, but the original
|
|
42
|
+
URL answers differently by cookie and by moment, so a CDN in front must not keep it under that
|
|
43
|
+
URL.
|
|
44
|
+
|
|
45
|
+
A CDN that should cache in front of Next keys on the request's assignments, never the visitor:
|
|
46
|
+
`assignmentsKey(await decideAssignments(proxyCms, draft, visitor))`, `""` when there are none.
|
|
47
|
+
`assignmentsKey` is exported from `@decocms/nextjs/proxy` with the same output as the TanStack
|
|
48
|
+
worker's.
|
|
49
|
+
|
|
50
|
+
## What carries over from the TanStack references
|
|
51
|
+
|
|
52
|
+
- `cache-keys.md`: everything except the example's `cacheKey` and `pageCache` code. Tracking
|
|
53
|
+
params, segments, never storing degraded or empty pages, private responses, single-flight.
|
|
54
|
+
- `egress-traps.md`: all traps; read `X-Cache` and `X-Cache-Reason` only if your CDN or code sets
|
|
55
|
+
them. Next's own response headers tell you whether a page came from its cache.
|
|
56
|
+
- `verification.md`: the probes, with your CDN's headers in place of the example's.
|
|
57
|
+
|
|
58
|
+
What does not carry over: `createDecoWorker`, `pageCache`, `cacheVersion`, `__cseg` and
|
|
59
|
+
`decoServerFnFetch`, and the example's purge route. On Next, a release reaching cached pages is a
|
|
60
|
+
question of `revalidate` and Next's own invalidation.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Playwright guardrails for cache and payload
|
|
2
|
+
|
|
3
|
+
Cache and egress gains regress quietly: one cookie in a section, one new query param, one product
|
|
4
|
+
object passed whole to a card. A Playwright spec that runs on every PR catches them. It works over
|
|
5
|
+
HTTP, so it tests the site as a visitor sees it. For the harness itself (config, fixtures, CI
|
|
6
|
+
setup) see `deco-e2e-testing` in decocms/skills.
|
|
7
|
+
|
|
8
|
+
## Where to run it
|
|
9
|
+
|
|
10
|
+
`pageCache` does not run in `vite dev`. Run the spec against a build:
|
|
11
|
+
|
|
12
|
+
```json
|
|
13
|
+
{
|
|
14
|
+
"scripts": {
|
|
15
|
+
"e2e:serve": "vite build && vite preview --port 4173 --strictPort",
|
|
16
|
+
"e2e:perf": "playwright test tests/e2e/perf-guardrails.spec.ts"
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Set `use.baseURL` to `http://127.0.0.1:4173` and `webServer.command` to `npm run e2e:serve` (or
|
|
22
|
+
`bun run e2e:serve`) in `playwright.config.ts`. Against a preview deployment, point `baseURL`
|
|
23
|
+
there instead; that also exercises the real Cache API.
|
|
24
|
+
|
|
25
|
+
Read expected header values from your worker entry's profiles instead of copying numbers into the
|
|
26
|
+
spec. If `PROFILES` and `browserCacheControl` are exported from a module the spec can import,
|
|
27
|
+
the spec follows a TTL change instead of failing on it.
|
|
28
|
+
|
|
29
|
+
## What to assert
|
|
30
|
+
|
|
31
|
+
| Area | Assertion |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Profiles | Each representative path answers the `Cache-Control` of its profile; the second request is `x-cache: HIT` |
|
|
34
|
+
| Private paths | `/cart`, `/checkout`, account pages: `private, no-cache, no-store, must-revalidate`, `x-cache: BYPASS` |
|
|
35
|
+
| Previews | `?__draft=off`: `max-age=0, no-cache, must-revalidate`, `vary` has `Cookie`, `x-robots-tag` has `noindex`, no `x-cache` |
|
|
36
|
+
| Signed-in shopper | The sign-in cookie gives `x-cache-reason: private` |
|
|
37
|
+
| Returning visitor | A cart or checkout cookie alone does not make the page private |
|
|
38
|
+
| Tracking params | `utm_*`, `gclid`, `fbclid`: 200, no `location`, same `x-cache-segment`, HIT once warm |
|
|
39
|
+
| No poisoning | A value sent in `gclid` never appears in the clean URL's HTML |
|
|
40
|
+
| No cookies on cached pages | A public page answers no `set-cookie` except `deco_segment` on a first visit |
|
|
41
|
+
| Payload | Raw HTML under a budget; a marker of heavy data (a schema.org type you trim) under a count |
|
|
42
|
+
| Assets | A fingerprinted asset is `public, max-age=31536000, immutable` |
|
|
43
|
+
| CLS | Home and a listing under 0.1 on desktop and mobile |
|
|
44
|
+
|
|
45
|
+
## Spec sketch
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { expect, test } from "@playwright/test";
|
|
49
|
+
|
|
50
|
+
const LISTING = "/some-category";
|
|
51
|
+
// Set from what you measure (see "Cache probe" below).
|
|
52
|
+
const BUDGET = { listingRawBytes: 800_000, priceSpecs: 200 };
|
|
53
|
+
const get = (request, path, headers = {}) =>
|
|
54
|
+
request.get(path, { headers, maxRedirects: 0 });
|
|
55
|
+
|
|
56
|
+
test("listing is stored and served from the cache", async ({ request }) => {
|
|
57
|
+
await get(request, LISTING);
|
|
58
|
+
const res = await get(request, LISTING);
|
|
59
|
+
expect(res.headers()["x-cache"]).toBe("HIT");
|
|
60
|
+
expect(res.headers()["x-cache-profile"]).toBe("listing");
|
|
61
|
+
expect(res.headers()["cache-control"]).toContain("public");
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test("tracking params share the clean entry and never leak", async ({ request }) => {
|
|
65
|
+
const clean = await get(request, LISTING);
|
|
66
|
+
const tagged = await get(request, `${LISTING}?utm_source=g&gclid=POISON42&fbclid=f`);
|
|
67
|
+
expect(tagged.status()).toBe(200);
|
|
68
|
+
expect(tagged.headers()["location"]).toBeUndefined();
|
|
69
|
+
expect(tagged.headers()["x-cache-segment"]).toBe(clean.headers()["x-cache-segment"]);
|
|
70
|
+
const after = await get(request, LISTING);
|
|
71
|
+
expect(await after.text()).not.toContain("POISON42");
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
test("a preview is never cached", async ({ request }) => {
|
|
75
|
+
const res = await get(request, "/?__draft=off");
|
|
76
|
+
expect(res.headers()["cache-control"]).toBe("max-age=0, no-cache, must-revalidate");
|
|
77
|
+
expect(res.headers()["x-cache"]).toBeUndefined();
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
test("a returning visitor's cart cookie does not make the page private", async ({ request }) => {
|
|
81
|
+
const res = await get(request, "/", { cookie: "<cart-cookie>=x" });
|
|
82
|
+
expect(res.headers()["x-cache-reason"]).not.toBe("private");
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
test("listing HTML stays under budget", async ({ request }) => {
|
|
86
|
+
const body = await (await get(request, LISTING)).text();
|
|
87
|
+
expect(body.length).toBeLessThan(BUDGET.listingRawBytes);
|
|
88
|
+
expect((body.match(/UnitPriceSpecification/g) ?? []).length).toBeLessThan(BUDGET.priceSpecs);
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The cache is per data center on a real deployment and local to the machine on `vite preview`.
|
|
93
|
+
Run the warm-up request and the assertion from the same runner.
|
|
94
|
+
|
|
95
|
+
## Probes worth keeping as scripts
|
|
96
|
+
|
|
97
|
+
**Visitor-profile fingerprint.** For a few listings, request the page with a set of profiles that
|
|
98
|
+
must see the same content: no cookies, the platform's segment cookie with only marketing fields,
|
|
99
|
+
tracking params in the URL, a test-bucket cookie on the same side. Fingerprint the ordered product
|
|
100
|
+
ids and fail on any mismatch. When one profile differs, the key or the segment is reading
|
|
101
|
+
something that does not change the content, or the content reads something the key misses.
|
|
102
|
+
|
|
103
|
+
**Empty upstream.** Give the loader a switch, off in production, that makes its upstream call
|
|
104
|
+
return `null` (an env variable or a test-only build flag). With the switch on, the page must answer `x-cache: BYPASS` with
|
|
105
|
+
`x-cache-reason: degraded`, twice in a row. With it off, the next request must render the full
|
|
106
|
+
page. This catches the most expensive bug in this skill: an empty page stored as valid.
|
|
107
|
+
|
|
108
|
+
**Cache probe.** A table of path, status, raw KB, `x-cache` and time for home, a clean listing, a
|
|
109
|
+
tagged listing and a product page, after one warm-up. Run it against production once to set
|
|
110
|
+
budgets about 30% above what you see, and after each deploy as a smoke check. The tagged and clean
|
|
111
|
+
listings should be within a few percent of each other.
|
|
112
|
+
|
|
113
|
+
## Static checks
|
|
114
|
+
|
|
115
|
+
Grep the content for blocks that point at loaders you know bypass your trimming or caching (for
|
|
116
|
+
example a raw upstream search loader instead of the site's trimmed one). The saved blocks are
|
|
117
|
+
the JSON files in `.deco/blocks` (on a site that reads content at runtime, what `deco pull`
|
|
118
|
+
wrote); a test that greps them fails the PR before any request is made.
|
|
119
|
+
|
|
120
|
+
## CI
|
|
121
|
+
|
|
122
|
+
Run `e2e:perf` and the probes on every PR that touches the worker entry, a loader, a section on a
|
|
123
|
+
cacheable page, or the segment.
|