rails-wayback 0.1.0 → 0.2.0

data/lib/rails_wayback/historical_asset_body.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  class HistoricalAssetBody
+    DEFAULT_CHUNK_SIZE = 64 * 1024
+
+    def initialize(sha:, public_path:, view_source: RailsWayback::ViewSource.new,
+                   resolver: RailsWayback::HistoricalAssetResolver.new,
+                   chunk_size: DEFAULT_CHUNK_SIZE)
+      @sha = sha
+      @public_path = public_path
+      @view_source = view_source
+      @resolver = resolver
+      @chunk_size = chunk_size
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      view_source.with_materialization(sha) do |root|
+        resolution = resolver.resolve_public_path(root: root, public_path: public_path)
+        unless resolution
+          raise RailsWayback::MaterializationError,
+                "Historical public asset #{public_path.inspect} is no longer available for #{sha}"
+        end
+
+        File.open(resolution.path, "rb") do |file|
+          while (chunk = file.read(chunk_size))
+            yield chunk
+          end
+        end
+      end
+    end
+
+    def close; end
+
+    private
+
+    attr_reader :sha, :public_path, :view_source, :resolver, :chunk_size
+  end
+end

data/lib/rails_wayback/historical_asset_helper.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  module HistoricalAssetHelper
+    MATERIALIZATION_ROOT_ENV = "rails_wayback.materialization_root"
+
+    def compute_asset_path(source, options = {})
+      resolve_historical_asset(source, options) || track_current_asset(source) { super }
+    end
+
+    def public_compute_asset_path(source, options = {})
+      resolve_historical_asset(source, options) || track_current_asset(source) { super }
+    end
+
+    def compute_asset_host(source = "", options = {})
+      if historical_asset_url?(source)
+        return request.base_url if options[:protocol] == :request
+
+        return nil
+      end
+
+      super
+    end
+
+    private
+
+    def resolve_historical_asset(source, options)
+      context = historical_asset_context
+      return unless context
+
+      sha, root = context
+      resolution = RailsWayback::HistoricalAssetResolver.new.resolve(
+        root: root,
+        source: source,
+        type: options[:type]
+      )
+      return unless resolution
+
+      RailsWayback::AssetProvenance.record(
+        origin: :historical,
+        identifier: "public/#{resolution.public_path}"
+      )
+      RailsWayback::HistoricalAssetResolver.url(
+        sha: sha,
+        public_path: resolution.public_path
+      )
+    end
+
+    def track_current_asset(source)
+      result = yield
+      RailsWayback::AssetProvenance.record(origin: :current, identifier: source.to_s) if historical_asset_context
+      result
+    end
+
+    def historical_asset_context
+      return unless respond_to?(:rails_wayback_active_ref)
+
+      sha = rails_wayback_active_ref.to_s
+      root = request.env[MATERIALIZATION_ROOT_ENV]
+      [sha, root] unless sha.empty? || !root
+    end
+
+    def historical_asset_url?(source)
+      sha = respond_to?(:rails_wayback_active_ref) ? rails_wayback_active_ref.to_s : ""
+      !sha.empty? && RailsWayback::HistoricalAssetResolver.historical_url?(source, sha: sha)
+    end
+  end
+end

