reqcord 0.1.0 → 0.1.2

data/lib/reqcord/renderers/payload.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Renderers
+    # The wire-level decisions every output format has to agree on: whether a
+    # request is JSON, how a nested query flattens, what the body looks like
+    # as text. cURL, Postman and any later exporter read these, never their
+    # own copy.
+    module Payload
+      module_function
+
+      def json?(request)
+        request.content_type.to_s.include?("json") ||
+          request.headers.any? do |key, value|
+            key.to_s.casecmp?("Content-Type") && value.to_s.include?("json")
+          end
+      end
+
+      # Rails bracket notation: { filter: { status: "a" }, ids: [1, 2] } becomes
+      # [["filter[status]", "a"], ["ids[]", 1], ["ids[]", 2]].
+      def flatten_query(hash, prefix = nil)
+        hash.flat_map do |key, value|
+          current = prefix ? "#{prefix}[#{key}]" : key.to_s
+
+          case value
+          when Hash
+            flatten_query(value, current)
+          when Array
+            value.flat_map do |item|
+              if item.is_a?(Hash)
+                flatten_query(item, "#{current}[]")
+              else
+                [["#{current}[]", item]]
+              end
+            end
+          else
+            [[current, value]]
+          end
+        end
+      end
+
+      def query_pairs(request)
+        flatten_query(request.query_params)
+      end
+
+      def form_pairs(request)
+        request.body.is_a?(Hash) ? flatten_query(request.body) : []
+      end
+
+      def path_with_query(request)
+        return request.path if request.query_params.empty?
+
+        "#{request.path}?#{URI.encode_www_form(query_pairs(request))}"
+      end
+
+      # The body as it goes on the wire: pretty JSON, a form string, or the
+      # raw text the test sent.
+      def raw_body(request)
+        if json?(request)
+          JSON.pretty_generate(request.body)
+        elsif request.body.is_a?(Hash)
+          URI.encode_www_form(form_pairs(request))
+        else
+          request.body.to_s
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/request_example.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class RequestExample
+    ATTRIBUTES = %i[
+      name
+      method
+      path
+      path_params
+      query_params
+      headers
+      body
+      content_type
+      response_status
+      source
+    ].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(
+      method:,
+      path:,
+      name: nil,
+      path_params: {},
+      query_params: {},
+      headers: {},
+      body: nil,
+      content_type: nil,
+      response_status: nil,
+      source: {}
+    )
+      @name = name
+      @method = method.to_s.upcase
+      @path = path
+      @path_params = path_params || {}
+      @query_params = query_params || {}
+      @headers = headers || {}
+      @body = body
+      @content_type = content_type
+      @response_status = response_status&.to_i
+      @source = source || {}
+    end
+
+    # `method` is the HTTP verb here; this alias keeps call sites that mean the
+    # verb from reading like reflection.
+    def http_method
+      method
+    end
+
+    # A payload of empty containers ({"experience" => {}}) carries nothing to
+    # document, and sending it as --data would only mislead.
+    def body?
+      meaningful?(body)
+    end
+
+    # The request the endpoint page leads with should be one that worked.
+    def successful?
+      response_status.nil? ? false : (200..299).cover?(response_status)
+    end
+
+    # Identical requests captured by several tests are stored once — but the
+    # same request that produced a different status is a different example.
+    # Sanitization can make a right and a wrong password look identical; the
+    # 200 must not be dropped because the 401 was captured first.
+    def signature
+      JSON.generate([method, path, headers, query_params, body, response_status])
+    end
+
+    def to_h
+      {
+        name: name,
+        method: method,
+        path: path,
+        path_params: path_params,
+        query_params: query_params,
+        headers: headers,
+        body: body,
+        content_type: content_type,
+        response_status: response_status,
+        source: source
+      }
+    end
+
+    # Tolerates keys this version does not know, so a dataset written by a
+    # newer Reqcord still loads.
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_sym).slice(*ATTRIBUTES)
+
+      new(**hash)
+    end
+
+    private
+
+    def meaningful?(value)
+      case value
+      when nil then false
+      when Hash then value.any? { |_key, nested| meaningful?(nested) }
+      when Array then value.any? { |item| meaningful?(item) }
+      when String then !value.empty?
+      else true
+      end
+    end
+  end
+end

