assiette 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e320ec60ec5cb1469b38e4bc4bcfc707f1fa044e219e7aee6c94f7a01154e9f
-  data.tar.gz: d73852fffc343121cc86b6e3d6cf1be17c3d9297eada8bc210c858409037345c
+  metadata.gz: e0f3b02555b0eb18e84813e36095d9fbd3528e9d7a61ed529e00c5b3dd6ecd5a
+  data.tar.gz: 20a0ec6ce64278f556608150ba66bf9429bef13f8bc45d41bc71e360f3f0151f
 SHA512:
-  metadata.gz: 1c7591ac6ecc0e9390200a8e567b5fcc8c6c325b67784fe6521a5104f181f2639074cdb5dce319bef10961d94b1c21dc08dfec136fc6628da544b6ad10aec0d0
-  data.tar.gz: cb7a98754dd1617e0d1cb18948ab5b81a8264a0c058fad121089d0b8480a84be64e77ff65b051e09bbc5fe030d9db85f246c54451710f600f32182f1ad8c6b92
+  metadata.gz: f6e01429228aefba47fc36242f8180b074c58c65297ed490ac6b94562988396d1a375acb8b6e31c6a3514f009960f5caf0dc7ffb56dea75d2247886aa89044ef
+  data.tar.gz: 5094d53275d9d5fc760f97c24905a840d55254e768aebfd979928d9afcb8c014819e443ee7e658600dd70aaa26825dcf4b95733581817cc7a9e98b33e91b7fc2

data/lib/assiette/asset_handler.rb

@@ -22,6 +22,9 @@ module Assiette
 
     JS_EXTENSIONS = %w[.js .mjs].to_set.freeze
 
+    # What #expose takes as a handle: "@" and a name, as in "@task_progress"
+    HANDLE_RE = /\A@[a-z0-9][\w.-]*\z/i
+
     attr_reader :dependency_graph
 
     # Every extension this handler serves, as ".ext" => content type. This is
@@ -42,9 +45,46 @@ module Assiette
     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)
+      @exposed = {}
       @dependency_graph = DependencyGraph.new(self)
     end
 
+    # Makes a directory - a gem's, say - available as "@handle/...". Its files
+    # are served at /@handle/..., and an import of "@handle/file.js" from any
+    # module this handler serves is rewritten to that file, fingerprinted:
+    #
+    #   handler.expose("@task_progress", TaskProgress.js_path)
+    #   import { followProgress } from "@task_progress/task_tree.js"
+    #
+    # Several directories under one handle are searched in the order given, and
+    # the root still comes first, so the app's own app/assets/@handle/file.js
+    # wins over the one exposed.
+    #
+    # Exposing a handle again with the same directories does nothing - an
+    # initializer that runs twice is the likely cause, and harmless. With other
+    # directories, the new ones replace the old, with a warning.
+    #
+    # Call it while setting up, before the handler serves anything.
+    def expose(handle, directories)
+      handle = handle.to_s
+      raise ArgumentError, "#{handle.inspect} is not a handle - it needs to look like \"@name\"" unless handle.match?(HANDLE_RE)
+      roots = Array(directories).map { |dir| Pathname.new(dir).expand_path }
+      return self if @exposed[handle] == roots
+      if @exposed.key?(handle)
+        warn "Assiette: #{handle} was exposed from #{@exposed[handle].join(", ")}, and now from #{roots.join(", ")} instead"
+      end
+      @exposed[handle] = roots
+      # A new array rather than changing this one, so a thread walking it is not disturbed
+      @mappings = @mappings.reject { |prefix, _root| prefix == handle } + roots.map { |root| [handle, root] }
+      @watched_directories = nil
+      self
+    end
+
+    # The exposed handles, each with the directories behind it
+    def exposed
+      @exposed.dup
+    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)
@@ -91,8 +131,9 @@ module Assiette
     def absolute_asset_url_path(path, script_name = "")
       clean = path.sub(%r{\A/}, "")
       return nil unless resolve_file(clean)
-      hash = @dependency_graph.tree_sha(clean) || "00000000"
-      "#{script_name}/#{clean}?s=#{hash}"
+      # No digest means the file went away mid-call. A constant tag would get cached like a real version
+      hash = @dependency_graph.tree_sha(clean)
+      hash ? "#{script_name}/#{clean}?s=#{hash}" : "#{script_name}/#{clean}"
     end
 
     def asset_integrity(path)
