domain_extractor 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e27f85f19d8a816ec9323daf5007fa86316e337c6233924b36b0178b2b99d1e1
-  data.tar.gz: e8dd889cad29d7ecc72b93e5d62e8e4e7543c68b8b5f3886d642ec51bc6bc4dc
+  metadata.gz: b770e3c09383122b5cae3baa952127a0f616ee721c2a241f1facd9ddc42a4762
+  data.tar.gz: de6e3561bba3d457da8a4cd9aee88c5f6c76aedaf233c3bda4930cb8402b2871
 SHA512:
-  metadata.gz: 35999ebc7fa0952f9d14d54bd07c214c7fef3ac92aeaa6e7f95882448abd1437a0e683afdab59db32f6f85905f0de722e82aed7adad55caa5abde2f87921ecc3
-  data.tar.gz: b4b989986447dd919bc797e4d103f45e9b64cd2f1116975436bdfb0a9d3972d8a5b50061c3332075b8d4d921425b0161dc36d8e07b3c1179e5c15d2bbc02bde0
+  metadata.gz: 342694e42f321dbea6b197a99909afba2fc4de4d13d01e6e92e66f54fa7d286c1abdfbc1713c56709783d1d05a840523c8f0b202c89528bdeca754eade68cf60
+  data.tar.gz: e23a61526b995375057f34b6a87053c9a26e1f6b6699a521332829921ecb28d1fa6fcf13802fdb9f79637a45200bc1ff98fa47fb8179671fbaed27500e9c16e9

data/CHANGELOG.md

@@ -5,7 +5,126 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.6] - 2025-11-09
+
+### Fixed - Rails Validator Registration
+
+**CRITICAL FIX**: Moved `DomainValidator` class to the **top-level namespace** (from `DomainExtractor::DomainValidator`) to ensure Rails can properly autoload and find the validator.
+
+#### The Problem
+
+Version 0.2.5 defined the validator as `DomainExtractor::DomainValidator`, which caused Rails to fail with:
+
+```
+ArgumentError: Unknown validator: 'DomainValidator'
+NameError: uninitialized constant Website::DomainValidator
+```
+
+This occurred because when using `validates :url, domain: { ... }`, Rails searches for `DomainValidator` in:
+
+1. The model's namespace (e.g., `Website::DomainValidator`)
+2. The top-level namespace (`::DomainValidator`)
+3. ActiveModel::Validations namespace
+
+It does **not** search module namespaces like `DomainExtractor::`.
+
+#### The Solution
+
+- Moved `DomainValidator` to top-level namespace where Rails can find it
+- Added `DomainExtractor::DomainValidator` as an alias for backward compatibility
+- All functionality remains identical; only the class location changed
+
+#### Verification
+
+- All 151 tests pass including 35 validator-specific tests
+- RuboCop clean with zero offenses
+- Verified in production Rails 8 application
+- Confirmed working with `validates :url, domain: { validation: :root_or_custom_subdomain }`
+
+## [0.2.5] - 2025-11-09 [YANKED]
+
+**This version was yanked due to validator registration issue. Use 0.2.6 instead.**
+
+### Added Rails Integration - Custom ActiveModel Validator (BROKEN)
+
+Added a comprehensive custom ActiveModel validator for declarative URL and domain validation in Rails applications. However, the validator was incorrectly namespaced and did not work in Rails applications.
+
+#### Features (Broken in 0.2.5)
+
+**Validation Modes:**
+
+- `:standard` - Validates any parseable URL (default mode)
+- `:root_domain` - Only allows root domains without subdomains (e.g., `example.com` ✅, `shop.example.com` ❌)
+- `:root_or_custom_subdomain` - Allows root or custom subdomains but excludes `www` subdomain (e.g., `example.com` ✅, `shop.example.com` ✅, `www.example.com` ❌)
+
+**Protocol Options:**
+
+- `use_protocol` (default: `true`) - Controls whether protocol (http/https) is required in the URL
+- `use_https` (default: `true`) - Controls whether HTTPS is required (only relevant when `use_protocol` is true)
+
+**Usage Examples:**
+
+```ruby
+# Standard validation - any valid URL
+validates :url, domain: { validation: :standard }
+
+# Root domain only, no subdomains
+validates :primary_domain, domain: { validation: :root_domain }
+
+# Custom subdomains allowed, but not www
+validates :custom_domain, domain: { validation: :root_or_custom_subdomain }
+
+# Flexible protocol requirements
+validates :domain, domain: {
+  validation: :root_domain,
+  use_protocol: false,
+  use_https: false
+}
+```
+
+#### Implementation Details
+
+- **Zero Configuration**: Automatically loads when ActiveModel is available
+- **Graceful Degradation**: Validator only loads in Rails environments; works independently in non-Rails contexts
+- **Clean Error Messages**: Provides clear, actionable validation error messages
+- **Performance**: Leverages existing DomainExtractor parsing engine with minimal overhead
+- **Thread-Safe**: Stateless validation logic safe for concurrent use
+
+#### Compatibility
+
+- **Rails 6.0+**: Full compatibility with ActiveModel::EachValidator API
+- **Rails 7.0+**: Compatible with modern errors API
+- **Rails 8.0+**: No breaking changes, fully supported
+- **Non-Rails**: Works with any application using ActiveModel (Sinatra, Hanami, etc.)
+
+#### Code Quality
+
+- **100% Test Coverage**: 35 comprehensive test cases covering all validation modes and options
+- **RuboCop Clean**: Zero offenses, follows Ruby style guide
+- **Well-Documented**: Extensive README section with real-world examples
+- **Type-Safe**: Proper argument validation with clear error messages
+
+#### Documentation
+
+- Added comprehensive **Rails Integration** section to README.md
+- Includes real-world examples:
+  - Multi-tenant applications with custom domains
+  - E-commerce store configuration
+  - API service registration
+  - Domain allowlists with flexible protocols
+- Documents all validation modes, options, and error messages
+- Shows integration with other Rails validators
+
+#### Use Cases
+
+Perfect for Rails applications requiring:
+
+- Multi-tenant custom domain validation
+- Secure URL validation (HTTPS enforcement)
+- Subdomain-based architecture validation
+- API endpoint domain validation
+- Domain allowlist/blocklist management
+- Custom subdomain requirements
 
 ## [0.1.8] - 2025-10-31
 