data/lib/reqcord/response_example.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Reqcord
+  class ResponseExample
+    ATTRIBUTES = %i[
+      name
+      status
+      headers
+      body
+      content_type
+      source
+    ].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(
+      status:,
+      name: nil,
+      headers: {},
+      body: nil,
+      content_type: nil,
+      source: {}
+    )
+      @name = name
+      @status = status.to_i
+      @headers = headers || {}
+      @body = body
+      @content_type = content_type
+      @source = source || {}
+    end
+
+    # "201 Created"
+    def status_text
+      Rack::Utils::HTTP_STATUS_CODES[status] || "Unknown"
+    end
+
+    def title
+      "#{status} #{status_text}"
+    end
+
+    def body?
+      !(body.nil? || (body.respond_to?(:empty?) && body.empty?))
+    end
+
+    def empty_body?
+      !body?
+    end
+
+    def signature
+      JSON.generate([status, body])
+    end
+
+    def to_h
+      {
+        name: name,
+        status: status,
+        headers: headers,
+        body: body,
+        content_type: content_type,
+        source: source
+      }
+    end
+
+    # Tolerates keys this version does not know, so a dataset written by a
+    # newer Reqcord still loads.
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_sym).slice(*ATTRIBUTES)
+
+      new(**hash)
+    end
+  end
+end

