rails-wayback 0.1.0 → 0.2.0

data/lib/rails_wayback/cli.rb

@@ -10,7 +10,8 @@ module RailsWayback
   #   rails-wayback status  # print current state
   #   rails-wayback clean   # remove the ref cache under tmp/
   class CLI
-    COMMANDS = %w[on off status clean help].freeze
+    COMMANDS = %w[on off status cache prune clean doctor help].freeze
+    DOCTOR_LABELS = { ok: "OK", warning: "WARN", error: "ERROR" }.freeze
 
     def self.start(argv, stdout: $stdout, stderr: $stderr)
       new(stdout: stdout, stderr: stderr).run(argv)
@@ -27,7 +28,10 @@ module RailsWayback
       when "on"     then cmd_on
       when "off"    then cmd_off
       when "status" then cmd_status
+      when "cache"  then cmd_cache
+      when "prune"  then cmd_prune
       when "clean"  then cmd_clean
+      when "doctor" then cmd_doctor
       when "help", "--help", "-h" then cmd_help
       else
         @stderr.puts "Unknown command: #{command}"
@@ -40,8 +44,11 @@ module RailsWayback
 
     def cmd_on
       RailsWayback.enable!
-      @stdout.puts "rails-wayback: enabled (mounted at /rails-wayback on the next request)"
+      @stdout.puts "rails-wayback: enabled for this server session (mounted at /rails-wayback on the next request)"
       0
+    rescue RailsWayback::DisabledError => e
+      @stderr.puts "rails-wayback: cannot enable: #{e.message}"
+      1
     end
 
     def cmd_off
@@ -51,7 +58,12 @@ module RailsWayback
     end
 
     def cmd_status
-      @stdout.puts "rails-wayback: #{RailsWayback.toggle.status}"
+      if RailsWayback.environment_allowed?
+        @stdout.puts "rails-wayback: #{RailsWayback.toggle.status}"
+      else
+        environment = RailsWayback.current_environment.inspect
+        @stdout.puts "rails-wayback: unavailable (environment #{environment} is not allowed)"
+      end
       0
     end
 
@@ -61,6 +73,36 @@ module RailsWayback
       0
     end
 
+    def cmd_cache
+      snapshot = RailsWayback::ViewSource.new.cache_snapshot
+      @stdout.puts cache_summary(snapshot)
+      0
+    rescue RailsWayback::MaterializationError => e
+      @stderr.puts "rails-wayback: cannot inspect cache: #{e.message}"
+      1
+    end
+
+    def cmd_prune
+      result = RailsWayback::ViewSource.new.prune!
+      @stdout.puts "rails-wayback: pruned #{result.removed.size} ref(s), " \
+                   "freed #{format_bytes(result.removed_size_bytes)}"
+      @stdout.puts cache_summary(result.snapshot)
+      result.limits_satisfied? ? 0 : 1
+    rescue RailsWayback::MaterializationError => e
+      @stderr.puts "rails-wayback: cannot prune cache: #{e.message}"
+      1
+    end
+
+    def cmd_doctor
+      result = RailsWayback::Doctor.new.call
+      @stdout.puts "rails-wayback doctor"
+      result.checks.each do |check|
+        @stdout.puts "[#{DOCTOR_LABELS.fetch(check.status)}] #{check.name}: #{check.message}"
+      end
+      @stdout.puts(result.ready? ? "Result: ready" : "Result: not ready")
+      result.exit_status
+    end
+
     def cmd_help
       @stdout.puts <<~HELP
         Usage: rails-wayback <command>
@@ -69,10 +111,35 @@ module RailsWayback
           on       Enable the wayback UI in this Rails app
           off      Disable the wayback UI
           status   Print whether the UI is currently enabled
+          cache    Print ref cache usage and configured limits
+          prune    Remove least-recently-used refs until limits are satisfied
           clean    Remove the tmp/rails_wayback ref cache
+          doctor   Check dependencies and host application readiness
           help     Show this help
       HELP
       0
     end
