assiette 0.3.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1267863146e1fa5c134f47f1cf797123609d8466690d3a39d9603fe9c35787ef
-  data.tar.gz: fcfbe591ac7de77fddb85bfe0d3b2cee0838ef30ac596aef612712b37294511a
+  metadata.gz: b94d7ebde46d04a55abfd53f02d95c2eb6b4d4df1bda833c98089afbefd1ab1b
+  data.tar.gz: 342adfcac7ade1a593af2f887883314bd35d1ccae4e87f91e503c0008e8db46a
 SHA512:
-  metadata.gz: d525c3fb1891574eac36d5b42ac82d5426b7a60e870a8001f4115edc15f32935e5559623a08ad849a6e580917788c25e16d39d64274deec47aa4291c3b399d8a
-  data.tar.gz: 3b35f41fec398a1ed00d3b18f2bec5167d14cd0af451d8cc838fa4f5957c21bf8d349e8fcc0a15d54ceeb788a9c78c0bb30e754baf44350c51961cf4e0836d53
+  metadata.gz: 26ede00337abc21c2ee238e0e99d7d2143d61cbae84eac72d22210f16cd373c0a41056a9edad881b6a6f049acb353e96605cde191238b6ea643998a4cb255db9
+  data.tar.gz: 7c5507d623a0cc264ecbd8f5776a71aef7ad001753d1117c9e0f8cced9fcbc67542a447d4faca3152d89109cea5e2175fc1a72d564aff1cfc22c2f5162e63361

data/lib/assiette/asset_handler.rb

@@ -1,31 +1,71 @@
 # frozen_string_literal: true
 
-require "digest/sha1"
-require "digest/sha2"
-require "base64"
 require "pathname"
-require_relative "version_tag"
+require "digest/sha2"
 
 module Assiette
   class AssetHandler
+    JS_CONTENT_TYPE = "application/javascript"
+
+    # The extensions every handler serves. Individual handlers can add to this
+    # (or override it) through the `content_types:` argument — see #initialize.
     CONTENT_TYPES = {
-      ".js" => "application/javascript",
-      ".mjs" => "application/javascript",
+      ".js" => JS_CONTENT_TYPE,
+      ".mjs" => JS_CONTENT_TYPE,
       ".css" => "text/css",
       ".svg" => "image/svg+xml",
       ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
       ".ico" => "image/x-icon"
     }.freeze
 
     JS_EXTENSIONS = %w[.js .mjs].to_set.freeze
 
-    def initialize(root:, additional_directory_mappings: {})
+    attr_reader :dependency_graph
+
+    # Every extension this handler serves, as ".ext" => content type. This is
+    # CONTENT_TYPES with the `content_types:` argument merged over it.
+    attr_reader :content_types
+
+    # `content_types` registers extra extensions on this handler alone, merged
+    # over CONTENT_TYPES — so it can also override a default mapping. The
+    # defaults themselves are never touched: a handler that was not given an
+    # extension keeps refusing it.
+    #
+    #   AssetHandler.new(root: "...", content_types: {".woff2" => "font/woff2"})
+    #
+    # Extensions are normalized to a leading dot and lowercase, so "woff2",
+    # ".woff2" and ".WOFF2" all register the same thing. Lookups and globs are
+    # case-insensitive as well, so a file on disk named PHOTO.JPG is served
+    # just like photo.jpg.
+    def initialize(root:, additional_directory_mappings: {}, content_types: {})
+      @content_types = CONTENT_TYPES.merge(content_types.to_h { |ext, type| [normalize_extension(ext), type] }).freeze
       @mappings = build_mappings(root, additional_directory_mappings)
-      @integrity_cache = {}
-      @integrity_mutex = Mutex.new
-      @modules_cache = nil
-      @modules_mutex = Mutex.new
-      @modules_version = nil
+      @dependency_graph = DependencyGraph.new(self)
+    end
+
+    # The content type this handler serves `path` as, or nil if its extension
+    # is not one this handler knows.
+    def content_type_for(path)
+      @content_types[normalize_extension(File.extname(path))]
+    end
+
+    # Yields (url_path, abs_path) for every file with a recognized extension.
+    def each_mapped_file
+      @mappings.each do |prefix, root|
+        @content_types.each_key do |ext|
+          Dir.glob(File.join(root, "**/*#{case_insensitive(ext)}")).each do |abs|
+            relative = Pathname.new(abs).relative_path_from(root).to_s
+            url_path = if prefix.empty?
+              relative
+            else
+              "#{prefix}/#{relative}"
+            end
+            yield url_path, abs
+          end
+        end
+      end
     end
 
     def resolve_file(path)
