assiette 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f24fbf1362c382584825ebb9ea4adf6b0abf0e24ad0b00c0792810b469152be
-  data.tar.gz: 747cafe7a7af67efec260a8ff506eecb390b69225fd8aebf7ff52122175f7a4f
+  metadata.gz: b94d7ebde46d04a55abfd53f02d95c2eb6b4d4df1bda833c98089afbefd1ab1b
+  data.tar.gz: 342adfcac7ade1a593af2f887883314bd35d1ccae4e87f91e503c0008e8db46a
 SHA512:
-  metadata.gz: df6146e2288d39315cd1d045e1af7c7b75e07fc89022d3288c7d52f544e01f4be7bdc1ee5a5a9fcf49d788cf967419801a7259e8477a57f3b3274a59475db1ad
-  data.tar.gz: d29c94ba6524db67f1c8f85a024c1648a9e1ea9ccf60078528ebcf24b1fbfd818181ce3c379b061519bfbd53a75ede042a15fda3734c47baddb7832cde3d4fd3
+  metadata.gz: 26ede00337abc21c2ee238e0e99d7d2143d61cbae84eac72d22210f16cd373c0a41056a9edad881b6a6f049acb353e96605cde191238b6ea643998a4cb255db9
+  data.tar.gz: 7c5507d623a0cc264ecbd8f5776a71aef7ad001753d1117c9e0f8cced9fcbc67542a447d4faca3152d89109cea5e2175fc1a72d564aff1cfc22c2f5162e63361

data/lib/assiette/asset_handler.rb

@@ -1,15 +1,22 @@
 # frozen_string_literal: true
 
 require "pathname"
+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
 
@@ -17,16 +24,38 @@ module Assiette
 
     attr_reader :dependency_graph
 
-    def initialize(root:, additional_directory_mappings: {})
+    # 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)
       @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[File.join(root, "**/*#{ext}")].each do |abs|
+        @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
@@ -73,8 +102,9 @@ module Assiette
     end
 
     def js_modules
+      js_glob = "**/*{#{javascript_extensions.map { |ext| case_insensitive(ext) }.join(",")}}"
       @mappings.flat_map { |prefix, root|
-        Dir[File.join(root, "**/*.{js,mjs}")].filter_map { |abs|
+        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("/")
@@ -83,8 +113,117 @@ module Assiette
       }.uniq { |m| m[:path] }.sort_by { |m| m[:path] }
     end
 
+    # 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
+
+    # 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|

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

@@ -85,6 +85,37 @@ module Assiette
       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
@@ -137,6 +168,13 @@ module Assiette
 
         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

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/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,30 +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
 
       # 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"}")
+      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
 
       raw_bytes = File.binread(file_path)
-      body = @handler.dependency_graph.rewrite_content(path_info, raw_bytes)
+      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.4.0"
+  VERSION = "0.6.0"
 end

data/lib/assiette.rb

@@ -9,6 +9,7 @@ module Assiette
   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.4.0
+  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,6 +36,7 @@ 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
@@ -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: []