+
+    def cache_summary(snapshot)
+      config = RailsWayback.configuration
+      count_limit = config.max_cached_refs.nil? ? "unlimited" : config.max_cached_refs
+      byte_limit = config.max_cache_bytes.nil? ? "unlimited" : format_bytes(config.max_cache_bytes)
+      "rails-wayback cache: #{snapshot.ref_count} ref(s), #{format_bytes(snapshot.size_bytes)}, " \
+        "#{snapshot.file_count} file(s); limits: #{count_limit} refs / #{byte_limit}"
+    end
+
+    def format_bytes(value)
+      bytes = Integer(value)
+      return "#{bytes} B" if bytes < 1024
+
+      units = %w[KiB MiB GiB TiB]
+      amount = bytes / 1024.0
+      unit = units.shift
+      while amount >= 1024 && units.any?
+        amount /= 1024
+        unit = units.shift
+      end
+      format("%<amount>.1f %<unit>s", amount: amount, unit: unit)
+    end
   end
 end

data/lib/rails_wayback/configuration.rb

@@ -10,14 +10,25 @@ module RailsWayback
     DEFAULT_VIEW_PATHS = ["app/views", "app/components"].freeze
     DEFAULT_ASSET_PATHS = ["app/assets", "public"].freeze
     DEFAULT_MAX_COMMITS = 50
+    DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024
+    DEFAULT_ALLOWED_ENVIRONMENTS = %w[development test].freeze
+    DEFAULT_TRUSTED_REF_PATTERNS = ["refs/heads/*"].freeze
+    DEFAULT_MAX_CACHED_REFS = 25
+    DEFAULT_MAX_CACHE_BYTES = 512 * 1024 * 1024
 
-    attr_accessor :view_paths, :asset_paths, :max_commits,
-                  :app_root, :cache_root, :toggle_file
+    attr_accessor :view_paths, :asset_paths, :max_commits, :allowed_environments,
+                  :max_response_bytes, :trusted_ref_patterns, :max_cached_refs,
+                  :max_cache_bytes, :app_root, :cache_root, :toggle_file
 
     def initialize
       @view_paths = DEFAULT_VIEW_PATHS.dup
       @asset_paths = DEFAULT_ASSET_PATHS.dup
       @max_commits = DEFAULT_MAX_COMMITS
+      @max_response_bytes = DEFAULT_MAX_RESPONSE_BYTES
+      @allowed_environments = DEFAULT_ALLOWED_ENVIRONMENTS.dup
+      @trusted_ref_patterns = DEFAULT_TRUSTED_REF_PATTERNS.dup
+      @max_cached_refs = DEFAULT_MAX_CACHED_REFS
+      @max_cache_bytes = DEFAULT_MAX_CACHE_BYTES
       @app_root = nil
       @cache_root = nil
       @toggle_file = nil

data/lib/rails_wayback/controller_extensions.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 module RailsWayback
-  # Auto-included in every `ActionController::Base` subclass through the
-  # engine's initializer. Does nothing on ordinary requests. When a
+  # Included in every `ActionController::Base` subclass. When a
   # request carries `?_wayback_ref=<sha>` and the gem is enabled, it
-  # materialises the ref and prepends the sandbox to the view paths so
-  # the current controller renders historical templates while keeping
-  # its own instance variables intact.
+  # leases the materialised ref and prepends its directories to the view
+  # paths so the current controller renders historical templates while
+  # keeping its own instance variables intact.
   module ControllerExtensions
     extend ActiveSupport::Concern
 
@@ -15,8 +14,9 @@ module RailsWayback
     RESPONSE_HEADER = "X-RailsWayback-Ref"
 
     included do
-      before_action :__rails_wayback_prepend_views
+      around_action :__rails_wayback_with_views
       helper_method :rails_wayback_active_ref
+      helper RailsWayback::HistoricalAssetHelper
     end
 
     def rails_wayback_active_ref
@@ -25,17 +25,63 @@ module RailsWayback
 
     private
 
-    def __rails_wayback_prepend_views
-      return unless RailsWayback.enabled?
+    def __rails_wayback_with_views(&action)
+      return action.call unless RailsWayback.enabled?
 
       ref = __rails_wayback_ref_from_request
-      return unless ref
+      return action.call unless ref
 
-      dirs = RailsWayback::ViewSource.new.view_root_for(ref)
+      selection = authorize_wayback_ref(ref)
+      return action.call unless selection
 
