Caching¶
How the platform caches, what each tier is for, and how stale each cache can be
across pods. The deployment this is written for: 2+ badger-web replicas behind
Cloudflare with no session affinity, badger-rest, badger-worker and
sync-worker, one shared Valkey (Redis), RabbitMQ.
The three cache managers¶
All three are defined in common/.../cache/CacheConfig.java.
| Manager | Where the data lives | Use it for |
|---|---|---|
redisCacheManager (@Primary, the default) |
Shared Valkey | Anything every pod must agree on the moment it changes. One eviction is seen by all pods. |
tieredCacheManager |
5 s per-pod Caffeine L1 in front of the Redis L2 | Read-on-every-request data that tolerates a few seconds of staleness on other pods. |
inMemoryCacheManager |
Per-pod Caffeine only | Hot data with its own cross-pod invalidation (message source, stereotypes). |
Pick with @Cacheable(cacheNames = "...", cacheManager = "tieredCacheManager");
omit cacheManager for Redis.
Redis key prefixes and tenants¶
Caches configured in CacheConfig.redisCacheConfigurations() with the
siteSpecific prefix — and every cache not listed there (the 5-minute
default) — are prefixed with the current tenant's siteId
(TenantContext), falling back to GENERIC_CACHE when there is no tenant.
Caches whose key already identifies the data globally (siteContexts-*,
siteConfiguration, siteEntitlement, ...) are not prefixed.
A cache of something every app can write must not be tenant-prefixed if the
writer may run without a TenantContext (the worker) — its eviction would land
in GENERIC_CACHE and miss the storefront's entry.
Redis failure is non-fatal¶
ResilientCacheErrorHandler (installed by CacheResilienceConfig, a
CachingConfigurer) applies to every annotation-driven cache:
- a failed get is a miss — the annotated method runs and reads Mongo;
- a failed put / evict / clear is logged and skipped.
Warnings are rate limited to one per operation and cache per minute, with a
count of what was suppressed; stack traces are at DEBUG. The Redis command
timeout defaults to 1 s (REDIS_DB_TIMEOUT). The connect timeout stays at
Lettuce's 10 s (REDIS_DB_CONNECT_TIMEOUT): Lettuce opens one shared connection
and reconnects in the background, so a short connect timeout protects no request
thread. It did make a CPU-starved pod's first connection fail right after
startup (seen on the dev worker at 2 s).
Circuit breaker¶
A 1 s timeout alone still makes a hung Valkey expensive: every cached lookup
waits the full second, runs the method, then waits again on the put, so a page
with a dozen cache calls takes tens of seconds. CircuitBreakingRedisCacheWriter
wraps the RedisCacheWriter underneath every Redis cache (including the L2 of
the tiered caches) with a breaker, RedisCacheCircuitBreaker:
| State | What cache calls do |
|---|---|
| Closed | Call Redis. failure-threshold consecutive failures open the circuit. |
Open for open-duration |
Don't touch Redis. Gets are misses (Mongo answers), puts are skipped, evictions and clears are queued. |
| Half-open | One caller is the trial: it replays the queued evictions, then makes its own call. Success closes the circuit; failure re-opens it for another open-duration. |
badger:
cache:
redis:
circuit-breaker:
failure-threshold: 3 # consecutive Redis failures before opening
open-duration: 10s # how long to bypass Redis before a trial call
Only a reply counts as success. Spring Data Redis routes put, evict and
clear through its asynchronous writer and discards the future, so those three
return in microseconds — and report success — against a Redis that is hung or
unreachable. Two consequences the writer has to work around, both of which
silently disabled the breaker before they were fixed:
- a
putis reported as unconfirmed and must not clear the failure count. A@Cacheablemiss is a failing get followed by one of those "successful" puts, so counting the put as a success reset the count on every request and the circuit never reached the threshold — every read kept paying the full 1 s timeout for the whole outage. evictandclearare issued throughevictIfPresentandinvalidate, which run the sameDEL/SCAN+DELbut return a value and therefore wait for the reply. Without that, an eviction during an outage raised no exception, so nothing was ever queued for replay andpending_invalidationsstayed at 0.
If you add a writer method, check whether it waits for a reply before feeding its result to the breaker.
Puts are immediate writes. CacheConfig builds the writer with
immediateWrites(), so a put waits for Redis too. By default it went out on
the reactive connection while evictions wait on the ordinary one, and the two
are not ordered: a @Cacheable miss followed by a save in the same thread (a
settings upsert reads the row, then saves it) could have its SET of the old
value land after the save's DEL, leaving the old value cached for the whole
TTL. The breaker still counts a put as unconfirmed; it doesn't depend on how the
writer is built.
Evictions are never just dropped. An eviction that can't reach Redis
(short-circuited, or failed while the circuit was still closed) is queued and
replayed as soon as Redis answers, before anything is read back from it. An
admin edit made during an outage doesn't leave a stale entry for the cache's
whole TTL. The queue holds 10,000 entries; beyond that, the affected caches are
cleared entirely on recovery. Queued evictions live in the pod's memory, so a
pod restarted mid-outage loses its queue, and the TTL is the backstop. That's
why no Redis cache lives longer than a day (themeContext and taxonomy).
Metrics: badger_cache_redis_circuit_open (1 while open or half-open — alert on
it), badger_cache_redis_circuit_short_circuited_total,
badger_cache_redis_pending_invalidations.
The breaker covers Spring caches only. Sessions, OAuth authorizations, the performance monitor and idempotency markers use Redis directly and still pay the command timeout while it is down.
allEntries evictions clear by SCAN, not KEYS, so they don't block Valkey.
Serialisation¶
Every Redis cache (and the copy-on-read L1, below) uses
CacheSerializers.redisValueSerializer(): Spring's
GenericJackson2JsonRedisSerializer plus JavaTimeModule,
FAIL_ON_UNKNOWN_PROPERTIES = false and EmptyEnumContainerTypeIds. A type is only safe to cache if it
round-trips field for field through it — if the cached copy is later saved
back to Mongo, any field lost in JSON is wiped in the database. Write a
round-trip test when you cache a new domain type. The
usual culprits: @JsonIgnore on a getter drops the whole property, computed
getters without setters, setters with side effects, no usable constructor.
An empty EnumSet or EnumMap used to fail the put outright: default
typing names the enum in the type id, Jackson finds it from the first element,
and with no elements it reflects on the JDK's private elementType, which the
module system refuses (InaccessibleObjectException). Location.capabilities
starts as EnumSet.noneOf(...) and Spring Data keeps that default when the
document has no such field. EmptyEnumContainerTypeIds writes an empty one as
a plain java.util.HashSet / HashMap; non-empty ones are written as before.
Tiered caches¶
TieredCacheManager wraps a Redis cache with a Caffeine L1 (5 s, 1,000 entries
per cache).
- L1 keys mirror L2 keys. The L1 key includes the Redis key prefix, evaluated per call, so a tenant-prefixed cache stays tenant-scoped in L1 too.
- Copy-on-read. Caches in
CacheConfig.TIERED_COPY_ON_READ_CACHESkeep the serialised bytes in L1 and hand every caller a fresh copy — the same isolation Redis gives. Use it for anything request code mutates in place. Other tiered caches return the same instance to every caller on the pod: never mutate what they return. - Writes evict L1 on the writing pod and L2 everywhere. Other pods' L1 is
cleared by a RabbitMQ broadcast (
CacheInvalidationPublisher→CacheInvalidationListener→TieredCacheManager.clearLocal) where the writer sends one; otherwise it expires within 5 s. - A load an eviction overtook isn't cached. A
@Cacheablemiss reads the source and then puts what it read. If a write evicts the key in between, that put would bring the old value back for the whole TTL.TieredCachenotes the key's eviction count at the miss and drops the put that follows on the same thread when the key was evicted (or the cache cleared, here or by another pod's broadcast) meanwhile; the next read loads again. A save of a store while a request (or the save's own availability rebuild) was reading the site's locations used to leave that store off the storefront for 30 minutes this way. A pod that put the old value just before another pod's broadcast reached it can still do so, which is whyLocationCacheEvictionListenerevicts a second time 2 s after each location change. - An eviction clears Redis before L1. Clearing L1 first left a gap: a read
that missed L1 found the old value still in Redis and copied it back into L1,
where it outlived the eviction for up to the L1's 5 s. The eviction count moves
before the Redis
DELand again after it, so a read Redis answered with the old value sees it move and leaves L1 alone; clears work the same way. @Cacheable(sync = true)gets the same check. It loads through Redis's own loader (TieredCache.get(key, Callable)), which is aGET, the load and aSET, with nothing stopping aDELlanding in between.TieredCachetakes the eviction count before it reads and, when it has moved by the time Redis returns, evicts what Redis just stored. Before this, a menu save while a request was rebuilding the menu (oldMenuNodesissync) could leave the old menu in Redis for 30 minutes.
TieredCacheInterleavingTest checks all of this. It runs a read and a save one
call at a time, tries every order of their calls into L1, Redis and the data, and
fails (printing the order) if either tier still holds the old value once the save
has finished. Each race above was first seen as an intermittently failing
integration test, and fails it on every run when its fix is reverted. When you
change TieredCache, add the new path to its scenarios rather than relying on
an integration test to catch a race.
| Tiered cache | Read by | Invalidation | Worst-case staleness on another pod |
|---|---|---|---|
siteContexts-id, siteContexts-domain |
TenantResolutionFilter, every request (copy-on-read) |
SiteContextCacheEvictionListener on any SiteContext save/delete, in any app, + broadcast |
one broadcast hop; 5 s if the broadcast is lost |
siteConfiguration |
SuperSiteConfigService, many times per request |
@CacheEvict on SiteConfigurationRepository |
5 s |
siteEntitlement |
entitlement checks on gated requests | @CacheEvict on SiteEntitlementRepository |
5 s |
themeContext |
template resolution | @CacheEvict on ThemeRepository |
5 s |
processorConfigurations |
ProcessorConfigurationRepository.findByPipelineNameAndSiteIdOrAllSites, through ProcessorConfigurationService: every pipeline event (each page view fires one), copy-on-read, keyed by pipeline and site |
ProcessorConfigurationCacheEvictionListener clears the whole cache on any save or delete (Mongo mapping events, so the initialisers' bulk loads and any app count; a shared allSites record is in every site's entry), + broadcast |
one broadcast hop; 5 s if the broadcast is lost |
variantGroups |
VariantGroupRepository.findByCatalogueId: a catalogue's sizes and colours, read by every shoppable image block and by product pages (copy-on-read, keyed by catalogueId) |
@CacheEvict(allEntries) on every repository write (site transfer, MCP and setup write through the repository directly) |
5 s on other pods |
locations |
LocationRepository.findBySiteIdOrderBySourcingPriorityAscNameAsc: the header's store list, stock availability and shipping locations, several times per storefront page (copy-on-read, keyed by siteId) |
LocationCacheEvictionListener on LocationChangedEvent, which every write through LocationServiceImpl publishes, in any app (the worker writes locations too, and the field-level updates bypass Mongo's mapping events), + broadcast, then the same again 2 s later |
one broadcast hop; 5 s if the broadcast is lost; up to 2 s if another pod's read put the old list back |
collectionRestrictions |
CollectionService.findCollectionAccess: the site's staff-only collections (roles, what each covers) and the unrestricted ones, keyed by catalogue, read by ShopperAccessService several times per storefront request |
@CacheEvict (tiered) on every CollectionRepository write; a site import's SiteCacheService.evictAll |
5 s |
activeTaxonomy |
TaxonomyService.getActiveTaxonomy only (TaxonomyRepository.readByIdAndCatalogueId), several times per listing page. Shared instance: read-only, editors read through taxonomy |
@CacheEvict on every TaxonomyRepository write, TaxonomyService writes through MongoTemplate and site flushes, + broadcast from TaxonomyService |
one broadcast hop; 5 s for writes outside TaxonomyService (worker, seeders) |
oldMenuNodes, menuHash |
navigation | MenuServiceImpl calls SiteCacheService.evictSiteCache for both on a v2 menu save or delete (admin and MCP manageMenus), on a collection save or delete (CollectionIndexEvent: menus list collections and their trees, and which ones a shopper sees), on a merchandising tree change and on a menu-related setting change: the site's Redis keys, this node's L1, and a broadcast for the others |
one broadcast hop |
Why menuHash must leave Redis too
The storefront keeps the menu in the browser and only fetches a new one when
menuHash changes. A CacheInvalidationPublisher broadcast on its own clears
other nodes' L1 and nothing in Redis, so before evictSiteCache a stale hash
kept the old menu on screen for the cache's 30-minute TTL after every edit.
A merchandising change is evicted from Redis only when it is made in a
request for the site (the event carries the catalogue, the keys the site);
otherwise it falls back to the L1 broadcast.
Deliberately not tiered: pages/pageCache/collectionService (one or
two lookups per request, larger values, no copy-on-read audit done) and anything
per-user or per-order (baskets) — mutable, read-modify-written data
must see an eviction on every pod immediately, which only a Redis-only cache
gives.
Other per-request caches¶
| Cache | Manager | Read by | Invalidation | Staleness |
|---|---|---|---|---|
taxonomy |
Redis, one day, unprefixed | TaxonomyService.getActiveTaxonomy (most storefront pages, via the scoped findByIdAndCatalogueId), admin lookups |
@CacheEvict(allEntries) on TaxonomyRepository writes |
none from web/admin/REST; worker writes, the TTL |
merchandisingPrimaryTree |
in-memory, 5 min | MerchandisingTreeSnapshots: the primary tree and its nodes by parent, for category pages' sub-category and sibling links, the top-level categories, the root page, the tree's default facets and BackingToFilterTranslator's group children. A catalogue with no primary tree is cached as empty |
MerchandisingNodeIndexEvent (every tree and node write through MerchandisingTreeService) drops it here and broadcasts; a site flush clears it |
one broadcast hop; 5 min for the demo seeders, which write the repositories directly |
pipelineDefinitions |
in-memory, 5 min | PipelineRegistry's site definitions, "none" included |
PipelineDefinitionServiceImpl save/reset calls PipelineRegistry.evictDefinition, which evicts here and broadcasts |
one broadcast hop |
searchRankingRule |
Redis, 5 min, unprefixed | SearchRankingRuleRepository.findByCatalogueIdAndQuery, every search and in-category search, "no rule" included |
@CacheEvict(allEntries) on every rule write (an edit can change the query) |
none from web/admin/REST; the worker's learned boosts, 5 min |
productReviewSummary |
Redis, 5 min, unprefixed | ProductReviewSummaryRepository.findBySiteIdAndProductId, every product page of a shop with reviews, "no summary" included |
@CacheEvict by key on save and delete |
none from web/admin/REST; worker writes, 5 min |
| bank holidays (global, not per site) | a field in BankHolidayServiceImpl, 1 hour |
WorkingDayCalendarImpl (every delivery promise and slot list): GOV.UK dates the worker stored plus the bundled CSV |
the worker's own copy is dropped when it stores a fetch; nothing broadcast | 1 hour after a weekly fetch (holidays are published months ahead) |
The snapshot's nodes are shared between requests: findVisibleChildren,
findVisibleSiblings and findVisibleTopLevelNodes return them for rendering
links and counting, never for editing. findNodeByPath (the node a category
page renders, which edit mode may change) and everything admin and MCP use
still read their own copy from Mongo.
Code that loads a rule or summary to change and save it reads through the
uncached twin (findOneByCatalogueIdAndQuery, findOneBySiteIdAndProductId),
so a copy the worker made stale never overwrites its change.
Remembered for one request (RequestMemo)¶
Even a cache hit has a cost: the cache proxy, the L1 lookup, and for a Redis
hit a round trip and a deserialisation. RequestMemo (in common, package
cache) remembers a lookup for the rest of the request, so a value read many
times while a page renders is fetched once.
TenantResolutionFilter opens a memo around every storefront GET and HEAD
(not /admin, /system, or any other method). Outside one (the worker, async
threads, REST, tests) RequestMemo.get just runs the loader, so a service
behaves the same with or without it.
| Remembered | Key | Cleared by | Saves |
|---|---|---|---|
TaxonomyService.getActiveTaxonomy |
siteId + catalogueId | any taxonomy save or delete through TaxonomyService, and setting the active taxonomy |
two of the three Redis reads (and deserialisations) of the whole taxonomy on a listing page |
SuperSiteConfigService stored values |
siteId + key + requested type | any write through SuperSiteConfigService |
about 60 lookups through the tiered siteConfiguration cache per listing page |
Rules for adding one:
- Only for values the request doesn't change. Every caller in the request gets the same instance (a remembered taxonomy is shared by the facet rail, the facet labels and the landing rules).
- The key names the tenant. A memo belongs to a thread, not a site.
- Clear it after a write of what it remembers (
RequestMemo.clear()), so the rest of the request sees the change. - A null result is remembered; an exception isn't.
The invalidation broadcast¶
CacheInvalidationPublisher sends a CacheInvalidationEvent to a RabbitMQ
fanout exchange; each pod has its own auto-delete queue bound to it, drained by
CacheInvalidationListener. The publisher serialises with the shared
messageConverter bean from AMQPConfig, which writes the payload's class name
into the __TypeId__ header.
Trusted packages: why the listener names its payload type
On the consuming side spring-amqp refuses to instantiate any class named in
__TypeId__ unless its package is in the converter's trusted list
(AMQPConfig.messageConverter()). The match is exact package equality, not
a prefix, and * (trust all) is not acceptable on a broker shared between
environments.
That check is only reached when the converter has no inferred payload type,
i.e. for a listener that takes a raw Message (as CacheInvalidationListener
does, because its queue is created at runtime) or a bean with several
@RabbitHandler methods. A @RabbitListener method with one concrete bean
parameter supplies the type itself and never hits it.
CacheInvalidationEvent lives in ...settbuilder.cache, which is not
trusted, so until the listener set
messageProperties.setInferredArgumentType(CacheInvalidationEvent.class) every
broadcast was rejected and other pods kept stale caches (invisible on a
single-replica dev cluster, "half applied" in prod). With the type supplied,
__TypeId__ is ignored altogether.
When you add an AMQP-published event type: give the consumer a single
concrete bean parameter; or, if it must take a raw Message, set the inferred
type as above; or, if it needs @RabbitHandler dispatch, put the bean in a
package listed in AMQPConfig.messageConverter() (today
...settbuilder.events.notifications) and add that package explicitly.
AMQPConfigMessageConverterTest and CacheInvalidationListenerTest push real
messages through the configured converter — extend them for a new type.
Flushing a whole site (or everything)¶
Per-entity @CacheEvicts are not enough after a bulk change. They clear the
key prefix of the tenant running the request, so an admin request that
writes another site (System > Tenants runs as the system site, as does a site
import) evicts system_$_..., not the target's entries; and per-pod caches only
hear about what is broadcast. Use SiteCacheService (common/.../cache/)
instead of listing cache names:
| Method | Redis | Every pod |
|---|---|---|
evictAll(siteContext) |
SCAN+DEL of <siteId>_$_* (every tenant-prefixed cache of the site, including ones added later), then the unprefixed siteContexts-*, siteConfiguration, themeContext, locations, processorConfigurations, variantGroups, taxonomy, searchRankingRule and productReviewSummary caches cleared whole |
broadcast CacheInvalidationEvent.SITE_CACHES → SiteCachesEvictedEvent: tiered L1s, the in-memory caches (stereotypes, sitemapXml, siteStructuredData, facet counts, merchandisingPrimaryTree), the site's messages, ExtensionService's model cache entries for the site, CategoryNavigationService's snapshot |
evictEverything() |
SCAN+DEL of *_$_* plus every unprefixed cache; other keys (performance statistics) are left alone |
the same event for every site, plus the message caches and the @DBRef document cache |
evictCache(name) |
both key layouts of one cache (name::*, *_$_name*) |
the cache's L1 / in-memory copy |
evictSiteCache(siteId, name) |
one site's keys of one tenant-prefixed cache (<siteId>_$_name*) |
the cache's L1 / in-memory copy |
The Redis side goes through the circuit-breaking writer, so with Redis down the
clear is queued and replayed on recovery; nothing here throws. Callers today:
the end of a site import (success or failure part-way), the end of a system
initialisation (BadgerInitialiser, which clears and reloads every site's data:
evictEverything()), a start-up that applied system updates (BadgerDataChanger,
evictEverything(), see System Updates), applying a site upgrade,
System > Tenants > {site} > Clear caches, and System > Cache statistics
(clear all / clear one), which used to clear only the pod that served the
request and only the system site's Redis keys.
A per-pod cache that is not a Spring cache (a service's own Caffeine instance)
should listen for SiteCachesEvictedEvent and drop the site's entries
(event.covers(siteId, catalogueId)), or everything when event.everything().
Specific caches¶
Users are not cached¶
UserRepository.getUserById (read by UserResolutionFilter on every storefront
request with a BDGR_USR cookie) deliberately goes to Mongo every time. The
request's User is saved back whole from many places (checkout details,
remember-me rotation, registration), so a cached copy that missed an eviction
would overwrite an admin's change to roles, a ban or a password. It would also
put password hashes and remember-me tokens in Valkey. A Redis hit costs the same
round trip as the _id read it replaces, so there is nothing to win.
The filter itself never writes the user: creating a first-seen visitor's
document and refreshing last-active date and location are queued to the worker,
which applies the activity as a targeted $set (UserService.recordActivity),
not a whole-document save. See Visitor Identity.
@DBRef documents (per pod)¶
Product.images is an eager @DBRef List<Media>. MongoConfiguration installs
CachingDbRefResolver, which serves media documents from
DbRefDocumentCache for both fetch and bulkFetch (hits from cache, misses
in one $in). Only collections in DbRefDocumentCache.CACHEABLE_COLLECTIONS
are cached.
- Stored as
RawBsonDocumentbytes, decoded per read — callers can't mutate cached values; BSON types are preserved. - 32 MB cap, 5-minute TTL.
- Evicted on every pod:
MediaDbRefCacheEvictionListener(Mongo events) andMediaRepositoryImpl'supdateFirstwrites (the worker's AI tagging) go throughDbRefDocumentInvalidator, which evicts locally and broadcastsCacheInvalidationEvent.DBREF_DOCUMENTS. The 5-minute TTL only bounds a lost broadcast. - Metrics:
cache_gets_total{cache="dbRefDocuments"}.
Message source (per pod)¶
BadgerMessageSource uses three dedicated Caffeine caches in the
inMemoryCacheManager: messageCache (50k), messageFormatCache (20k) and
siteSpecificMessageMap (5k), 1-hour TTL. Editing a site's text calls
reloadSiteMessages, which drops that catalogue's entries locally and
broadcasts CacheInvalidationEvent.SITE_MESSAGES; other pods handle it as an
InvalidateMessagesEvent. The TTL is only a backstop for a lost broadcast.
A key the site hasn't customised (nearly every key) is cached as null, which means
"use the platform's text". The caches allow null values, and the lookups read them
with Cache.get(key), whose wrapper tells a cached null apart from a miss.
get(key, String.class) returns null for both, so don't use it here: every
uncustomised key would be looked up and written again on each use.
Extension model caching¶
Separate from the Spring caches above, ExtensionService can cache the model an extension returns (in
ExtensionModelCache, one per node), so
an extension that does real work runs once per scope per TTL instead of on every render. It is opt-in:
BadgerExtension.cachePolicy() defaults to CachePolicy.NONE.
- Scope says what the model may vary on:
SITE,SITE_AUTH(logged in vs anonymous),SITE_ITEM(the product, collection or page being rendered) orSITE_ITEM_AUTH. Declare a scope only if the output is a pure function of it; anything else (the basket, a user's own data, query params, cookies) meansNONE. - Key: tenant, catalogue version, extension name, placement id, then the item (typed, so a page and a
product with the same seoName don't share an entry) and auth state per scope, then
cacheVersion()if the extension supplies one. - In memory, per node (Caffeine, 10,000 entries). Models aren't Redis-serialisable, and a hit returns a shallow copy, so nested values must be treated as read-only.
- Bypassed for edit and inline-edit, form posts and any request with form values.
cacheableFor(requestContext)lets an extension opt out per request (the blog list caches only its unfiltered first page). - Freshness: a publish bumps the catalogue version and drops everything. Saving a page, product,
collection, stereotype (extension placements live on these), site configuration, the site or a taxonomy
also clears that site's cached models on every pod (
ExtensionModelCacheInvalidator, driven by Mongo's save events, so it covers admin, REST, MCP and the worker). Writes are coalesced to one eviction per site or catalogue per second, so an import costs a few evictions, not thousands. Deletes clear every site's models. Writes that bypass Mongo's mapping events (bulk operations,updateMulti) and changes to other data an extension reads (donations, fundraisers, blog posts' media) show when the TTL runs out, so keep TTLs to a few minutes, and a minute for donation-driven data.cacheVersion()(as the global CSS extension uses) remains for anything that needs to be exact. The eviction isSiteCacheService.evictExtensionModels; a site import or "clear caches" (evictAll) also drops that site's cached models.
Opted in: favicon, global CSS, Open Graph, collection chooser, featured products, animation scene,
product bundle, taxonomy attributes, the blog list, latest-posts and related-articles extensions, and the
fundraiser hero, progress, story, updates and donation-widget and donation-display extensions. Log
uk.co.kedos.badger.settbuilder.extensions.ExtensionModelCache at DEBUG for HIT/MISS per render.
Rendered HTML (per pod)¶
A step further than the model: RenderedFragmentCache keeps the HTML an extension's template renders, so a
fragment that prints the same for every shopper is rendered once rather than on every page. The header menu
is the one user so far. Every theme renders the navMenu slot two or three times per page (the bar and the
drawer), and the menu is the largest piece of the header.
- Opting in takes two parts. The extension returns a
renderVersion(model)that changes whenever its HTML would; the menu generator uses its menu hash plus whether it sent the skeleton. The slot'sth:replacealso carriesbdgr:render-cache="${extension[renderCacheKey]}"; every theme'snav.htmlhas it on itsnavMenuinserts. With no version the key is null, and theth:replaceruns as usual. - Key:
ExtensionModelCacheadds the site, catalogue, extension, placement, signed-in state and the shopper's hidden collections (ShopperAccessService.cacheKey). The attribute adds the theme (template resolution attributes), locale, currency, symbol style and tax display. - Only for HTML that is the same for every shopper with the same key: no basket, no forms (their CSRF token is per session), no current-page highlighting. Edit mode and form posts always render.
- Freshness: a menu edit changes the menu hash, and so the key. Entries expire after 5 minutes
(
badger.thymeleaf.rendered-fragment-cache-ttl-seconds), which bounds how far product details in a menu panel can lag. A site flush (SiteCachesEvictedEvent) drops the site's entries. The cache is bounded by size (rendered-fragment-cache-max-chars, 8 million characters). - A miss renders the cached fragment model on its own with
TemplateManager.process. Blank lines in the fragment were already collapsed when its template was parsed (the Kedos ThymeleafWhitespaceCollapsingDialect, seethymeleaf-kedos.md), so the kept HTML needs no further pass. A blank line just before the slot and the fragment's first one can both print, where a per-render collapse would have merged them; browsers render the two the same. - Meter:
cache="renderedFragments".
Thymeleaf's template and expression caches¶
The storefront's SpringTemplateEngine (Boot's, which renders every storefront and admin page) uses
CaffeineThymeleafCacheManager rather than Thymeleaf's StandardCacheManager. That one holds 200 templates
and 500 expressions and evicts first in, first out. An entry is one (owner template, fragment, theme)
combination, so Nova alone needs about 400, and the storefront has about 6,600 distinct expressions. A miss
looks the template up through the theme resolvers and re-parses it during render.
- Sizes:
badger.thymeleaf.template-cache-max-size(4,000) andbadger.thymeleaf.expression-cache-max-size(15,000). - Meters:
cache="thymeleafTemplates"andcache="thymeleafExpressions"(cache_gets_total{result},cache_size,cache_evictions_total). Steady evictions mean the size is too small. - The email and pattern-library engines are built with
newand keep Thymeleaf's defaults.
At the edge (Cloudflare)¶
Cloudflare caches a response only when it is public and sets no cookie. Most storefront
responses are neither: tenant and user resolution set SETT_SITE_ID and BDGR_USR, and
pages are no-store. Static files are kept off that path:
/settBuilder/**and/vendor/**are served from the classpath with a one-yearmax-ageand resolve no tenant or user (TenantResolutionFilter.isNonTenantPath)./favicon.icoand/apple-touch-icon*.png(including-precomposedand the sized forms, which browsers fetch on their own) are answered byIconProbeFilter, ahead of Spring Security and the tenant filters. It finds the shop from the host (the cached domain lookup), then redirects (302) to the shop's icons (ShopIconService, the same ones the page head links), serves the platform favicon, or returns an empty 404. Every answer hasCache-Control: public, max-age=86400and no cookie, so the edge answers repeats per host and a changed icon shows within a day.
A new root-level file that browsers or crawlers request unprompted belongs in one of these, not behind a controller: anything that reaches the tenant and user filters mints a visitor and can't be cached.
Adding a cache — checklist¶
- Redis unless you have a reason; tiered only for read-hot, staleness-tolerant data; per-pod only with a broadcast or a TTL you can live with.
- Decide the key's tenant scope explicitly (prefix, or a key that includes the tenant, or a globally unique id).
- If the value is ever mutated by callers: Redis, or tiered with copy-on-read.
- Evict from every write path. If apps without
@EnableCaching(worker, sync-worker) can write it, evict from a Mongo mapping-event listener rather than@CacheEvict. - Round-trip test the value type through
CacheSerializers. - Never cache
nullfor something that is about to be created. - Don't cache an entity that callers load, modify and save back whole: a stale
copy becomes a lost update (this is why
Userisn't cached). - Keep the TTL at a day or less. It is the backstop for a lost eviction.
- If you broadcast a new payload type, mind the trusted-packages rule (see the invalidation broadcast).
- A per-pod cache outside the three managers must handle
SiteCachesEvictedEvent(see Flushing a whole site), or a site import leaves it stale until its TTL.