data/lib/reqcord/route_collector.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # The documented surface is the route table, not the captured traffic: every
+  # matching route becomes an endpoint, and captures are attached to it. Routes
+  # no test exercised stay in the dataset as documentation gaps.
+  #
+  # Nothing is dropped silently: a route either becomes a Route, or is counted
+  # in `skipped` with the reason (redirect, Rack mount, Rails internal).
+  class RouteCollector
+    # A route that answers any verb (`via: :all`); the captured verb decides
+    # what gets documented.
+    ANY = "ANY"
+
+    Route = Struct.new(
+      :name,
+      :method,
+      :path,
+      :controller,
+      :action,
+      :resource,
+      :api_version,
+      :rails_route,
+      :mount_prefix,
+      keyword_init: true
+    ) do
+      def endpoint(method: self.method)
+        Endpoint.new(
+          method: method,
+          path: path,
+          controller: controller,
+          action: action,
+          resource: resource,
+          api_version: api_version,
+          route_name: name
+        )
+      end
+
+      def any_verb?
+        method == ANY
+      end
+
+      def matches?(request_method, request_path)
+        return false unless any_verb? || method == request_method.to_s.upcase
+
+        relative = relative_path(request_path)
+        return false if relative.nil?
+
+        !!rails_route.path.match(relative)
+      end
+
+      private
+
+      # An engine's pattern knows nothing about where it was mounted.
+      def relative_path(request_path)
+        return request_path if mount_prefix.nil? || mount_prefix.empty?
+        return nil unless request_path.start_with?(mount_prefix)
+
+        rest = request_path.delete_prefix(mount_prefix)
+        return nil unless rest.empty? || rest.start_with?("/")
+
+        rest.empty? ? "/" : rest
+      end
+    end
+
+    def self.call(
+      resources: [],
+      version: nil,
+      prefix: nil,
+      route_set: nil
+    )
+      new(
+        resources: resources,
+        version: version,
+        prefix: prefix,
+        route_set: route_set
+      ).call
+    end
+
+    # Routes that were seen but cannot be documented, by reason.
+    attr_reader :skipped
+
+    def initialize(resources:, version:, prefix:, route_set: nil)
+      @resources = Array(resources).map(&:to_s)
+      @version = version&.to_s
+      @prefix = prefix
+      @route_set = route_set
+      @skipped = Hash.new(0)
+    end
+
+    def call
+      @skipped = Hash.new(0)
+
+      collect(route_set.routes, mount_prefix: nil)
+    end
+
+    def skipped_count
+      skipped.values.sum
+    end
+
+    private
+
+    attr_reader :resources, :version, :prefix
+
+    def route_set
+      @route_set ||= Rails.application.routes
+    end
+
+    def collect(rails_routes, mount_prefix:)
+      rails_routes.flat_map { |rails_route| build_routes(rails_route, mount_prefix) }
+    end
+
+    def build_routes(rails_route, mount_prefix)
+      return [] if rails_route.internal
+
+      app = rails_route.app
+      spec = normalize_path(rails_route.path.spec.to_s)
+
+      # A mounted engine's routes live in its own table, relative to the mount.
+      if engine?(app)
+        return collect(app.rack_app.routes.routes, mount_prefix: join(mount_prefix, spec))
+      end
+
+      controller = rails_route.defaults[:controller]&.to_s
+      action = rails_route.defaults[:action]&.to_s
+
+      if controller.nil? || action.nil?
+        @skipped[skip_reason(app)] += 1
+        return []
+      end
+
+      return [] if internal?(controller)
+
+      path = join(mount_prefix, spec)
+
+      return [] unless matches_prefix?(path)
+      return [] unless matches_version?(controller, path)
+
+      resource = controller.split("/").last
+
+      return [] unless matches_resource?(resource, controller)
+
+      normalize_methods(rails_route.verb).map do |method|
+        Route.new(
+          name: rails_route.name,
+          method: method,
+          path: path,
+          controller: controller,
+          action: action,
+          resource: resource,
+          api_version: detect_version(controller, path),
+          rails_route: rails_route,
+          mount_prefix: mount_prefix
+        )
+      end
+    end
+
+    # A mounted app that carries its own route table (a Rails::Engine, or
+    # anything shaped like one). Checked by shape rather than by class: the
+    # `Rails::Engine` constant need not be loaded, and a Sinatra app — whose
+    # `routes` is a plain Hash — is a Rack mount, not an engine.
+    def engine?(app)
+      return false unless app.respond_to?(:rack_app)
+
+      rack_app = app.rack_app
+
+      rack_app.respond_to?(:routes) && rack_app.routes.respond_to?(:routes)
+    end
+
+    def skip_reason(app)
+      rack_app = app.respond_to?(:rack_app) ? app.rack_app : app
+
+      if defined?(ActionDispatch::Routing::Redirect) && rack_app.is_a?(ActionDispatch::Routing::Redirect)
+        "redirect"
+      else
+        "mount"
+      end
+    end
+
+    # Rails 8 exposes the verb as a plain string: "GET", "GET|POST" for
+    # `via: [:get, :post]`, "" for `via: :all`. Older versions used a regexp
+    # whose source carried anchors.
+    def normalize_methods(verb)
+      values = verb.to_s
+                   .gsub(/[$^]/, "")
+                   .split("|")
+                   .map(&:strip)
+                   .reject(&:empty?)
+                   .map(&:upcase)
+
+      values.empty? ? [ANY] : values
+    end
+
+    def normalize_path(path)
+      path.sub(/\(\.:format\)\z/, "")
+    end
+
+    def join(mount_prefix, path)
+      return path if mount_prefix.nil? || mount_prefix.empty?
+      return mount_prefix if path == "/"
+
+      "#{mount_prefix}#{path}"
+    end
+
+    def internal?(controller)
+      controller.start_with?(
+        "rails/",
+        "active_storage/",
+        "action_mailbox/",
+        "turbo/"
+      )
+    end
+
+    def matches_prefix?(path)
+      return true if prefix.nil? || prefix.empty?
+
+      path.start_with?(prefix)
+    end
+
+    # `RESOURCE=customers`, `RESOURCE=cart` (a singular resource is served by
+    # `carts`) and `RESOURCE=api/v2/customers` all name the same thing.
+    def matches_resource?(resource, controller)
+      return true if resources.empty?
+
+      candidates = [resource, controller, Support.singularize(resource)]
+
+      resources.any? { |wanted| candidates.include?(wanted) }
+    end
+
+    def matches_version?(controller, path)
+      return true if version.nil? || version.empty?
+
+      controller.split("/").include?(version) ||
+        path.split("/").include?(version)
+    end
+
+    def detect_version(controller, path)
+      controller.split("/").find { |segment| segment.match?(/\Av\d+\z/) } ||
+        path.split("/").find { |segment| segment.match?(/\Av\d+\z/) }
+    end
+  end
+end