data/lib/rails_wayback/historical_asset_resolver.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rack/utils"
+
+module RailsWayback
+  class HistoricalAssetResolver
+    TYPE_DIRECTORIES = {
+      audio: "audios",
+      font: "fonts",
+      image: "images",
+      javascript: "javascripts",
+      stylesheet: "stylesheets",
+      video: "videos"
+    }.freeze
+    ENCODED_TRAVERSAL = /%(?:2e|2f|5c)/i
+
+    Resolution = Struct.new(:path, :public_path, :size_bytes, keyword_init: true)
+
+    def resolve(root:, source:, type: nil)
+      candidates(source, type).each do |candidate|
+        resolution = resolve_public_path(root: root, public_path: candidate)
+        return resolution if resolution
+      end
+      nil
+    end
+
+    def resolve_public_path(root:, public_path:)
+      relative = normalize(public_path)
+      return unless relative
+
+      public_root = Pathname.new(root).join("public")
+      return unless safe_public_root?(public_root)
+
+      candidate = public_root.join(relative)
+      return unless candidate.file?
+
+      public_real = public_root.realpath
+      candidate_real = candidate.realpath
+      return unless under?(candidate_real, public_real)
+
+      Resolution.new(path: candidate_real, public_path: relative, size_bytes: candidate_real.size)
+    rescue SystemCallError
+      nil
+    end
+
+    def self.url(sha:, public_path:, mount: RailsWayback::EngineMount.path)
+      base = mount.to_s.sub(%r{/+\z}, "")
+      escaped = Rack::Utils.escape_path(public_path.to_s)
+      "#{base}/refs/#{sha}/assets/#{escaped}"
+    end
+
+    def self.historical_url?(source, sha:)
+      source.to_s.include?("/refs/#{sha}/assets/")
+    end
+
+    private
+
+    def candidates(source, type)
+      relative = normalize(source)
+      return [] unless relative
+
+      directory = TYPE_DIRECTORIES[type&.to_sym]
+      [relative, (File.join(directory, relative) if directory)].compact.uniq
+    end
+
+    def normalize(value)
+      raw = value.to_s
+      return unless safe_raw_path?(raw)
+
+      segments = raw.split("/", -1)
+      return if segments.any? { |segment| unsafe_segment?(segment) }
+
+      clean = Pathname.new(raw).cleanpath.to_s
+      clean unless clean == "." || clean.start_with?("../")
+    rescue ArgumentError
+      nil
+    end
+
+    def safe_raw_path?(raw)
+      !raw.empty? && !raw.start_with?("/") &&
+        !raw.include?("\0") && !raw.include?("\\") && !raw.match?(ENCODED_TRAVERSAL)
+    end
+
+    def unsafe_segment?(segment)
+      segment.empty? || [".", ".."].include?(segment)
+    end
+
+    def safe_public_root?(public_root)
+      stat = File.lstat(public_root)
+      stat.directory? && !stat.symlink?
+    rescue SystemCallError
+      false
+    end
+
+    def under?(path, root)
+      value = path.to_s
+      base = root.to_s
+      value.start_with?("#{base}#{File::SEPARATOR}")
+    end
+  end
+end

data/lib/rails_wayback/ref_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  # Authorizes immutable commits before historical files enter Action View.
+  class RefPolicy
+    ENV_KEY = "rails_wayback.ref_policy"
+    FULL_SHA = /\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/i
+
+    Result = Struct.new(:input, :sha, :trusted_refs, :reason, :message, keyword_init: true) do
+      def accepted?
+        reason.nil?
+      end
+
+      def rejected?
+        !accepted?
+      end
+    end
+
+    def initialize(configuration: RailsWayback.configuration, git: RailsWayback::Git.new)
+      @configuration = configuration
+      @git = git
+    end
+
+    def authorize(ref)
+      input = ref.to_s
+
+      unless valid_sha?(input)
+        return rejection(input, :invalid_format, "expected a full 40- or 64-character commit SHA")
+      end
+
+      sha = git.resolve_ref(input).downcase
+      trusted = trusted_refs_containing(sha)
+      if trusted.empty?
+        return rejection(input, :untrusted_ref, "commit is not reachable from a trusted Git ref", sha: sha)
+      end
+
+      Result.new(input: input, sha: sha, trusted_refs: trusted.freeze)
+    rescue RefNotFoundError
+      rejection(input, :unknown_ref, "commit does not exist in the local repository")
+    end
+
+    private
+
+    attr_reader :configuration, :git
+
+    def valid_sha?(ref)
+      ref.match?(FULL_SHA)
+    end
+
+    def trusted_refs_containing(sha)
+      patterns = Array(configuration.trusted_ref_patterns).map(&:to_s)
+      git.refs_containing(sha).select do |ref|
+        patterns.any? { |pattern| File.fnmatch?(pattern, ref) }
+      end.sort
+    end
+
+    def rejection(input, reason, detail, sha: nil)
+      label = (sha || input).inspect
+      label = "#{label.byteslice(0, 120)}..." if label.bytesize > 120
+      message = "Rejected travel ref #{label}: #{detail}."
+      Result.new(input: input, sha: sha, trusted_refs: [].freeze, reason: reason, message: message)
+    end
+  end
+end

data/lib/rails_wayback/render_context.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  # Exposes the request-owned render tracker to notification callbacks.
+  # Ruby fiber storage is inherited by child fibers and scoped separately
+  # for sibling fibers, which matches the lifecycle of async Rack requests.
+  module RenderContext
+    KEY = :rails_wayback_render_tracker
+
+    module_function
+
+    def current
+      Fiber[KEY]
+    end
+
+    def with(tracker)
+      previous = current
+      Fiber[KEY] = tracker
+      yield
+    ensure
+      Fiber[KEY] = previous
+    end
+  end
+end