+      request.env[RailsWayback::RefPolicy::ENV_KEY] = selection
+      if selection.rejected?
+        reject_wayback_ref(selection)
+        return action.call
+      end
+
+      render_with_wayback_views(selection, &action)
+    end
+
+    def authorize_wayback_ref(ref)
+      RailsWayback::RefPolicy.new.authorize(ref)
+    rescue RailsWayback::RefNotFoundError, RailsWayback::Git::GitError => e
+      handle_wayback_error(e)
+      nil
+    end
+
+    def render_with_wayback_views(selection, &action)
+      action_started = false
+      RailsWayback::ViewSource.new.with_view_roots(selection.sha) do |dirs, root|
+        with_wayback_materialization(root) do
+          prepend_wayback_views(selection, dirs)
+          action_started = true
+          action.call
+        end
+      end
+    rescue RailsWayback::RefNotFoundError, RailsWayback::Git::GitError => e
+      raise if action_started
+
+      handle_wayback_error(e)
+      action.call
+    end
+
+    def with_wayback_materialization(root)
+      request.env[RailsWayback::HistoricalAssetHelper::MATERIALIZATION_ROOT_ENV] = root
+      yield
+    ensure
+      request.env.delete(RailsWayback::HistoricalAssetHelper::MATERIALIZATION_ROOT_ENV)
+    end
+
+    def handle_wayback_error(error)
+      log_warning("#{error.class}: #{error.message}")
+      write_wayback_header("error:#{error.class}")
+    end
+
+    def prepend_wayback_views(selection, dirs)
       if dirs.empty?
-        log_warning("no view directories materialised for ref #{ref}")
-        set_header("empty:#{ref}")
+        log_warning("no view directories materialised for ref #{selection.sha}")
+        write_wayback_header("empty:#{selection.sha}")
         return
       end
 
@@ -44,14 +90,11 @@ module RailsWayback
       # lookup context.
       dirs.each { |dir| prepend_view_path(dir.to_s) }
 
-      @__rails_wayback_active_ref = ref
-      set_header(ref)
+      @__rails_wayback_active_ref = selection.sha
+      write_wayback_header(selection.sha)
 
-      log_info("prepended #{dirs.size} view path(s) from ref #{ref}")
+      log_info("prepended #{dirs.size} view path(s) from ref #{selection.sha}")
       log_info("resolver order: #{resolver_summary}")
-    rescue RailsWayback::RefNotFoundError, RailsWayback::Git::GitError => e
-      log_warning("#{e.class}: #{e.message}")
-      set_header("error:#{e.class}")
     end
 
     # Params take precedence for one-off overrides (e.g. a shared URL);
@@ -65,6 +108,13 @@ module RailsWayback
       cookies[WAYBACK_COOKIE].to_s.then { |v| v.empty? ? nil : v }
     end
 
+    def reject_wayback_ref(selection)
+      response.delete_cookie(WAYBACK_COOKIE, path: "/")
+      response.delete_cookie("rails_wayback_branch", path: "/")
+      log_warning(selection.message)
+      write_wayback_header("rejected:#{selection.reason}")
+    end
+
     def resolver_summary
       lookup_context.view_paths.to_a.map { |r| resolver_path(r) }.join(" | ")
     rescue StandardError
@@ -74,11 +124,12 @@ module RailsWayback
     def resolver_path(resolver)
       return resolver.to_path if resolver.respond_to?(:to_path)
       return resolver.path    if resolver.respond_to?(:path)
+
       resolver.class.name
     end
 
-    def set_header(value)
-      response.set_header(RESPONSE_HEADER, value) if response
+    def write_wayback_header(value)
+      response&.set_header(RESPONSE_HEADER, value)
     rescue StandardError
       nil
     end

