slugifiable 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f707db7b8e857da8289a7e17754261aa3dd4b06b517673b983936cc449e530
-  data.tar.gz: 36144ba06043096a3ead2aa5e3728a3c6c0f54bf9be15c27d085e944d47a1b76
+  metadata.gz: 230e7c9d0a24d77af781a78aed46daf46d404aa942572c4fab12f592fd24b3f7
+  data.tar.gz: ab8007017ef1f1ae5ecf563efb5a188e9a10150f5d861f9fc352d1b7f9023026
 SHA512:
-  metadata.gz: 848886284f316ccb3086afcb268ddf09bf136c040a055c353fa4492021d578e439367ce137d471334a339fb43ff2997271267b2c0668d25f7654803cd4e73cad
-  data.tar.gz: 984f18e9268a0fff5b64f3e8d28e654c2586fa99c02f2199134bbac798cb311e68e5714b17c22ef6583eae75f51cce22b209ac08791d973dbe7f71a2e8830645
+  metadata.gz: 4649bfbb6dc0864f4397942a1f62621c437a09dd1b3b056194d5c0e82a54fbf9bd42deb48aaf5ea5da4cc16916568bdb2491c3a0fad1b8ddcfa465315cb7d52c
+  data.tar.gz: db9186508f938faf89e8ca4781929e53a1e45aaea006c24a3663bec97a9c80e285b8be6dbef125d6f344de62afb2084f91c5c1177e04bedaf99744226e00c33a

data/.simplecov

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # Track the lib and app directories
+  track_files "{lib,app}/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression
+  minimum_coverage line: 90, branch: 90
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  puts "Branch Coverage: #{SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || 'N/A'}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/Appraisals

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Note: Rails < 7.2 is not compatible with Ruby 3.4
+# (Logger became a bundled gem in Ruby 3.4, and only Rails 7.2+ handles this)
+# See: https://stdgems.org/logger/
+
+# Test against Rails 7.2 (minimum version compatible with Ruby 3.4)
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# Test against Rails 8.0
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+# Test against Rails 8.1 (latest)
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.2"
+end

data/CHANGELOG.md

@@ -1,4 +1,26 @@
+## [0.3.0] - 2026-02-19
+
+- Fixed race condition: retry with new random suffix on `RecordNotUnique` instead of crashing
+- Added PostgreSQL-safe savepoints for retry logic
+- Added support for NOT NULL slug columns (see README for setup)
+- Changed `set_slug` to use `save!` instead of `save` (raises on validation errors)
+- `before_create` and `after_create` callbacks re-run on retry — keep them idempotent
+
+## [0.2.0] - 2026-01-16
+
+- Added a full Minitest test suite
+- Fixed `respond_to?(:slug)` returning false for models using method_missing by implementing `respond_to_missing?`
+- Fixed collision resolution generating identical suffixes by switching from id-based deterministic suffixes to SecureRandom-based random suffixes
+- Fixed length parameter edge cases (zero, negative, very large values) by adding length validation and clamping via `normalize_length` method
+- Fixed timestamp fallback to include random suffix for additional uniqueness guarantee
+- Added length validation constants (`MAX_HEX_STRING_LENGTH`, `MAX_NUMBER_LENGTH`) to prevent invalid length values
+
+## [0.1.1] - 2024-03-21
+
+- Slugs can be now generated based off methods that return a string, not just based off attributes
+- Enhanced collision resolution strategy so that it doesn't get stuck in infinite loops
+- Added comprehensive test suite
+
 ## [0.1.0] - 2024-10-30
 
 - Initial release
-

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project.

data/README.md

@@ -1,8 +1,11 @@
-# 🐌 `slugifiable` - Rails gem to generate SEO-friendly slugs
+# 🐌 `slugifiable` - Generate SEO-optimized URL slugs
 