@@ -51,44 +91,139 @@ module Assiette
     def absolute_asset_url_path(path, script_name = "")
       clean = path.sub(%r{\A/}, "")
       return nil unless resolve_file(clean)
-      "#{script_name}/#{clean}?v=#{Assiette.version_tag}"
+      hash = @dependency_graph.tree_sha(clean) || "00000000"
+      "#{script_name}/#{clean}?s=#{hash}"
     end
 
     def asset_integrity(path)
-      version_tag = Assiette.version_tag
-      @integrity_mutex.synchronize do
-        if @integrity_version != version_tag
-          @integrity_cache = {}
-          @integrity_version = version_tag
-        end
-        return @integrity_cache[path] if @integrity_cache.key?(path)
-
-        clean = path.sub(%r{\A/}, "")
-        @integrity_cache[path] = compute_integrity(clean, version_tag)
-      end
+      clean = path.sub(%r{\A/}, "")
+      return nil unless resolve_file(clean)
+      @dependency_graph.tree_integrity(clean)
     end
 
     def js_modules
-      version_tag = Assiette.version_tag
-      @modules_mutex.synchronize do
-        return @modules_cache if @modules_version == version_tag
+      js_glob = "**/*{#{javascript_extensions.map { |ext| case_insensitive(ext) }.join(",")}}"
+      @mappings.flat_map { |prefix, root|
+        Dir.glob(File.join(root, js_glob)).filter_map { |abs|
+          next unless File.foreach(abs).any? { |line| line.match?(/\A\s*(import|export)\s/) }
+          relative = Pathname.new(abs).relative_path_from(root).to_s
+          mod_path = "/#{"#{prefix}/" unless prefix.empty?}#{relative}".squeeze("/")
+          {path: mod_path, integrity: asset_integrity(mod_path)}
+        }
+      }.uniq { |m| m[:path] }.sort_by { |m| m[:path] }
+    end
 
-        @modules_cache = @mappings.flat_map { |prefix, root|
-          Dir[File.join(root, "**/*.{js,mjs}")].filter_map { |abs|
-            next unless File.foreach(abs).any? { |line| line.match?(/\A\s*(import|export)\s/) }
-            relative = Pathname.new(abs).relative_path_from(root).to_s
-            mod_path = "/#{"#{prefix}/" unless prefix.empty?}#{relative}".squeeze("/")
-            {path: mod_path, integrity: asset_integrity(mod_path)}
-          }
-        }.uniq { |m| m[:path] }.sort_by { |m| m[:path] }
+    # A single 16-char hex hash covering every asset this handler can serve.
+    # Fold it into a page's ETag and the page stops validating as soon as any
+    # Assiette URL on it would come out different.
+    #
+    # This is not a sweep over every mapped file — it hashes the dependency
+    # graph's apexes, whose digests already fold in everything they reach.
+    def digest
+      ensure_graph_populated!
+      combined = Digest::SHA256.new
+      @dependency_graph.apex_paths.each do |url_path|
+        combined << url_path << "\0" << @dependency_graph.tree_sha(url_path).to_s << "\0"
+      end
+      combined.hexdigest[0, 16]
+    end
 
-        @modules_version = version_tag
-        @modules_cache
+    # A hash covering exactly the assets named in `url_paths`, for a page that
+    # knows its own entry points and wants a validator scoped to them:
+    #
+    #   fresh_when(@post, etag: handler.digest_for(["/application.css", "/js/app.js"]))
+    #
+    # Naming the nodes is what makes this cheap, and short. Each one's
+    # fingerprint already folds in its whole import subtree, so one entry module
+    # covers however many files hang off it, and nothing has to be discovered —
+    # no glob, no apex set, no populated graph, just one `File.mtime` per named
+    # node and per node below it that the graph already holds.
+    #
+    # An unknown path hashes as the empty string, so a page keeps busting when
+    # an asset it links is deleted or renamed away. What this cannot cover is a
+    # page that renders a listing of whatever the handler holds — the
+    # modulepreload tags — because that depends on which files exist, not only
+    # on the ones named here. Use #digest for those.
+    def digest_for(url_paths)
+      combined = Digest::SHA256.new
+      url_paths.map { |path| path.sub(%r{\A/}, "") }.uniq.sort.each do |url_path|
+        combined << url_path << "\0" << @dependency_graph.tree_sha(url_path).to_s << "\0"
       end
+      combined.hexdigest[0, 16]
     end
 
     private
 
+    # The extensions served as JavaScript: .js and .mjs, plus anything this
+    # handler had registered with a JavaScript content type.
+    def javascript_extensions
+      @content_types.select { |_ext, content_type| content_type == JS_CONTENT_TYPE }.keys
+    end
+
+    # Dir.glob ignores File::FNM_CASEFOLD - "Case sensitivity depends on your
+    # system" - so on Linux a "*.jpg" pattern walks straight past PHOTO.JPG.
+    # Fold the case into the pattern itself instead: ".jpg" => ".[jJ][pP][gG]".
+    def case_insensitive(extension)
+      extension.gsub(/[a-z]/) { |char| "[#{char}#{char.upcase}]" }
+    end
+
+    # ".JPG", "jpg" and ".jpg" all name the same extension.
+    def normalize_extension(extension)
+      ext = extension.to_s.downcase
+      ext.start_with?(".") ? ext : ".#{ext}"
+    end
+
+    # The apex set is only meaningful over a fully populated graph, and the
+    # graph is lazy — asking it opportunistically gives different answers
+    # depending on what has been requested so far, which would have two Puma
+    # workers computing different ETags for identical content.
+    #
+    # The walk is amortised behind a directory-mtime guard rather than a glob
+    # per call. Directory mtimes move when an entry is added, removed or
+    # renamed — exactly the events that change the file list. Editing a file in
+    # place does not move them, and does not need to: the graph checks per-file
+    # mtimes on every access.
+    def ensure_graph_populated!
+      return if watched_directories_unchanged?
+      each_mapped_file { |url_path, _abs_path| @dependency_graph[url_path] }
+      @dependency_graph.prune_deleted!
+      @watched_directories = directory_mtimes
+    end
+
+    def watched_directories_unchanged?
+      return false unless @watched_directories
+      @watched_directories.all? { |dir, mtime| File.mtime(dir) == mtime }
+    rescue Errno::ENOENT
+      false
+    end
+
+    # Every directory under every mapped root, with its mtime.
+    #
+    # Watching only the directories that held a servable file leaves a hole
+    # right where it hurts. Adding app/assets/js/new_thing/a.js moves the mtime
+    # of app/assets/js — but if that directory holds no servable file of its
+    # own it was never watched, and the new asset stays invisible to the
+    # digest: every page keeps validating while linking HTML that has no idea
+    # the file exists. Watching the intermediate directories too costs one more
+    # `stat` apiece per call and closes it.
+    #
+    # nil rather than an empty Hash when there is nothing to watch, because an
+    # empty Hash reads as "nothing changed" forever — a root that does not
+    # exist yet would never be picked up once it did.
+    def directory_mtimes
+      mtimes = {}
+      @mappings.each do |_prefix, root|
+        next unless root.directory?
+        [root.to_s, *Dir.glob(File.join(root, "**/"))].each do |dir|
+          path = dir.chomp("/")
+          mtimes[path] ||= File.mtime(path)
+        end
+      end
+      mtimes.empty? ? nil : mtimes
+    rescue Errno::ENOENT
+      nil # something vanished mid-walk; re-walk on the next call
+    end
+
     def build_mappings(root, additional_directory_mappings)
       mappings = [["", Pathname.new(root).expand_path]]
       additional_directory_mappings.each do |prefix, path|
@@ -97,19 +232,5 @@ module Assiette
       end
       mappings
     end
-
-    def compute_integrity(clean, version_tag)
-      file_path = resolve_file(clean)
-      return nil unless file_path
-
-      raw = File.read(file_path)
-      ext = File.extname(clean)
-      served = case ext
-      when ".js", ".mjs" then Rewriter.rewrite_js_imports(raw, version_tag)
-      when ".css" then Rewriter.rewrite_css_urls(raw, version_tag)
-      else raw
-      end
-      "sha256-#{Base64.strict_encode64(Digest::SHA256.digest(served))}"
-    end
   end
 end

data/lib/assiette/controller_etag.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Assiette
+  # Extends ActionController::Base with a one-line macro that folds the
+  # Assiette apex digest into every ETag the controller generates.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include_assiette_etags!
+  #   end
+  #
+  # Without this, a page whose ETag is built from the code revision plus model
+  # cache keys keeps validating after you edit a stylesheet — neither of those
+  # moved — and a caching layer happily serves stored HTML linking the previous
+  # ?s= hash.
+  #
+  # The value folded in covers every asset the request's handlers can serve,
+  # rather than the ones this particular page happens to link. That is the
+  # coarse answer, and it is the only one available before the template runs:
+  # `etag` blocks are evaluated inside `fresh_when`, in the action, and skipping
+  # the render is the entire point of a conditional GET. A page that wants a
+  # narrower validator can name its entry points and pass
+  # AssetHandler#digest_for to fresh_when itself.
+  module ControllerEtag
+    def include_assiette_etags!
+      etag do
+        # Every handler that saw the request, not only the innermost one. The
+        # view helpers resolve an asset against the whole stack, so a page can
+        # link assets an outer handler serves — and a change to one of those
+        # has to move this page's ETag just the same.
+        #
+        # Resolved off the Rack env rather than Rails.application.assets so
+        # this works in mode 1 too.
+        stack = request.env["assiette.stack"]
+        stack.map { |entry| entry[:handler].digest }.join("/") if stack&.any?
+      end
+    end
+  end
+end