data/lib/rails_wayback/doctor.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "pathname"
+require "tempfile"
+
+module RailsWayback
+  # Performs explicit, non-destructive readiness checks for the host app.
+  class Doctor
+    Check = Struct.new(:name, :status, :message, keyword_init: true) do
+      def error?
+        status == :error
+      end
+    end
+
+    Result = Struct.new(:checks, keyword_init: true) do
+      def ready?
+        checks.none?(&:error?)
+      end
+
+      def exit_status
+        ready? ? 0 : 1
+      end
+    end
+
+    def initialize(configuration: RailsWayback.configuration, git: nil,
+                   environment: RailsWayback.current_environment, capture3: nil)
+      @configuration = configuration
+      @git = git || Git.new(root: configuration.app_root_path)
+      @environment = environment.to_s
+      @capture3 = capture3 || Open3.method(:capture3)
+    end
+
+    def call
+      root_check = app_root_check
+      checks = [environment_check, root_check]
+      git_check = executable_check("Git", "git")
+      checks << git_check
+      checks << repository_check unless git_check.error? || root_check.error?
+      checks << executable_check("tar", "tar", version_optional: true)
+      checks << if root_check.error?
+                  check("Cache directory", :error, "not checked because the application root is missing")
+                else
+                  cache_check
+                end
+      checks << configured_paths_check
+      Result.new(checks: checks)
+    end
+
+    private
+
+    attr_reader :configuration, :git, :environment, :capture3
+
+    def environment_check
+      allowed = Array(configuration.allowed_environments).map(&:to_s)
+      return check("Rails environment", :warning, "not detected; allowed: #{allowed.join(", ")}") if environment.empty?
+      return check("Rails environment", :ok, "#{environment} (allowed)") if allowed.include?(environment)
+
+      check("Rails environment", :error, "#{environment} is not allowed; allowed: #{allowed.join(", ")}")
+    end
+
+    def app_root_check
+      root = configuration.app_root_path
+      return check("Application root", :ok, root.to_s) if root.directory?
+
+      check("Application root", :error, "directory does not exist: #{root}")
+    end
+
+    def executable_check(label, executable, version_optional: false)
+      stdout, stderr, status = capture3.call(executable, "--version")
+      details = [stdout, stderr].map(&:strip).find { |value| !value.empty? }
+      return check(label, :ok, details || "available") if status.success?
+      return check(label, :warning, "available, but `#{executable} --version` is unsupported") if version_optional
+
+      check(label, :error, "#{executable} --version exited with status #{status.exitstatus}")
+    rescue Errno::ENOENT
+      check(label, :error, "required executable `#{executable}` was not found in PATH")
+    rescue SystemCallError => e
+      check(label, :error, "could not execute `#{executable}`: #{e.message}")
+    end
+
+    def repository_check
+      return check("Git repository", :ok, git.root.to_s) if git.repository?
+
+      check("Git repository", :error, "no Git work tree found at #{git.root}")
+    end
+
+    def cache_check
+      root = configuration.cache_root_path
+      FileUtils.mkdir_p(root)
+      Tempfile.create(".rails-wayback-doctor-", root) { |file| file.write("ok") }
+      check("Cache directory", :ok, "writable: #{root}")
+    rescue SystemCallError => e
+      check("Cache directory", :error, "not writable at #{root}: #{e.message}")
+    end
+
+    def configured_paths_check
+      paths = (Array(configuration.view_paths) + Array(configuration.asset_paths)).map(&:to_s).uniq
+      invalid = paths.select { |path| unsafe_relative_path?(path) }
+      return check("Configured paths", :error, "must be safe relative paths: #{invalid.join(", ")}") if invalid.any?
+
+      existing, missing = paths.partition { |path| configuration.app_root_path.join(path).directory? }
+      message = "#{existing.size}/#{paths.size} exist"
+      message = "#{message}; absent paths are skipped: #{missing.join(", ")}" if missing.any?
+      status = existing.empty? ? :warning : :ok
+      check("Configured paths", status, message)
+    end
+
+    def unsafe_relative_path?(value)
+      return true if value.empty?
+
+      path = Pathname.new(value)
+      path.absolute? || path.cleanpath.each_filename.first == ".."
+    rescue ArgumentError
+      true
+    end
+
+    def check(name, status, message)
+      Check.new(name: name, status: status, message: message)
+    end
+  end
+end

data/lib/rails_wayback/engine.rb

@@ -9,6 +9,13 @@ module RailsWayback
   class Engine < ::Rails::Engine
     isolate_namespace RailsWayback
 