data/lib/rails_wayback/render_provenance.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RailsWayback
+  # Classifies Action View render identifiers by filesystem origin and
+  # normalizes them back to paths relative to the host application. Both the
+  # engine logger and toolbar use this module so they cannot drift into
+  # applying different provenance rules.
+  module RenderProvenance
+    module_function
+
+    def origin_for(identifier, configuration: RailsWayback.configuration)
+      path = absolute_path(identifier)
+      return :other unless path
+
+      refs_root = File.expand_path(configuration.refs_cache_path.to_s)
+      return :historical if under?(path, refs_root)
+      return :current if current_view_roots(configuration).any? { |root| under?(path, root) }
+
+      :other
+    end
+
+    def paths_by_origin(entries, configuration: RailsWayback.configuration)
+      result = { historical: [], current: [] }
+
+      Array(entries).each do |entry|
+        identifier = identifier_from(entry)
+        origin = origin_for(identifier, configuration: configuration)
+        next unless result.key?(origin)
+
+        relative = relative_path(identifier, origin, configuration)
+        result[origin] << relative if relative
+      end
+
+      result.transform_values(&:uniq)
+    end
+
+    def under?(path, root)
+      path == root || path.start_with?("#{root}/")
+    end
+    private_class_method :under?
+
+    def absolute_path(identifier)
+      value = identifier.to_s
+      return nil if value.empty? || !Pathname.new(value).absolute?
+
+      File.expand_path(value)
+    end
+    private_class_method :absolute_path
+
+    def current_view_roots(configuration)
+      app_root = File.expand_path(configuration.app_root_path.to_s)
+      configuration.view_paths.map { |path| File.expand_path(path.to_s, app_root) }
+    end
+    private_class_method :current_view_roots
+
+    def identifier_from(entry)
+      case entry
+      when Hash
+        (entry[:identifier] || entry["identifier"]).to_s
+      else
+        entry.to_s
+      end
+    end
+    private_class_method :identifier_from
+
+    def relative_path(identifier, origin, configuration)
+      path = absolute_path(identifier)
+      return unless path
+
+      case origin
+      when :historical
+        refs_root = File.expand_path(configuration.refs_cache_path.to_s)
+        # Drop the refs root and the following SHA directory.
+        path.delete_prefix("#{refs_root}/").split("/", 2)[1]
+      when :current
+        app_root = File.expand_path(configuration.app_root_path.to_s)
+        path.delete_prefix("#{app_root}/") if under?(path, app_root)
+      end
+    end
+    private_class_method :relative_path
+  end
+end

data/lib/rails_wayback/render_tracker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  # Collects render events for one request. A tracker can be shared with
+  # child execution contexts while keeping mutation and closure atomic.
+  class RenderTracker
+    def initialize
+      @entries = []
+      @mutex = Mutex.new
+      @closed = false
+    end
+
+    def record(event:, identifier:)
+      @mutex.synchronize do
+        next false if @closed
+
+        @entries << { event: event.to_s, identifier: identifier.to_s }.freeze
+        true
+      end
+    end
+
+    def entries
+      @mutex.synchronize { @entries.dup }
+    end
+
+    def close
+      @mutex.synchronize { @closed = true }
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+  end
+end

data/lib/rails_wayback/toggle.rb

@@ -3,11 +3,12 @@
 require "fileutils"
 
 module RailsWayback
-  # Persists whether the engine should be mounted in the host app.
+  # Shares the current server session's state between the CLI and Rails.
   #
   # The flag is a plain file inside `tmp/rails_wayback/enabled` (ignored by
   # git). We keep it as a file so the CLI, rake tasks and running Rails
-  # process all agree on the same state without booting extra services.
+  # process all agree on the same state without booting extra services. The
+  # engine clears stale state whenever a new Rails server session starts.
   class Toggle
     def initialize(configuration = RailsWayback.configuration)
       @configuration = configuration
@@ -30,6 +31,13 @@ module RailsWayback
       true
     end
 
+    # Start a new server session disabled. Unlike `disable!`, this does not
+    # touch routes: Rails is already loading them as part of server boot.
+    def reset!
+      FileUtils.rm_f(configuration.toggle_file_path)
+      true
+    end
+
     def status
       enabled? ? :on : :off
     end

data/lib/rails_wayback/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsWayback
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end