-[![Gem Version](https://badge.fury.io/rb/slugifiable.svg)](https://badge.fury.io/rb/slugifiable)
+[![Gem Version](https://badge.fury.io/rb/slugifiable.svg)](https://badge.fury.io/rb/slugifiable) [![Build Status](https://github.com/rameerez/slugifiable/workflows/Tests/badge.svg)](https://github.com/rameerez/slugifiable/actions)
 
-Automatically generates unique slugs for your Rails' model records, so you can expose SEO-friendly URLs.
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=slugifiable)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=slugifiable)!
+
+Ruby gem to automatically generate unique slugs for your Rails' model records, so you can expose SEO-friendly URLs.
 
 Example:
 ```
@@ -77,9 +80,53 @@ Product.first.slug
 
 If your model has a `slug` attribute in the database, `slugifiable` will automatically generate a slug for that model upon instance creation, and save it to the DB.
 
-> [!IMPORTANT]
-> Your `slug` attribute **SHOULD NOT** have `null: false` in the migration / database. If it does, `slugifiable` will not be able to save the slug to the database, and will raise an error like `ERROR:  null value in column "slug" of relation "posts" violates not-null constraint (PG::NotNullViolation)`
-> This is because records are created without a slug, and the slug is generated later.
+### Nullable vs NOT NULL Slug Columns
+
+**Nullable columns (default, simpler):**
+```ruby
+# migration
+add_column :products, :slug, :string
+add_index :products, :slug, unique: true
+
+# model
+class Product < ApplicationRecord
+  include Slugifiable::Model
+  generate_slug_based_on :name
+end
+```
+
+**NOT NULL columns (requires `before_validation` setup):**
+```ruby
+# migration
+add_column :products, :slug, :string, null: false
+add_index :products, :slug, unique: true
+
+# model
+class Product < ApplicationRecord
+  include Slugifiable::Model
+  generate_slug_based_on :name
+
+  before_validation :ensure_slug_present, on: :create
+
+  private
+
+  def ensure_slug_present
+    self.slug = compute_slug if slug.blank?
+  end
+end
+```
+
+> [!NOTE]
+> When using NOT NULL slug columns, `slugifiable` handles race conditions automatically. If two processes try to create records with the same slug simultaneously, the second one will retry with a new random suffix.
+
+> [!CAUTION]
+> For NOT NULL slug columns, retries re-run the `around_create` callback chain. If a slug collision happens, your `before_create` callbacks will run again. Keep `before_create` callbacks idempotent (or move side effects to `after_create`/background jobs).
+
+> [!NOTE]
+> Retry handling is DB-constraint-driven (`RecordNotUnique`), not validation-driven. A validation-layer race that raises `RecordInvalid` will bubble up.
+
+> [!NOTE]
+> Slug collision detection matches errors containing `slug`/`_on_slug`. If your index uses a custom name that does not include those patterns, retries will not trigger and the exception will bubble up.
 
 If you're generating slugs based off the model `id`, you can also set a desired length:
 ```ruby
@@ -183,7 +230,7 @@ end
 This will generate slugs like:
 ```ruby
 Event.first.slug
-=> "my-awesome-event-new-york-new-york"  # Automatically parameterized
+=> "my-awesome-event-new-york"  # Automatically parameterized
 ```
 
 There may be collisions if two records share the same name – but slugs should be unique! To resolve this, when this happens, `slugifiable` will append a unique string at the end to make the slug unique:

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,17 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.0"
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "simplecov", require: false
+  gem "sqlite3", ">= 2.1"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,17 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.0.0"
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "simplecov", require: false
+  gem "sqlite3", ">= 2.1"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,17 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.2"
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "simplecov", require: false
+  gem "sqlite3", ">= 2.1"
+end
+
+gemspec path: "../"

data/lib/slugifiable/model.rb

@@ -28,11 +28,17 @@ module Slugifiable
     DEFAULT_SLUG_STRING_LENGTH = 11
     DEFAULT_SLUG_NUMBER_LENGTH = 6
 
-    # Maximum number of attempts to generate a unique slug
-    # before falling back to timestamp-based suffix
+    # SHA256 produces 64 hex characters
+    MAX_HEX_STRING_LENGTH = 64
+    # 10^18 fits safely in a 64-bit integer
+    MAX_NUMBER_LENGTH = 18
+
+    # Maximum number of attempts to generate a unique slug before raising.
+    # Also used by generate_unique_slug for EXISTS? check loop (with timestamp fallback).
     MAX_SLUG_GENERATION_ATTEMPTS = 10
 
     included do
+      around_create :retry_create_on_slug_unique_violation
       after_create :set_slug
       after_find :update_slug_if_nil
       validates :slug, uniqueness: true
@@ -51,13 +57,17 @@ module Slugifiable
     end
 
     def method_missing(missing_method, *args, &block)
-      if missing_method.to_s == "slug" && !self.methods.include?(:slug)
+      if missing_method.to_s == "slug" && !has_slug_method?
         compute_slug
       else
         super
       end
     end
 
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s == "slug" && !has_slug_method? || super
+    end
+
     def compute_slug
       strategy, options = determine_slug_generation_method
 
@@ -71,12 +81,12 @@ module Slugifiable
     end
 
     def compute_slug_as_string(length = DEFAULT_SLUG_STRING_LENGTH)
-      length ||= DEFAULT_SLUG_STRING_LENGTH
+      length = normalize_length(length, DEFAULT_SLUG_STRING_LENGTH, MAX_HEX_STRING_LENGTH)
       (Digest::SHA2.hexdigest self.id.to_s).first(length)
     end
 
     def compute_slug_as_number(length = DEFAULT_SLUG_NUMBER_LENGTH)
-      length ||= DEFAULT_SLUG_NUMBER_LENGTH
+      length = normalize_length(length, DEFAULT_SLUG_NUMBER_LENGTH, MAX_NUMBER_LENGTH)
       generate_random_number_based_on_id_hex(length)
     end
 
@@ -129,8 +139,61 @@ module Slugifiable
 
     private
 
+    # S1: around_create retry for NOT NULL slug columns (pre-INSERT collision)
+    # S2: Uses savepoint (requires_new: true) for PostgreSQL compatibility
+    # S4: Skips overhead when slug column is nullable (no INSERT-time collision possible)
+    def retry_create_on_slug_unique_violation
+      return yield unless slug_persisted? && slug_column_not_null?
+
+      with_slug_retry(for_insert: true) do |attempts|
+        # `around_create` retries can re-enter create callbacks. Set a fresh slug
+        # before retrying so pre-insert slug strategies don't reuse a collided value.
+        self.slug = compute_slug if attempts.positive?
+        yield
+      end
+    end
+
+    # S3: Shared retry helper with savepoints for both paths
+    # PostgreSQL requires savepoints: without them, retry fails with
+    # "current transaction is aborted, commands ignored until end"
+    def with_slug_retry(for_insert: false)
+      attempts = 0
+      begin
+        self.class.transaction(requires_new: true) { yield(attempts) }
+      rescue ActiveRecord::RecordNotUnique => e
+        raise unless slug_unique_violation?(e)
+        raise if for_insert && persisted? # Already inserted; don't retry whole create
+
+        attempts += 1
+        raise if attempts >= MAX_SLUG_GENERATION_ATTEMPTS # S6: Raise on exhaustion
+
+        retry
+      end
+    end
+
+    # S4: Optimization guard - skip savepoint wrapper when slug is nullable
+    def slug_column_not_null?
+      return false unless self.class.respond_to?(:columns_hash)
+      column = self.class.columns_hash["slug"]
+      column && !column.null
+    end
+
+    # S5: Detect slug unique violations across PostgreSQL/MySQL/SQLite
+    # Pattern matches: "slug" as word boundary OR "_on_slug" (index naming convention)
+    # Safe false-negative for custom index names (error bubbles up instead of silent retry)
+    def slug_unique_violation?(error)
+      message = error.message.to_s.downcase
+      message.match?(/\bslug\b|_on_slug\b/)
+    end
+
+    def normalize_length(length, default, max)
+      length = length.to_i
+      return default if length <= 0
+      [length, max].min
+    end
+
     def generate_random_number_based_on_id_hex(length = DEFAULT_SLUG_NUMBER_LENGTH)
-      length ||= DEFAULT_SLUG_NUMBER_LENGTH
+      length = normalize_length(length, DEFAULT_SLUG_NUMBER_LENGTH, MAX_NUMBER_LENGTH)
       ((Digest::SHA2.hexdigest(id.to_s)).hex % (10 ** length))
     end
 
@@ -147,14 +210,16 @@ module Slugifiable
 
       while self.class.exists?(slug: slug_candidate) && attempts < MAX_SLUG_GENERATION_ATTEMPTS
         attempts += 1
-        random_suffix = compute_slug_as_number
+        # Use SecureRandom for truly random suffixes during collision resolution
+        # This ensures each attempt tries a different suffix
+        random_suffix = SecureRandom.random_number(10 ** DEFAULT_SLUG_NUMBER_LENGTH)
         slug_candidate = "#{base_slug}-#{random_suffix}"
       end
 
       # If we couldn't find a unique slug after MAX_SLUG_GENERATION_ATTEMPTS,
-      # append timestamp to ensure uniqueness
-      if attempts == MAX_SLUG_GENERATION_ATTEMPTS
-        slug_candidate = "#{base_slug}-#{Time.current.to_i}"
+      # append timestamp + random to ensure uniqueness
+      if attempts >= MAX_SLUG_GENERATION_ATTEMPTS
+        slug_candidate = "#{base_slug}-#{Time.current.to_i}-#{SecureRandom.random_number(1000)}"
       end
 
       slug_candidate
@@ -185,7 +250,7 @@ module Slugifiable
             return [DEFAULT_SLUG_GENERATION_STRATEGY, options]
           end
         elsif strategy.key?(:attribute)
-          return [:compute_slug_based_on_attribute, strategy[:attribute], options]
+          return [:compute_slug_based_on_attribute, strategy[:attribute]]
         end
       end
 
@@ -193,18 +258,33 @@ module Slugifiable
     end
 
     def slug_persisted?
-      self.methods.include?(:slug) && self.attributes.include?("slug")
+      has_slug_method? && self.attributes.include?("slug")
+    end
+
+    def has_slug_method?
+      # Check if slug method exists from ActiveRecord (not from method_missing)
+      self.class.method_defined?(:slug) || self.class.private_method_defined?(:slug)
     end
 
+    # S1: after_create retry for nullable slug columns (post-INSERT collision)
+    # S2: Uses savepoint via with_slug_retry for PostgreSQL compatibility
     def set_slug
       return unless slug_persisted?
+      return unless slug.blank?
 
-      self.slug = compute_slug if id_changed? || slug.blank?
-      self.save
+      with_slug_retry do |_attempts|
+        self.slug = compute_slug
+        save!
+      end
     end
 
+    # S7: Non-bang save for after_find repair path to avoid read-time exceptions
+    # This path handles legacy records that may have nil slugs
     def update_slug_if_nil
-      set_slug if slug_persisted? && self.slug.nil?
+      return unless slug_persisted? && slug.nil?
+
+      self.slug = compute_slug
+      save # Non-bang: read operations should not raise
     end
 
   end

data/lib/slugifiable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slugifiable
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/slugifiable.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 require_relative "slugifiable/version"
 require_relative "slugifiable/model"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: slugifiable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-02-23 00:00:00.000000000 Z
+date: 2026-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -32,10 +32,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".simplecov"
+- AGENTS.md
+- Appraisals
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/slugifiable.rb
 - lib/slugifiable/model.rb
 - lib/slugifiable/version.rb