rails-wayback 0.1.0 → 0.2.0

data/lib/rails_wayback/view_source.rb

@@ -3,51 +3,111 @@
 require "fileutils"
 require "open3"
 require "pathname"
+require "tempfile"
+require "tmpdir"
+require "rails_wayback/cache_inventory"
 
 module RailsWayback
-  # Materialises the view/asset directories of a given git ref into a
-  # sandbox under tmp/, so a controller can prepend that sandbox as a
-  # view path and render the historical templates.
+  # Materialises the view/asset directories of a given git ref into the
+  # refs cache under tmp/, so a controller can prepend those directories
+  # as view paths and render the historical templates.
   #
   # Only the directories listed in `configuration.view_paths` and
   # `configuration.asset_paths` are pulled from the ref. Nothing is
   # executed, and the developer's real files are never mutated.
   class ViewSource
     # Bumped whenever the materialization format changes so stale
-    # sandboxes from earlier gem versions get rebuilt instead of
+    # cached refs from earlier gem versions get rebuilt instead of
     # being reused.
-    MATERIALIZATION_VERSION = "2"
+    MATERIALIZATION_VERSION = CacheInventory::MATERIALIZATION_VERSION
 
     attr_reader :configuration, :git
 
     def initialize(configuration: RailsWayback.configuration, git: RailsWayback::Git.new)
       @configuration = configuration
       @git = git
+      @cache_inventory = CacheInventory.new(configuration: configuration)
     end
 
     def materialize(ref)
       sha = git.resolve_ref(ref)
-      target = configuration.refs_cache_path.join(sha)
-      return target if fresh?(target, sha)
-
-      FileUtils.rm_rf(target)
-      FileUtils.mkdir_p(target)
-      tracked_paths.each { |path| extract_path(sha, path, target) }
-      write_marker(target, sha)
-      target
+      with_cache_lock(File::LOCK_SH) { materialize_locked(sha).first }
     end
 
     def view_root_for(ref)
-      target = materialize(ref)
-      configuration.view_paths.map { |p| target.join(p) }.select(&:directory?)
+      view_roots(materialize(ref))
+    end
+
+    # Keeps a shared cache lease while the caller uses any files from the
+    # materialization. Pruning and cleanup take an exclusive lease, so they
+    # wait until every active user has finished before removing files.
+    def with_materialization(ref)
+      sha = git.resolve_ref(ref)
+      materialized = false
+
+      with_cache_lock(File::LOCK_SH) do
+        target, materialized = materialize_locked(sha)
+        yield target
+      end
+    ensure
+      automatic_prune if materialized
+    end
+
+    def with_view_roots(ref)
+      with_materialization(ref) do |target|
+        yield view_roots(target), target
+      end
     end
 
     def cleanup!
-      FileUtils.rm_rf(configuration.refs_cache_path)
+      with_cache_lock(File::LOCK_EX) do
+        FileUtils.rm_rf(configuration.refs_cache_path)
+        FileUtils.rm_rf(configuration.cache_root_path.join("locks"))
+      end
+    end
+
+    def cache_snapshot
+      with_cache_lock(File::LOCK_SH) { cache_inventory.snapshot }
+    end
+
+    def prune!(preserve: [])
+      with_cache_lock(File::LOCK_EX) { cache_inventory.prune!(preserve: preserve) }
     end
 
     private
 
+    attr_reader :cache_inventory
+
+    def materialize_locked(sha)
+      target = configuration.refs_cache_path.join(sha)
+      if fresh?(target, sha)
+        touch_access(target)
+        return [target, false]
+      end
+
+      with_ref_lock(sha) do
+        if fresh?(target, sha)
+          touch_access(target)
+          next [target, false]
+        end
+
+        [build_materialization(sha, target), true]
+      end
+    end
+
+    def view_roots(target)
+      configuration.view_paths.map { |path| target.join(path) }.select(&:directory?)
+    end
+
+    def automatic_prune
+      result = prune!
+      return if result.limits_satisfied?
+
+      log_cache_warning("automatic pruning could not satisfy the configured cache limits")
+    rescue StandardError => e
+      log_cache_warning("automatic pruning failed: #{e.class}: #{e.message}")
+    end
+
     def tracked_paths
       (configuration.view_paths + configuration.asset_paths).uniq
     end
@@ -69,6 +129,43 @@ module RailsWayback
       marker_path(target).write("#{MATERIALIZATION_VERSION}:#{sha}")
     end
 
