feat(action_dispatch): allow custom domain extractor class

Author: rainerborene

actionpack/lib/action_dispatch/http/url.rb

@@ -11,8 +11,105 @@ module URL
       HOST_REGEXP     = /(^[^:]+:\/\/)?(\[[^\]]+\]|[^:]+)(?::(\d+$))?/
       PROTOCOL_REGEXP = /^([^:]+)(:)?(\/\/)?$/
 
+      # DomainExtractor provides utility methods for extracting domain and subdomain
+      # information from host strings. This module is used internally by Action Dispatch
+      # to parse host names and separate the domain from subdomains based on the
+      # top-level domain (TLD) length.
+      #
+      # The module assumes a standard domain structure where domains consist of:
+      # - Subdomains (optional, can be multiple levels)
+      # - Domain name
+      # - Top-level domain (TLD, can be multiple levels like .co.uk)
+      #
+      # For example, in "api.staging.example.co.uk":
+      # - Subdomains: ["api", "staging"]
+      # - Domain: "example.co.uk" (with tld_length=2)
+      # - TLD: "co.uk"
+      module DomainExtractor
+        extend self
+
+        # Extracts the domain part from a host string, including the specified
+        # number of top-level domain components.
+        #
+        # The domain includes the main domain name plus the TLD components.
+        # The +tld_length+ parameter specifies how many components from the right
+        # should be considered part of the TLD.
+        #
+        # ==== Parameters
+        #
+        # [+host+]
+        #   The host string to extract the domain from.
+        #
+        # [+tld_length+]
+        #   The number of domain components that make up the TLD. For example,
+        #   use 1 for ".com" or 2 for ".co.uk".
+        #
+        # ==== Examples
+        #
+        #   # Standard TLD (tld_length = 1)
+        #   DomainExtractor.domain_from("www.example.com", 1)
+        #   # => "example.com"
+        #
+        #   # Country-code TLD (tld_length = 2)
+        #   DomainExtractor.domain_from("www.example.co.uk", 2)
+        #   # => "example.co.uk"
+        #
+        #   # Multiple subdomains
+        #   DomainExtractor.domain_from("api.staging.myapp.herokuapp.com", 1)
+        #   # => "herokuapp.com"
+        #
+        #   # Single component (returns the host itself)
+        #   DomainExtractor.domain_from("localhost", 1)
+        #   # => "localhost"
+        def domain_from(host, tld_length)
+          host.split(".").last(1 + tld_length).join(".")
+        end
+
+        # Extracts the subdomain components from a host string as an Array.
+        #
+        # Returns all the components that come before the domain and TLD parts.
+        # The +tld_length+ parameter is used to determine where the domain begins
+        # so that everything before it is considered a subdomain.
+        #
+        # ==== Parameters
+        #
+        # [+host+]
+        #   The host string to extract subdomains from.
+        #
+        # [+tld_length+]
+        #   The number of domain components that make up the TLD. This affects
+        #   where the domain boundary is calculated.
+        #
+        # ==== Examples
+        #
+        #   # Standard TLD (tld_length = 1)
+        #   DomainExtractor.subdomains_from("www.example.com", 1)
+        #   # => ["www"]
+        #
+        #   # Country-code TLD (tld_length = 2)
+        #   DomainExtractor.subdomains_from("api.staging.example.co.uk", 2)
+        #   # => ["api", "staging"]
+        #
+        #   # No subdomains
+        #   DomainExtractor.subdomains_from("example.com", 1)
+        #   # => []
+        #
+        #   # Single subdomain with complex TLD
+        #   DomainExtractor.subdomains_from("www.mysite.co.uk", 2)
+        #   # => ["www"]
+        #
+        #   # Multiple levels of subdomains
+        #   DomainExtractor.subdomains_from("dev.api.staging.example.com", 1)
+        #   # => ["dev", "api", "staging"]
+        def subdomains_from(host, tld_length)
+          parts = host.split(".")
+          parts[0..-(tld_length + 2)]
+        end
+      end
+
       mattr_accessor :secure_protocol, default: false
       mattr_accessor :tld_length, default: 1
+      mattr_accessor :domain_extractor, default: DomainExtractor
 
       class << self
         # Returns the domain part of a host given the domain level.
@@ -96,12 +193,11 @@ def add_anchor(path, anchor)
           end
 
           def extract_domain_from(host, tld_length)
-            host.split(".").last(1 + tld_length).join(".")
+            domain_extractor.domain_from(host, tld_length)
           end
 
           def extract_subdomains_from(host, tld_length)
-            parts = host.split(".")
-            parts[0..-(tld_length + 2)]
+            domain_extractor.subdomains_from(host, tld_length)
           end
 
           def build_host_url(host, port, protocol, options, path)

actionpack/lib/action_dispatch/railtie.rb

@@ -55,6 +55,10 @@ class Railtie < Rails::Railtie # :nodoc:
       ActionDispatch::Http::URL.secure_protocol = app.config.force_ssl
       ActionDispatch::Http::URL.tld_length = app.config.action_dispatch.tld_length
 
+      unless app.config.action_dispatch.domain_extractor.nil?
+        ActionDispatch::Http::URL.domain_extractor = app.config.action_dispatch.domain_extractor
+      end
+
       ActionDispatch::ParamBuilder.ignore_leading_brackets = app.config.action_dispatch.ignore_leading_brackets
       ActionDispatch::QueryParser.strict_query_string_separator = app.config.action_dispatch.strict_query_string_separator
 

actionpack/test/dispatch/request_test.rb

@@ -333,6 +333,34 @@ class RequestDomain < BaseRequestTest
   end
 end
 
+class RequestDomainExtractor < BaseRequestTest
+  module CustomExtractor
+    extend self
+
+    def domain_from(_, _)
+      "world"
+    end
+
+    def subdomains_from(_, _)
+      ["hello"]
+    end
+  end
+
+  setup { ActionDispatch::Http::URL.domain_extractor = CustomExtractor }
+
+  teardown { ActionDispatch::Http::URL.domain_extractor = ActionDispatch::Http::URL::DomainExtractor }
+
+  test "domain" do
+    request = stub_request "HTTP_HOST" => "foobar.foobar.com"
+    assert_equal "world", request.domain
+  end
+
+  test "subdomains" do
+    request = stub_request "HTTP_HOST" => "foobar.foobar.com"
+    assert_equal "hello", request.subdomain
+  end
+end
+
 class RequestPort < BaseRequestTest
   test "standard_port" do
     request = stub_request

guides/source/configuring.md

@@ -2069,6 +2069,26 @@ Specifies the default character set for all renders. Defaults to `nil`.
 
 Sets the TLD (top-level domain) length for the application. Defaults to `1`.
 
+#### `config.action_dispatch.domain_extractor`
+
+Configures the domain extraction strategy used by Action Dispatch for parsing host names into domain and subdomain components. This must be an object that responds to `domain_from(host, tld_length)` and `subdomains_from(host, tld_length)` methods.
+
+Defaults to `ActionDispatch::Http::URL::DomainExtractor`, which provides the standard domain parsing logic. You can provide a custom extractor to implement specialized domain parsing behavior:
+
+```ruby
+class CustomDomainExtractor
+  def self.domain_from(host, tld_length)
+    # Custom domain extraction logic
+  end
+
+  def self.subdomains_from(host, tld_length)
+    # Custom subdomain extraction logic
+  end
+end
+
+config.action_dispatch.domain_extractor = CustomDomainExtractor
+```
+
 #### `config.action_dispatch.ignore_accept_header`
 
 Is used to determine whether to ignore accept headers from a request. Defaults to `false`.