data/lib/reqcord/sanitizers/sanitizer.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Sanitizers
+    # Works on a raw captured exchange, before anything reaches the dataset:
+    # credentials must never be written to a generated file.
+    class Sanitizer
+      DEFAULT_SECRET_HEADERS = %w[
+        Authorization
+        Proxy-Authorization
+        Cookie
+        Set-Cookie
+        X-Api-Key
+        X-Auth-Token
+        X-Csrf-Token
+      ].freeze
+
+      SCHEME_PATTERN = /\A(Bearer|Token|Basic)\s+/i
+
+      def self.call(exchange, configuration:)
+        new(
+          exchange,
+          configuration: configuration
+        ).call
+      end
+
+      def initialize(exchange, configuration:)
+        @exchange = deep_dup(exchange)
+        @configuration = configuration
+      end
+
+      def call
+        sanitize_headers!(
+          exchange.dig("request", "headers")
+        )
+
+        sanitize_headers!(
+          exchange.dig("response", "headers"),
+          response: true
+        )
+
+        sanitize_body!("request")
+        sanitize_body!("response")
+
+        exchange
+      end
+
+      private
+
+      attr_reader :exchange, :configuration
+
+      def sanitize_headers!(headers, response: false)
+        return unless headers.is_a?(Hash)
+
+        replacements = configuration.sanitized_headers
+
+        headers.keys.each do |key|
+          if configuration.noisy_header?(key)
+            headers.delete(key)
+            next
+          end
+
+          if blank?(headers[key])
+            headers.delete(key)
+            next
+          end
+
+          replacement = find_replacement(replacements, key)
+
+          if replacement
+            headers[key] = replacement
+            next
+          end
+
+          headers[key] = redact(key, headers[key]) if secret_header?(key)
+        end
+      end
+
+      def sanitize_body!(side)
+        body = exchange.dig(side, "body")
+
+        return unless body.is_a?(Hash) || body.is_a?(Array)
+
+        exchange[side]["body"] = sanitize_value(body)
+      end
+
+      def sanitize_value(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), result|
+            replacement = body_replacement(key)
+
+            result[key] = replacement || sanitize_value(nested)
+          end
+        when Array
+          value.map { |item| sanitize_value(item) }
+        else
+          value
+        end
+      end
+
+      def body_replacement(key)
+        configuration.sanitized_body_keys.find do |name, _value|
+          name.to_s.casecmp?(key.to_s)
+        end&.last
+      end
+
+      def find_replacement(replacements, key)
+        pair = replacements.find do |header, _value|
+          header.to_s.casecmp?(key.to_s)
+        end
+
+        pair&.last
+      end
+
+      # The scheme is kept so the generated cURL stays copy-pasteable.
+      def redact(key, value)
+        placeholder = "{{#{key.to_s.tr('-', '_').downcase}}}"
+
+        match = value.to_s.match(SCHEME_PATTERN)
+
+        match ? "#{match[1]} #{placeholder}" : placeholder
+      end
+
+      def secret_header?(key)
+        DEFAULT_SECRET_HEADERS.any? do |header|
+          header.casecmp?(key.to_s)
+        end
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+
+      def deep_dup(value)
+        Marshal.load(Marshal.dump(value))
+      end
+    end
+  end
+end