rails-wayback 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d994f992691b844562d34eb5e06afaf69be7502d98c2107313a7fabcfe99209
-  data.tar.gz: d8175d1cd12a74f6db23b6a58c4d26acd11a36825a98b6c49da50515c154d945
+  metadata.gz: '083ed3185650e0e8a199b639e18a5a2fe69fcd75d76871803e8bf74aea1afb31'
+  data.tar.gz: e7c79e78e2838c107d622d7a73fc793174b2678815e5239a6bf632ff39375fe8
 SHA512:
-  metadata.gz: 3c90265c6459015b3c684fe0f3446f52bda36d1fae2e54cdbba0beb7748d912add4da80946b5d431c2e0f174975d9ceb1591ec24bb3163b5087bb72fc46f6994
-  data.tar.gz: ba0e7095c8ebc4e2ea1d8034b9b3c9f49ed28a4b26608977c9cc9fc2a83c4594ec9e59476abb73b7c6856fec107ff85e8ae45b0a4b1818e0b6f8388f80ca204d
+  metadata.gz: 3a179537ef40d42489189aeddecdd2f885eb8ed2d1233b9379d95e322ab0e8c23c73a568c1d2e5303c7e64ffcd2d74bd1baf5df04060c7f650ce6cd23711064b
+  data.tar.gz: 40c9c0c81cbef0580603672c0114dcf63f0fc312a243bc64260ede1736d4d3cb61b9e080035122ff12088f66a0c67cc10be1bd365203e5f823614356aa0ca970

data/README.md

@@ -50,11 +50,20 @@ Turn the UI on when you need it, off when you don't:
 bundle exec rails-wayback on      # enable and inject the bar in every page
 bundle exec rails-wayback off     # disable it
 bundle exec rails-wayback status  # print current state
+bundle exec rails-wayback cache   # report ref cache usage and limits
+bundle exec rails-wayback prune   # apply configured LRU cache limits
 bundle exec rails-wayback clean   # drop the tmp/rails_wayback ref cache
