hash_public plugin — content hash based alternative to timestamp_public

[yykamei]

The timestamp_public plugin generates cache-busting paths using File.mtime(). This works well in traditional deployment environments, but does not work correctly in all containerized environments.

When building a Docker image, the mtime of files inside the image reflects the mtime on the build host. For example, in a typical CI/CD pipeline using GitHub Actions, git checkout sets the mtime of every file to the checkout time, so each deployment produces a fresh set of mtime values even when file content has not changed. Whether cache-busting works correctly therefore depends on how and where docker build is executed — a dependency that is better avoided.

A content hash is deterministic regardless of the build environment: as long as the file content is the same, the cache-busting path stays the same.

Roda's assets plugin does support content-based hashing for compiled assets, but it only handles CSS and JavaScript files. For other static files such as images, fonts, and downloadable documents, timestamp_public is currently the only cache-busting option available. This gap makes a content-hash-based alternative particularly valuable.

Proposal

Add a new hash_public plugin that uses a digest of the file content (e.g. SHA256) instead of mtime to generate the cache-busting path segment.

Example usage:

plugin :hash_public

route do |r|
  r.hash_public

  r.get "example" do
    # "/static/a1b2c3d4e5f67890/images/foo.png"
    hash_path("images/foo.png")
  end
end

Design notes

• The API would mirror timestamp_public (a hash_path helper and an r.hash_public routing method), keeping it familiar to existing users.
• Since SHA256 hex digests are 64 characters long, which can make URLs unwieldy, it may be worth supporting a :length option to truncate the hash (e.g. 16 characters). Even a truncated hash provides far more uniqueness than is needed for cache busting.
• Computed hashes could be cached in memory (keyed by file path) to avoid repeated disk reads. A mechanism to clear the cache on application restart would be sufficient for most use cases.
• The routing side would use a String matcher (hex pattern) instead of the Integer matcher that timestamp_public uses, which is one reason a separate plugin makes more sense than adding an option to timestamp_public.
• The assets plugin already uses SHA256 for compiled asset filenames (asset_digest), so there is precedent for content-based hashing in Roda.

[jeremyevans]

Thank you for your proposal and pull request (#418). I merged the pull request with some minor changes.