Fingerprinted Cache Tiers

Behaviour#

A fingerprinted file’s URL is derived from its content, so a given URL always means the same bytes and can be cached forever. An HTML page’s URL stays the same while its content changes, so it must be checked on every request. The upload encodes that difference in two passes over the same public/ tree.

Files the first pass has just uploaded are already identical at the destination, so the second pass skips them and they keep their long header. Its job is to give every remaining file the short header and to prune keys the new build no longer produces.

The filtered --delete trap#

What the pattern relies on#

The long tier is only safe because the site generator renames a file whenever its content changes. The pattern trusts the name: a file that is fingerprinted under a different naming scheme falls into the revalidate tier, which is safe but forgoes long caching. A file that matches the pattern but is not content-hashed would be cached for a year with no way to update it.

Invalidation with /* covers the other direction: without it, an edge could keep serving an old page that references the previous build’s assets. CloudFront bills a /* invalidation as a single path.

Examples#

# Hugo fingerprints CSS and JS as name.min.<hash>.ext, so those are safe to cache
# forever. Everything else is revalidated, and only the unfiltered pass may carry
# --delete: filters apply to the destination too, so a filtered delete would
# remove every key the filter excluded.
aws s3 sync public/ "s3://$bucket/" \
	--cache-control 'public, max-age=31536000, immutable' \
	--exclude '*' --include '*.min.*.css' --include '*.min.*.js'
aws s3 sync public/ "s3://$bucket/" --delete \
	--cache-control 'public, max-age=0, must-revalidate'

aws cloudfront create-invalidation --distribution-id "$distribution" --paths '/*' > /dev/null

In a Hugo template, the fingerprinted name comes from piping a resource through minify and fingerprint:

{{ $theme := resources.Get "js/theme.js" | minify | fingerprint }}