+bundle exec rails-wayback doctor  # check dependencies and app readiness
 ```
 
 Same commands as rake tasks: `rake wayback:on`, `wayback:off`,
-`wayback:status`, `wayback:clean`.
+`wayback:status`, `wayback:cache`, `wayback:prune`, `wayback:clean`,
+`wayback:doctor`.
+
+Run `bin/rails wayback:doctor` from a Rails application to check Git and `tar`,
+the repository root, cache write access, configured view and asset paths, and
+the active Rails environment. Warnings do not fail the command; missing
+dependencies or invalid runtime requirements return a non-zero exit status.
 
 Activation lasts for the current Rails server session. Every new server start
 begins with `rails-wayback` disabled, while `on` and `off` can still be used at
@@ -63,10 +72,16 @@ any time without restarting Rails.
 With the gem enabled, load any page of your app. A dark bar appears at the
 bottom with:
 
-- `Current branch` — dropdown of your local branches.
-- `Current commit` — dropdown of the recent commits on that branch.
+- `Current ref` — dropdown of trusted branches, remote-tracking branches, and
+  tags already stored in the local repository. Its search box filters the
+  loaded refs by name, label, or type.
+- `Current commit` — dropdown of the recent commits on that ref. Its search
+  box filters the loaded commits by SHA, subject, author, or date.
 - `Travel` — reloads the current URL using views from that commit.
 - `Return to HEAD` — appears while traveling; goes back to live views.
+  It uses a server-side reset endpoint, which is also available directly at
+  `/rails-wayback/reset` if a historical template prevents the page from
+  rendering.
 
 There is no dedicated `/rails-wayback` page. The gem stays quiet on assets,
 ActionCable, and every URL under `/rails-wayback/*.json` (used by the bar to
@@ -83,13 +98,42 @@ fetch git data).
 3. The same before_action calls `prepend_view_path` with the sandbox, so
    Action View resolves templates from the ref before falling back to the
    current tree.
-4. Your controller runs as usual, sets its `@` variables, and renders. The
+4. Standard Rails asset helpers resolve browser-ready files from the ref's
+   `public/` directory to immutable, SHA-specific engine URLs. Missing files
+   fall back to the current Rails asset resolver.
+5. Your controller runs as usual, sets its `@` variables, and renders. The
    visual layer (layouts, partials, ERB) comes from the past; the data and
    business logic come from the present.
 
 If a historical template references a helper or assign that no longer
 exists, you'll get the same `ActionView` error you'd get from any missing
-piece — the app itself never changes.
+piece — the app itself never changes. Open `/rails-wayback/reset` to clear the
+travel cookies if that error prevents the toolbar from rendering.
+
+The toolbar tracks templates, partials, layouts, and collections. While
+traveling it labels a response as historical, current fallback, or mixed so
+you can tell when Rails filled a missing historical file from the current
+view tree. It also reports historical public assets and current asset
+fallbacks discovered through standard Rails helpers.
+
+### Historical public assets
+
+While traveling, existing calls to `asset_path`, `image_tag`,
+`stylesheet_link_tag`, `javascript_include_tag`, and the other standard Rails
+asset helpers automatically look for browser-ready files in the selected
+commit's `public/` directory. A historical file is served from a URL such as
+`/rails-wayback/refs/<sha>/assets/images/logo.svg`; the SHA prevents browser
+and proxy caches from mixing revisions. Asset responses reauthorize the ref,
+reject unsafe paths and escaping symlinks, use immutable caching, and keep a
+cache lease for the complete streamed response.
+
+If a public file is absent, the normal current Rails resolver remains the
+fallback and the toolbar reports it. Direct hard-coded URLs such as
+`/assets/application.css` bypass Rails helpers and are not rewritten.
+Historical Propshaft/Sprockets compilation, Sass or TypeScript processing,
+import maps, and JavaScript/CSS bundlers are not reproduced yet; `app/assets`
+continues to be extracted for comparison but is not served by this initial
+static-file strategy.
 
 ## Configuration (optional)
 
@@ -97,14 +141,71 @@ piece — the app itself never changes.
 
 ```ruby
 RailsWayback.configure do |config|
+  # config.allowed_environments = %w[development test]
+  # config.trusted_ref_patterns = ["refs/heads/*"]
   # config.view_paths  = %w[app/views]
   # config.asset_paths = %w[app/assets public]
   # config.max_commits = 50
+  # config.max_cached_refs = 25
+  # config.max_cache_bytes = 512 * 1024 * 1024
+  # config.max_response_bytes = 2 * 1024 * 1024
 end
 ```
 
-Everything above has a sensible default. Delete the initializer if you
-don't need to change anything.
+Rails Wayback refuses to activate outside `development` and `test` by
+default, even if its toggle file exists. Adding another environment is an
+explicit opt-in; historical templates execute inside the host Rails process,
+so only trusted refs should be used. Travel accepts only full commit SHAs and,
+by default, the commit must be reachable from a local branch. Narrow
+`trusted_ref_patterns` to branches such as `refs/heads/main` or
+`refs/heads/release/*`, or explicitly add locally stored remote-tracking refs
+and tags:
+
+```ruby
+config.trusted_ref_patterns = [
+  "refs/heads/*",
+  "refs/remotes/origin/review/*",
+  "refs/tags/preview-*"
+]
+```
+
+Matching refs appear in the toolbar and can be used for commit discovery.
+Ref and commit search is performed in the browser over the data already loaded
+by the toolbar; commit search is therefore limited to `max_commits` entries for
+the selected ref and does not run additional Git commands or network requests.
+Rails Wayback never runs `git fetch`: remote-tracking refs must already exist
+locally, symbolic aliases such as `origin/HEAD` are omitted, and untrusted refs
+cannot be queried through the commits endpoint. Detached commits remain blocked.
+
+This policy reduces accidental execution but is not a sandbox. Historical ERB
+and other executable template handlers run with the Rails server's filesystem,
+database, credentials, environment, and network permissions. Historical
+JavaScript also executes in the browser under the development application's
+origin. The toolbar shows a permanent warning and asks for confirmation on the
+first travel action in each browser session. The response-size limit applies only to
+toolbar injection; streaming, encoded, file, partial, and larger responses are
+returned untouched. Toolbar CSS and JavaScript are served from the mounted
+engine, so CSP policies should allow same-origin styles, scripts, and fetches.
+Rails-generated CSP nonces are copied to both asset tags automatically.
+Everything above has a sensible default. Delete the initializer if you don't
+need to change anything.
+
+Cached refs use least-recently-used access metadata. After materialising a new
+ref, Rails Wayback automatically removes the oldest refs until the configured
+count and byte limits are met. A shared cache lease protects each ref for the
+complete historical render, so automatic or manual `prune` and `clean`
+operations wait for active previews before removing their files.
+`rails-wayback cache` reports logical payload size and file count, while
+`rails-wayback prune` applies the limits immediately. `rails-wayback clean`
+removes all ref data and per-ref lock files. Set either cache limit to `nil` to
+disable it.
+
+## Compatibility
+
+Rails Wayback requires Ruby 3.3 or newer and Rails 8.0 or newer. CI runs the
+complete matrix of Ruby 3.3, 3.4, and 4.0 against Rails 8.0 and 8.1.
+Compatibility here means that the gem's suite passes on that combination; it
+does not extend the upstream maintenance or security lifetime of Ruby or Rails.
 
 ## Development
 
@@ -113,6 +214,14 @@ bundle install
 bundle exec rspec
 ```
 
+Rails dependency sets are managed with Appraisal. Regenerate their Gemfiles
+after changing `Appraisals`, then run an individual Rails line with:
+
+```bash
+bundle exec appraisal generate
+bundle exec appraisal rails-8-0 rspec
+```
+
 ## Release
 
 Releases are cut by pushing an annotated `vX.Y.Z` git tag. GitHub Actions runs

data/Rakefile

@@ -2,10 +2,26 @@
 
 require "bundler/gem_tasks"
 
+default_tasks = []
+
 begin
   require "rspec/core/rake_task"
   RSpec::Core::RakeTask.new(:spec)
-  task default: :spec
+  default_tasks << :spec
 rescue LoadError
   # RSpec is only available in development
 end
+
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new(:rubocop) do |task|
+    task.options = ["--parallel"]
+  end
+  desc "Run RuboCop"
+  task lint: :rubocop
+  default_tasks << :rubocop
+rescue LoadError
+  # RuboCop is only available in development
+end
+
+task default: default_tasks

data/app/controllers/rails_wayback/assets_controller.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+require "rack/mime"
+require "rails_wayback/bar_renderer"
+
+module RailsWayback
+  # Serves the toolbar's bundled assets without depending on the host
+  # application's asset pipeline.
+  class AssetsController < ApplicationController
+    CACHE_CONTROL = "public, max-age=31536000, immutable"
+
+    def stylesheet
+      render_asset(BarRenderer::STYLES, "text/css")
+    end
+
+    def javascript
+      render_asset(BarRenderer::SCRIPT, "application/javascript")
+    end
+
+    def historical
+      selection = RailsWayback::RefPolicy.new.authorize(params[:sha])
+      return render_rejection(selection) if selection.rejected?
+
+      source = RailsWayback::ViewSource.new
+      resolution = resolve_asset(source, selection.sha, params[:path])
+      return head :not_found unless resolution
+
+      set_historical_headers(selection.sha, resolution)
+      return head :ok if request.head?
+
+      self.response_body = RailsWayback::HistoricalAssetBody.new(
+        sha: selection.sha,
+        public_path: resolution.public_path,
+        view_source: source
+      )
+    rescue RailsWayback::Git::GitError, RailsWayback::MaterializationError => e
+      render json: { error: e.message }, status: :service_unavailable
+    end
+
+    private
+
+    def resolve_asset(source, sha, path)
+      resolution = nil
+      source.with_materialization(sha) do |root|
+        resolution = RailsWayback::HistoricalAssetResolver.new.resolve_public_path(
+          root: root,
+          public_path: path
+        )
+      end
+      resolution
+    end
+
+    def set_historical_headers(sha, resolution)
+      content_type = Rack::Mime.mime_type(File.extname(resolution.public_path), "application/octet-stream")
+      response.content_type = content_type
+      response.set_header("Content-Length", resolution.size_bytes.to_s)
+      response.set_header("Cache-Control", CACHE_CONTROL)
+      response.set_header("X-Content-Type-Options", "nosniff")
+      response.set_header("ETag", %("#{Digest::SHA256.hexdigest("#{sha}:#{resolution.public_path}")}"))
+    end
+
+    def render_rejection(selection)
+      status = case selection.reason
+               when :invalid_format then :bad_request
+               when :unknown_ref then :not_found
+               else :forbidden
+               end
+      render json: { error: selection.message }, status: status
+    end
+
+    def render_asset(content, content_type)
+      response.set_header("Cache-Control", CACHE_CONTROL)
+      response.set_header("X-Content-Type-Options", "nosniff")
+      render plain: content, content_type: content_type
+    end
+  end
+end

data/app/controllers/rails_wayback/pages_controller.rb

@@ -1,28 +1,40 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module RailsWayback
   # JSON endpoints consumed by the bar's JavaScript to populate the
   # branch and commit selectors. All rendering of the actual UI lives
   # in the middleware; this controller only exposes git metadata.
   class PagesController < ApplicationController
+    WAYBACK_COOKIES = %w[rails_wayback_ref rails_wayback_branch].freeze
+    Result = Struct.new(:value, :error)
+    private_constant :Result
+
     def branches
       current_branch = safe_call { git.current_branch }
       current_commit = safe_call { git.current_commit }
-      branches = safe_call { git.branches }
+      references = safe_call { git.references }
+      list = references.value || []
 
       render json: {
         current_branch: current_branch.value,
         current_commit: current_commit.value,
-        branches: branches.value || [],
-        errors: [branches.error].compact
+        branches: list.select { |reference| reference.kind == :branch }.map(&:name),
+        refs: list.map { |reference| reference_json(reference) },
+        errors: [references.error].compact
       }
     end
 
     def commits
-      branch = params[:branch].to_s.sub(/\.json\z/, "")
-      result = safe_call { git.commits(branch) }
+      selector = params[:branch].to_s.sub(/\.json\z/, "")
+      result = safe_call do
+        reference = git.reference(selector)
+        [reference, git.commits(reference.full_name)]
+      end
+      reference, commits = result.value
 
-      list = (result.value || []).map do |commit|
+      list = (commits || []).map do |commit|
         {
           sha: commit.sha,
           short_sha: commit.short_sha,
@@ -33,15 +45,22 @@ module RailsWayback
       end
 
       render json: {
-        branch: branch,
+        branch: reference&.name || selector,
+        ref: reference && reference_json(reference),
         commits: list,
         error: result.error
       }
     end
 
-    private
+    # Emergency escape hatch that does not render any host application view.
+    # It remains usable when a historical template crashes before the injected
+    # toolbar can render its normal Return to HEAD control.
+    def reset
+      WAYBACK_COOKIES.each { |name| response.delete_cookie(name, path: "/") }
+      redirect_to safe_return_to, allow_other_host: false
+    end
 
-    Result = Struct.new(:value, :error)
+    private
 
     def safe_call
       Result.new(yield, nil)
@@ -49,5 +68,27 @@ module RailsWayback
       Rails.logger.warn("[rails-wayback] #{e.class}: #{e.message}") if defined?(Rails)
       Result.new(nil, "#{e.class}: #{e.message}")
     end
+
+    def reference_json(reference)
+      {
+        full_name: reference.full_name,
+        name: reference.name,
+        type: reference.kind,
+        label: reference.label
+      }
+    end
+
+    def safe_return_to
+      target = params[:return_to].to_s
+      return "/" if target.empty? || target.include?("\\")
+
+      uri = URI.parse(target)
+      return "/" unless target.start_with?("/") && !target.start_with?("//")
+      return "/" if uri.scheme || uri.host
+
+      target
+    rescue URI::InvalidURIError
+      "/"
+    end
   end
 end

data/config/routes.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 RailsWayback::Engine.routes.draw do
+  get "assets/bar.css", to: "assets#stylesheet", format: false, as: :bar_stylesheet
+  get "assets/bar.js", to: "assets#javascript", format: false, as: :bar_javascript
+  get "refs/:sha/assets/*path", to: "assets#historical", format: false, as: :historical_asset
+
   # `format: false` keeps Rails from parsing a trailing `.json` as an
   # implicit format, and the glob `*branch` allows branch names that
   # contain slashes (e.g. "feature/foo"). The controller trims a
   # trailing `.json` defensively in case a client still appends it.
   get "branches", to: "pages#branches", format: false, as: :branches
   get "commits/*branch", to: "pages#commits", format: false, as: :commits
+  get "reset", to: "pages#reset", format: false, as: :reset
 end

data/lib/generators/rails_wayback/install/install_generator.rb

@@ -17,8 +17,9 @@ module RailsWayback
         ROUTE
 
         routes_file = "config/routes.rb"
+        routes_path = File.join(destination_root, routes_file)
 
-        if File.file?(routes_file) && File.read(routes_file).include?("RailsWayback::Engine")
+        if File.file?(routes_path) && File.read(routes_path).include?("RailsWayback::Engine")
           say_status :skip, "RailsWayback::Engine mount already present in #{routes_file}"
         else
           route route_snippet.strip
@@ -27,10 +28,11 @@ module RailsWayback
 
       def update_gitignore
         gitignore = ".gitignore"
+        gitignore_path = File.join(destination_root, gitignore)
         entry = "/tmp/rails_wayback/\n"
-        if File.file?(gitignore) && !File.read(gitignore).include?("tmp/rails_wayback")
+        if File.file?(gitignore_path) && !File.read(gitignore_path).include?("tmp/rails_wayback")
           append_to_file(gitignore, entry)
-        elsif !File.file?(gitignore)
+        elsif !File.file?(gitignore_path)
           create_file(gitignore, entry)
         end
       end

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

@@ -8,11 +8,28 @@
 # so you can pick a branch/commit and travel to that ref's views for
 # the current URL. Delete this file if the defaults below work for you.
 RailsWayback.configure do |config|
+  # Rails Wayback is unavailable outside these environments, even if its
+  # toggle file exists. Add another environment only as an explicit opt-in.
+  # config.allowed_environments = %w[development test]
+  # Commits must be reachable from one of these Git ref patterns.
+  # Add refs/remotes/... or refs/tags/... patterns to show locally stored
+  # remote-tracking branches or tags. Rails Wayback never fetches from Git.
+  # config.trusted_ref_patterns = ["refs/heads/*"]
+
   # Directories (relative to Rails.root) whose contents are pulled from
-  # the target git ref and used to render the historical preview.
+  # the target git ref. Browser-ready files under historical public/ are
+  # discovered through standard Rails helpers; pipeline builds are not run.
   # config.view_paths  = %w[app/views]
   # config.asset_paths = %w[app/assets public]
 
   # How many recent commits per branch are shown in the bar dropdown.
   # config.max_commits = 50
+  # Both LRU limits are applied automatically after a new ref is cached.
+  # Set either value to nil to disable that limit.
+  # config.max_cached_refs = 25
+  # config.max_cache_bytes = 512 * 1024 * 1024
+
+  # Maximum buffered HTML response size that may receive the toolbar.
+  # Streaming, encoded, file, and larger responses are always left untouched.
+  # config.max_response_bytes = 2 * 1024 * 1024
 end

data/lib/rails_wayback/asset_provenance.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  module AssetProvenance
+    EVENT_PREFIX = "rails_wayback.asset."
+    ORIGINS = %i[historical current].freeze
+
+    module_function
+
+    def record(origin:, identifier:)
+      return unless ORIGINS.include?(origin.to_sym)
+
+      RailsWayback::RenderContext.current&.record(
+        event: "#{EVENT_PREFIX}#{origin}",
+        identifier: identifier
+      )
+    end
+
+    def paths_by_origin(entries)
+      result = { historical: [], current: [] }
+      Array(entries).each do |entry|
+        event = entry_value(entry, :event)
+        next unless event.start_with?(EVENT_PREFIX)
+
+        origin = event.delete_prefix(EVENT_PREFIX).to_sym
+        next unless result.key?(origin)
+
+        identifier = entry_value(entry, :identifier)
+        result[origin] << identifier unless identifier.empty?
+      end
+      result.transform_values(&:uniq)
+    end
+
+    def entry_value(entry, key)
+      return "" unless entry.is_a?(Hash)
+
+      (entry[key] || entry[key.to_s]).to_s
+    end
+    private_class_method :entry_value
+  end
+end