Attempt at supporting Etag caching with Phlex views in rails

[ianwhite]

I've been using the following technique to enable Etag cache keys in a rails app for Phlex views. This approach allows view dependency tracking (so cache is expired when relevant view code changes) and setting cache keys based on ivars or instance methods.

Summary:

• Dependencies are specified via cache_dependency class method, and are recursively resolved
• The resolved dependencies are used to compute a cache_dependencies_digest based on the dependency source files, this is memoized on the class.
• Other cache dependencies can be specified via cache_key class method, and refer to instance methods or ivars
• Thus a Phlex::HTML view instance can provide #cache_key that can be used for Etag support, but also for caching the results of #call
• Currently using rails idioms (ActiveSupport::Concern and friends)

What do others think of this technique? Is it worth creating a rubygem for this?

Here's an example of it in use (see below for the library code)

# app/controllers/presentations_controller.rb
class PresentationsController < ApplicationController
  include Phlex::RenderStale

  def show
    render_stale Presentations::IndexView.new(event:, user:)
  end
end

# app/views/application_component.rb
class ApplicationComponent < Phlex::HTML
  include Phlex::CacheDependency  # add dependency tracking to all components
end

# app/views/application_view.rb
class ApplicationView < ApplicationComponent
  include Phlex::Caching # add the #cache_key only to views
end

# app/views/presentations_component.rb
class PresentationsComponent < ApplicationComponent
  ...
end

# app/views/navbar_component.rb
class NavbarComponent < ApplicationComponent
  cache_dependency BrandingComponent
  ...
end

# app/views/presentations/index_view.rb
class Presentations::IndexView < ApplicationView
  cache_dependency PresentationsComponent, NavbarComponent

  cache_key :@event, :user_has_notifications?

  def initialize(event:, user:)
    @user = user
    @event = event
  end

  def template
    render NavbarComponent.new(event: @event, notifications: user_has_notifications?)
    render PresentationsComponent.new(event: @event)
  end

  def user_has_notifications? = @user.notifications_for_event(@event).any?
end

Presentations::IndexView.cache_dependencies 
# => [Presentations::IndexView, ApplicationView, ApplicationComponent, PresentationsComponent, NavbarComponent, BrandingComponent]
Presentations::IndexView.cache_dependencies_digest 
# => "499b39a0e1289887dc5e3c0f542a80bd" 
# ^ will change if any of the dependency source files change

view = Presentations::IndexView.new(event:, user:)
view.cache_key
# => ["499b39a0e1289887dc5e3c0f542a80bd", #<Event:...>, false]

ActiveSupport::Caching.expand_cache_key(view.cache_key)
# => "499b39a0e1289887dc5e3c0f542a80bd/events/1-20231219104245585961/false"

Library code:

# lib/phlex/caching.rb
module Phlex
  # include into a Phlex component to enable specifying a cache key, and cache dependencies
  module Caching
    extend ActiveSupport::Concern

    included do
      include CacheKey
      include CacheDependency

      cache_key :cache_dependencies_digest
    end

    # You can use Phlex::RenderStale in a controller to render with etag freshness support.
    #
    # Or, to use caching in all rendering, here is an example of using cache_key to cache a component:
    #
    #  def call(...)
    #    Rails.cache.fetch(cache_key, expires_in: 1.hour) do
    #      super
    #    end
    #  end

    def cache_dependencies_digest = self.class.cache_dependencies_digest
  end
end

# lib/phlex/cache_key.rb
module Phlex
  module CacheKey
    extend ActiveSupport::Concern

    included do
      class_attribute :cache_keys, instance_accessor: false, default: []
    end

    module ClassMethods
      def cache_key(*method_or_ivar_names)
        self.cache_keys += method_or_ivar_names
      end
    end

    def cache_key
      @cache_key ||= self.class.cache_keys.map { _1[0] == "@" ? instance_variable_get(_1) : send(_1) }
    end
  end
end