data/README.md

@@ -355,6 +355,275 @@ DomainExtractor.parse_query_params(query_string)
 # Returns: Hash of query parameters
 ```
 
+## Rails Integration
+
+DomainExtractor provides a custom ActiveModel validator for Rails applications, enabling declarative URL/domain validation with multiple modes and options.
+
+### Installation
+
+The Rails validator is automatically available when using DomainExtractor in a Rails application (or any application with ActiveModel). No additional setup is required.
+
+### Basic Usage
+
+```ruby
+class Website < ApplicationRecord
+  # Standard validation - accepts any valid URL
+  validates :url, domain: { validation: :standard }
+end
+```
+
+### Validation Modes
+
+#### `:standard` - Accept Any Valid URL
+
+Validates that the URL is parseable and valid. This is the default mode.
+
+```ruby
+class Website < ApplicationRecord
+  validates :url, domain: { validation: :standard }
+end
+
+# Valid URLs
+website = Website.new(url: 'https://mysite.com')        # ✅ Valid
+website = Website.new(url: 'https://shop.mysite.com')   # ✅ Valid
+website = Website.new(url: 'https://www.mysite.com')    # ✅ Valid
+website = Website.new(url: 'https://api.staging.mysite.com') # ✅ Valid
+
+# Invalid URLs
+website = Website.new(url: 'not-a-url')                 # ❌ Invalid
+```
+
+#### `:root_domain` - Root Domain Only
+
+Only allows root domains without any subdomains.
+
+```ruby
+class PrimaryDomain < ApplicationRecord
+  validates :domain, domain: { validation: :root_domain }
+end
+
+# Valid URLs
+domain = PrimaryDomain.new(domain: 'https://mysite.com')      # ✅ Valid
+
+# Invalid URLs
+domain = PrimaryDomain.new(domain: 'https://shop.mysite.com') # ❌ Invalid (has subdomain)
+domain = PrimaryDomain.new(domain: 'https://www.mysite.com')  # ❌ Invalid (has www subdomain)
+```
+
+#### `:root_or_custom_subdomain` - Root or Custom Subdomain (No WWW)
+
+Allows root domains or custom subdomains, but specifically excludes the 'www' subdomain.
+
+```ruby
+class CustomDomain < ApplicationRecord
+  validates :url, domain: { validation: :root_or_custom_subdomain }
+end
+
+# Valid URLs
+domain = CustomDomain.new(url: 'https://mysite.com')       # ✅ Valid (root domain)
+domain = CustomDomain.new(url: 'https://shop.mysite.com')  # ✅ Valid (custom subdomain)
+domain = CustomDomain.new(url: 'https://api.mysite.com')   # ✅ Valid (custom subdomain)
+
+# Invalid URLs
+domain = CustomDomain.new(url: 'https://www.mysite.com')   # ❌ Invalid (www not allowed)
+```
+
+### Protocol Options
+
+#### `use_protocol` (default: `true`)
+
+Controls whether the protocol (http:// or https://) is required in the URL.
+
+```ruby
+class Website < ApplicationRecord
+  # Require protocol (default behavior)
+  validates :url, domain: { validation: :standard, use_protocol: true }
+
+  # Don't require protocol
+  validates :domain_without_protocol, domain: {
+    validation: :standard,
+    use_protocol: false
+  }
+end
+
+# With use_protocol: true (default)
+Website.new(url: 'https://mysite.com')  # ✅ Valid
+Website.new(url: 'mysite.com')          # ✅ Valid (auto-adds https://)
+
+# With use_protocol: false
+Website.new(domain_without_protocol: 'mysite.com')        # ✅ Valid
+Website.new(domain_without_protocol: 'https://mysite.com') # ✅ Valid (protocol stripped)
+```
+
+#### `use_https` (default: `true`)
+
+Controls whether HTTPS is required. Only relevant when `use_protocol` is `true`.
+
+```ruby
+class SecureWebsite < ApplicationRecord
+  # Require HTTPS (default behavior)
+  validates :url, domain: { validation: :standard, use_https: true }
+end
+
+class FlexibleWebsite < ApplicationRecord
+  # Allow both HTTP and HTTPS
+  validates :url, domain: { validation: :standard, use_https: false }
+end
+
+# With use_https: true (default)
+SecureWebsite.new(url: 'https://mysite.com')  # ✅ Valid
+SecureWebsite.new(url: 'http://mysite.com')   # ❌ Invalid
+
+# With use_https: false
+FlexibleWebsite.new(url: 'https://mysite.com') # ✅ Valid
+FlexibleWebsite.new(url: 'http://mysite.com')  # ✅ Valid
+```
+
+### Real-World Examples
+
+#### Multi-Tenant Application with Custom Domains
+
+```ruby
+class Tenant < ApplicationRecord
+  # Allow custom subdomains but not www
+  validates :custom_domain, domain: {
+    validation: :root_or_custom_subdomain,
+    use_https: true
+  }
+
+  # Primary domain must be root only
+  validates :primary_domain, domain: {
+    validation: :root_domain,
+    use_protocol: false
+  }
+end
+
+# Valid configurations
+tenant = Tenant.create(
+  custom_domain: 'https://shop.example.com',    # ✅ Custom subdomain
+  primary_domain: 'example.com'                 # ✅ Root without protocol
+)
+
+# Invalid configurations
+tenant = Tenant.new(
+  custom_domain: 'https://www.example.com'      # ❌ www not allowed
+)
+```
+
+#### E-commerce Store Configuration
+
+```ruby
+class Store < ApplicationRecord
+  # Main storefront can be root or custom subdomain
+  validates :storefront_url, domain: {
+    validation: :root_or_custom_subdomain,
+    use_https: true
+  }
+
+  # Admin panel must be a subdomain (not root, not www)
+  validates :admin_url, domain: { validation: :standard }
+  validate :admin_must_have_subdomain
+
+  private
+
+  def admin_must_have_subdomain
+    parsed = DomainExtractor.parse(admin_url)
+    if parsed.valid? && !parsed.subdomain?
+      errors.add(:admin_url, 'must have a subdomain')
+    end
+  end
+end
+```
+
+#### API Service Registration
+
+```ruby
+class ApiEndpoint < ApplicationRecord
+  # API endpoints must use HTTPS
+  validates :url, domain: {
+    validation: :standard,
+    use_https: true
+  }
+
+  # Custom validation for API subdomain
+  validate :must_be_api_subdomain
+
+  private
+
+  def must_be_api_subdomain
+    return unless url.present?
+
+    parsed = DomainExtractor.parse(url)
+    if parsed.valid? && parsed.subdomain.present?
+      unless parsed.subdomain.start_with?('api')
+        errors.add(:url, 'must use an api subdomain')
+      end
+    end
+  end
+end
+```
+
+#### Domain Allowlist with Flexible Protocol
+
+```ruby
+class AllowedDomain < ApplicationRecord
+  # Accept domains with or without protocol
+  validates :domain, domain: {
+    validation: :root_domain,
+    use_protocol: false,
+    use_https: false
+  }
+end
+
+# All these are valid
+AllowedDomain.create(domain: 'example.com')
+AllowedDomain.create(domain: 'https://example.com')
+AllowedDomain.create(domain: 'http://example.com')
+```
+
+### Combining with Other Validators
+
+The domain validator works seamlessly with other Rails validators:
+
+```ruby
+class Website < ApplicationRecord
+  validates :url, presence: true,
+                  domain: { validation: :standard },
+                  uniqueness: { case_sensitive: false }
+
+  validates :backup_url, domain: {
+    validation: :root_or_custom_subdomain,
+    use_https: true
+  }, allow_blank: true
+end
+```
+
+### Error Messages
+
+The validator provides clear, specific error messages:
+
+```ruby
+website = Website.new(url: 'not-a-url')
+website.valid?
+website.errors[:url]
+# => ["is not a valid URL"]
+
+domain = PrimaryDomain.new(domain: 'https://shop.example.com')
+domain.valid?
+domain.errors[:domain]
+# => ["must be a root domain (no subdomains allowed)"]
+
+custom = CustomDomain.new(url: 'https://www.example.com')
+custom.valid?
+custom.errors[:url]
+# => ["cannot use www subdomain"]
+
+secure = SecureWebsite.new(url: 'http://example.com')
+secure.valid?
+secure.errors[:url]
+# => ["must use https://"]
+```
+
 ## Use Cases
 
 **Web Scraping**

data/lib/domain_extractor/domain_validator.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# Try to load ActiveModel, but don't fail if it's not available
+begin
+  require 'active_model'
+rescue LoadError
+  # Create a stub for testing environments without Rails
+  module ActiveModel
+    class EachValidator
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+    end
+  end
+end
+
+# DomainValidator is a custom ActiveModel validator for URL/domain validation.
+#
+# This validator is defined at the top level so Rails can find it when using:
+#   validates :url, domain: { validation: :standard }
+#
+# Validation modes:
+# - :standard - Validates any valid URL using DomainExtractor.valid?
+# - :root_domain - Only allows root domains (no subdomains) like https://mysite.com
+# - :root_or_custom_subdomain - Allows root or custom subdomains but excludes 'www'
+#
+# Optional flags:
+# - use_protocol (default: true) - Whether protocol (http/https) is required
+# - use_https (default: true) - Whether https is required (only if use_protocol is true)
+#
+# @example Standard validation
+#   validates :url, domain: { validation: :standard }
+#
+# @example Root domain only, no protocol required
+#   validates :url, domain: { validation: :root_domain, use_protocol: false }
+#
+# @example Root or custom subdomain with https required
+#   validates :url, domain: { validation: :root_or_custom_subdomain, use_https: true }
+class DomainValidator < ActiveModel::EachValidator
+  VALIDATION_MODES = %i[standard root_domain root_or_custom_subdomain].freeze
+  WWW_SUBDOMAIN = 'www'
+
+  def validate_each(record, attribute, value)
+    return if blank?(value)
+
+    validation_mode = extract_validation_mode
+    use_protocol = options.fetch(:use_protocol, true)
+    use_https = options.fetch(:use_https, true)
+
+    normalized_url = normalize_url(value, use_protocol, use_https)
+
+    return unless protocol_valid?(record, attribute, normalized_url, use_protocol, use_https)
+
+    parsed = parse_and_validate_url(record, attribute, normalized_url)
+    return unless parsed
+
+    apply_validation_mode(record, attribute, parsed, validation_mode)
+  end
+
+  private
+
+  # Extract and validate the validation mode option
+  def extract_validation_mode
+    validation_mode = options.fetch(:validation, :standard)
+    return validation_mode if VALIDATION_MODES.include?(validation_mode)
+
+    raise ArgumentError, "Invalid validation mode: #{validation_mode}. " \
+                         "Must be one of: #{VALIDATION_MODES.join(', ')}"
+  end
+
+  # Check protocol requirements
+  def protocol_valid?(record, attribute, url, use_protocol, use_https)
+    return true unless use_protocol
+    return true if valid_protocol?(url, use_https)
+
+    protocol = use_https ? 'https://' : 'http:// or https://'
+    record.errors.add(attribute, "must use #{protocol}")
+    false
+  end
+
+  # Parse URL and validate it's valid
+  def parse_and_validate_url(record, attribute, url)
+    parsed = DomainExtractor.parse(url)
+    return parsed if parsed.valid?
+
+    record.errors.add(attribute, 'is not a valid URL')
+    nil
+  end
+
+  # Apply the validation mode rules
+  def apply_validation_mode(record, attribute, parsed, validation_mode)
+    case validation_mode
+    when :standard
+      # Already validated - any valid URL passes
+      nil
+    when :root_domain
+      validate_root_domain(record, attribute, parsed)
+    when :root_or_custom_subdomain
+      validate_root_or_custom_subdomain(record, attribute, parsed)
+    end
+  end
+
+  # Check if value is blank (nil, empty string, or whitespace-only)
+  def blank?(value)
+    value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+      (value.is_a?(String) && value.strip.empty?)
+  end
+
+  # Normalize URL for validation based on protocol requirements
+  def normalize_url(url, use_protocol, use_https)
+    return url if blank?(url)
+
+    url = url.strip
+
+    # If protocol is not required, strip any existing protocol
+    url = url.gsub(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://}, '') unless use_protocol
+
+    # Add protocol if needed for parsing
+    unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
+      scheme = use_https ? 'https://' : 'http://'
+      url = scheme + url
+    end
+
+    url
+  end
+
+  # Check if URL has valid protocol
+  def valid_protocol?(url, use_https)
+    return true unless url.match?(%r{\A[A-Za-z][A-Za-z0-9+\-.]*://})
+
+    if use_https
+      url.start_with?('https://')
+    else
+      url.start_with?('http://', 'https://')
+    end
+  end
+
+  # Validate that URL is a root domain (no subdomain)
+  def validate_root_domain(record, attribute, parsed)
+    return unless parsed.subdomain?
+
+    record.errors.add(attribute, 'must be a root domain (no subdomains allowed)')
+  end
+
+  # Validate that URL is either root domain or has custom subdomain (not 'www')
+  def validate_root_or_custom_subdomain(record, attribute, parsed)
+    return unless parsed.subdomain == WWW_SUBDOMAIN
+
+    record.errors.add(attribute, 'cannot use www subdomain')
+  end
+end
+
+# Also register in DomainExtractor namespace for backwards compatibility
+module DomainExtractor
+  # DomainValidator is now defined at the top level for Rails autoloading.
+  # This constant provides a reference for explicit usage.
+  #
+  # Validation modes:
+  # - :standard - Validates any valid URL using DomainExtractor.valid?
+  # - :root_domain - Only allows root domains (no subdomains) like https://mysite.com
+  # - :root_or_custom_subdomain - Allows root or custom subdomains, but excludes 'www'
+  #
+  # Optional flags:
+  # - use_protocol (default: true) - Whether protocol (http/https) is required
+  # - use_https (default: true) - Whether https is required (only if use_protocol is true)
+  #
+  # @example Standard validation
+  #   validates :url, domain: { validation: :standard }
+  #
+  # @example Root domain only, no protocol required
+  #   validates :url, domain: { validation: :root_domain, use_protocol: false }
+  DomainValidator = ::DomainValidator
+end

data/lib/domain_extractor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DomainExtractor
-  VERSION = '0.2.4'
+  VERSION = '0.2.6'
 end

data/lib/domain_extractor.rb

@@ -9,6 +9,13 @@ require_relative 'domain_extractor/parsed_url'
 require_relative 'domain_extractor/parser'
 require_relative 'domain_extractor/query_params'
 
+# Conditionally load Rails validator if ActiveModel is available
+begin
+  require_relative 'domain_extractor/domain_validator'
+rescue LoadError
+  # ActiveModel not available - skip loading validator
+end
+
 # DomainExtractor provides a high-performance API for url parsing and domain parsing.
 # It exposes simple helpers for single URL normalization, domain extraction, and batch operations.
 module DomainExtractor

data/spec/domain_validator_spec.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe DomainValidator do
+  # Mock record class for testing
+  let(:record_class) do
+    Class.new do
+      attr_accessor :url
+      attr_reader :errors
+
+      def initialize
+        @errors = ErrorsCollection.new
+      end
+    end
+  end
+
+  # Mock errors collection
+  let(:errors_collection_class) do
+    Class.new do
+      attr_reader :messages
+
+      def initialize
+        @messages = []
+      end
+
+      def add(attribute, message)
+        @messages << { attribute: attribute, message: message }
+      end
+
+      def empty?
+        @messages.empty?
+      end
+
+      def full_messages
+        @messages.map { |m| "#{m[:attribute]} #{m[:message]}" }
+      end
+    end
+  end
+
+  let(:record) { record_class.new }
+
+  before(:each) do
+    stub_const('ErrorsCollection', errors_collection_class)
+  end
+
+  describe 'validation modes' do
+    context 'with :standard validation' do
+      let(:validator) { described_class.new(attributes: [:url], validation: :standard) }
+
+      it 'accepts valid URLs with subdomains' do
+        record.url = 'https://shop.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts valid URLs without subdomains' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts www subdomain' do
+        record.url = 'https://www.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'rejects invalid URLs' do
+        record.url = 'not-a-url'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('not a valid URL')
+      end
+
+      it 'allows blank values' do
+        record.url = ''
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+    end
+
+    context 'with :root_domain validation' do
+      let(:validator) { described_class.new(attributes: [:url], validation: :root_domain) }
+
+      it 'accepts root domain URLs' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'rejects URLs with subdomains' do
+        record.url = 'https://shop.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('no subdomains allowed')
+      end
+
+      it 'rejects www subdomain' do
+        record.url = 'https://www.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('no subdomains allowed')
+      end
+
+      it 'rejects custom subdomains' do
+        record.url = 'https://api.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('no subdomains allowed')
+      end
+    end
+
+    context 'with :root_or_custom_subdomain validation' do
+      let(:validator) do
+        described_class.new(attributes: [:url], validation: :root_or_custom_subdomain)
+      end
+
+      it 'accepts root domain URLs' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts custom subdomain URLs' do
+        record.url = 'https://shop.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts api subdomain' do
+        record.url = 'https://api.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'rejects www subdomain' do
+        record.url = 'https://www.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('cannot use www subdomain')
+      end
+    end
+  end
+
+  describe 'protocol options' do
+    context 'with use_protocol: true (default)' do
+      let(:validator) { described_class.new(attributes: [:url], validation: :standard) }
+
+      it 'accepts URLs with https protocol' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts URLs without protocol by auto-adding https' do
+        record.url = 'mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+    end
+
+    context 'with use_protocol: false' do
+      let(:validator) do
+        described_class.new(attributes: [:url], validation: :standard, use_protocol: false)
+      end
+
+      it 'accepts URLs without protocol' do
+        record.url = 'mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts URLs with protocol by stripping it' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'works with root_domain validation' do
+        validator = described_class.new(
+          attributes: [:url],
+          validation: :root_domain,
+          use_protocol: false
+        )
+        record.url = 'mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'rejects subdomains with root_domain validation' do
+        validator = described_class.new(
+          attributes: [:url],
+          validation: :root_domain,
+          use_protocol: false
+        )
+        record.url = 'shop.mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+      end
+    end
+
+    context 'with use_https: true (default)' do
+      let(:validator) { described_class.new(attributes: [:url], validation: :standard) }
+
+      it 'accepts https URLs' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'rejects http URLs' do
+        record.url = 'http://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).not_to be_empty
+        expect(record.errors.messages.first[:message]).to include('must use https://')
+      end
+    end
+
+    context 'with use_https: false' do
+      let(:validator) do
+        described_class.new(attributes: [:url], validation: :standard, use_https: false)
+      end
+
+      it 'accepts https URLs' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts http URLs' do
+        record.url = 'http://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+    end
+
+    context 'with use_protocol: false and use_https: false' do
+      let(:validator) do
+        described_class.new(
+          attributes: [:url],
+          validation: :standard,
+          use_protocol: false,
+          use_https: false
+        )
+      end
+
+      it 'accepts domain without protocol' do
+        record.url = 'mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts domain with http protocol' do
+        record.url = 'http://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+
+      it 'accepts domain with https protocol' do
+        record.url = 'https://mysite.com'
+        validator.validate_each(record, :url, record.url)
+        expect(record.errors.messages).to be_empty
+      end
+    end
+  end
+
+  describe 'complex scenarios' do
+    it 'validates root_domain without protocol' do
+      validator = described_class.new(
+        attributes: [:url],
+        validation: :root_domain,
+        use_protocol: false
+      )
+      record.url = 'mysite.com'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+
+    it 'validates root_or_custom_subdomain with https only' do
+      validator = described_class.new(
+        attributes: [:url],
+        validation: :root_or_custom_subdomain,
+        use_https: true
+      )
+      record.url = 'https://shop.mysite.com'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+
+    it 'rejects www in root_or_custom_subdomain mode' do
+      validator = described_class.new(
+        attributes: [:url],
+        validation: :root_or_custom_subdomain,
+        use_protocol: false
+      )
+      record.url = 'www.mysite.com'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).not_to be_empty
+      expect(record.errors.messages.first[:message]).to include('cannot use www subdomain')
+    end
+
+    it 'handles URLs with paths' do
+      validator = described_class.new(attributes: [:url], validation: :standard)
+      record.url = 'https://mysite.com/path/to/page'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+
+    it 'handles URLs with query parameters' do
+      validator = described_class.new(attributes: [:url], validation: :standard)
+      record.url = 'https://mysite.com?foo=bar&baz=qux'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+
+    it 'handles multi-level subdomains with root_or_custom_subdomain' do
+      validator = described_class.new(
+        attributes: [:url],
+        validation: :root_or_custom_subdomain
+      )
+      record.url = 'https://api.staging.mysite.com'
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+  end
+
+  describe 'error handling' do
+    it 'raises error for invalid validation mode' do
+      expect do
+        validator = described_class.new(attributes: [:url], validation: :invalid_mode)
+        validator.validate_each(record, :url, 'https://mysite.com')
+      end.to raise_error(ArgumentError, /Invalid validation mode/)
+    end
+
+    it 'handles nil values gracefully' do
+      validator = described_class.new(attributes: [:url], validation: :standard)
+      record.url = nil
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+
+    it 'handles whitespace-only values' do
+      validator = described_class.new(attributes: [:url], validation: :standard)
+      record.url = '   '
+      validator.validate_each(record, :url, record.url)
+      expect(record.errors.messages).to be_empty
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: domain_extractor
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - OpenSite AI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-08 00:00:00.000000000 Z
+date: 2025-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: public_suffix
@@ -41,6 +41,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/domain_extractor.rb
+- lib/domain_extractor/domain_validator.rb
 - lib/domain_extractor/errors.rb
 - lib/domain_extractor/normalizer.rb
 - lib/domain_extractor/parsed_url.rb
@@ -50,6 +51,7 @@ files:
 - lib/domain_extractor/validators.rb
 - lib/domain_extractor/version.rb
 - spec/domain_extractor_spec.rb
+- spec/domain_validator_spec.rb
 - spec/parsed_url_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/opensite-ai/domain_extractor