dommy-rack 0.8.0

data/lib/dommy/rack/form_submission.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    # Collects successful form controls and resolves the effective method,
+    # action, and enctype for a form submission. Stateless given the form,
+    # submitter, and session config — it returns a plain data hash and does
+    # not make any requests itself.
+    class FormSubmission
+      FORM_URLENCODED = "application/x-www-form-urlencoded"
+      MULTIPART = "multipart/form-data"
+      OVERRIDE_METHODS = %w[PATCH PUT DELETE].freeze
+
+      def initialize(form, submitter, config)
+        @form = form
+        @submitter = submitter
+        @config = config
+      end
+
+      # Returns { method:, url:, params:, enctype: }.
+      def submit!
+        method = form_method
+        params = collect_params
+        method = apply_method_override(method, params)
+        params = apply_charset(params)
+
+        {
+          method: method,
+          url: resolve_action(form_method),
+          params: params,
+          enctype: form_enctype
+        }
+      end
+
+      private
+
+      def form_method
+        raw = (attr(@submitter, "formmethod") || attr(@form, "method")).to_s.upcase
+        %w[GET POST].include?(raw) ? raw : "GET"
+      end
+
+      def form_enctype
+        attr(@submitter, "formenctype") || attr(@form, "enctype") || FORM_URLENCODED
+      end
+
+      # For GET forms the action's existing query string is discarded and
+      # replaced by the form data; POST keeps it.
+      def resolve_action(method)
+        raw = (attr(@submitter, "formaction") || attr(@form, "action") || "").to_s
+        method == "GET" ? raw.split("?", 2).first.to_s : raw
+      end
+
+      # Returns ordered [name, value] pairs in document order. The clicked
+      # submitter is emitted at its document position; only if it isn't among
+      # the form's controls do we append it at the end.
+      def collect_params
+        pairs = []
+        submitter_emitted = false
+        controls.each do |el|
+          next if disabled?(el)
+
+          case el.tag_name
+          when "INPUT" then submitter_emitted = true if collect_input(el, pairs)
+          when "TEXTAREA" then collect_named(el, normalize_newlines(el.value.to_s), pairs)
+          when "SELECT" then collect_select(el, pairs)
+          when "BUTTON" then submitter_emitted = true if collect_button(el, pairs)
+          end
+        end
+        append_submitter(pairs) unless submitter_emitted
+        pairs
+      end
+
+      # Returns true when this input is the clicked submitter (and was emitted).
+      def collect_input(el, pairs)
+        type = el.type
+        if %w[submit image].include?(type)
+          return false unless submitter?(el)
+
+          emit_submitter(el, pairs)
+          return true
+        end
+        return false if %w[reset button].include?(type) # never submitted
+
+        case type
+        when "checkbox", "radio"
+          if el.checked
+            value = el.has_attribute?("value") ? el.get_attribute("value") : "on"
+            collect_named(el, value, pairs)
+          end
+        when "file"
+          collect_file(el, pairs)
+        else
+          collect_named(el, el.value.to_s, pairs)
+        end
+        false
+      end
+
+      # Only the clicked submitter button contributes its name/value.
+      def collect_button(el, pairs)
+        return false unless submitter?(el)
+
+        emit_submitter(el, pairs)
+        true
+      end
+
+      def submitter?(el)
+        @submitter && el.__dommy_backend_node__.equal?(@submitter.__dommy_backend_node__)
+      end
+
+      # Each File becomes its own entry. An empty file input still
+      # contributes an empty File so the field name survives (HTML spec).
+      def collect_file(el, pairs)
+        name = attr(el, "name")
+        return if blank?(name)
+
+        files = el.respond_to?(:files) ? el.files : nil
+
+        unless multipart?
+          # Non-multipart forms submit only the file's basename, per browsers.
+          filename = files && !files.empty? ? files.first.name.to_s : ""
+          pairs << [name, ::File.basename(filename)]
+          return
+        end
+
+        if files && !files.empty?
+          files.each { |file| pairs << [name, file] }
+        else
+          pairs << [name, Dommy::File.new([], "", "type" => "application/octet-stream")]
+        end
+      end
+
+      def multipart?
+        form_enctype == MULTIPART
+      end
+
+      def collect_select(el, pairs)
+        name = attr(el, "name")
+        return if blank?(name)
+
+        each_node(el.selected_options) do |option|
+          pairs << [name, option.value.to_s]
+        end
+      end
+
+      # Browsers submit textarea values with CRLF line endings.
+      def normalize_newlines(value)
+        value.gsub(/\r\n|\r|\n/, "\r\n")
+      end
+
+      def collect_named(el, value, pairs)
+        name = attr(el, "name")
+        pairs << [name, value] unless blank?(name)
+      end
+
+      # Fallback when the submitter is not among the form's controls.
+      def append_submitter(pairs)
+        return unless @submitter
+
+        emit_submitter(@submitter, pairs)
+      end
+
+      # The submitter's name/value (or image coordinates) join the form data.
+      # `formaction`/`formmethod`/`formenctype` are honored elsewhere;
+      # `formtarget` is ignored (single session, like `target`) and
+      # `formnovalidate` is moot (dommy-rack runs no client-side validation).
+      def emit_submitter(el, pairs)
+        if image_submitter?(el)
+          # Image buttons submit click coordinates. With no layout we use 0,0.
+          prefix = blank?(attr(el, "name")) ? "" : "#{attr(el, "name")}."
+          pairs << ["#{prefix}x", "0"]
+          pairs << ["#{prefix}y", "0"]
+          return
+        end
+
+        name = attr(el, "name")
+        return if blank?(name)
+
+        pairs << [name, attr(el, "value") || ""]
+      end
+
+      def image_submitter?(el)
+        el.tag_name == "INPUT" && el.type == "image"
+      end
+
+      # Honor the form's accept-charset by encoding string values into the
+      # requested charset's bytes; urlencoding/multipart then carries them
+      # verbatim. Names are assumed ASCII. UTF-8 (the default) is a no-op.
+      def apply_charset(pairs)
+        charset = form_charset
+        return pairs if charset.nil? || charset == Encoding::UTF_8
+
+        pairs.map { |name, value| [name, encode_in(value, charset)] }
+      end
+
+      def form_charset
+        raw = attr(@form, "accept-charset").to_s
+        token = raw.split(/[\s,]+/).find { |t| !t.empty? }
+        return nil unless token
+
+        begin
+          Encoding.find(token)
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      def encode_in(value, charset)
+        case value
+        when Array then value.map { |v| encode_in(v, charset) }
+        when String then encode_string(value, charset)
+        else value # File/Blob pass through unchanged
+        end
+      end
+
+      def encode_string(value, charset)
+        value.encode(charset).b
+      rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+        value
+      end
+
+      def apply_method_override(method, pairs)
+        return method unless method == "POST" && @config.respect_method_override
+
+        index = pairs.index { |name, _| name == @config.method_override_param }
+        return method unless index
+
+        override = pairs.delete_at(index)[1]
+        candidate = override.to_s.upcase
+        OVERRIDE_METHODS.include?(candidate) ? candidate : method
+      end
+
+      # All controls belonging to this form, in document order: descendants
+      # without a `form` attribute, plus any element anywhere associated to
+      # this form by `form="<this form's id>"`. Scanning the whole document
+      # once keeps them in document order (matters for param ordering).
+      def controls
+        form_id = attr(@form, "id")
+        @form.document.query_selector_all("input, textarea, select, button").select do |el|
+          if el.has_attribute?("form")
+            !blank?(form_id) && el.get_attribute("form") == form_id
+          else
+            el.closest("form")&.equal?(@form)
+          end
+        end
+      end
+
+      # A control is unsuccessful if it or an ancestor <fieldset> is disabled.
+      def disabled?(el)
+        return true if el.has_attribute?("disabled")
+
+        fieldset = el.closest("fieldset")
+        fieldset ? fieldset.has_attribute?("disabled") : false
+      end
+
+
+      def attr(el, name)
+        el&.get_attribute(name)
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+
+      def each_node(collection)
+        if collection.respond_to?(:each)
+          collection.each { |node| yield node }
+        else
+          collection.length.times { |i| yield collection.item(i) }
+        end
+      end
+    end
+  end
+end