data/lib/assiette/dependency_graph.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+require "base64"
+require "pathname"
+
+module Assiette
+  class DependencyGraph
+    # Per-file node in the dependency graph.
+    class Asset
+      attr_reader :url_path
+      attr_accessor :abs_path, :mtime, :digest, :deps, :dependents
+
+      def initialize(url_path:, abs_path:, mtime:)
+        @url_path = url_path.freeze
+        @abs_path = abs_path
+        @mtime = mtime
+        @digest = nil
+        @deps = []
+        @dependents = Set.new
+      end
+
+      # 8-char hex hash for ?s= cache-busting query params.
+      def checksum_tag
+        digest&.unpack1("H8")
+      end
+
+      # SRI integrity string for integrity= attributes.
+      def sri_integrity
+        return nil unless digest
+        "sha256-#{Base64.strict_encode64(digest)}"
+      end
+
+      # Whether this asset's file has changed since last scan.
+      def stale?
+        File.mtime(abs_path) != mtime
+      rescue Errno::ENOENT
+        true
+      end
+
+      # Whether the file no longer exists on disk.
+      def deleted?
+        !File.exist?(abs_path.to_s)
+      end
+    end
+
+    def initialize(handler)
+      @handler = handler
+      @mutex = Mutex.new
+      @assets = {}
+    end
+
+    # Returns the Asset for a url_path, or nil.
+    def [](url_path)
+      @mutex.synchronize do
+        ensure_asset!(url_path)
+      end
+    end
+
+    # Returns the 8-char hex content hash for a URL path.
+    def tree_sha(url_path)
+      self[url_path]&.checksum_tag
+    end
+
+    # Returns the SRI integrity string for a URL path.
+    def tree_integrity(url_path)
+      self[url_path]&.sri_integrity
+    end
+
+    # Resolves a relative import path to a URL path.
+    def resolve_import_for(from_url_path, relative_path)
+      if relative_path.start_with?("/")
+        relative_path.sub(%r{\A/}, "")
+      else
+        dir = File.dirname(from_url_path)
+        File.expand_path(relative_path, "/#{dir}").sub(%r{\A/}, "")
+      end
+    end
+
+    # Rewrites content with per-dependency hashes. Thread-safe.
+    def rewrite_content(url_path, raw_content)
+      @mutex.synchronize do
+        ensure_asset!(url_path)
+        rewrite_content_internal(url_path, raw_content)
+      end
+    end
+
+    # URL paths of the graph's apexes — assets nothing else imports or
+    # references. Every apex's digest already folds in its entire dependency
+    # subtree, so hashing the apexes hashes the whole graph with each file
+    # counted exactly once.
+    #
+    # A cycle that nothing points into has no member with empty dependents, so
+    # it would silently drop out. Rather than keeping SCC bookkeeping around
+    # (it is discarded once resolution finishes), walk down from the apexes and
+    # adopt whatever was never reached.
+    def apex_paths
+      @mutex.synchronize do
+        apexes = @assets.each_value.select { |asset| asset.dependents.empty? }.map(&:url_path)
+        reached = Set.new
+        queue = apexes.dup
+        while (url_path = queue.shift)
+          next unless reached.add?(url_path)
+          queue.concat(@assets[url_path]&.deps || [])
+        end
+        (apexes + (@assets.keys - reached.to_a)).sort
+      end
+    end
+
+    # Drops nodes whose files have disappeared from disk. Assets that something
+    # still imports get pruned as a side effect of resolving their dependents,
+    # but an orphan that nobody points at is never revisited and would linger.
+    def prune_deleted!
+      @mutex.synchronize do
+        @assets.each_value.select(&:deleted?).each { |asset| remove_asset!(asset.url_path) }
+      end
+    end
+
+    # Forces a full rebuild on next access.
+    def invalidate!
+      @mutex.synchronize do
+        @assets = {}
+      end
+    end
+
+    private
+
+    # Lazily resolve a single asset and its transitive dependencies.
+    # Returns the Asset or nil if the file doesn't exist.
+    def ensure_asset!(url_path)
+      @resolving = Set.new
+      @checked = Set.new
+      @cycle_groups = []
+      asset = resolve_asset!(url_path)
+      # Process any cycles detected during resolution
+      @cycle_groups.each { |scc| compute_cycle_digests(scc) }
+      @resolving = nil
+      @checked = nil
+      @cycle_groups = nil
+      asset
+    end
+
+    # Recursive resolution. Detects cycles via @resolving set.
+    # @checked prevents re-verifying the same asset within one ensure_asset! call.
+    # Returns the Asset or nil. Also returns whether anything changed downstream.
+    def resolve_asset!(url_path)
+      # Already verified fresh in this ensure_asset! call
+      return @assets[url_path] if @checked.include?(url_path)
+
+      existing = @assets[url_path]
+      if existing
+        if existing.deleted?
+          remove_asset!(url_path)
+          return nil
+        end
+
+        if existing.stale?
+          rescan_asset!(existing)
+          @checked << url_path
+          return existing
+        end
+
+        # Not stale itself — but deps might be. Check them recursively.
+        @checked << url_path
+        old_dep_digests = existing.deps.map { |dp| @assets[dp]&.digest }
+        existing.deps.each { |dp| resolve_asset!(dp) }
+        new_dep_digests = existing.deps.map { |dp| @assets[dp]&.digest }
+
+        if old_dep_digests != new_dep_digests
+          compute_digest_for(url_path)
+          # And tell whoever imports this one, exactly as rescan_asset! does.
+          # Without it a node recomputed here keeps stale dependents: they
+          # compare their deps' digests from before and after their own visit,
+          # and a dep already updated during an earlier visit looks unchanged.
+          # Their rewritten content carries the new ?s= while their own
+          # fingerprint still says otherwise, so nobody refetches them.
+          propagate_to_dependents!(existing)
+        end
+
+        return existing
+      end
+
+      # Resolve url_path to an absolute path
+      abs_path = @handler.resolve_file(url_path)
+      return nil unless abs_path
+
+      # Cycle detection
+      unless @resolving.add?(url_path)
+        return @assets[url_path]
+      end
+
+      # Create the asset node
+      asset = @assets[url_path] = Asset.new(
+        url_path: url_path,
+        abs_path: abs_path,
+        mtime: File.mtime(abs_path)
+      )
+      asset.deps = parse_deps(url_path, File.read(abs_path))
+
+      # Recursively resolve dependencies
+      in_cycle = false
+      asset.deps.each do |dep_path|
+        if @resolving.include?(dep_path) && !@assets[dep_path]&.digest
+          in_cycle = true
+        end
+        dep = resolve_asset!(dep_path)
+        dep.dependents << url_path if dep
+      end
+
+      if in_cycle || asset.deps.any? { |dp| @resolving.include?(dp) && !@assets[dp]&.digest }
+        scc = collect_cycle(url_path)
+        @cycle_groups << scc unless scc.empty?
+      else
+        compute_digest_for(url_path)
+      end
+
+      @checked << url_path
+      @resolving.delete(url_path)
+      asset
+    end
+
+    # Collect strongly connected component members starting from url_path.
+    def collect_cycle(url_path)
+      visited = Set.new
+      stack = [url_path]
+      members = Set.new
+
+      while (node = stack.pop)
+        next unless visited.add?(node)
+        asset = @assets[node]
+        next unless asset
+        members << node if @resolving.include?(node)
+        asset.deps.each do |dep|
+          stack << dep if @resolving.include?(dep)
+        end
+      end
+
+      members.to_a
+    end
+
+    # Re-read a stale asset, re-parse deps, recursively ensure deps fresh, recompute digest.
+    def rescan_asset!(asset)
+      url_path = asset.url_path
+      asset.mtime = File.mtime(asset.abs_path)
+
+      # Remove old reverse links
+      asset.deps.each do |dep_path|
+        dep = @assets[dep_path]
+        dep&.dependents&.delete(url_path)
+      end
+
+      # Re-parse imports
+      raw = File.read(asset.abs_path)
+      asset.deps = parse_deps(url_path, raw)
+
+      # Recursively ensure deps are fresh
+      asset.deps.each do |dep_path|
+        dep = resolve_asset!(dep_path)
+        dep.dependents << url_path if dep
+      end
+
+      # Recompute digest
+      compute_digest_for(url_path)
+
+      # Propagate to dependents already in the graph
+      propagate_to_dependents!(asset)
+    end
+
+    # Recompute digests for all transitive dependents of an asset.
+    def propagate_to_dependents!(asset)
+      queue = asset.dependents.to_a
+      visited = Set.new
+      while (dep_url = queue.shift)
+        next unless visited.add?(dep_url)
+        dep_asset = @assets[dep_url]
+        next unless dep_asset
+        compute_digest_for(dep_url)
+        queue.concat(dep_asset.dependents.to_a)
+      end
+    end
+
+    def parse_deps(url_path, raw)
+      ext = File.extname(url_path)
+      import_paths = case ext
+      when ".js", ".mjs", ".es" then Rewriter.extract_js_imports(raw)
+      when ".css" then Rewriter.extract_css_urls(raw)
+      else []
+      end
+      import_paths.map { |p| resolve_import_for(url_path, p) }
+    end
+
+    def compute_digest_for(url_path)
+      asset = @assets[url_path]
+      return unless asset
+
+      raw = File.read(asset.abs_path)
+      if asset.deps.empty?
+        asset.digest = Digest::SHA256.digest(raw)
+      else
+        rewritten = rewrite_content_internal(url_path, raw)
+        asset.digest = Digest::SHA256.digest(rewritten)
+      end
+    end
+
+    # For cyclic dependencies: hash all members' raw contents together.
+    def compute_cycle_digests(scc)
+      combined = scc.sort.filter_map { |url_path|
+        asset = @assets[url_path]
+        next unless asset
+        File.read(asset.abs_path)
+      }.join("\0")
+
+      digest = Digest::SHA256.digest(combined)
+      scc.each do |url_path|
+        asset = @assets[url_path]
+        asset.digest = digest if asset
+      end
+    end
+
+    def rewrite_content_internal(url_path, raw_content)
+      ext = File.extname(url_path)
+      case ext
+      when ".js", ".mjs", ".es"
+        Rewriter.rewrite_js_imports(raw_content) do |import_path|
+          resolved = resolve_import_for(url_path, import_path)
+          @assets[resolved]&.checksum_tag || "00000000"
+        end
+      when ".css"
+        Rewriter.rewrite_css_urls(raw_content) do |ref_path|
+          resolved = resolve_import_for(url_path, ref_path)
+          @assets[resolved]&.checksum_tag || "00000000"
+        end
+      else
+        raw_content
+      end
+    end
+
+    def remove_asset!(url_path)
+      asset = @assets.delete(url_path)
+      return unless asset
+
+      asset.deps.each do |dep_path|
+        dep = @assets[dep_path]
+        dep&.dependents&.delete(url_path)
+      end
+    end
+  end
+end

data/lib/assiette/helpers.rb

@@ -3,18 +3,18 @@
 module Assiette
   module Helpers
     # Returns the URL path to an asset served by Assiette, with a cache-busting
-    # version tag appended.
+    # version tag appended. Returns nil if no handler in the stack has the file.
     def assiette_asset_path(path)
-      entry = request.env["assiette.stack"]&.last
-      raise "No Assiette::Server in middleware stack" unless entry
+      entry = assiette_entry_resolving(path)
+      return unless entry
       entry[:handler].absolute_asset_url_path(path, entry[:script_name])
     end
 
     # Returns the SRI integrity hash for an asset, computed over the served
     # (rewritten) content. Returns nil if the file is not found.
     def assiette_asset_integrity(path)
-      entry = request.env["assiette.stack"]&.last
-      raise "No Assiette::Server in middleware stack" unless entry
+      entry = assiette_entry_resolving(path)
+      return unless entry
       entry[:handler].asset_integrity(path)
     end
 
@@ -27,14 +27,36 @@ module Assiette
     # Generates <link rel="modulepreload"> tags for all detected ES modules
     # under the configured asset roots. Each tag includes an SRI integrity
     # hash computed over the served (rewritten) content.
+    #
+    # Unlike the path helpers this stays scoped to a single handler — the
+    # innermost Server in the stack — on purpose. It renders a listing of
+    # everything a handler holds, so walking the stack would put one tenant's
+    # file list on another tenant's page.
     def assiette_modulepreload_tags