+    # Activation is scoped to a Rails server session. The marker still lets
+    # the standalone CLI toggle a running server, but a later server boot
+    # always starts with Wayback disabled.
+    server do
+      RailsWayback.toggle.reset!
+    end
+
     initializer "rails_wayback.controller_extensions" do
       ActiveSupport.on_load(:action_controller_base) do
         include RailsWayback::ControllerExtensions
@@ -20,25 +27,26 @@ module RailsWayback
     end
 
     initializer "rails_wayback.render_instrumentation" do
-      ActiveSupport::Notifications.subscribe("render_template.action_view") do |*args|
-        event = ActiveSupport::Notifications::Event.new(*args)
-        identifier = event.payload[:identifier].to_s
-        next if identifier.empty?
-
-        origin = if identifier.include?("/tmp/rails_wayback/refs/")
-                   "SANDBOX"
-                 elsif identifier.start_with?("/")
-                   "CURRENT"
-                 else
-                   "OTHER"
-                 end
-        Rails.logger.info("[rails-wayback] render #{origin}: #{identifier}") if Rails.respond_to?(:logger)
-
-        # Per-request tracker so the middleware can report, in the bar,
-        # which templates the current page actually pulled from the
-        # sandbox. Middleware clears this at the start of every request.
-        tracker = Thread.current[RailsWayback::RENDER_TRACKER_KEY] ||= []
-        tracker << identifier
+      RailsWayback::RENDER_EVENTS.each do |event_name|
+        ActiveSupport::Notifications.subscribe(event_name) do |*args|
+          next unless RailsWayback.enabled?
+
+          event = ActiveSupport::Notifications::Event.new(*args)
+          identifier = event.payload[:identifier].to_s
+          next if identifier.empty?
+
+          origin = RailsWayback::RenderProvenance.origin_for(identifier)
+          Rails.logger&.info(
+            "[rails-wayback] #{event.name} #{origin.to_s.upcase}: #{identifier}"
+          )
+
+          # Notifications outside the middleware's request scope are logged
+          # but deliberately excluded from toolbar provenance.
+          RailsWayback::RenderContext.current&.record(
+            event: event.name,
+            identifier: identifier
+          )
+        end
       end
     end
 

data/lib/rails_wayback/engine_mount.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  module EngineMount
+    module_function
+
+    def path
+      RailsWayback::Engine.routes.default_url_options[:script_name] ||
+        RailsWayback::Engine.routes.find_script_name({}) ||
+        "/rails-wayback"
+    rescue StandardError
+      "/rails-wayback"
+    end
+  end
+end

data/lib/rails_wayback/git.rb

@@ -9,17 +9,28 @@ module RailsWayback
   # We shell out to git instead of pulling in a dependency to keep the
   # gem light. All commands are scoped to the host app root and return
   # plain Ruby data structures.
+  #
+  # NOTE: Maybe we should need to use a git library instead of shelling out to git.
+  # Only if this functionality is not enough for the gem on the future.
   class Git
     Commit = Struct.new(:sha, :short_sha, :subject, :author, :date, keyword_init: true)
+    Reference = Struct.new(:full_name, :name, :kind, :label, keyword_init: true)
+    REFERENCE_PREFIXES = {
+      "refs/heads/" => :branch,
+      "refs/remotes/" => :remote,
+      "refs/tags/" => :tag
+    }.freeze
+    REFERENCE_KIND_ORDER = { branch: 0, remote: 1, tag: 2 }.freeze
 
     class GitError < StandardError; end
+    class ExecutableNotFoundError < GitError; end
 
     def initialize(root: nil)
       @root = Pathname.new(root || RailsWayback.configuration.app_root_path)
     end
 
     def repository?
-      Dir.exist?(@root.join(".git")) || run("rev-parse", "--is-inside-work-tree").strip == "true"
+      run("rev-parse", "--is-inside-work-tree").strip == "true"
     rescue GitError
       false
     end
@@ -37,6 +48,44 @@ module RailsWayback
       output.split("\n").map(&:strip).reject(&:empty?)
     end
 