+    def touch_access(target)
+      FileUtils.touch(marker_path(target))
+    rescue SystemCallError => e
+      log_cache_warning("could not update cache access time: #{e.message}")
+    end
+
+    def log_cache_warning(message)
+      return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+      Rails.logger&.warn("[rails-wayback] #{message}")
+    end
+
+    def build_materialization(sha, target)
+      refs_root = configuration.refs_cache_path
+      FileUtils.mkdir_p(refs_root)
+      staging = Pathname.new(Dir.mktmpdir(".#{sha}-building-", refs_root.to_s))
+
+      begin
+        tracked_paths.each { |path| extract_path(sha, path, staging) }
+        write_marker(staging, sha)
+        cache_inventory.write_metadata(staging, sha)
+
+        # Keep an existing materialization available until the replacement is
+        # complete. A failed extraction never removes the last known cache.
+        FileUtils.rm_rf(target)
+        File.rename(staging, target)
+        target
+      rescue MaterializationError
+        raise
+      rescue SystemCallError => e
+        raise MaterializationError,
+              "Could not materialize git ref #{sha}: #{e.message}"
+      ensure
+        FileUtils.rm_rf(staging) if staging.exist?
+      end
+    end
+
     # Uses `git archive | tar -x` to extract a subtree at a given ref.
     # This avoids the pitfalls of hand-rolled ls-tree + show pipelines
     # (encoding, binary files, missing directories, permissions) and
@@ -83,17 +180,67 @@ module RailsWayback
       archive_cmd = ["git", "-C", git.root.to_s, "archive", "--format=tar", spec]
       tar_cmd     = ["tar", "-xf", "-", "-C", dest.to_s]
 
-      Open3.pipeline(archive_cmd, tar_cmd)
+      Tempfile.create(["rails-wayback-extraction", ".log"]) do |errors|
+        statuses = extraction_pipeline(archive_cmd, tar_cmd, errors)
+        next if statuses.all?(&:success?)
+
+        errors.flush
+        errors.rewind
+        details = errors.read.strip
+        exits = statuses.map { |status| status.exitstatus || "unknown" }.join(", ")
+        message = "Could not extract #{spec} (pipeline exit statuses: #{exits})"
+        message = "#{message}: #{details}" unless details.empty?
+        raise MaterializationError, message
+      end
+    rescue SystemCallError => e
+      raise MaterializationError, "Could not extract #{spec}: #{e.message}"
     end
 
     def tree_exists?(sha, path)
-      # `git cat-file -t <sha>:<path>` prints "tree" for directories and
-      # "blob" for files. Anything else (or a non-zero exit) means the
-      # path is not present at that ref, in which case we skip it.
-      out, _err, status = Open3.capture3(
-        "git", "-C", git.root.to_s, "cat-file", "-t", "#{sha}:#{path}"
-      )
-      status.success? && out.strip == "tree"
+      git.tree?(sha, path)
+    end
+
+    def extraction_pipeline(archive_cmd, tar_cmd, errors)
+      Open3.pipeline(archive_cmd, tar_cmd, err: errors)
+    rescue Errno::ENOENT => e
+      executable = [archive_cmd.first, tar_cmd.first].find do |candidate|
+        e.message.end_with?(" - #{candidate}")
+      end || "git or tar"
+      raise MaterializationError,
+            "Required executable `#{executable}` was not found in PATH. " \
+            "Run `bundle exec rails-wayback doctor` for diagnostics."
+    rescue SystemCallError => e
+      raise MaterializationError,
+            "Could not execute the git/tar extraction pipeline: #{e.message}. " \
+            "Run `bundle exec rails-wayback doctor` for diagnostics."
+    end
+
+    def with_cache_lock(mode, &)
+      with_file_lock(configuration.cache_root_path.join(".refs.lock"), mode, &)
+    end
+
+    def with_ref_lock(sha, &)
+      path = configuration.cache_root_path.join("locks", "#{sha}.lock")
+      with_file_lock(path, File::LOCK_EX, &)
+    end
+
+    def with_file_lock(path, mode)
+      file = acquire_file_lock(path, mode)
+      yield
+    ensure
+      file&.close
+    end
+
+    def acquire_file_lock(path, mode)
+      FileUtils.mkdir_p(path.dirname)
+      file = File.open(path, File::RDWR | File::CREAT, 0o644)
+      return file if file.flock(mode)
+
+      file.close
+      raise MaterializationError, "Could not lock the refs cache at #{path}"
+    rescue SystemCallError => e
+      file&.close
+      raise MaterializationError, "Could not lock the refs cache: #{e.message}"
     end
   end
 end

data/lib/rails_wayback.rb

@@ -2,21 +2,34 @@
 
 require "rails_wayback/version"
 require "rails_wayback/configuration"
+require "rails_wayback/render_context"
+require "rails_wayback/render_provenance"
+require "rails_wayback/render_tracker"
+require "rails_wayback/asset_provenance"
 require "rails_wayback/toggle"
 require "rails_wayback/git"
+require "rails_wayback/ref_policy"
+require "rails_wayback/cache_inventory"
 require "rails_wayback/view_source"
+require "rails_wayback/engine_mount"
+require "rails_wayback/historical_asset_resolver"
+require "rails_wayback/historical_asset_body"
+require "rails_wayback/historical_asset_helper"
+require "rails_wayback/doctor"
 
 module RailsWayback
   class Error < StandardError; end
   class DisabledError < Error; end
   class RefNotFoundError < Error; end