# lib/phlex/cache_dependency.rb
module Phlex
  # Determin a digest of the source files where the cache dependencies are defined.
  #
  # Usage: include this module into a Phlex component to add cache dependency tracking
  #
  # specify dependencies with `cache_dependency`:
  #  cache_dependency EventNavComponent, PresentationsComponent, "SurveysComponent"
  #
  # subclasses will get dependency tracking, and ancestors (and self) are automatically in their dependencies:
  #  class ApplicationComponent < Phlex::HTML
  #    include Phlex::CacheDependency
  #  end
  #
  #  class PresentationComponent < ApplicationComponent
  #  end
  #
  #  class PresentationsComponent < ApplicationComponent
  #    cache_dependency PresentationComponent
  #  end
  #
  #  class EventComponent < ApplicationComponent
  #    cache_dependency PresentationsComponent
  #  end
  #
  #  ApplicationComponent.cache_dependencies   # => [ApplicationComponent]
  #  PresentationComponent.cache_dependencies  # => [PresentationComponent, ApplicationComponent]
  #  PresentationsComponent.cache_dependencies # => [PresentationsComponent, ApplicationComponent,
  #                                                  PresentationComponent]
  #  EventComponent.cache_dependencies         # => [EventComponent, ApplicationComponent, 
  #                                                  PresentationsComponent, PresentationComponent]
  module CacheDependency
    extend ActiveSupport::Concern

    included do
      class_attribute :cache_dependency_names, instance_accessor: false, default: []
    end

    module ClassMethods
      def cache_dependency(*constant_names)
        self.cache_dependency_names += constant_names.map { _1.respond_to?(:name) ? _1.name : _1.to_s }
      end

      def cache_dependencies = CacheDependency.resolve(self)

      def cache_dependencies_digest
        @_cache_dependencies_digest ||= CacheDependency.digest(cache_dependencies)
      end
    end

    # given a constant, return a list of all the constants that it depends on, according to cache_dependency
    def self.resolve(constant, resolved = [])
      return resolved if resolved.include?(constant)

      resolved = resolved + [constant]

      return resolved unless constant.is_a?(CacheDependency::ClassMethods)

      # dependencies are the constant's ancestors that extend CacheDependency, plus its specified cache_dependencies
      dependencies = constant.ancestors.select { _1.is_a? CacheDependency::ClassMethods } +
                     constant.cache_dependency_names.map(&:constantize)

      dependencies.reduce(resolved) do |current_resolved, dependency|
        resolve dependency, current_resolved
      end
    end

    # given an array of constants, return a digest of all the source files where the constants are defined
    def self.digest(constants)
      paths = constants.map { |constant| Object.const_source_location(constant.name)[0] } # get source file paths
                       .select { |path| path && File.exist?(path) }.uniq.sort             # sanitize and sort paths

      paths.reduce(Digest::MD5.new) { |digest, path| digest << File.read(path) } # create digest from paths content
           .hexdigest                                                            # return digest
    end
  end
end

# lib/phlex/render_stale.rb
module Phlex
  # mixin for controllers to render a phlex view, with etag freshness support
  module RenderStale
    def render_stale(view, **kwargs)
      response.cache_control.delete(:no_store)
      response.weak_etag = view.cache_key

      if request.fresh?(response)
        head :not_modified
      else
        render view, **kwargs
      end
    end
  end
end

[ianwhite]

I should also note that I am not using separate layouts in my app, and I do not use rails controller "helper" methods, which makes reasoning about the cache_key much easier. Basically everything that changes a view goes into the View.new(...) call.

[joeldrapper]

This is an interesting solution. I wonder if we could enhance it further by freezing the Phlex::HTML classes after they are first defined? This would effectively guarantee that the contents of the files are the canonical definitions of the classes, since otherwise, you can patch them from anywhere else.

Is it worth creating a rubygem for this?

I’ll need to take some time to review the specifics, but I’d be interested in including this in Phlex core.

[ianwhite]

I wonder if we could enhance it further by freezing the Phlex::HTML classes after they are first defined? This would effectively guarantee that the contents of the files are the canonical definitions of the classes, since otherwise, you can patch them from anywhere else.

That's a good idea, but non Phlex::HTML classes can also be cache_dependencies, eg.

class InvoiceFormatter
  # does some sort of invoice presenting logic that is used by views, and also emails, or something
end

class InvoiceView < ApplicationView
  cache_dependency InvoiceFormatter
end

So, perhaps freezing Phlex::HTML classes (which we have control over) + issuing a warning if a cache_dependency is not frozen?

[ianwhite]

I’ll need to take some time to review the specifics, but I’d be interested in including this in Phlex core.

OK great! Let me know if you'd like me to start a pull request.

Side note: phlex is great (thanks) - and it's been fast enough for my purposes so far without caching, but I'm looking into the new turbo 8 stuff, and there's a lot more full page renders with that approach, and I've determined that I will need caching, hence all this.