Using filemtime to cache bust editor assets is not reliable

[retlehs]

Describe the bug
Gutenberg is using filemtime in several areas when enqueueing assets, such as the editor CSS

When updating Gutenberg, you can run into a scenario where outdated assets are being served because filemtime is cached

To reproduce
Steps to reproduce the behavior:

1. Note the version being attached to Gutenberg assets, such as build/editor/style.css, on the ver query variable seen via dev tools or the source:

   <link rel='stylesheet' id='wp-editor-css'  href='.../plugins/gutenberg/build/editor/style.css?ver=[filemtime generated version is output here]' type='text/css' media='all' />
   

2. Switch or update Gutenberg versions
3. See that the version is not updated until after clearing cache

Expected behavior
The latest version of assets should always be served

In #440 it was suggested to introduce a GUTENBERG_VERSION constant to avoid this problem

Screenshots

Notice how the new breadcrumb bar (which is an awesome new feature ❤️) isn't styled correctly because the cache wasn't busted after updating from 6.7 to 6.8

[paaljoachim]

Hey @retlehs Ben

Thank you for creating this issue!
A long time has passed.
Is this issue still valid?

[retlehs]

@paaljoachim np! yeah, it looks like it is still valid:

• https://github.com/WordPress/gutenberg/search?q=filemtime
• https://github.com/WordPress/gutenberg/blob/13e7ab3e38bbc95d2e5e5e8b76e07bfb313c70e3/lib/client-assets.php

[paaljoachim]

I believe that Ari @aristath and @gziolo might want to know about this issue.

[gziolo]

Thank you for the report. GUTENBERG_VERSION might be good for production, for development we could as well disable caching by using a timestamp of something similar.

In the WordPress core we skip the part that sets version, letting WordPress handle it with its current version:

https://github.com/WordPress/wordpress-develop/blob/c145ff4a1a5a45bdbef775b9b47400fcb3311b85/src/wp-includes/script-loader.php#L1493-L1524

[hellofromtonya]

Using GUTENBERG_VERSION for production makes sense as it's clean, concise, and aligned with how the assets are versioned in core (i.e. editor assets use the WordPress version).

What about for development?

It depends upon whether the goal is for asset specific versioning or global versioning for all assets.

• For asset specific versioning: use clearstatcache with filemtime to clear the realpath cache for the specific file while using the asset file's modification time as its version.

• For global asset version: use time() or microtime() for all like assets.

Notes about filemtime and the realpath cache:

• filemtime hits the filesystem to get the file's modification time
• filemtime is cached for performance in realpath cache
• Realpath cache lifecycle is configurable through php.ini's realpath_cache_ttl
• Realpath cache for a specific file is clearable via clearstatcache( true, [path to the asset file] );

👉 Which versioning is best for development: asset specific versioning or global versioning for all assets?

[hellofromtonya]

I'm having trouble reproducing the problem.

Env:

• Chrome Version 89.0.4389.72
• WordPress 5.7
• Docker wp-env
• Using released versions of the plugin

Steps:

Using GB plugin version 9.9.3:

...gutenberg/build/editor/style.css?ver=1612535758

Updated the plugin to version 10.1.1:

...gutenberg/build/editor/style.css?ver=1615414301

@retlehs can you share more information on how you were able to reproduce this problem?

[hellofromtonya]

Test 2

Using: build/build-directory/style/css
Versions: 9.9.3 vs. 10.1.1

In 9.9.3, I made the following change to the CSS:

:root{--wp-admin-theme-color:#00ba3e;

whereas in 10.1.1 the color:

:root{--wp-admin-theme-color:#007cba;

Objective: Though the version numbers change as noted above, does each plugin's file get served up or is it the cached one?

Start with 9.9.3

Steps:

1. Install version 9.9.3
2. Refreshed the edit post page

Results:

<link rel="stylesheet" id="wp-block-directory-css" href="http://wpcore.local/wp-content/plugins/gutenberg/build/block-directory/style.css?ver=1615418702" media="all">

• the #00ba3e color did render
• the right CSS file was served to the browser

Update to 10.1.1

Steps:

1. Updated to v 10.1.1 through the Plugins screen
2. Refreshed the edit post page

Results:

<link rel="stylesheet" id="wp-block-library-theme-css" href="http://wpcore.local/wp-content/plugins/gutenberg/build/block-library/theme.css?ver=1615418787" media="all">

• Version number is different
• #007cba color renders
• Correct CSS file is served to the browser

Findings

When updating from one version of the plugin to another:

• The version number changed
• The correct stylesheet file was served to the browser (not served from cache)
• filemtime worked as expected without a realpath caching issue

[gziolo]

I checked how we handle assets registered from block.json with register_block_type_from_metadata.

We use filemtime in WP core for styles registered from block.json:
https://github.com/WordPress/wordpress-develop/blob/e20b23d81030a9c57cd6b3a81cf4b01a08679e2e/src/wp-includes/blocks.php#L169-L174

For JS, we let webpack do its thing or the developer has to add an asset file with the required details:
https://github.com/WordPress/wordpress-develop/blob/e20b23d81030a9c57cd6b3a81cf4b01a08679e2e/src/wp-includes/blocks.php#L127-L132

Once we migrate to webpack 5, we definitely should look into outputting a similar asset file for CSS and stop using filemtime.

[hellofromtonya]

Opened PR #29775 which proposes replacing filemtime with the production and development version strategies. While I was unable to reproduce the reported problem, it is conceivable that the realpath cache could produce this problem.

There are other benefits to switching the approach such as simplifying the code and a teeny teeny tiny microseconds execution time boost.

I think it's a good strategy to move forward with the fix. And then as @gziolo notes above, once we migrate to webpack 5, then the stylesheet versioning can also be used to further simplify the package style registrations and make it the same as the scripts registration for consistency.

[retlehs]

closed by #29775 - thank you @hellofromtonya and everyone else who helped!