+  class MaterializationError < Error; end
   class RenderError < Error; end
 
-  # Thread-local key where the render subscriber accumulates the
-  # `identifier` of every template resolved during a single request.
-  # The middleware resets this at the start of each request and reads
-  # it back to report per-page diff coverage in the bar.
-  RENDER_TRACKER_KEY = :rails_wayback_rendered_templates
+  RENDER_EVENTS = %w[
+    render_template.action_view
+    render_partial.action_view
+    render_layout.action_view
+    render_collection.action_view
+  ].freeze
 
   class << self
     def configure
@@ -37,11 +50,33 @@ module RailsWayback
       @toggle ||= Toggle.new(configuration)
     end
 
+    def current_environment
+      if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+        Rails.env.to_s
+      else
+        ENV["RAILS_ENV"] || ENV.fetch("RACK_ENV", nil)
+      end
+    end
+
+    def environment_allowed?
+      environment = current_environment.to_s
+      return true if environment.empty?
+
+      configuration.allowed_environments.map(&:to_s).include?(environment)
+    end
+
     def enabled?
-      toggle.enabled?
+      environment_allowed? && toggle.enabled?
     end
 
     def enable!
+      unless environment_allowed?
+        allowed = configuration.allowed_environments.join(", ")
+        raise DisabledError,
+              "environment #{current_environment.inspect} is not allowed " \
+              "(allowed: #{allowed})"
+      end
+
       toggle.enable!
     end
 
@@ -51,6 +86,7 @@ module RailsWayback
 
     def root
       return Rails.root if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
       Pathname.new(Dir.pwd)
     end
   end

data/lib/tasks/rails_wayback.rake

@@ -22,4 +22,21 @@ namespace :wayback do
   task clean: :environment do
     RailsWayback::CLI.start(["clean"])
   end
+
+  desc "Print rails-wayback ref cache usage"
+  task cache: :environment do
+    RailsWayback::CLI.start(["cache"])
+  end
+
+  desc "Prune least-recently-used refs to the configured limits"
+  task prune: :environment do
+    status = RailsWayback::CLI.start(["prune"])
+    raise "rails-wayback cache remains over its configured limits" unless status.zero?
+  end
+
+  desc "Check rails-wayback dependencies and host application readiness"
+  task doctor: :environment do
+    status = RailsWayback::CLI.start(["doctor"])
+    raise "rails-wayback doctor found critical problems" unless status.zero?
+  end
 end

data/rails-wayback.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   DESC
   spec.homepage = "https://github.com/MrCesar107/rails-wayback"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.1"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
@@ -37,8 +37,5 @@ Gem::Specification.new do |spec|
   spec.executables = ["rails-wayback"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rails", ">= 7.0"
-
-  spec.add_development_dependency "rspec", "~> 3.13"
-  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_dependency "rails", ">= 8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-wayback
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - MrCesar107
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,42 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '8.0'
 description: |
   rails-wayback is a Rails engine that lets you travel through git history to
   render past versions of your application's views inside the browser. It runs
@@ -69,6 +41,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/rails_wayback/application_controller.rb
+- app/controllers/rails_wayback/assets_controller.rb
 - app/controllers/rails_wayback/pages_controller.rb
 - config/routes.rb
 - exe/rails-wayback
@@ -77,13 +50,28 @@ files:
 - lib/generators/rails_wayback/install/templates/initializer.rb.tt
 - lib/rails-wayback.rb
 - lib/rails_wayback.rb
+- lib/rails_wayback/asset_provenance.rb
 - lib/rails_wayback/bar_middleware.rb
+- lib/rails_wayback/bar_renderer.css
+- lib/rails_wayback/bar_renderer.html.erb
+- lib/rails_wayback/bar_renderer.js
 - lib/rails_wayback/bar_renderer.rb
+- lib/rails_wayback/bar_search.js
+- lib/rails_wayback/cache_inventory.rb
 - lib/rails_wayback/cli.rb
 - lib/rails_wayback/configuration.rb
 - lib/rails_wayback/controller_extensions.rb
+- lib/rails_wayback/doctor.rb
 - lib/rails_wayback/engine.rb
+- lib/rails_wayback/engine_mount.rb
 - lib/rails_wayback/git.rb
+- lib/rails_wayback/historical_asset_body.rb
+- lib/rails_wayback/historical_asset_helper.rb
+- lib/rails_wayback/historical_asset_resolver.rb
+- lib/rails_wayback/ref_policy.rb
+- lib/rails_wayback/render_context.rb
+- lib/rails_wayback/render_provenance.rb
+- lib/rails_wayback/render_tracker.rb
 - lib/rails_wayback/toggle.rb
 - lib/rails_wayback/version.rb
 - lib/rails_wayback/view_source.rb
@@ -105,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="