encoded_id-rails 1.0.0.rc1 → 1.0.0.rc7

data/context/encoded_id.md

@@ -0,0 +1,437 @@
+# EncodedId Ruby Gem - Technical Documentation
+
+## Overview
+
+`encoded_id` is a Ruby gem that provides reversible obfuscation of numerical and hexadecimal IDs into human-readable strings suitable for use in URLs. It offers a secure way to hide sequential database IDs from users while maintaining the ability to decode them back to their original values.
+
+## Key Features
+
+- **Reversible Encoding**: Unlike UUIDs, encoded IDs can be decoded back to their original numeric values
+- **Multiple ID Support**: Encode multiple numeric IDs in a single string
+- **Algorithm Choice**: Supports both HashIds and Sqids encoding algorithms
+- **Human-Readable Format**: Character grouping and configurable separators for better readability
+- **Character Mapping**: Handles easily confused characters (0/O, 1/I/l) through equivalence mapping
+- **Performance Optimized**: Uses an optimized HashIds implementation for better performance
+- **Profanity Protection**: Built-in blocklist support to prevent offensive words in generated IDs
+- **Customizable**: Configurable alphabets, lengths, and formatting options
+- **Blocklist Modes**: Three modes for controlling blocklist checking performance
+
+## Quick Reference
+
+```ruby
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(min_length: 10)
+id = coder.encode(123)          # => "p5w9-z27j-k8"
+nums = coder.decode(id)         # => [123]
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt", min_length: 8)
+id = coder.encode([78, 45])     # => "z2j7-0dmw"
+nums = coder.decode(id)         # => [78, 45]
+
+# UUID encoding (experimental)
+hex_id = coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+uuid = coder.decode_hex(hex_id).first
+```
+
+## Core API
+
+### EncodedId::ReversibleId
+
+The main class for encoding and decoding IDs.
+
+#### Factory Methods (Recommended)
+
+Factory methods provide the cleanest way to create encoders:
+
+```ruby
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 10,
+  blocklist: ["bad", "words"]
+)
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(
+  salt: "my-salt",
+  min_length: 8,
+  blocklist: ["bad", "words"]
+)
+```
+
+Both factory methods accept all configuration options described below.
+
+#### Constructor (Alternative)
+
+You can also use the constructor with explicit configuration objects:
+
+```ruby
+# Using Sqids configuration
+config = EncodedId::Encoders::SqidsConfiguration.new(
+  min_length: 8,                 # Minimum length of encoded string
+  split_at: 4,                   # Split encoded string every X characters
+  split_with: "-",               # Character to split with
+  alphabet: EncodedId::Alphabet.modified_crockford,
+  hex_digit_encoding_group_size: 4,
+  max_length: 128,               # Maximum length limit
+  max_inputs_per_id: 32,         # Maximum IDs to encode together
+  blocklist: nil,                # Words to prevent in IDs
+  blocklist_mode: :length_threshold,  # :always, :length_threshold, or :raise_if_likely
+  blocklist_max_length: 32       # Max length for :length_threshold mode
+)
+coder = EncodedId::ReversibleId.new(config)
+
+# Using Hashids configuration (requires salt)
+config = EncodedId::Encoders::HashidConfiguration.new(
+  salt: "my-salt",               # Required for Hashids (min 4 chars)
+  min_length: 8,
+  # ... other options same as above
+)
+coder = EncodedId::ReversibleId.new(config)
+```
+
+**Note**: As of v1.0.0, the default encoder is `:sqids`. For backwards compatibility with pre-v1 versions, use `ReversibleId.hashid()`.
+
+#### Key Methods
+
+##### encode(values)
+Encodes one or more integer IDs into an obfuscated string.
+
+```ruby
+coder = EncodedId::ReversibleId.sqids
+
+# Single ID
+coder.encode(123) # => "p5w9-z27j"
+
+# Multiple IDs
+coder.encode([78, 45]) # => "z2j7-0dmw"
+```
+
+##### decode(encoded_id, downcase: false)
+Decodes an encoded string back to original IDs.
+
+```ruby
+coder.decode("p5w9-z27j") # => [123]
+coder.decode("z2j7-0dmw") # => [78, 45]
+
+# Case-sensitive by default (v1.0.0+)
+coder.decode("p5w9-z27J") # => [] (case doesn't match)
+
+# For case-insensitive matching (pre-v1 behavior)
+coder.decode("p5w9-z27J", downcase: true) # => [123]
+```
+
+**Note**: As of v1.0.0, decoding is case-sensitive by default (`downcase: false`). Set `downcase: true` for backwards compatibility.
+
+##### encode_hex(hex_strings) (Experimental)
+Encodes hexadecimal strings (like UUIDs).
+
+```ruby
+# Encode UUID
+coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+# => "5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr"
+
+# With larger group size for shorter output
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
+coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+# => "vr7m-qra8-m5y6-dkgj-5rqr-q44e-gp4a-52"
+```
+
+##### decode_hex(encoded_id, downcase: false) (Experimental)
+Decodes back to hexadecimal strings.
+
+```ruby
+coder.decode_hex("w72a-y0az") # => ["10f8c"]
+
+# For case-insensitive decoding (pre-v1 behavior)
+coder.decode_hex("W72A-Y0AZ", downcase: true) # => ["10f8c"]
+```
+
+### EncodedId::Alphabet
+
+Class for creating custom alphabets.
+
+#### Predefined Alphabets
+
+```ruby
+# Default: modified Crockford Base32
+# Characters: "0123456789abcdefghjkmnpqrstuvwxyz"
+# Excludes: i, l, o, u (easily confused)
+# Equivalences: {"o"=>"0", "i"=>"j", "l"=>"1", ...}
+EncodedId::Alphabet.modified_crockford
+```
+
+#### Custom Alphabets
+
+```ruby
+# Simple custom alphabet
+alphabet = EncodedId::Alphabet.new("0123456789abcdef")
+
+# With character equivalences
+alphabet = EncodedId::Alphabet.new(
+  "0123456789ABCDEF",
+  {"a"=>"A", "b"=>"B", "c"=>"C", "d"=>"D", "e"=>"E", "f"=>"F"}
+)
+
+# Greek alphabet example
+alphabet = EncodedId::Alphabet.new("αβγδεζηθικλμνξοπρστυφχψω")
+coder = EncodedId::ReversibleId.sqids(alphabet: alphabet)
+coder.encode(123) # => "θεαψ-ζκυο"
+```
+
+### EncodedId::Blocklist
+
+Class for managing profanity/word blocklists.
+
+#### Predefined Blocklists
+
+```ruby
+# Empty blocklist (no filtering)
+EncodedId::Blocklist.empty
+
+# Minimal blocklist (~50 common profane words)
+EncodedId::Blocklist.minimal
+
+# Full Sqids default blocklist (comprehensive)
+EncodedId::Blocklist.sqids_blocklist
+
+# Use in configuration
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal
+)
+```
+
+#### Custom Blocklists
+
+```ruby
+# From array
+blocklist = EncodedId::Blocklist.new(["bad", "offensive", "words"])
+
+# Merge blocklists
+combined = EncodedId::Blocklist.minimal.merge(
+  EncodedId::Blocklist.new(["custom", "words"])
+)
+
+# Filter for specific alphabet (automatic with configuration)
+filtered = blocklist.filter_for_alphabet(EncodedId::Alphabet.modified_crockford)
+```
+
+**Note**: Blocklists are automatically filtered to only include words possible with your configured alphabet. This optimization improves performance.
+
+## Configuration Options
+
+### Basic Options
+
+- **min_length**: Minimum length of encoded string (default: 8)
+- **max_length**: Maximum allowed length (default: 128) to prevent DoS attacks
+- **max_inputs_per_id**: Maximum IDs encodable together (default: 32)
+- **hex_digit_encoding_group_size**: Group size for hex encoding (default: 4)
+
+### Encoder Selection
+
+```ruby
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids
+
+# Hashids encoder (requires salt - minimum 4 characters)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt-minimum-4-chars")
+```
+
+**Important**:
+- As of v1.0.0, `:sqids` is the default encoder
+- **Sqids**: No salt required, automatically avoids blocklisted words via iteration
+- **Hashids**: Salt required (min 4 chars), raises exception if blocklisted word appears
+- HashIds and Sqids produce different encodings and are **not compatible**
+- Do NOT change encoders after going to production with existing encoded IDs
+
+### Blocklist Configuration
+
+#### Blocklist Modes
+
+Control how blocklist checking behaves to balance performance and safety:
+
+```ruby
+# :length_threshold (default) - Check blocklist only until encoded length reaches blocklist_max_length
+# Best for most use cases - prevents performance issues with very long IDs
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32  # Stop checking after 32 characters
+)
+
+# :always - Always check blocklist regardless of encoded length
+# Can be slow for long IDs or large blocklists
+coder = EncodedId::ReversibleId.hashid(
+  salt: "my-salt",
+  blocklist: ["bad", "words"],
+  blocklist_mode: :always
+)
+
+# :raise_if_likely - Raise error at configuration time if settings likely cause blocklist collisions
+# Prevents configurations that would cause performance issues
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 8,
+  blocklist: ["bad", "words"],
+  blocklist_mode: :raise_if_likely
+)
+# Raises InvalidConfigurationError if min_length > blocklist_max_length
+```
+
+**Blocklist Behavior by Encoder**:
+- **Sqids**: Iteratively regenerates to avoid blocklisted words (may impact encoding performance)
+- **Hashids**: Raises `EncodedId::BlocklistError` if a blocklisted word appears
+
+**Recommendation**: Use `:length_threshold` mode (default) for best balance of performance and safety.
+
+### Formatting Options
+
+```ruby
+# Custom splitting
+coder = EncodedId::ReversibleId.sqids(
+  split_at: 3,      # Group every 3 chars
+  split_with: "."   # Use dots
+)
+coder.encode(123) # => "p5w.9z2.7j"
+
+# No splitting
+coder = EncodedId::ReversibleId.sqids(split_at: nil)
+coder.encode(123) # => "p5w9z27j"
+```
+
+## Exception Handling
+
+| Exception | Description |
+|-----------|-------------|
+| `EncodedId::InvalidConfigurationError` | Invalid configuration parameters |
+| `EncodedId::InvalidAlphabetError` | Invalid alphabet (< 16 unique chars) |
+| `EncodedId::EncodedIdFormatError` | Invalid encoded ID format |
+| `EncodedId::EncodedIdLengthError` | Encoded ID exceeds max_length |
+| `EncodedId::InvalidInputError` | Invalid input (negative integers, too many inputs) |
+| `EncodedId::SaltError` | Invalid salt (too short, only for Hashids) |
+| `EncodedId::BlocklistError` | Generated ID contains blocklisted word (Hashids only) |
+
+## Usage Examples
+
+### Basic Usage
+```ruby
+# Initialize with Sqids (no salt needed)
+coder = EncodedId::ReversibleId.sqids
+
+# Encode/decode cycle
+encoded = coder.encode(123)        # => "p5w9-z27j"
+decoded = coder.decode(encoded)    # => [123]
+original_id = decoded.first        # => 123
+```
+
+### Multiple IDs
+```ruby
+# Encode multiple IDs in one string
+encoded = coder.encode([78, 45, 92])  # => "z2j7-0dmw-kf8p"
+decoded = coder.decode(encoded)        # => [78, 45, 92]
+```
+
+### With Hashids and Blocklist
+```ruby
+coder = EncodedId::ReversibleId.hashid(
+  salt: "my-app-salt",
+  min_length: 12,
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold
+)
+
+encoded = coder.encode(123)
+# Raises BlocklistError if result contains blocklisted word
+```
+
+### Custom Configuration
+```ruby
+# Highly customized Sqids instance
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 12,
+  split_at: 3,
+  split_with: ".",
+  alphabet: EncodedId::Alphabet.new("0123456789ABCDEF"),
+  blocklist: ["BAD", "FAKE"],
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32
+)
+```
+
+### Hex Encoding (UUIDs)
+```ruby
+# For encoding UUIDs efficiently
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
+
+uuid = "550e8400-e29b-41d4-a716-446655440000"
+encoded = coder.encode_hex(uuid)
+decoded = coder.decode_hex(encoded).first # => original UUID (without hyphens)
+```
+
+## Performance Considerations
+
+1. **Algorithm Choice**:
+   - HashIds: Faster encoding, especially with blocklists
+   - Sqids: Faster decoding, automatically avoids blocklisted words
+
+2. **Blocklist Impact**:
+   - Large blocklists slow encoding, especially with Sqids (which iterates to avoid words)
+   - Hashids may raise exceptions requiring retry logic
+   - Use `blocklist_mode: :length_threshold` for best performance
+   - `:always` mode can significantly impact encoding speed for long IDs
+   - Blocklists are automatically filtered for your alphabet, improving performance
+
+3. **Blocklist Mode Performance**:
+   - `:length_threshold` (default): Only checks blocklist for IDs ≤ `blocklist_max_length` (default: 32)
+   - `:always`: Checks all IDs regardless of length (can be slow)
+   - `:raise_if_likely`: Validates configuration at initialization to prevent performance issues
+
+4. **Length vs Performance**: Longer minimum lengths may require more computation
+
+5. **Memory Usage**: The gem uses optimized implementations to minimize memory allocation
+
+## Version Compatibility
+
+**v1.0.0 Breaking Changes:**
+
+1. **Default encoder**: Changed from `:hashids` to `:sqids`
+2. **Case sensitivity**: `decode` is now case-sensitive by default (`downcase: false`)
+   - Pre-v1: `decode("ABC")` and `decode("abc")` were equivalent
+   - v1.0.0+: These produce different results unless `downcase: true`
+3. **Salt requirement**: Sqids (default) doesn't require salt; Hashids still requires salt
+4. **Migration**: For backwards compatibility with pre-v1:
+   ```ruby
+   coder = EncodedId::ReversibleId.hashid(salt: "your-salt")
+   decoded = coder.decode(id, downcase: true)
+   ```
+
+## Security Notes
+
+**Important**: Encoded IDs are NOT cryptographically secure. They provide obfuscation, not encryption. Do not rely on them for security purposes. They can potentially be reversed through brute-force attacks if the salt is compromised.
+
+Use encoded IDs for:
+- Hiding sequential database IDs
+- Creating user-friendly URLs
+- Preventing ID enumeration attacks
+- Obscuring business metrics (user counts, order volumes)
+
+Do NOT use for:
+- Secure tokens
+- Authentication
+- Sensitive data protection
+- Cryptographic purposes
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'encoded_id'
+```
+
+## Best Practices
+
+1. **Consistent Configuration**: Once in production, don't change salt, encoder, or alphabet
+2. **Error Handling**: Always handle potential exceptions when decoding user input
+3. **Length Limits**: Set appropriate max_length to prevent DoS attacks
+4. **Validation**: Validate decoded IDs before using them in database queries
+5. **Blocklist Mode**: Use `:length_threshold` (default) for production - best performance/safety balance
+6. **Factory Methods**: Prefer `ReversibleId.sqids()` and `ReversibleId.hashid()` over constructor

data/lib/encoded_id/rails/active_record_finders.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Rails
+    # This module overrides standard ActiveRecord finder methods to automatically decode encoded IDs.
+    # Important: This module should NOT be used with models that use string-based primary keys (e.g., UUIDs)
+    # as it will cause conflicts between string IDs and encoded IDs.
+    module ActiveRecordFinders
+      extend ActiveSupport::Concern
+
+      # @rbs!
+      #   include ::ActiveRecord::FinderMethods
+      #   extend ::ActiveRecord::QueryMethods
+
+      included do
+        if columns_hash["id"]&.type == :string
+          ::Rails.logger.warn("EncodedId::Rails::ActiveRecordFinders has been included in #{name}, but this model uses string-based IDs. This may cause conflicts with encoded ID handling.")
+        end
+      end
+
+      # Class methods for overriding ActiveRecord's finder methods to decode encoded IDs.
+      module ClassMethods
+        # @rbs (*untyped args) -> untyped
+        def find(*args)
+          first_arg = args.first
+          return super unless args.size == 1 && first_arg.is_a?(String)
+
+          decoded_ids = decode_encoded_id(first_arg)
+
+          if decoded_ids.blank?
+            raise ::ActiveRecord::RecordNotFound
+          elsif decoded_ids.size == 1
+            super(decoded_ids.first)
+          else
+            super(decoded_ids)
+          end
+        end
+
+        # Override find_by_id to handle encoded IDs
+        # @rbs (untyped id) -> untyped
+        def find_by_id(id)
+          if id.is_a?(String)
+            decoded_ids = decode_encoded_id(id)
+            return nil if decoded_ids.blank?
+            return super(decoded_ids.first)
+          end
+          super
+        end
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/annotated_id.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
-require "cgi"
+# rbs_inline: enabled
 
 module EncodedId
   module Rails
-    class AnnotatedId
+    # Represents an encoded ID with an annotation prefix (e.g., "user_ABC123").
+    class AnnotatedId < CompositeIdBase
+      # @rbs (annotation: String, id_part: String, ?separator: String) -> void
       def initialize(annotation:, id_part:, separator: "_")
-        @annotation = annotation
-        @id_part = id_part
-        @separator = separator
+        super(first_part: annotation, id_part: id_part, separator: separator)
       end
 
+      # @rbs return: String
       def annotated_id
-        unless @id_part.present? && @annotation.present?
-          raise ::StandardError, "The model does not provide a valid ID and/or annotation"
-        end
-        "#{@annotation.to_s.parameterize}#{CGI.escape(@separator)}#{@id_part}"
+        build_composite_id
+      end
+
+      private
+
+      # @rbs return: String
+      def invalid_id_error_message
+        "The model does not return a valid ID and/or annotation"
       end
     end
   end

data/lib/encoded_id/rails/annotated_id_parser.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
+    # Parses an annotated ID into its annotation and ID components.
     class AnnotatedIdParser
+      # @rbs @annotation: String?
+      # @rbs @id: String
+
+      # @rbs (String annotated_id, ?separator: String) -> void
       def initialize(annotated_id, separator: "_")
         if separator && annotated_id.include?(separator)
           parts = annotated_id.split(separator)
@@ -13,7 +20,8 @@ module EncodedId
         end
       end
 
-      attr_reader :annotation, :id
+      attr_reader :annotation #: String?
+      attr_reader :id #: String
     end
   end
 end

data/lib/encoded_id/rails/coder.rb

@@ -1,36 +1,81 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
+    # Encodes and decodes IDs using the configured encoder and settings.
     class Coder
-      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:)
+      # @rbs @salt: String?
+      # @rbs @id_length: Integer
+      # @rbs @character_group_size: Integer
+      # @rbs @separator: String
+      # @rbs @alphabet: ::EncodedId::Alphabet
+      # @rbs @encoder: Symbol
+      # @rbs @blocklist: ::EncodedId::Blocklist?
+      # @rbs @blocklist_mode: Symbol
+      # @rbs @blocklist_max_length: Integer
+      # @rbs @downcase_on_decode: bool
+
+      # @rbs (salt: String?, id_length: Integer, character_group_size: Integer, separator: String, alphabet: ::EncodedId::Alphabet, ?encoder: Symbol?, ?blocklist: ::EncodedId::Blocklist?, ?blocklist_mode: Symbol?, ?blocklist_max_length: Integer?, ?downcase_on_decode: bool?) -> void
+      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:, encoder: nil, blocklist: nil, blocklist_mode: nil, blocklist_max_length: nil, downcase_on_decode: nil)
         @salt = salt
         @id_length = id_length
         @character_group_size = character_group_size
         @separator = separator
         @alphabet = alphabet
+        config = EncodedId::Rails.configuration
+        @encoder = encoder || config.encoder
+        @blocklist = blocklist || config.blocklist
+        @blocklist_mode = blocklist_mode || config.blocklist_mode
+        @blocklist_max_length = blocklist_max_length || config.blocklist_max_length
+        @downcase_on_decode = downcase_on_decode.nil? ? config.downcase_on_decode : downcase_on_decode
       end
 
+      # @rbs (Integer | Array[Integer] id) -> String
       def encode(id)
         coder.encode(id)
       end
 
+      # @rbs (String encoded_id) -> Array[Integer]
       def decode(encoded_id)
-        coder.decode(encoded_id)
+        coder.decode(encoded_id, downcase: @downcase_on_decode)
       rescue EncodedId::EncodedIdFormatError, EncodedId::InvalidInputError
-        nil
+        []
       end
 
       private
 
+      # @rbs return: ::EncodedId::ReversibleId
       def coder
-        ::EncodedId::ReversibleId.new(
-          salt: @salt,
-          length: @id_length,
-          split_at: @character_group_size,
-          split_with: @separator,
-          alphabet: @alphabet
-        )
+        # Build the appropriate configuration based on encoder type
+        config = case @encoder
+        when :hashids
+          ::EncodedId::Encoders::HashidConfiguration.new(
+            salt: @salt || raise(ArgumentError, "Salt is required for hashids encoder"),
+            min_length: @id_length,
+            split_at: @character_group_size,
+            split_with: @separator,
+            alphabet: @alphabet,
+            blocklist: @blocklist,
+            blocklist_mode: @blocklist_mode,
+            blocklist_max_length: @blocklist_max_length
+          )
+        when :sqids
+          ::EncodedId::Encoders::SqidsConfiguration.new(
+            min_length: @id_length,
+            split_at: @character_group_size,
+            split_with: @separator,
+            alphabet: @alphabet,
+            blocklist: @blocklist,
+            blocklist_mode: @blocklist_mode,
+            blocklist_max_length: @blocklist_max_length
+          )
+        else
+          raise ArgumentError, "Unknown encoder type: #{@encoder}"
+        end
+
+        ::EncodedId::ReversibleId.new(config)
       end
     end
   end

data/lib/encoded_id/rails/composite_id_base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "cgi"
+
+module EncodedId
+  module Rails
+    # Base class for composite IDs (slugged and annotated)
+    class CompositeIdBase
+      # @rbs @first_part: String
+      # @rbs @id_part: String
+      # @rbs @separator: String
+
+      # @rbs (first_part: String, id_part: String, separator: String) -> void
+      def initialize(first_part:, id_part:, separator:)
+        @first_part = first_part
+        @id_part = id_part
+        @separator = separator
+      end
+
+      private
+
+      # @rbs return: String
+      def build_composite_id
+        unless @id_part.present? && @first_part.present?
+          raise ::StandardError, invalid_id_error_message
+        end
+        "#{@first_part.to_s.parameterize}#{CGI.escape(@separator)}#{@id_part}"
+      end
+
+      # Default error message. Subclasses can override for more specific messages.
+      # @rbs return: String
+      def invalid_id_error_message
+        "The model does not return a valid ID and/or prefix"
+      end
+    end
+  end
+end