recipe_scrapers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7ef3e9e75436df3b37c84f48c98c7d09586560a9c1d90b567ee990b5ea9d288
+  data.tar.gz: c1fab2685faf5fbb236a74b8c9b4b5130b3f0c0c351c9fedfec919768e6dc260
+SHA512:
+  metadata.gz: 06cf44e4b1e4bc58c93d4176bd9bb8140ddcc9db43e6593f8685eea72557f709e8488245e82b8fb6289547a39d91072e6ee17084bab3a3d65a6927644eb35200
+  data.tar.gz: 11b3a22c61673e7232411f915e575aad8ef2f8f3b6ac838e54f63e03a21b023b2817c03aa4a415213530d6d8c7f515fae2befa0b31834ba79d2f742429f586ca

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+The first release.

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 David Khotelov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# recipe_scrapers
+
+A Ruby gem that reads recipes from cooking websites: the title, ingredients, instructions, times,
+yields and nutrition. It uses the [schema.org](https://schema.org/Recipe) markup most recipe sites
+publish, falls back to [OpenGraph](https://ogp.me/), and reads the HTML directly for sites that
+publish neither. It does not get around bot protection.
+
+## Installation
+
+```console
+bundle add recipe_scrapers
+```
+
+The gem runs on every Ruby version that has not reached its end of life.
+
+## Usage
+
+```ruby
+require "recipe_scrapers"
+
+recipe = RecipeScrapers.scrape("https://www.recipetineats.com/crispy-potato-straws-pommes-paille/")
+recipe.title                       # => "Crispy potato straws (Pommes Paille)"
+recipe.ingredients[1]              # => "1 1/2 - 2 cups vegetable oil (canola, sunflower or peanut oil)"
+recipe.parsed_ingredients[1].to_h  # => { amount: 1.5, unit: "cups", name: "vegetable oil" }
+recipe.cook_time                   # => 10
+recipe.to_h                        # every field as plain data, ready for JSON
+```
+
+To read HTML you already have, without a request:
+
+```ruby
+recipe = RecipeScrapers.parse(html, url: url)
+```
+
+## Documentation
+
+- [Usage](wiki/Usage.md): fetching, other HTTP clients, unsupported sites, errors
+- [Recipe Fields](wiki/Recipe-Fields.md): every field with its type and an example
+- [Configuration](wiki/Configuration.md): timeouts, size limits, your own connection
+- [Parsers](wiki/Parsers.md): your own ingredient and nutrient parsers
+- [API reference](https://rubydoc.info/gems/recipe_scrapers)
+- [Changelog](CHANGELOG.md)
+- [Copyright and Usage](wiki/Copyright-and-Usage.md): what you are responsible for
+
+## Contributing
+
+A site stopped working, or you need a new one? [Open an issue](https://github.com/davqasd/recipe_scrapers/issues)
+with the URL of a recipe page. To add it yourself, see [CONTRIBUTING](CONTRIBUTING.md). Report a
+security problem privately, see [SECURITY](SECURITY.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE). The pages recorded for the tests are not covered by it, see
+[License](wiki/License.md).

data/lib/recipe_scrapers/configuration.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module RecipeScrapers
+  # The settings for fetching pages and parsing fields. Read them through {RecipeScrapers.config}
+  # and change them with {RecipeScrapers.configure}. Changing a fetch setting rebuilds the connection
+  # on its next use, unless an application assigned its own with {#connection=}.
+  #
+  # @!attribute [rw] user_agent
+  #   @return [String] the User-Agent header every request sends
+  # @!attribute [rw] timeout
+  #   @return [Integer] seconds to wait for a whole response, 15 by default
+  # @!attribute [rw] open_timeout
+  #   @return [Integer] seconds to wait for the connection to open, 5 by default
+  # @!attribute [rw] max_redirects
+  #   @return [Integer] redirects to follow before {TooManyRedirects}, 3 by default
+  # @!attribute [rw] max_body_bytes
+  #   @return [Integer] the largest body accepted before {ResponseTooLarge}, 5 MiB by default
+  # @!attribute [rw] allow_private_addresses
+  #   @return [Boolean] fetch hosts that resolve to private or loopback addresses, false by default
+  # @!attribute [rw] error_tracker
+  #   @return [#call] gets the error of a failing parser, {ErrorTracker} by default
+  # @!attribute [rw] retry_options
+  #   @return [Hash] options for faraday-retry, used on timeouts, refused connections and 5xx
+  # @!attribute [rw] adapter
+  #   @return [Symbol, Class] the Faraday adapter, `:recipe_scrapers_net_http` ({Http::Adapter}) by default
+  # @!attribute [rw] resolver
+  #   @return [#call, nil] turns a host into IPAddr addresses, such as a DNS cache. Nil uses the
+  #     system resolver
+  class Configuration
+    DEFAULT_ADAPTER = :recipe_scrapers_net_http
+    RETRIED = [Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::ServerError].freeze
+
+    SETTINGS = %i[
+      user_agent timeout open_timeout max_redirects max_body_bytes
+      allow_private_addresses error_tracker retry_options adapter resolver
+    ].freeze
+
+    SETTINGS.each do |setting|
+      attr_reader setting
+
+      define_method(:"#{setting}=") do |value|
+        instance_variable_set(:"@#{setting}", value)
+        @connection = nil unless @connection_assigned
+        value
+      end
+    end
+
+    DEFAULTS = {
+      user_agent: "recipe_scrapers/#{VERSION} (+https://github.com/davqasd/recipe_scrapers)",
+      timeout: 15,
+      open_timeout: 5,
+      max_redirects: 3,
+      max_body_bytes: 5 * 1024 * 1024,
+      allow_private_addresses: false,
+      error_tracker: ErrorTracker,
+      retry_options: { max: 2, interval: 1, backoff_factor: 2 },
+      adapter: DEFAULT_ADAPTER,
+      resolver: nil
+    }.freeze
+
+    private_constant :DEFAULT_ADAPTER, :RETRIED, :SETTINGS, :DEFAULTS
+
+    # The parsers of every field that takes them, tried in order. A parser answers
+    # `call(text, language:)` with a hash of the model's attributes, or nil for text it cannot read.
+    #
+    # @example Put a parser in front of the bundled one
+    #   RecipeScrapers.config.parsers[:ingredients].unshift(GramsOnly)
+    # @return [Hash{Symbol => Array<#call>}]
+    attr_reader :parsers
+
+    def initialize
+      DEFAULTS.each { |setting, value| instance_variable_set(:"@#{setting}", value.dup) }
+      @parsers = Parsers::Chain.defaults
+      @connection = nil
+      @connection_assigned = false
+    end
+
+    # The Faraday connection {RecipeScrapers.scrape} fetches with, built from these settings.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= build_connection
+    end
+
+    # Replaces the connection with one the application builds. Nil goes back to the built one.
+    #
+    # @param value [Faraday::Connection, nil]
+    def connection=(value)
+      @connection_assigned = !value.nil?
+      @connection = value
+    end
+
+    # Builds a new connection with the retry, redirect, address guard, body limit and encoding
+    # middleware, in that order.
+    #
+    # @return [Faraday::Connection]
+    def build_connection
+      Faraday.new(headers: { "User-Agent" => user_agent }) do |faraday|
+        install_middleware(faraday)
+        faraday.options.timeout = timeout
+        faraday.options.open_timeout = open_timeout
+        faraday.adapter(adapter)
+      end
+    end
+
+    private
+
+    def install_middleware(faraday)
+      faraday.request(:retry, methods: [:get], exceptions: RETRIED, **retry_options)
+      faraday.use(:recipe_scrapers_follow_redirects, limit: max_redirects)
+      faraday.use(:recipe_scrapers_address_guard, allow_private: allow_private_addresses, resolver: resolver)
+      faraday.use(:recipe_scrapers_body_limit, bytes: max_body_bytes)
+      faraday.response(:recipe_scrapers_encoding)
+    end
+  end
+end

data/lib/recipe_scrapers/declaration.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RecipeScrapers
+  # Tells the gem where the recipe fields are on a site whose markup is missing or wrong. A
+  # declaration is built by {RecipeScrapers.register}. Inside its block, each recipe field is a
+  # method that takes a CSS selector:
+  #
+  # - `title "h1.recipe-title"` reads the text of the first match.
+  # - `ingredients rows: "ul.ingredients li"` reads one line per match, for ingredients,
+  #   instructions, keywords and equipment.
+  # - `ingredient_groups heading: "h3", item: "li"` splits the ingredients under their headings.
+  #
+  # A declared field wins over the schema.org value. Every field left out falls back to it.
+  #
+  # @example
+  #   RecipeScrapers.register "example.com" do
+  #     title "h1.recipe-title"
+  #     ingredients rows: ".ingredients li"
+  #     instructions rows: ".steps li"
+  #     encoding "windows-1251"
+  #   end
+  class Declaration
+    DECLARABLE = (Scraper::CONTRACT - %i[host]).freeze
+    private_constant :DECLARABLE
+
+    # @return [String] the host the declaration was registered for
+    attr_reader :host
+
+    # @return [String, nil] the encoding the site sends without saying so, set with {#encoding}
+    attr_reader :encoding_name
+
+    # @param host [String]
+    # @yield the declaration body, evaluated on the new declaration
+    # @return [Declaration]
+    def self.build(host, &block)
+      new(host).tap { |declaration| declaration.instance_eval(&block) if block }
+    end
+
+    def initialize(host)
+      @host = host
+      @rules = {}
+      @parsers = {}
+      @encoding_name = nil
+    end
+
+    # @param field [Symbol] a field of {Scraper::CONTRACT}
+    # @return [Hash, nil] what the declaration says about the field: `{selector:}`, `{rows:}`, or
+    #   `{heading:, item:}` for ingredient groups
+    #
+    # @api private
+    def rule(field)
+      @rules[field]
+    end
+
+    # Declares the encoding of pages that send no charset, or the wrong one.
+    #
+    # @param name [String] an encoding Ruby knows, such as "windows-1251"
+    def encoding(name)
+      @encoding_name = name
+    end
+
+    # Sets the parsers of a field for this site, in the order they are tried.
+    #
+    # @param field [Symbol] :ingredients or :nutrients
+    # @param parsers [Array<#call>]
+    # @raise [ArgumentError] for a field that takes no parser
+    def parser(field, *parsers)
+      @parsers[Parsers::Chain.field!(field)] = parsers
+    end
+
+    # @param field [Symbol]
+    # @return [Array<#call>, nil] the parsers this site sets for the field
+    #
+    # @api private
+    def parsers_for(field)
+      @parsers[field]
+    end
+
+    DECLARABLE.each do |field|
+      define_method(field) do |selector = nil, **options|
+        @rules[field] = selector ? { selector: selector } : options
+      end
+    end
+  end
+end

data/lib/recipe_scrapers/error_tracker.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RecipeScrapers
+  # The default {Configuration#error_tracker}. It raises the error again, so a failing parser is
+  # never swallowed. An application replaces it with anything that answers call(error), such as a
+  # lambda that reports to its error service and returns.
+  module ErrorTracker
+    # @param exception [StandardError] the error a parser raised
+    # @raise [StandardError] always, the error it was given
+    def self.call(exception)
+      raise exception
+    end
+  end
+end

data/lib/recipe_scrapers/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RecipeScrapers
+  # The ancestor of every error the gem raises.
+  class Error < StandardError; end
+  # Raised when the gem does not support the host and supported_only is on.
+  class UnsupportedSite < Error; end
+  # Raised when a page has no recipe title or no ingredients.
+  class RecipeNotFound < Error; end
+  # Raised when a response body is larger than {Configuration#max_body_bytes}.
+  class ResponseTooLarge < Error; end
+  # Raised when a host resolves to no address, or to a private, loopback or other non-public one.
+  class BlockedAddress < Error; end
+  # Raised when a redirect chain is longer than {Configuration#max_redirects}.
+  class TooManyRedirects < Error; end
+end

data/lib/recipe_scrapers/http/adapter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http"
+require_relative "address_guard"
+
+module RecipeScrapers
+  # The Faraday adapter and middleware that fetch a page safely.
+  module Http
+    # Faraday's net/http adapter, connecting to the addresses {AddressGuard} checked instead of
+    # resolving the host again. It tries the pinned addresses in order and moves on when one does not
+    # answer. The host name still goes into the TLS handshake and the Host header. Registered as
+    # `:recipe_scrapers_net_http`, the default {Configuration#adapter}.
+    class Adapter < Faraday::Adapter::NetHttp
+      PIN_KEY = AddressGuard::PIN_KEY
+      ATTEMPT_KEY = :recipe_scrapers_address
+      private_constant :PIN_KEY, :ATTEMPT_KEY
+
+      # @param env [Faraday::Env]
+      # @return [Faraday::Response]
+      # @raise [Faraday::ConnectionFailed] when no pinned address answers
+      #
+      # @api private
+      def call(env)
+        addresses = Array(env[:request]&.context&.dig(PIN_KEY))
+        return super if addresses.empty?
+
+        addresses.each_with_index do |address, index|
+          env[ATTEMPT_KEY] = address
+          return super(env)
+        rescue Faraday::ConnectionFailed
+          raise if index == addresses.size - 1
+        end
+      end
+
+      # @param env [Faraday::Env]
+      # @return [Net::HTTP] the connection, set to the pinned address unless a proxy is in use
+      #
+      # @api private
+      def net_http_connection(env)
+        super.tap do |http|
+          address = env[ATTEMPT_KEY] || Array(env[:request]&.context&.dig(PIN_KEY)).first
+          http.ipaddr = address if address && !http.proxy?
+        end
+      end
+    end
+  end
+end
+
+Faraday::Adapter.register_middleware(recipe_scrapers_net_http: RecipeScrapers::Http::Adapter)

data/lib/recipe_scrapers/http/address_guard.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "ipaddr"
+require "resolv"
+
+module RecipeScrapers
+  module Http
+    # Refuses a request whose host resolves to no address, or to a loopback, private, link-local,
+    # multicast, CGNAT or unspecified one, so a URL from a user cannot reach the internal network. It
+    # pins the addresses it checked for {Adapter}, which closes the window where DNS could answer
+    # differently the second time. Registered as `:recipe_scrapers_address_guard`.
+    class AddressGuard < Faraday::Middleware
+      CGNAT = IPAddr.new("100.64.0.0/10")
+      MULTICAST_V4 = IPAddr.new("224.0.0.0/4")
+      MULTICAST_V6 = IPAddr.new("ff00::/8")
+      UNSPECIFIED = [IPAddr.new("0.0.0.0"), IPAddr.new("::")].freeze
+      private_constant :CGNAT, :MULTICAST_V4, :MULTICAST_V6, :UNSPECIFIED
+
+      # The key of the request context where the guard pins the addresses it checked.
+      #
+      # @api private
+      PIN_KEY = :recipe_scrapers_resolve
+
+      # @param app [#call]
+      # @param allow_private [Boolean] let every address through, for development
+      # @param resolver [#call, nil] takes a host and returns IPAddr objects, the system resolver when nil
+      def initialize(app, allow_private: false, resolver: nil)
+        super(app)
+        @allow_private = allow_private
+        @resolver = resolver || method(:resolve)
+      end
+
+      # @param env [Faraday::Env]
+      # @raise [BlockedAddress]
+      #
+      # @api private
+      def on_request(env)
+        host = env.url.host.to_s
+        addresses = @resolver.call(host)
+        raise BlockedAddress, "#{host} did not resolve to any address" if addresses.empty?
+
+        addresses.each { |address| check(host, address) }
+        pin(env, addresses)
+      end
+
+      private
+
+      def check(host, address)
+        return if @allow_private
+        return unless blocked?(unwrap(address))
+
+        raise BlockedAddress, "#{host} resolved to #{address}, which is not a public address"
+      end
+
+      def blocked?(address)
+        return true if address.loopback? || address.private? || address.link_local?
+        return true if multicast?(address) || UNSPECIFIED.include?(address)
+
+        address.ipv4? && CGNAT.include?(address)
+      end
+
+      def multicast?(address)
+        address.ipv4? ? MULTICAST_V4.include?(address) : MULTICAST_V6.include?(address)
+      end
+
+      def unwrap(address)
+        address.ipv6? && address.ipv4_mapped? ? address.native : address
+      end
+
+      def pin(env, addresses)
+        env.request.context = (env.request.context || {}).merge(PIN_KEY => addresses.map(&:to_s))
+      end
+
+      def resolve(host)
+        Resolv.getaddresses(host).filter_map { |address| to_ip(address) }
+      end
+
+      def to_ip(address)
+        IPAddr.new(address)
+      rescue IPAddr::InvalidAddressError
+        nil
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(
+  recipe_scrapers_address_guard: RecipeScrapers::Http::AddressGuard
+)

data/lib/recipe_scrapers/http/body_limit.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module RecipeScrapers
+  module Http
+    # Refuses a response larger than a limit, checked against Content-Length and against the body
+    # itself. Registered as `:recipe_scrapers_body_limit`.
+    class BodyLimit < Faraday::Middleware
+      # @param app [#call]
+      # @param bytes [Integer] the largest body accepted
+      def initialize(app, bytes:)
+        super(app)
+        @bytes = bytes
+      end
+
+      # @param env [Faraday::Env]
+      # @raise [ResponseTooLarge]
+      #
+      # @api private
+      def on_complete(env)
+        refuse(declared_size(env).to_i) if over_limit?(declared_size(env))
+
+        actual = env[:body].to_s.bytesize
+        refuse(actual) if actual > @bytes
+      end
+
+      private
+
+      def declared_size(env)
+        env[:response_headers].to_h.find { |name, _| name.to_s.casecmp?("content-length") }&.last
+      end
+
+      def over_limit?(declared)
+        !declared.nil? && declared.to_i > @bytes
+      end
+
+      def refuse(size)
+        raise ResponseTooLarge, "response of #{size} bytes exceeds the limit of #{@bytes}"
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(recipe_scrapers_body_limit: RecipeScrapers::Http::BodyLimit)

data/lib/recipe_scrapers/http/encoding.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module RecipeScrapers
+  module Http
+    # Converts a response body to UTF-8, using the charset of the Content-Type header or of the meta
+    # tag in the first 4 KiB. Invalid bytes are replaced. Registered as `:recipe_scrapers_encoding`.
+    class Encoding < Faraday::Middleware
+      HEADER_CHARSET = /charset=([\w-]+)/i
+      META_CONTENT = /<meta[^>]+charset=["']?([\w-]+)/i
+      SNIFF_BYTES = 4096
+      private_constant :HEADER_CHARSET, :META_CONTENT, :SNIFF_BYTES
+
+      # @param env [Faraday::Env]
+      # @return [void]
+      #
+      # @api private
+      def on_complete(env)
+        body = env[:body]
+        return if body.nil? || body.empty?
+
+        env[:body] = to_utf8(body, charset_from(env[:response_headers]) || charset_from_meta(body))
+      end
+
+      private
+
+      def charset_from(headers)
+        header = headers.to_h.find { |name, _| name.to_s.casecmp?("content-type") }&.last
+        header&.[](HEADER_CHARSET, 1)
+      end
+
+      def charset_from_meta(body)
+        head = body.byteslice(0, SNIFF_BYTES).to_s.force_encoding(::Encoding::BINARY)
+        head[META_CONTENT, 1]
+      end
+
+      def to_utf8(body, name)
+        source = ::Encoding.find(name || "UTF-8")
+        body.dup.force_encoding(source).encode(::Encoding::UTF_8, invalid: :replace, undef: :replace)
+      rescue ArgumentError
+        body.dup.force_encoding(::Encoding::UTF_8).scrub
+      end
+    end
+  end
+end
+
+Faraday::Response.register_middleware(recipe_scrapers_encoding: RecipeScrapers::Http::Encoding)

data/lib/recipe_scrapers/http/follow_redirects.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "uri"
+
+module RecipeScrapers
+  module Http
+    # Follows 301, 302, 303, 307 and 308 redirects as GET requests. Every hop goes through the
+    # middleware after it again, so {AddressGuard} checks each host. The Authorization header is dropped
+    # when a redirect leaves the origin. Registered as `:recipe_scrapers_follow_redirects`.
+    class FollowRedirects < Faraday::Middleware
+      REDIRECTS = [301, 302, 303, 307, 308].freeze
+      CLEARED_ON_HOP = %i[status response response_headers].freeze
+      UNSAFE_IN_LOCATION = %r{[^\-_.!~*'()a-zA-Z\d;/?:@&=+$,\[\]%]}
+      AUTHORIZATION = "Authorization"
+      private_constant :REDIRECTS, :CLEARED_ON_HOP, :UNSAFE_IN_LOCATION, :AUTHORIZATION
+
+      # @param app [#call]
+      # @param limit [Integer] redirects to follow
+      def initialize(app, limit: 3)
+        super(app)
+        @limit = limit
+      end
+
+      # @param env [Faraday::Env]
+      # @return [Faraday::Response] the response of the last hop
+      # @raise [TooManyRedirects]
+      #
+      # @api private
+      def call(env)
+        follow(env, @limit)
+      end
+
+      private
+
+      def follow(env, hops_left)
+        response = @app.call(env)
+        location = redirect_location(response)
+        return response if location.nil?
+        raise TooManyRedirects, "gave up after #{@limit} redirects at #{env.url}" if hops_left.zero?
+
+        follow(next_hop(response.env.dup, location), hops_left - 1)
+      end
+
+      def redirect_location(response)
+        return nil unless REDIRECTS.include?(response.status)
+
+        location = response.headers["Location"].to_s.split("#").first.to_s
+        location.empty? ? nil : location.gsub(UNSAFE_IN_LOCATION) { |raw| escape(raw) }
+      end
+
+      def next_hop(env, location)
+        from = env.url
+        env.url = from + location
+        CLEARED_ON_HOP.each { |key| env.delete(key) }
+        env.method = :get
+        env.body = nil
+        env.request_headers.delete(AUTHORIZATION) unless same_origin?(from, env.url)
+        env
+      end
+
+      def same_origin?(from, to)
+        [from.scheme, from.host, from.port] == [to.scheme, to.host, to.port]
+      end
+
+      def escape(raw)
+        raw.unpack("C*").map { |byte| format("%%%02X", byte) }.join
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(
+  recipe_scrapers_follow_redirects: RecipeScrapers::Http::FollowRedirects
+)

data/lib/recipe_scrapers/models/ingredient.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RecipeScrapers
+  # The value objects the gem returns.
+  module Models
+    # One ingredient line split into its parts. {Models::Recipe#parsed_ingredients} holds these.
+    #
+    # @!attribute [r] amount
+    #   @return [Float, nil] the quantity, rounded to two places. A range keeps its lower bound
+    # @!attribute [r] unit
+    #   @return [String, nil] the unit as the page writes it, such as "cups" or "g"
+    # @!attribute [r] name
+    #   @return [String, nil] the ingredient, without text in parentheses
+    Ingredient = Data.define(:amount, :unit, :name) do
+      def initialize(amount: nil, unit: nil, name: nil)
+        super
+      end
+    end
+  end
+end

data/lib/recipe_scrapers/models/ingredient_group.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RecipeScrapers
+  module Models
+    # The ingredients under one heading of the page. {Models::Recipe#ingredient_groups} holds these.
+    #
+    # @!attribute [r] purpose
+    #   @return [String, nil] the heading, such as "For the sauce", or nil for ungrouped ingredients
+    # @!attribute [r] ingredients
+    #   @return [Array<String>] the ingredient lines of the group
+    # @!attribute [r] parsed_ingredients
+    #   @return [Array<Models::Ingredient>, nil] the same lines split into an amount, a unit and a
+    #     name, in the same order
+    IngredientGroup = Data.define(:purpose, :ingredients, :parsed_ingredients) do
+      def initialize(purpose:, ingredients:, parsed_ingredients: nil)
+        super
+      end
+    end
+  end
+end