-      entry = request.env["assiette.stack"]&.last
-      raise "No Assiette::Server in middleware stack" unless entry
-      modules = entry[:handler].js_modules
-      safe_join(modules.map { |mod|
-        tag.link(rel: "modulepreload", href: assiette_asset_path(mod[:path]),
+      entry = assiette_stack.last
+      handler = entry[:handler]
+      safe_join(handler.js_modules.map { |mod|
+        tag.link(rel: "modulepreload",
+          href: handler.absolute_asset_url_path(mod[:path], entry[:script_name]),
           integrity: mod[:integrity], crossorigin: "anonymous")
       }, "\n")
     end
+
+    private
+
+    def assiette_stack
+      stack = request.env["assiette.stack"]
+      raise "No Assiette::Server in middleware stack" if stack.nil? || stack.empty?
+      stack
+    end
+
+    # Walks the stack from the innermost Server outwards and returns the first
+    # entry whose handler actually has the file. With one Server mounted that is
+    # simply the only entry; with several — an app serving a per-tenant
+    # directory next to a shared one — the innermost is not necessarily the one
+    # holding the asset a page asks for. Returns nil if none of them has it.
+    def assiette_entry_resolving(path)
+      assiette_stack.reverse_each.find { |entry| entry[:handler].resolve_file(path) }
+    end
   end
 end

data/lib/assiette/railtie.rb

@@ -13,5 +13,11 @@ module Assiette
         include Assiette::RailsAssetUrlHelper
       end
     end
+
+    initializer "assiette.controller_etag" do
+      ActiveSupport.on_load(:action_controller_base) do
+        extend Assiette::ControllerEtag
+      end
+    end
   end
 end

data/lib/assiette/rewriter.rb

@@ -15,16 +15,37 @@ module Assiette
 
     module_function
 
-    def rewrite_js_imports(source, version_tag)
+    # Rewrites JS imports with per-import hashes via a block.
+    # The block receives the import path and must return the hash for that import.
+    def rewrite_js_imports(source, &block)
       source.gsub(JS_IMPORT_RE) do
-        "#{$1}#{$2}?v=#{version_tag}#{$1}"
+        quote = $1
+        path = $2
+        hash = yield(path)
+        "#{quote}#{path}?s=#{hash}#{quote}"
       end
     end
 
-    def rewrite_css_urls(source, version_tag)
+    # Rewrites CSS url() references with per-url hashes via a block.
+    # The block receives the url path and must return the hash for that url.
+    def rewrite_css_urls(source, &block)
       source.gsub(CSS_URL_RE) do
-        "url(#{$1}#{$2}?v=#{version_tag}#{$3})"
+        open = $1
+        path = $2
+        close = $3
+        hash = yield(path)
+        "url(#{open}#{path}?s=#{hash}#{close})"
       end
     end
+
+    # Returns an array of import paths found in JS source.
+    def extract_js_imports(source)
+      source.scan(JS_IMPORT_RE).map { |m| m[1] }
+    end
+
+    # Returns an array of url() paths found in CSS source.
+    def extract_css_urls(source)
+      source.scan(CSS_URL_RE).map { |m| m[1] }
+    end
   end
 end

data/lib/assiette/server.rb

@@ -4,19 +4,30 @@ module Assiette
   class Server
     CACHE_CONTROL = "public, max-age=432000, must-revalidate"
 
-    # Accepts either a pre-built handler or keyword args:
+    # Accepts a pre-built handler, something callable returning a handler for
+    # the request at hand, or keyword args:
     #   Server.new(app, handler)
+    #   Server.new(app, ->(env) { Tenant.for(env)&.assiette_handler })
     #   Server.new(app, root: "...", additional_directory_mappings: {})
+    #
+    # The callable form is for applications whose served locations vary per
+    # request — a multi-tenant app hands every tenant its own AssetHandler
+    # rooted in that tenant's directory. It is called once per request with the
+    # Rack env and may return nil, meaning "nothing to serve here": the request
+    # then passes straight through, with no entry added to the handler stack.
     def initialize(app, handler = nil, root: nil, additional_directory_mappings: {})
       @app = app
       @handler = handler || AssetHandler.new(root: root, additional_directory_mappings: additional_directory_mappings)
     end
 
     def call(env)
+      handler = resolve_handler(env)
+      return @app.call(env) unless handler
+
       stack = (env["assiette.stack"] ||= [])
-      stack << {handler: @handler, script_name: env["SCRIPT_NAME"].to_s}
+      stack << {handler: handler, script_name: env["SCRIPT_NAME"].to_s}
 
-      result = serve(env)
+      result = serve(env, handler)
       return result if result
 
       @app.call(env)
@@ -24,37 +35,33 @@ module Assiette
 
     private
 
-    def serve(env)
+    def resolve_handler(env)
+      @handler.respond_to?(:call) ? @handler.call(env) : @handler
+    end
+
+    def serve(env, handler)
       return unless env["REQUEST_METHOD"] == "GET" || env["REQUEST_METHOD"] == "HEAD"
 
       path_info = Rack::Utils.unescape_path(env["PATH_INFO"])
       path_info = path_info.sub(%r{\A/}, "")
 
-      extension = File.extname(path_info)
-      content_type = AssetHandler::CONTENT_TYPES[extension]
+      content_type = handler.content_type_for(path_info)
       return unless content_type
 
-      file_path = @handler.resolve_file(path_info)
+      file_path = handler.resolve_file(path_info)
       return unless file_path
 
-      raw_bytes = File.binread(file_path)
-
-      # ETag from raw bytes for stability
-      etag = %("#{Digest::SHA1.hexdigest(raw_bytes)}")
+      # Use the dependency graph's content hash for the ETag — it reflects
+      # the file's own content plus all its transitive dependencies, and is
+      # already computed as part of serving. This lets us short-circuit with
+      # a 304 before reading the file for rewriting.
+      etag = %("#{handler.dependency_graph.tree_sha(path_info) || "0"}")
       if env["HTTP_IF_NONE_MATCH"] == etag
         return [304, {"etag" => etag, "cache-control" => CACHE_CONTROL}, []]
       end
 
-      query = Rack::Utils.parse_query(env["QUERY_STRING"])
-      tag = query["v"].to_s.empty? ? Assiette.version_tag : query["v"]
-
-      body = if AssetHandler::JS_EXTENSIONS.include?(extension)
-        Rewriter.rewrite_js_imports(raw_bytes, tag)
-      elsif extension == ".css"
-        Rewriter.rewrite_css_urls(raw_bytes, tag)
-      else
-        raw_bytes
-      end
+      raw_bytes = File.binread(file_path)
+      body = handler.dependency_graph.rewrite_content(path_info, raw_bytes)
 
       headers = {
         "content-type" => content_type,

data/lib/assiette/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Assiette
-  VERSION = "0.3.1"
+  VERSION = "0.6.0"
 end

data/lib/assiette.rb

@@ -5,9 +5,11 @@ require_relative "assiette/version"
 module Assiette
   autoload :Rewriter, File.expand_path("assiette/rewriter", __dir__)
   autoload :AssetHandler, File.expand_path("assiette/asset_handler", __dir__)
+  autoload :DependencyGraph, File.expand_path("assiette/dependency_graph", __dir__)
   autoload :Server, File.expand_path("assiette/server", __dir__)
   autoload :Helpers, File.expand_path("assiette/helpers", __dir__)
   autoload :RailsAssetUrlHelper, File.expand_path("assiette/rails_asset_url_helper", __dir__)
+  autoload :ControllerEtag, File.expand_path("assiette/controller_etag", __dir__)
 end
 
 require_relative "assiette/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assiette
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Julik Tarkhanov
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -35,13 +36,14 @@ files:
 - Rakefile
 - lib/assiette.rb
 - lib/assiette/asset_handler.rb
+- lib/assiette/controller_etag.rb
+- lib/assiette/dependency_graph.rb
 - lib/assiette/helpers.rb
 - lib/assiette/rails_asset_url_helper.rb
 - lib/assiette/railtie.rb
 - lib/assiette/rewriter.rb
 - lib/assiette/server.rb
 - lib/assiette/version.rb
-- lib/assiette/version_tag.rb
 - lib/generators/assiette/install/install_generator.rb
 - lib/generators/assiette/install/templates/initializer.rb.tt
 homepage: https://github.com/julik/assiette
@@ -52,6 +54,7 @@ metadata:
   homepage_uri: https://github.com/julik/assiette
   source_code_uri: https://github.com/julik/assiette
   changelog_uri: https://github.com/julik/assiette/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -66,7 +69,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: Zero-build asset serving for Rails engines
 test_files: []

data/lib/assiette/version_tag.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-require "digest/sha1"
-
-module Assiette
-  # Computes a short version tag for cache busting.
-  # In development: timestamp for instant invalidation on each request
-  # In production: derived from APP_REVISION env var or Gemfile.lock digest
-  def self.version_tag
-    @version_tag ||= compute_version_tag
-  end
-
-  def self.reset_version_tag!
-    @version_tag = nil
-  end
-
-  def self.compute_version_tag
-    if Rails.env.development?
-      Time.now.utc.strftime("%Y%m%d%H%M%S")
-    elsif (app_revision = ENV["APP_REVISION"]).present?
-      Digest::SHA1.hexdigest(app_revision)[0, 4]
-    else
-      gemfile_lock_path = Rails.root.join("Gemfile.lock")
-      if gemfile_lock_path.exist?
-        Digest::SHA1.file(gemfile_lock_path).hexdigest[0, 4]
-      else
-        (Time.now.utc.to_i / 300).to_s(16)
-      end
-    end
-  end
-
-  private_class_method :compute_version_tag
-end