How does new client library code for JS and CSS gets served in my AEMaaCS website after development, staging, production release, and how does the correct version of the client libs are being used on AEMaaCS?
Ensuring that users receive the latest updates—such as new client libraries (CSS and JS)—requires a carefully managed caching strategy. This article explores how cache invalidation is handled upon releasing new code, particularly clientlibs, and uses the Adobe WKND project as an example to explain the process.
1. Introduction
In this article, we will step through how typically an AEMaaCS website serves newly released client-libraries JS and CSS to users, and we will take a look at the Adobe WKND project as an example.
2. Automatic Cache Invalidation: How It Works
Upon releasing new client libraries, AEMaaCS uses versioned clientlibs. This involves adding a unique hash (previous understanding of the hash generated is pretty much converting the entire minified CSS and JS into MD5 Hash – ACS Commons Approach) to the filenames of clientlibs, served on newly fresh requested HTML pages from the AEM publishers, which forces the CDN and browser caches to recognize and fetch the new files. This automatic mechanism helps ensure that users are served the updated versions.
And please keep in mind, it’s the fresh uncached version of the AEM .html pages who actually serves the path of the versioned clientlibs files. Lets understand .html are cached invalidated from the dispatcher and CDN cache.
Examples of hashed client libs:
/etc.clientlibs/settings/wcm/designs/gandalf/clientlibs/css/all.en-us.min.LIHASHed376af2042959edf283b2591e37eff9.css
3. Example Configuration: Adobe WKND Project
In this article, we will purely inspect the Adobe WKND project which is production live code examples of recommended rules for cache invalidating .html files. The following configuration from the WKND project shows how HTML pages are handled in terms of caching:
1 2 3 4 5 6 | <LocationMatch "^/content/.*\.html$"> Header unset Cache-Control Header always set Cache-Control "max-age=300,stale-while-revalidate=3600" "expr=%{REQUEST_STATUS} < 400" Header always set Surrogate-Control "stale-while-revalidate=43200,stale-if-error=43200" "expr=%{REQUEST_STATUS} < 400" Header set Age 0 </LocationMatch> |
4. Breakdown of the Configuration
1. LocationMatch, Targeting HTML Pages:
– The configuration applies to all HTML pages under the /content/ path.
2. Cache-Control Settings:
- max-age=300: HTML pages are cached for 5 minutes. During this time, the CDN serves the cached content without checking with the origin server.
- stale-while-revalidate=3600: After 5 minutes, if a request is made, the CDN serves the stale content and fetches a new version from the server in the background. This background fetch happens within 1 hour, ensuring minimal disruption.
3. Surrogate-Control for CDN:
- stale-while-revalidate=43200: The CDN can continue serving stale content while fetching fresh content for up to 12 hours.
- stale-if-error=43200: In the event of errors fetching the new content, the CDN serves stale content for up to 12 hours.
4. Age Header:
– Header set Age 0: This resets the age of the content to zero, indicating that it is freshly cached.
5. Key Mechanisms and Timings
Initial Cache Period (max-age=300):
– For the first 300 seconds (5 minutes) after the content is cached, the CDN serves the cached version without rechecking with the origin server.
Stale-While-Revalidate (stale-while-revalidate=3600):
– After 5 minutes, the max-age period expires, if a user requests the content, the CDN serves the stale (cached) content immediately and fetches a new version from the origin server in the background. This mechanism ensures that users receive immediate responses, even if the content is slightly outdated, while the cache is refreshed in the background. And again, it’s the fresh uncached version of the AEM .html pages who actually serves the path of the versioned clientlibs files, which is why invalidation on the HTML file is important here.
After Stale-While-Revalidate:
– If a new version has not been successfully fetched within the stale-while-revalidate window (up to 1 hour), and another request is made, the CDN serves the most recently cached version while attempting to fetch the new version again.
6. Conclusion
The correct dispatcher configurations ensures that new client libraries and other updates are served efficiently. The HTML pages need to reference the new clientlibs versioned paths to reflect the latest updates. Since the WKND configuration sets HTML page caching to a maximum of 5 minutes with additional revalidation periods, the new HTML pages and associated clientlibs may not appear immediately; after 5 minutes, if a user requests the content, the CDN serves the stale (cached) content immediately and fetches a new version from the origin server in the background. This mechanism ensures that users receive immediate responses, even if the content is slightly outdated, while the cache is refreshed in the background, the stale-while-revalidate directive helps ensure users see updated content with minimal disruption. This setup minimizes the impact of cache misses and ensures that updated content is available without noticeable delay to the user. This well-balanced approach allows for efficient content delivery while maintaining a seamless user experience.