@@ -101,16 +142,37 @@ module Assiette
       @dependency_graph.tree_integrity(clean)
     end
 
-    def js_modules
-      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] }
+    # The modules to preload: every module under the handler's own roots, and
+    # of the exposed directories only what those modules reach through their
+    # imports. A static import and a literal `import("...")` count alike, since
+    # the graph records both, so the browser is handed the whole tree up front
+    # and discovers nothing on its own. An app that imports one file of a gem
+    # preloads that file and what it pulls in, and none of the gem's other
+    # modules.
+    #
+    # `exposed:` changes what the exposed directories contribute:
+    #
+    #   :imported           what the own modules reach (the default)
+    #   :all                every module of every exposed directory
+    #   :none, []           nothing
+    #   "@gem", ["@a", ..]  every module of those handles, and in the other
+    #                       handles still what is reached - for an app whose
+    #                       `import()` of a gem file is computed at run time,
+    #                       which no scan can see
+    def js_modules(exposed: :imported)
+      own_mappings, exposed_mappings = @mappings.partition { |prefix, _root| !@exposed.key?(prefix) }
+      own = modules_under(own_mappings)
+      whole_handles, follow_imports = case exposed
+      when :imported then [[], true]
+      when :all, true then [@exposed.keys, false]
+      when :none, nil then [[], false]
+      else
+        handles = Array(exposed).map(&:to_s)
+        [handles, handles.any?]
+      end
+      listed = modules_under(exposed_mappings.select { |mapping| whole_handles.include?(mapping.first) })
+      reached = follow_imports ? exposed_modules_imported_by(own) : []
+      (own + listed + reached).uniq { |m| m[:path] }.sort_by { |m| m[:path] }
     end
 
     # A single 16-char hex hash covering every asset this handler can serve.
@@ -154,6 +216,43 @@ module Assiette
 
     private
 
+    # Every file under `mappings` with a JavaScript extension that imports or
+    # exports something, as {path:, integrity:}
+    def modules_under(mappings)
+      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)}
+        }
+      }
+    end
+
+    # The exposed JavaScript modules reached from `modules` by walking the
+    # graph's deps. Listing `modules` resolved each of them already, so the
+    # walk is over nodes that are in memory, with their mtimes checked.
+    def exposed_modules_imported_by(modules)
+      seen = Set.new
+      queue = modules.map { |m| m[:path].delete_prefix("/") }
+      found = []
+      until queue.empty?
+        url_path = queue.shift
+        next unless seen.add?(url_path)
+        asset = @dependency_graph[url_path]
+        next unless asset
+        found << {path: "/#{url_path}", integrity: asset.sri_integrity} if exposed_javascript?(url_path)
+        queue.concat(asset.deps)
+      end
+      found
+    end
+
+    def exposed_javascript?(url_path)
+      @exposed.each_key.any? { |handle| url_path.start_with?("#{handle}/") } &&
+        javascript_extensions.include?(normalize_extension(File.extname(url_path)))
+    end
+
     # The extensions served as JavaScript: .js and .mjs, plus anything this
     # handler had registered with a JavaScript content type.
     def javascript_extensions

data/lib/assiette/dependency_graph.rb

@@ -10,12 +10,15 @@ module Assiette
     class Asset
       attr_reader :url_path
       attr_accessor :abs_path, :mtime, :digest, :deps, :dependents
+      # Set only for cycle members, whose served bytes differ from what the shared digest covers
+      attr_accessor :served_digest
 
       def initialize(url_path:, abs_path:, mtime:)
         @url_path = url_path.freeze
         @abs_path = abs_path
         @mtime = mtime
         @digest = nil
+        @served_digest = nil
         @deps = []
         @dependents = Set.new
       end
@@ -27,8 +30,9 @@ module Assiette
 
       # SRI integrity string for integrity= attributes.
       def sri_integrity
-        return nil unless digest
-        "sha256-#{Base64.strict_encode64(digest)}"
+        sri_digest = served_digest || digest
+        return nil unless sri_digest
+        "sha256-#{Base64.strict_encode64(sri_digest)}"
       end
 
       # Whether this asset's file has changed since last scan.
@@ -67,9 +71,12 @@ module Assiette
       self[url_path]&.sri_integrity
     end
 
