rack-url-canonicalizer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9bcf0b3bfa0b272e1ec7d8eb41e3a98b19460341241c24559150d0f2cdb009
-  data.tar.gz: 90c19805083edf665a1c84f0b5966fb937f4249df73be65592d8e4359762e1a3
+  metadata.gz: 0cc0592b66830e51b4f791b9b7c9503fa98ca0c20f25fb4fe92ae9379af404ed
+  data.tar.gz: 572708d83ec547c190e93d78dd900db96af8de7cca0c3760122a132fef8282c6
 SHA512:
-  metadata.gz: f407b4ca1f132cc6f87124706e84532d329a94cb9eb0176a20488518e630fb591439f9d1f191c844ddec558065bd248403897159a24f4ea1d1929e79425d1a25
-  data.tar.gz: d982f92f9dfc76c23b0888ac68b1268fe6a749e8acf57ff0ec9a2888ce686e34cc89c70111f3c511b4f26430cb7dc48fba5f772aa9ee914b8054cbf85e3817c0
+  metadata.gz: 1e1b05c26326297a9b6cd425433face278ebeae8d9ca9deddf34f637d092b3f8875d64591cf5b59a0265187933cfcbe88822ef5c0d52a7c30f08b6010c19f0d8
+  data.tar.gz: ffc8f3651b5a9bd64a50365dd86e9a5f9129903bfd4e998d44da3a3a8a024f30a60673bfd4e6aea365954cb12299985de08c95bf12df3e0daa04ad9c59c6989e

data/README.md

@@ -3,10 +3,11 @@
 `rack-url-canonicalizer` is a lightweight, zero-dependency Rack middleware for Ruby applications (Rails, Sinatra, Hanami, Roda, or plain Rack).
 
 It automatically canonicalizes incoming request URLs to prevent search engine **Duplicate Content** penalties by enforcing:
-1. Removal of the `www.` sub-domain prefix.
+1. Stripping `www.` or enforcing `www.` sub-domain prefix.
 2. Collapsing duplicate slashes (`//path//to` ➔ `/path/to`).
 3. Stripping trailing slashes from paths (`/path/` ➔ `/path`).
-4. Validating `locale` GET query parameters against an allowed list and stripping invalid locales.
+4. Canonicalizing URL paths to lowercase (`/About-Us` ➔ `/about-us`), globally or selectively.
+5. Validating `locale` GET query parameters against an allowed list and stripping invalid locales.
 
 ---
 
@@ -16,7 +17,7 @@ Search engines (Google, Yandex, Bing) treat every unique URL string as a distinc
 
 This gem is essential when:
 - **Protecting SEO & Domain Authority**: You need to prevent index cannibalization caused by variations like `example.com/item` vs. `www.example.com/item`, `example.com/item/`, or `example.com//item`.
-- **Enforcing Single Canonical URLs**: You want incoming traffic from user typos or legacy backlinks to be redirected with an HTTP 301 (Moved Permanently) status to a single canonical address before reaching your application logic.
+- **Enforcing Single Canonical URLs**: You want incoming traffic from user typos, mobile keyboard auto-capitalization, or legacy backlinks to be redirected with an HTTP 301 (Moved Permanently) status to a single canonical address before reaching your application logic.
 - **Handling Multi-Locale Query Parameters**: Your app supports localization (e.g. `?locale=en`) and you want to sanitize or discard invalid/malformed locale parameters (e.g. `?locale=xyz`) that would otherwise generate infinite duplicate URL variants.
 - **High-Performance Early Redirects**: You want URL normalization to happen at the lightweight Rack middleware layer—avoiding unnecessary Rails controller instantiations, routing checks, or database queries.
 - **Simplified Deployment with Kamal & Modern Stacks**: Ideal for containerized setups deployed with **Kamal**, **Thruster**, or Docker, where configuring and maintaining separate Nginx/Caddy redirect rules or complex DNS edge layers adds unnecessary overhead. This gem handles canonicalization directly inside your application stack for fast, zero-config deployments.
@@ -44,10 +45,15 @@ bundle install
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `strip_www` | `Boolean` | `true` | Removes `www.` prefix from host. |
+| `strip_www` | `Boolean` | `true` | Removes `www.` prefix from host. Automatically set to `false` if `enforce_www` is enabled. |
+| `enforce_www` | `Boolean` | `false` | Prepends `www.` to requests lacking it (aliased as `prefer_www`). Automatically skips localhost and IP addresses. |
 | `collapse_slashes` | `Boolean` | `true` | Replaces multiple slashes `//` with `/`. |
 | `strip_trailing_slash` | `Boolean` | `true` | Removes trailing slash from path (except root `/`). |
+| `downcase_path` | `Boolean` | `false` | Converts path to lowercase (e.g. `/About-Us` ➔ `/about-us`). Query string casing is preserved. |
+| `downcase_paths` | `Array<String \| Regexp \| Proc> \| Boolean` | `nil` | Selective allowlist: only paths matching these prefixes or patterns are downcased. |
+| `downcase_exclude_paths` | `Array<String \| Regexp \| Proc>` | `[]` | Array of path prefixes, patterns, or procs to bypass from downcasing (preserves casing for tokens/IDs). |
 | `exclude_paths` | `Array<String>` | `[]` | Array of path prefixes to bypass (e.g. `%w[/api /assets]`). |
+| `exclude_hosts` | `Array<String \| Regexp \| Proc>` | `[]` | Array of hosts or patterns to bypass from host redirection. |
 | `locale_param` | `String` | `"locale"` | GET parameter key for locale. |
 | `allowed_locales` | `Array<String> \| Proc` | `nil` | List of allowed locales or callable returning them. |
 | `redirect_status` | `Integer` | `301` | HTTP status code for redirects. |
@@ -62,12 +68,31 @@ bundle install
 In `config/application.rb`:
 
 ```ruby
+# Strip www, normalize paths, and enforce lowercase:
 config.middleware.use Rack::UrlCanonicalizer,
   strip_www: true,
   collapse_slashes: true,
   strip_trailing_slash: true,
+  downcase_path: true,
   exclude_paths: %w[/api /assets /up],
   allowed_locales: -> { I18n.available_locales }
+
+# Or selective downcasing for specific marketing / content routes:
+config.middleware.use Rack::UrlCanonicalizer,
+  downcase_paths: [
+    "/about",
+    "/contribution",
+    "/pricing",
+    %r{\A/(docs|faq)/}i
+  ],
+  downcase_exclude_paths: [
+    %r{\A/invites/[A-Za-z0-9_-]+}
+  ]
+
+# Or enforce www (example.com -> www.example.com):
+config.middleware.use Rack::UrlCanonicalizer,
+  enforce_www: true,
+  exclude_hosts: %w[api.example.com]
 ```
 
 ### Sinatra / Plain Rack
@@ -78,7 +103,8 @@ In `config.ru`:
 require "rack/url_canonicalizer"
 
 use Rack::UrlCanonicalizer,
-  strip_www: true,
+  downcase_path: true,
+  enforce_www: true,
   exclude_paths: ["/api"]
 
 run MyApp
@@ -90,8 +116,9 @@ Alternatively, set global defaults:
 
 ```ruby
 Rack::UrlCanonicalizer.configure do |config|
-  config.strip_www = true
+  config.enforce_www = true
   config.collapse_slashes = true
+  config.downcase_path = true
   config.allowed_locales = %w[en ru es]
 end
 

data/lib/rack/url_canonicalizer/configuration.rb

@@ -3,26 +3,48 @@
 module Rack
   class UrlCanonicalizer
     class Configuration
-      attr_accessor :strip_www,
-                    :collapse_slashes,
+      attr_accessor :collapse_slashes,
                     :strip_trailing_slash,
+                    :downcase_path,
+                    :downcase_paths,
+                    :downcase_exclude_paths,
                     :exclude_paths,
+                    :exclude_hosts,
                     :locale_param,
                     :allowed_locales,
                     :redirect_status,
                     :cache_control
+      attr_reader :strip_www, :enforce_www
 
       def initialize
         @strip_www = true
+        @enforce_www = false
         @collapse_slashes = true
         @strip_trailing_slash = true
+        @downcase_path = false
+        @downcase_paths = nil
+        @downcase_exclude_paths = []
         @exclude_paths = []
-        @locale_param = "locale"
+        @exclude_hosts = []
+        @locale_param = 'locale'
         @allowed_locales = nil
         @redirect_status = 301
-        @cache_control = "public, max-age=86400"
+        @cache_control = 'public, max-age=86400'
       end
 
+      def strip_www=(val)
+        @strip_www = val
+        @enforce_www = false if val
+      end
+
+      def enforce_www=(val)
+        @enforce_www = val
+        @strip_www = false if val
+      end
+
+      alias prefer_www enforce_www
+      alias prefer_www= enforce_www=
+
       def allowed_locales_list
         return nil if allowed_locales.nil?
 

data/lib/rack/url_canonicalizer/version.rb

@@ -2,6 +2,6 @@
 
 module Rack
   class UrlCanonicalizer
-    VERSION = "0.1.0"
+    VERSION = '0.3.0'
   end
 end

data/lib/rack/url_canonicalizer.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-require "rack"
-require_relative "url_canonicalizer/version"
-require_relative "url_canonicalizer/configuration"
-require_relative "url_canonicalizer/railtie"
+require 'rack'
+require_relative 'url_canonicalizer/version'
+require_relative 'url_canonicalizer/configuration'
+require_relative 'url_canonicalizer/railtie'
 
 module Rack
   class UrlCanonicalizer
+    IPV4_REGEX = /\A\d{1,3}(?:\.\d{1,3}){3}\z/
+    REDIRECT_BODIES = {
+      301 => 'Moved Permanently',
+      302 => 'Found',
+      307 => 'Temporary Redirect',
+      308 => 'Permanent Redirect'
+    }.freeze
+
     class << self
       def configuration
         @configuration ||= Configuration.new
@@ -25,98 +33,142 @@ module Rack
       @app = app
       @config = self.class.configuration.dup
 
+      validate_options!(options)
+
       options.each do |key, value|
-        writer = "#{key}="
-        @config.send(writer, value) if @config.respond_to?(writer)
+        @config.public_send("#{key}=", value) if @config.respond_to?("#{key}=")
       end
     end
 
     def call(env)
       req = Rack::Request.new(env)
+      return @app.call(env) unless (req.get? || req.head?) && !xhr_request?(req, env)
 
-      return @app.call(env) unless req.get? || req.head?
-      return @app.call(env) if xhr_request?(req, env)
+      path = env['PATH_INFO'] || ''
+      return @app.call(env) if excluded_path?(path)
 
-      path_info = env["PATH_INFO"] || ""
+      target_host, host_redirect = normalize_host(req.host || '')
+      norm_path = normalize_path(path)
+      query_params = req.GET.dup
+      locale_redirect = locale_redirect?(query_params)
+
+      return @app.call(env) unless host_redirect || path != norm_path || locale_redirect
+
+      [
+        @config.redirect_status,
+        {
+          'location' => redirect_url(req, target_host, norm_path, query_params),
+          'content-type' => 'text/html',
+          'cache-control' => @config.cache_control
+        },
+        [REDIRECT_BODIES.fetch(@config.redirect_status, 'Redirected')]
+      ]
+    end
 
-      if excluded_path?(path_info)
-        return @app.call(env)
-      end
+    private
 
-      host = req.host || ""
-      host_redirect = @config.strip_www && host.start_with?("www.")
-      target_host = host_redirect ? host.sub(/\Awww\./, "") : host
+    def validate_options!(options)
+      strip = options[:strip_www] || options['strip_www']
+      enforce = options[:enforce_www] || options['enforce_www'] || options[:prefer_www] || options['prefer_www']
 
-      raw_path = path_info
-      normalized_path = raw_path.dup
+      raise ArgumentError, 'Conflicting options: cannot enable both :strip_www and :enforce_www' if strip && enforce
+    end
 
-      if @config.collapse_slashes
-        normalized_path.gsub!(%r{/{2,}}, "/")
-      end
+    def xhr_request?(req, env)
+      return true if req.respond_to?(:xhr?) && req.xhr?
 
-      if @config.strip_trailing_slash && normalized_path.length > 1 && normalized_path.end_with?("/")
-        normalized_path.chomp!("/")
-      end
+      env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
+    end
 
-      query_params = req.GET.dup
-      locale_redirect = false
-      locale_key = @config.locale_param
-
-      if locale_key && query_params.key?(locale_key)
-        allowed = @config.allowed_locales_list
-        if allowed && !allowed.include?(query_params[locale_key].to_s)
-          query_params.delete(locale_key)
-          locale_redirect = true
+    def excluded_path?(path_info)
+      return false if @config.exclude_paths.nil? || @config.exclude_paths.empty?
+
+      @config.exclude_paths.any? { |prefix| path_info.start_with?(prefix) }
+    end
+
+    def excluded_host?(host)
+      return false if @config.exclude_hosts.nil? || @config.exclude_hosts.empty?
+
+      @config.exclude_hosts.any? do |pattern|
+        case pattern
+        when Regexp then pattern.match?(host)
+        when Proc then pattern.call(host)
+        else pattern.to_s.casecmp?(host)
         end
       end
+    end
 
-      if host_redirect || raw_path != normalized_path || locale_redirect
-        scheme = req.scheme
-        port = req.port
-        port_part = [ 80, 443 ].include?(port) ? "" : ":#{port}"
-
-        new_query = Rack::Utils.build_nested_query(query_params)
-        new_url = +"#{scheme}://#{target_host}#{port_part}#{normalized_path}"
-        new_url << "?#{new_query}" unless new_query.empty?
-
-        return [
-          @config.redirect_status,
-          {
-            "location" => new_url,
-            "content-type" => "text/html",
-            "cache-control" => @config.cache_control
-          },
-          [ redirect_body(@config.redirect_status) ]
-        ]
-      end
+    def normalize_host(host)
+      return [host, false] if excluded_host?(host)
+      return [host.sub(/\Awww\./i, ''), true] if @config.strip_www && host.downcase.start_with?('www.')
+      return ["www.#{host}", true] if @config.enforce_www && should_enforce_www?(host)
 
-      @app.call(env)
+      [host, false]
     end
 
-    private
+    def should_enforce_www?(host)
+      return false if host.empty? ||
+                      host.downcase.start_with?('www.') ||
+                      host == 'localhost' ||
+                      host.end_with?('.localhost', '.local', '.test')
 
-    def xhr_request?(req, env)
-      return true if req.respond_to?(:xhr?) && req.xhr?
+      !host.match?(IPV4_REGEX) && !host.include?(':')
+    end
 
-      env["HTTP_X_REQUESTED_WITH"] == "XMLHttpRequest"
+    def normalize_path(path)
+      path = path.gsub(%r{/{2,}}, '/') if @config.collapse_slashes
+      path = path.chomp('/') if @config.strip_trailing_slash && path.length > 1 && path.end_with?('/')
+      path = path.downcase if should_downcase_path?(path)
+      path
     end
 
-    def excluded_path?(path_info)
-      return false if @config.exclude_paths.nil? || @config.exclude_paths.empty?
+    def should_downcase_path?(path)
+      return false if downcase_excluded?(path)
 
-      @config.exclude_paths.any? do |prefix|
-        path_info.start_with?(prefix)
+      if @config.downcase_paths == true
+        true
+      elsif @config.downcase_paths
+        match_path_patterns?(@config.downcase_paths, path)
+      else
+        @config.downcase_path
       end
     end
 
-    def redirect_body(status)
-      case status
-      when 301 then "Moved Permanently"
-      when 302 then "Found"
-      when 307 then "Temporary Redirect"
-      when 308 then "Permanent Redirect"
-      else "Redirected"
+    def downcase_excluded?(path)
+      return false if @config.downcase_exclude_paths.nil? || @config.downcase_exclude_paths.empty?
+
+      match_path_patterns?(@config.downcase_exclude_paths, path)
+    end
+
+    def match_path_patterns?(patterns, path)
+      Array(patterns).any? do |pattern|
+        case pattern
+        when Regexp then pattern.match?(path) || pattern.match?(path.downcase)
+        when Proc then pattern.call(path)
+        else
+          prefix = pattern.to_s.downcase
+          prefix = "/#{prefix}" unless prefix.start_with?('/')
+          path.downcase.start_with?(prefix)
+        end
       end
     end
+
+    def locale_redirect?(query_params)
+      key = @config.locale_param
+      return false unless key && query_params.key?(key)
+
+      allowed = @config.allowed_locales_list
+      return false if allowed&.include?(query_params[key].to_s)
+
+      query_params.delete(key)
+      true
+    end
+
+    def redirect_url(req, host, path, query_params)
+      port = [80, 443].include?(req.port) ? '' : ":#{req.port}"
+      query = Rack::Utils.build_nested_query(query_params)
+      url = "#{req.scheme}://#{host}#{port}#{path}"
+      query.empty? ? url : "#{url}?#{query}"
+    end
   end
 end

data/lib/rack-url-canonicalizer.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require "rack/url_canonicalizer"
+require 'rack/url_canonicalizer'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-url-canonicalizer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Abramov
@@ -37,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,19 +94,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: rack-test
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
 description: Removes www, collapses slashes, strips trailing slashes, and validates
   locale params to prevent duplicate content SEO penalties.
 email:
@@ -97,7 +125,8 @@ files:
 homepage: https://github.com/o-200/rack-url-canonicalizer
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -112,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Rack middleware for URL normalization and SEO canonicalization
 test_files: []