data/lib/dommy/rack/header_store.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    # The persistent request headers a Session sends on every request, plus the
+    # auth conveniences that set them. Encapsulates the header state and the
+    # case-insensitive merge the way CookieJar encapsulates cookie state — a
+    # Session owns one HeaderStore and mutates it via set / delete / basic_auth
+    # / bearer.
+    #
+    # HTTP header names are case-insensitive, so #delete and #merge match names
+    # case-insensitively: a per-request override replaces a stored default even
+    # when the two names differ only in case.
+    class HeaderStore
+      def initialize
+        @headers = {}
+      end
+
+      # A copy of the stored headers. Mutate via #set / #delete.
+      def to_h = @headers.dup
+
+      def set(name, value)
+        @headers[name.to_s] = value.to_s
+        self
+      end
+
+      def delete(name)
+        target = name.to_s.downcase
+        @headers.delete_if { |key, _| key.downcase == target }
+        self
+      end
+
+      # The headers to send for one request: the stored defaults with the
+      # per-request `override` applied on top. An override wins even if its name
+      # differs only in case from a default.
+      def merge(override)
+        return @headers.dup if override.nil? || override.empty?
+
+        merged = @headers.dup
+        override.each do |name, value|
+          merged.delete_if { |existing, _| existing.to_s.downcase == name.to_s.downcase }
+          merged[name] = value
+        end
+        merged
+      end
+
+      # HTTP Basic auth: sets a persistent Authorization header.
+      def basic_auth(user, password)
+        set("Authorization", "Basic #{["#{user}:#{password}"].pack("m0")}")
+      end
+
+      # Bearer-token auth: sets a persistent Authorization header.
+      def bearer(token)
+        set("Authorization", "Bearer #{token}")
+      end
+    end
+  end
+end

data/lib/dommy/rack/history.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    # Browser-tab-style navigation history: an ordered stack of visited URLs
+    # with a cursor. Visiting a new URL truncates any forward entries.
+    class History
+      def initialize
+        @stack = []
+        @index = -1
+      end
+
+      def push(url)
+        kept = @index >= 0 ? @stack[0..@index] : []
+        @stack = kept + [url]
+        @index = @stack.size - 1
+        url
+      end
+
+      # Move the cursor back one entry and return that URL, or nil at the start.
+      def back
+        return nil if @index <= 0
+
+        @index -= 1
+        current
+      end
+
+      # Move the cursor forward one entry and return that URL, or nil at the end.
+      def forward
+        return nil if @index >= @stack.size - 1
+
+        @index += 1
+        current
+      end
+
+      def current
+        @stack[@index] if @index >= 0
+      end
+
+      def entries
+        @stack.dup
+      end
+    end
+  end
+end

data/lib/dommy/rack/locator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rack
+    # Finds DOM elements within a document by Capybara-style locators. Pure
+    # querying: it raises ElementNotFoundError / AmbiguousElementError but does
+    # not mutate the DOM or perform navigation.
+    class Locator
+      def initialize(document)
+        @document = document
+      end
+
+      # A form field by id, name, label text, placeholder, or aria-label.
+      def find_field(locator)
+        candidates = []
+        by_id = @document.get_element_by_id(locator)
+        candidates << by_id if by_id
+        candidates.concat(by_name(locator))
+        candidates.concat(label_targets(locator))
+        candidates.concat(by_field_attribute("placeholder", locator))
+        candidates.concat(by_field_attribute("aria-label", locator))
+        resolve_single(candidates, locator)
+      end
+
+      # An <a> by visible text, id, title, or exact href.
+      def find_link(locator)
+        matches = @document.query_selector_all("a").select { |a| link_matches?(a, locator) }
+        resolve_single(matches, locator)
+      end
+
+      # A submit-capable button by text, value, id, name, or alt.
+      def find_button(locator)
+        buttons = @document.query_selector_all(
+          "button, input[type='submit'], input[type='image'], input[type='button']"
+        )
+        resolve_single(buttons.select { |b| button_matches?(b, locator) }, locator)
+      end
+
+      # The <option> of a select matching by visible text, then by value.
+      def find_option(select_el, value)
+        options = select_el.options.to_a
+        options.find { |o| o.text_content.strip == value.to_s } ||
+          options.find { |o| (o.get_attribute("value") || "").to_s == value.to_s }
+      end
+
+      # The form owning an element: an explicit `form` attribute, else the
+      # nearest ancestor <form>.
+      def form_for(element)
+        form_id = element.get_attribute("form")
+        if form_id && !form_id.empty?
+          @document.get_element_by_id(form_id)
+        else
+          element.closest("form")
+        end
+      end
+
+      private
+
+      def by_name(locator)
+        @document.query_selector_all("[name]").select { |e| e.get_attribute("name") == locator }
+      end
+
+      def by_field_attribute(attribute, value)
+        @document.query_selector_all("input, textarea, select")
+          .select { |e| e.get_attribute(attribute) == value }
+      end
+
+      def label_targets(locator)
+        @document.query_selector_all("label")
+          .select { |label| label.text_content.strip == locator }
+          .map { |label| label_control(label) }
+          .compact
+      end
+
+      def label_control(label)
+        return label.control if label.respond_to?(:control) && label.control
+
+        for_id = label.get_attribute("for")
+        if for_id && !for_id.empty?
+          @document.get_element_by_id(for_id)
+        else
+          label.query_selector("input, textarea, select")
+        end
+      end
+
+      def link_matches?(anchor, locator)
+        anchor.text_content.strip == locator ||
+          anchor.get_attribute("id") == locator ||
+          anchor.get_attribute("title") == locator ||
+          anchor.get_attribute("href") == locator
+      end
+
+      def button_matches?(button, locator)
+        if button.tag_name == "BUTTON"
+          return true if button.text_content.strip == locator
+        end
+        button.get_attribute("value") == locator ||
+          button.get_attribute("id") == locator ||
+          button.get_attribute("name") == locator ||
+          button.get_attribute("alt") == locator
+      end
+
+      def resolve_single(candidates, locator)
+        unique = candidates.compact.uniq(&:__dommy_backend_node__)
+        raise ElementNotFoundError, "no element matching #{locator.inspect}" if unique.empty?
+
+        if unique.size > 1
+          raise AmbiguousElementError, "#{unique.size} elements match #{locator.inspect}"
+        end
+
+        unique.first
+      end
+    end
+  end
+end

data/lib/dommy/rack/navigation.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Dommy
+  module Rack
+    # URL resolution, redirect following, same-origin enforcement, and
+    # browser-tab-style history. Reads policy from the frozen Config and drives
+    # the Session only through its request seam (raw_request /
+    # apply_navigation_response / current_url).
+    class Navigation
+      KEEP_METHOD_STATUSES = [307, 308].freeze
+
+      def initialize(session, config)
+        @session = session
+        @config = config
+      end
+
+      # Resolve a possibly-relative URL against a base (current URL or host).
+      def resolve_url(url_or_path, base_url)
+        base = base_url || @config.default_host
+        URI.join(base, url_or_path.to_s).to_s
+      rescue URI::InvalidURIError
+        url_or_path.to_s
+      end
+
+      def check_same_origin!(url)
+        return unless @config.enforce_same_origin
+        return if same_origin?(url, @config.default_host)
+
+        raise CrossOriginError, "cross-origin request to #{url} is not allowed"
+      end
+
+      # Perform a navigation, following redirects per session policy, then
+      # apply the final response to the session (updating document + history).
+      def navigate(method:, url:, params: nil, body: nil, headers: {})
+        verb = method.to_s.upcase
+        target = resolve_url(url, @session.current_url)
+        check_same_origin!(target)
+
+        response, final_url = run(method: verb, url: target, params: params, body: body, headers: headers)
+        @session.apply_navigation_response(response, final_url)
+        maybe_follow_meta_refresh(response) || response
+      end
+
+      # Fetch-style request: resolves and enforces origin, runs the redirect
+      # loop per mode, and returns the Response without touching session state.
+      def fetch(url, method: "GET", params: nil, body: nil, headers: {}, redirect: :follow)
+        verb = method.to_s.upcase
+        target = resolve_url(url, @session.current_url)
+        check_same_origin!(target)
+
+        args = {method: verb, url: target, params: params, body: body, headers: headers}
+        case redirect
+        when :follow
+          run(**args, follow: true).first
+        when :manual
+          run(**args, follow: false).first
+        when :error
+          response = run(**args, follow: false).first
+          raise Error, "redirect encountered with redirect: :error" if response.redirect?
+
+          response
+        else
+          raise ArgumentError, "unsupported redirect mode: #{redirect.inspect}"
+        end
+      end
+
+      # Re-navigate to an already-resolved URL without pushing a new history
+      # entry (used by Session#back / #forward).
+      def revisit(url)
+        response, final_url = run(method: "GET", url: url)
+        @session.apply_navigation_response(response, final_url, push_history: false)
+        response
+      end
+
+      # Run the request/redirect loop. Returns [response, final_url].
+      # Public so Session#fetch can reuse it without applying navigation state.
+      def run(method:, url:, params: nil, body: nil, headers: {}, follow: true)
+        verb = method
+        target = url
+        # Carry the fragment across redirects: a redirect Location without its
+        # own fragment preserves the previous one (browser behavior).
+        fragment = uri_fragment(target)
+        redirect_count = 0
+        chain = []
+
+        loop do
+          response = @session.raw_request(
+            verb, target, params: params, body: body, headers: headers
+          )
+
+          unless follow && redirect_to_follow?(response)
+            response.redirects = chain
+            return [response, with_fragment(target, fragment)]
+          end
+
+          chain << {status: response.status, url: target, location: response.location_header}
+          redirect_count += 1
+          if redirect_count > @config.max_redirects
+            raise TooManyRedirectsError, "exceeded #{@config.max_redirects} redirects"
+          end
+
+          target = resolve_url(response.location_header, target)
+          check_same_origin!(target)
+          location_fragment = uri_fragment(target)
+          fragment = location_fragment unless location_fragment.nil? || location_fragment.empty?
+
+          unless KEEP_METHOD_STATUSES.include?(response.status)
+            params = nil
+            body = nil
+          end
+          verb = redirect_method(response.status, verb)
+        end
+      end
+
+      private
+
+      # If the just-applied response asks for an immediate meta refresh,
+      # navigate there (browser behavior). Returns the final response after any
+      # chain of refreshes, or nil if none applied. Detecting the refresh is
+      # the Response's job; this only performs the navigation.
+      def maybe_follow_meta_refresh(response, depth = 0)
+        return nil unless @config.follow_meta_refresh
+
+        url = response.meta_refresh_url
+        return nil unless url
+
+        if depth >= @config.max_redirects
+          raise TooManyRedirectsError, "exceeded #{@config.max_redirects} meta refreshes"
+        end
+
+        target = resolve_url(url, @session.current_url)
+        check_same_origin!(target)
+        next_response, final_url = run(method: "GET", url: target)
+        @session.apply_navigation_response(next_response, final_url)
+        maybe_follow_meta_refresh(next_response, depth + 1) || next_response
+      end
+
+      def uri_fragment(url)
+        URI.parse(url.to_s).fragment
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def with_fragment(url, fragment)
+        return url if fragment.nil? || fragment.empty?
+        return url unless uri_fragment(url).to_s.empty?
+
+        "#{url}##{fragment}"
+      end
+
+      def redirect_to_follow?(response)
+        response.redirect? &&
+          @config.follow_redirects &&
+          !response.location_header.to_s.empty?
+      end
+
+      def redirect_method(status, original)
+        case status
+        when 303 then "GET"
+        when 301, 302 then original == "POST" ? "GET" : original
+        else original # 307, 308 keep the method
+        end
+      end
+
+      def same_origin?(url_a, url_b)
+        a = URI.parse(url_a)
+        b = URI.parse(url_b)
+        a.scheme == b.scheme && a.host == b.host && a.port == b.port
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+  end
+end