-    # Resolves a relative import path to a URL path.
+    # Resolves a relative import path to a URL path. An "@handle/..." path is
+    # already one - see AssetHandler#expose
     def resolve_import_for(from_url_path, relative_path)
-      if relative_path.start_with?("/")
+      if relative_path.start_with?("@")
+        relative_path
+      elsif relative_path.start_with?("/")
         relative_path.sub(%r{\A/}, "")
       else
         dir = File.dirname(from_url_path)
@@ -239,7 +246,7 @@ module Assiette
     end
 
     # Re-read a stale asset, re-parse deps, recursively ensure deps fresh, recompute digest.
-    # Returns false if the file went away while we were looking at it.
+    # Returns true, or false if the file went away while we were looking at it.
     def rescan_asset!(asset)
       url_path = asset.url_path
       raw, mtime = read_or_drop!(asset)
@@ -265,6 +272,9 @@ module Assiette
 
       # Propagate to dependents already in the graph
       propagate_to_dependents!(asset)
+
+      # Not the walk's value: a `while` evaluates to nil, which reads as "gone"
+      true
     end
 
     # Recompute digests for all transitive dependents of an asset.
@@ -275,7 +285,7 @@ module Assiette
     # renamed away lingers in the graph as an importer, and the next edit to
     # anything it used to import tries to read a path that is not there. Its
     # own dependents still have to hear about it: they keep the vanished node
-    # in their deps until they are rescanned, and it rewrites to 00000000 now.
+    # in their deps until they are rescanned, and it rewrites without ?s= now.
     def propagate_to_dependents!(asset)
       queue = asset.dependents.to_a
       visited = Set.new
@@ -322,6 +332,7 @@ module Assiette
 
       raw, _mtime = read_or_drop!(asset)
       return unless raw
+      asset.served_digest = nil
       if asset.deps.empty?
         asset.digest = Digest::SHA256.digest(raw)
       else
@@ -331,17 +342,19 @@ module Assiette
     end
 
     # For cyclic dependencies: hash all members' raw contents together.
+    # That shared digest only fingerprints - each member is served rewritten with
+    # its partners' ?s=, so SRI has to be taken over those bytes or the browser refuses it
     def compute_cycle_digests(scc)
-      combined = scc.sort.filter_map { |url_path|
+      raws = scc.sort.each_with_object({}) do |url_path, acc|
         asset = @assets[url_path]
-        next unless asset
-        read_or_drop!(asset)&.first
-      }.join("\0")
+        raw = asset && read_or_drop!(asset)&.first
+        acc[url_path] = raw if raw
+      end
 
-      digest = Digest::SHA256.digest(combined)
-      scc.each do |url_path|
-        asset = @assets[url_path]
-        asset.digest = digest if asset
+      digest = Digest::SHA256.digest(raws.values.join("\0"))
+      raws.each_key { |url_path| @assets[url_path].digest = digest }
+      raws.each do |url_path, raw|
+        @assets[url_path].served_digest = Digest::SHA256.digest(rewrite_content_internal(url_path, raw))
       end
     end
 
@@ -349,14 +362,14 @@ module Assiette
       ext = File.extname(url_path)
       case ext
       when ".js", ".mjs", ".es"
-        Rewriter.rewrite_js_imports(raw_content) do |import_path|
+        Rewriter.rewrite_js_imports(raw_content, from: url_path) do |import_path|
           resolved = resolve_import_for(url_path, import_path)
-          @assets[resolved]&.checksum_tag || "00000000"
+          @assets[resolved]&.checksum_tag
         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"
+          @assets[resolved]&.checksum_tag
         end
       else
         raw_content

data/lib/assiette/helpers.rb

@@ -32,10 +32,17 @@ module Assiette
     # 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
+    #
+    # Of the exposed directories (AssetHandler#expose) it lists what the app's
+    # own modules import, directly or down the chain, and nothing else: the
+    # import is the selection. `exposed: "@my_gem"` lists all of that handle
+    # instead, for an `import()` the app computes at run time; `exposed: :all`
+    # lists every exposed module and `exposed: []` none. See
+    # AssetHandler#js_modules.
+    def assiette_modulepreload_tags(exposed: :imported)
       entry = assiette_stack.last
       handler = entry[:handler]
