assiette 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b94d7ebde46d04a55abfd53f02d95c2eb6b4d4df1bda833c98089afbefd1ab1b
-  data.tar.gz: 342adfcac7ade1a593af2f887883314bd35d1ccae4e87f91e503c0008e8db46a
+  metadata.gz: e0f3b02555b0eb18e84813e36095d9fbd3528e9d7a61ed529e00c5b3dd6ecd5a
+  data.tar.gz: 20a0ec6ce64278f556608150ba66bf9429bef13f8bc45d41bc71e360f3f0151f
 SHA512:
-  metadata.gz: 26ede00337abc21c2ee238e0e99d7d2143d61cbae84eac72d22210f16cd373c0a41056a9edad881b6a6f049acb353e96605cde191238b6ea643998a4cb255db9
-  data.tar.gz: 7c5507d623a0cc264ecbd8f5776a71aef7ad001753d1117c9e0f8cced9fcbc67542a447d4faca3152d89109cea5e2175fc1a72d564aff1cfc22c2f5162e63361
+  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)
@@ -155,7 +162,7 @@ module Assiette
         end
 
         if existing.stale?
-          rescan_asset!(existing)
+          return nil unless rescan_asset!(existing)
           @checked << url_path
           return existing
         end
@@ -239,9 +246,12 @@ module Assiette
     end
 
     # Re-read a stale asset, re-parse deps, recursively ensure deps fresh, recompute digest.
+    # Returns true, or false if the file went away while we were looking at it.
     def rescan_asset!(asset)
       url_path = asset.url_path
-      asset.mtime = File.mtime(asset.abs_path)
+      raw, mtime = read_or_drop!(asset)
+      return false unless raw
+      asset.mtime = mtime
 
       # Remove old reverse links
       asset.deps.each do |dep_path|
@@ -249,8 +259,6 @@ module Assiette
         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
@@ -264,9 +272,20 @@ 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.
+    #
+    # A dependent whose own file has since gone is dropped rather than
+    # recomputed. Nothing ever resolves an orphan from above — it is only
+    # reached from below, through this very walk — so without this a file
+    # 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 without ?s= now.
     def propagate_to_dependents!(asset)
       queue = asset.dependents.to_a
       visited = Set.new
@@ -274,8 +293,12 @@ module Assiette
         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)
+        if dep_asset.deleted?
+          remove_asset!(dep_url)
+        else
+          compute_digest_for(dep_url)
+        end
       end
     end
 
@@ -289,11 +312,27 @@ module Assiette
       import_paths.map { |p| resolve_import_for(url_path, p) }
     end
 
+    # Reads an asset's bytes, together with the mtime they were read at, and
+    # returns nil after dropping the node if the file is not there any more.
+    #
+    # Every read of a path the graph remembers goes through here. Those paths
+    # come from an earlier request, and while the server is up any of them can
+    # be renamed or deleted between two renders — a disappearance has to read
+    # as "gone from the graph", never as an exception out of a view helper.
+    def read_or_drop!(asset)
+      [File.read(asset.abs_path), File.mtime(asset.abs_path)]
+    rescue Errno::ENOENT
+      remove_asset!(asset.url_path)
+      nil
+    end
+
     def compute_digest_for(url_path)
       asset = @assets[url_path]
       return unless asset
 
-      raw = File.read(asset.abs_path)
+      raw, _mtime = read_or_drop!(asset)
+      return unless raw
+      asset.served_digest = nil
       if asset.deps.empty?
         asset.digest = Digest::SHA256.digest(raw)
       else
@@ -303,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
-        File.read(asset.abs_path)
-      }.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
 
@@ -321,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.0"
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assiette
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack