rack-url-canonicalizer 0.1.0

checksums.yaml

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,117 @@
+# Rack::UrlCanonicalizer
+
+`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.
+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.
+
+---
+
+## When Is This Gem Necessary?
+
+Search engines (Google, Yandex, Bing) treat every unique URL string as a distinct page. Without strict URL normalization, subtle variations in request paths create **Duplicate Content**, which splits link authority (PageRank), degrades search rankings, and wastes crawl budget.
+
+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.
+- **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.
+
+---
+
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "rack-url-canonicalizer"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `strip_www` | `Boolean` | `true` | Removes `www.` prefix from host. |
+| `collapse_slashes` | `Boolean` | `true` | Replaces multiple slashes `//` with `/`. |
+| `strip_trailing_slash` | `Boolean` | `true` | Removes trailing slash from path (except root `/`). |
+| `exclude_paths` | `Array<String>` | `[]` | Array of path prefixes to bypass (e.g. `%w[/api /assets]`). |
+| `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. |
+| `cache_control` | `String` | `"public, max-age=86400"` | `Cache-Control` header for redirect responses. |
+
+---
+
+## Usage
+
+### Ruby on Rails
+
+In `config/application.rb`:
+
+```ruby
+config.middleware.use Rack::UrlCanonicalizer,
+  strip_www: true,
+  collapse_slashes: true,
+  strip_trailing_slash: true,
+  exclude_paths: %w[/api /assets /up],
+  allowed_locales: -> { I18n.available_locales }
+```
+
+### Sinatra / Plain Rack
+
+In `config.ru`:
+
+```ruby
+require "rack/url_canonicalizer"
+
+use Rack::UrlCanonicalizer,
+  strip_www: true,
+  exclude_paths: ["/api"]
+
+run MyApp
+```
+
+### Global Configuration
+
+Alternatively, set global defaults:
+
+```ruby
+Rack::UrlCanonicalizer.configure do |config|
+  config.strip_www = true
+  config.collapse_slashes = true
+  config.allowed_locales = %w[en ru es]
+end
+
+# In Rack stack:
+use Rack::UrlCanonicalizer
+```
+
+---
+
+## Development & Testing
+
+Run tests with RSpec:
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+# rack-url-canonicalizer

data/lib/rack/url_canonicalizer/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rack
+  class UrlCanonicalizer
+    class Configuration
+      attr_accessor :strip_www,
+                    :collapse_slashes,
+                    :strip_trailing_slash,
+                    :exclude_paths,
+                    :locale_param,
+                    :allowed_locales,
+                    :redirect_status,
+                    :cache_control
+
+      def initialize
+        @strip_www = true
+        @collapse_slashes = true
+        @strip_trailing_slash = true
+        @exclude_paths = []
+        @locale_param = "locale"
+        @allowed_locales = nil
+        @redirect_status = 301
+        @cache_control = "public, max-age=86400"
+      end
+
+      def allowed_locales_list
+        return nil if allowed_locales.nil?
+
+        locs = allowed_locales.respond_to?(:call) ? allowed_locales.call : allowed_locales
+        Array(locs).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/rack/url_canonicalizer/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+if defined?(Rails::Railtie)
+  module Rack
+    class UrlCanonicalizer
+      class Railtie < ::Rails::Railtie
+      end
+    end
+  end
+end

data/lib/rack/url_canonicalizer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rack
+  class UrlCanonicalizer
+    VERSION = "0.1.0"
+  end
+end

data/lib/rack/url_canonicalizer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "rack"
+require_relative "url_canonicalizer/version"
+require_relative "url_canonicalizer/configuration"
+require_relative "url_canonicalizer/railtie"
+
+module Rack
+  class UrlCanonicalizer
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+
+    def initialize(app, options = {})
+      @app = app
+      @config = self.class.configuration.dup
+
+      options.each do |key, value|
+        writer = "#{key}="
+        @config.send(writer, value) if @config.respond_to?(writer)
+      end
+    end
+
+    def call(env)
+      req = Rack::Request.new(env)
+
+      return @app.call(env) unless req.get? || req.head?
+      return @app.call(env) if xhr_request?(req, env)
+
+      path_info = env["PATH_INFO"] || ""
+
+      if excluded_path?(path_info)
+        return @app.call(env)
+      end
+
+      host = req.host || ""
+      host_redirect = @config.strip_www && host.start_with?("www.")
+      target_host = host_redirect ? host.sub(/\Awww\./, "") : host
+
+      raw_path = path_info
+      normalized_path = raw_path.dup
+
+      if @config.collapse_slashes
+        normalized_path.gsub!(%r{/{2,}}, "/")
+      end
+
+      if @config.strip_trailing_slash && normalized_path.length > 1 && normalized_path.end_with?("/")
+        normalized_path.chomp!("/")
+      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
+        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
+
+      @app.call(env)
+    end
+
+    private
+
+    def xhr_request?(req, env)
+      return true if req.respond_to?(:xhr?) && req.xhr?
+
+      env["HTTP_X_REQUESTED_WITH"] == "XMLHttpRequest"
+    end
+
+    def excluded_path?(path_info)
+      return false if @config.exclude_paths.nil? || @config.exclude_paths.empty?
+
+      @config.exclude_paths.any? do |prefix|
+        path_info.start_with?(prefix)
+      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"
+      end
+    end
+  end
+end

data/lib/rack-url-canonicalizer.rb

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

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: rack-url-canonicalizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Abramov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.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'
+description: Removes www, collapses slashes, strips trailing slashes, and validates
+  locale params to prevent duplicate content SEO penalties.
+email:
+- omgout.200@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rack-url-canonicalizer.rb
+- lib/rack/url_canonicalizer.rb
+- lib/rack/url_canonicalizer/configuration.rb
+- lib/rack/url_canonicalizer/railtie.rb
+- lib/rack/url_canonicalizer/version.rb
+homepage: https://github.com/o-200/rack-url-canonicalizer
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Rack middleware for URL normalization and SEO canonicalization
+test_files: []