-      safe_join(handler.js_modules.map { |mod|
+      safe_join(handler.js_modules(exposed: exposed).map { |mod|
         tag.link(rel: "modulepreload",
           href: handler.absolute_asset_url_path(mod[:path], entry[:script_name]),
           integrity: mod[:integrity], crossorigin: "anonymous")

data/lib/assiette/rewriter.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Assiette
   module Rewriter
     # Matches quoted strings that look like relative/absolute JS import paths.
-    # Handles ./  ../  /  but NOT protocol-relative //
+    # Handles ./  ../  /  but NOT protocol-relative //, and "@handle/..." for a
+    # directory exposed with AssetHandler#expose
     # $1 = quote char, $2 = path including extension
-    JS_IMPORT_RE = /(["'])(\.{0,2}\/(?!\/)[^"']*\.(?:js|mjs|es))\1/
+    JS_IMPORT_RE = /(["'])((?:\.{0,2}\/(?!\/)|@[\w.-]+\/)[^"']*\.(?:js|mjs|es))\1/
 
     # Matches url() in CSS with relative/absolute paths.
     # Handles url(./path), url("./path"), url('../path'), url(/path)
@@ -16,25 +19,42 @@ module Assiette
     module_function
 
     # 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)
+    # The block receives the import path and returns the hash for that import,
+    # or nil to leave the import unversioned.
+    #
+    # An "@handle/..." import that gets a hash is also turned into a path
+    # relative to `from` - the URL path of the file being rewritten - since a
+    # browser cannot resolve a bare "@handle" without an import map. Relative,
+    # so it keeps working under whatever SCRIPT_NAME the handler is mounted at.
+    # One that gets no hash is left as written, for an import map to resolve.
+    def rewrite_js_imports(source, from: "", &block)
       source.gsub(JS_IMPORT_RE) do
         quote = $1
         path = $2
         hash = yield(path)
+        next "#{quote}#{path}#{quote}" unless hash
+        path = relative_to(from, path) if path.start_with?("@")
         "#{quote}#{path}?s=#{hash}#{quote}"
       end
     end
 
+    # "@x/y.js" as seen from the directory of `from`, always starting with ./
+    # or ../ - "y.js" alone would be a bare specifier again
+    def relative_to(from, path)
+      relative = Pathname.new(path).relative_path_from(Pathname.new(File.dirname(from))).to_s
+      relative.start_with?("../") ? relative : "./#{relative}"
+    end
+
     # 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.
+    # The block receives the url path and returns the hash for that url,
+    # or nil to leave the url unversioned.
     def rewrite_css_urls(source, &block)
       source.gsub(CSS_URL_RE) do
         open = $1
         path = $2
         close = $3
         hash = yield(path)
-        "url(#{open}#{path}?s=#{hash}#{close})"
+        hash ? "url(#{open}#{path}?s=#{hash}#{close})" : "url(#{open}#{path}#{close})"
       end
     end
 

data/lib/assiette/server.rb

@@ -18,6 +18,10 @@ module Assiette
     def initialize(app, handler = nil, root: nil, additional_directory_mappings: {})
       @app = app
       @handler = handler || AssetHandler.new(root: root, additional_directory_mappings: additional_directory_mappings)
+      # In Rails a gem exposes its directory from ActiveSupport.on_load(:assiette), which runs on
+      # every handler a Server is built with - whenever the gem's block was registered. A handler
+      # made per request is not announced: the hooks keep every handler they ran on, for ever
+      ActiveSupport.run_load_hooks(:assiette, @handler) if defined?(Assiette::Railtie) && @handler.is_a?(AssetHandler)
     end
 
     def call(env)

data/lib/assiette/version.rb

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

data/lib/generators/assiette/install/templates/initializer.rb.tt

@@ -16,6 +16,10 @@ handler = Assiette::AssetHandler.new(
   }
 )
 
+# Gems that ship JS or CSS for Assiette expose their directories on this
+# handler themselves, as "@some_gem" - import "@some_gem/file.js" from your own
+# modules. Add your own with handler.expose("@name", path).
+
 # Serve files through the shared handler.
 Rails.application.config.middleware.use Assiette::Server, handler
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assiette
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Julik Tarkhanov
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-21 00:00:00.000000000 Z
+date: 2026-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -53,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
@@ -67,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: []