+    # Lists refs that are already present in the local repository and match
+    # the same trust patterns used to authorize historical rendering. This
+    # never fetches or mutates Git state.
+    def references(patterns: RailsWayback.configuration.trusted_ref_patterns)
+      output = run(
+        "for-each-ref",
+        "--format=%(refname)%09%(symref)",
+        "refs/heads/",
+        "refs/remotes/",
+        "refs/tags/"
+      )
+
+      discovered = output.split("\n").filter_map do |line|
+        full_name, symbolic_target = line.split("\t", 2)
+        next unless symbolic_target.to_s.empty?
+        next unless trusted_reference?(full_name, patterns)
+
+        build_reference(full_name)
+      end
+      discovered.sort_by { |reference| [REFERENCE_KIND_ORDER.fetch(reference.kind), reference.label] }
+    end
+
+    # Resolves either a canonical full ref name (preferred) or a legacy short
+    # branch name, but only from the configured trusted discovery set.
+    def reference(selector, patterns: RailsWayback.configuration.trusted_ref_patterns)
+      available = references(patterns: patterns)
+      input = selector.to_s
+      exact = available.find { |candidate| candidate.full_name == input }
+      return exact if exact
+
+      compatible = available.find do |candidate|
+        candidate.name == input || candidate.label == input
+      end
+      return compatible if compatible
+
+      raise GitError, "Git ref #{input.inspect} is not trusted or is unavailable locally"
+    end
+
     def commits(branch, limit: RailsWayback.configuration.max_commits)
       output = run(
         "log",
@@ -53,6 +102,8 @@ module RailsWayback
 
     def resolve_ref(ref)
       run("rev-parse", "--verify", "#{ref}^{commit}").strip
+    rescue ExecutableNotFoundError
+      raise
     rescue GitError
       raise RefNotFoundError, "Unknown git ref: #{ref.inspect}"
     end
@@ -61,6 +112,14 @@ module RailsWayback
       run("show", "#{ref}:#{path}")
     end
 
+    def tree?(ref, path)
+      run("cat-file", "-t", "#{ref}:#{path}").strip == "tree"
+    rescue ExecutableNotFoundError
+      raise
+    rescue GitError
+      false
+    end
+
     # Returns the local branch names that contain `sha` in their history.
     # Used by the bar to reflect the branch you are RENDERING with when
     # you travel, instead of the branch that is checked out on disk
@@ -72,6 +131,11 @@ module RailsWayback
       []
     end
 
+    def refs_containing(sha)
+      output = run("for-each-ref", "--contains=#{sha}", "--format=%(refname)")
+      output.split("\n").map(&:strip).reject(&:empty?)
+    end
+
     # Same as `branches_containing`, but picks the most contextual one
     # for display in the bar when the developer did NOT provide an
     # explicit branch alongside the sha:
@@ -121,20 +185,40 @@ module RailsWayback
       FileUtils.rm_f(target.join(".rails_wayback_index")) if target
     end
 
-    def root
-      @root
-    end
+    attr_reader :root
 
     private
 
-    def run(*args)
-      run_with_env({}, *args)
+    def trusted_reference?(full_name, patterns)
+      Array(patterns).map(&:to_s).any? { |pattern| File.fnmatch?(pattern, full_name) }
     end
 
-    def run_with_env(env, *args)
-      stdout, stderr, status = Open3.capture3(env, "git", "-C", @root.to_s, *args)
+    def build_reference(full_name)
+      prefix, kind = REFERENCE_PREFIXES.find { |candidate, _value| full_name.start_with?(candidate) }
+      return unless prefix
+
+      name = full_name.delete_prefix(prefix)
+      label = kind == :tag ? "tag:#{name}" : name
+      Reference.new(full_name: full_name, name: name, kind: kind, label: label)
+    end
+
+    def run(*)
+      run_with_env({}, *)
+    end
+
+    def run_with_env(env, *)
+      stdout, stderr, status = Open3.capture3(env, "git", "-C", @root.to_s, *)
       raise GitError, stderr.strip unless status.success?
+
       stdout
+    rescue Errno::ENOENT
+      raise ExecutableNotFoundError,
+            "Required executable `git` was not found in PATH. " \
+            "Run `bundle exec rails-wayback doctor` for diagnostics."
+    rescue SystemCallError => e
+      raise GitError,
+            "Could not execute required executable `git`: #{e.message}. " \
+            "Run `bundle exec rails-wayback doctor` for diagnostics."
     end
   end
 end