opaque_id 1.3.0 → 1.6.0

data/docs/development.md

@@ -10,6 +10,9 @@ permalink: /development/
 
 This guide covers development setup, guidelines, and contribution information for OpaqueId. Whether you're contributing to the project or developing applications that use OpaqueId, this guide will help you get started.
 
+- TOC
+  {:toc}
+
 ## Prerequisites
 
 Before you begin development, ensure you have the following installed:

data/docs/getting-started.md

@@ -10,6 +10,9 @@ permalink: /getting-started/
 
 This guide will help you get up and running with OpaqueId in your Rails application. We'll cover installation, basic setup, and common usage patterns.
 
+- TOC
+  {:toc}
+
 ## Prerequisites
 
 Before you begin, ensure you have:

data/docs/index.md

@@ -12,7 +12,10 @@ permalink: /
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 [![Gem Downloads](https://img.shields.io/badge/gem%20downloads-opaque_id-blue)](https://rubygems.org/gems/opaque_id)
 
-A Ruby gem for generating cryptographically secure, collision-free opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for `nanoid.rb` using Ruby's built-in `SecureRandom` methods with optimized algorithms for unbiased distribution.
+A simple Ruby gem for generating secure, opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for `nanoid.rb` using Ruby's built-in `SecureRandom` methods, with slug-like IDs as the default for optimal URL safety and user experience.
+
+- TOC
+  {:toc}
 
 ## Features
 
@@ -54,10 +57,10 @@ end
 
 # Create a user - opaque_id is automatically generated
 user = User.create!(name: "John Doe")
-puts user.opaque_id # => "V1StGXR8_Z5jdHi6B-myT"
+puts user.opaque_id # => "izkpm55j334u8x9y2"
 
 # Find by opaque_id
-user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id("izkpm55j334u8x9y2")
 ```
 
 ## Why OpaqueId?

data/docs/installation.md

@@ -10,6 +10,9 @@ permalink: /installation/
 
 This guide covers all installation methods for OpaqueId, from basic setup to advanced configurations.
 
+- TOC
+  {:toc}
+
 ## Requirements
 
 Before installing OpaqueId, ensure your environment meets these requirements:

data/docs/performance.md

@@ -8,17 +8,20 @@ permalink: /performance/
 
 # Performance
 
-OpaqueId is designed for high performance with optimized algorithms and efficient memory usage. This guide covers benchmarks, optimization strategies, and scalability considerations.
+OpaqueId is designed for efficient ID generation with optimized algorithms and memory usage. This guide covers performance characteristics, optimization strategies, and scalability considerations.
+
+- TOC
+  {:toc}
 
 ## Performance Characteristics
 
 ### Generation Speed
 
-OpaqueId is designed for high performance with optimized algorithms for different alphabet sizes and ID lengths.
+OpaqueId is designed for efficient ID generation with optimized algorithms for different alphabet sizes and ID lengths.
 
 #### Algorithm Performance
 
-- **Fast Path (64-character alphabets)**: Uses bitwise operations for maximum speed with no rejection sampling overhead
+- **Fast Path (64-character alphabets)**: Uses bitwise operations for efficient generation with no rejection sampling overhead
 - **Unbiased Path (Other alphabets)**: Uses rejection sampling for unbiased distribution with slight performance overhead
 - **Performance scales linearly** with ID length and batch size
 

data/docs/security.md

@@ -10,6 +10,9 @@ permalink: /security/
 
 OpaqueId is designed with security as a primary concern, providing cryptographically secure ID generation with protection against various attack vectors. This guide covers security considerations, best practices, and threat model analysis.
 
+- TOC
+  {:toc}
+
 ## Cryptographic Security
 
 ### SecureRandom Foundation

data/docs/usage.md

@@ -10,6 +10,9 @@ permalink: /usage/
 
 This guide covers all usage patterns for OpaqueId, from basic standalone generation to advanced ActiveRecord integration.
 
+- TOC
+  {:toc}
+
 ## Standalone ID Generation
 
 OpaqueId can be used independently of ActiveRecord for generating secure, random IDs.
@@ -17,9 +20,9 @@ OpaqueId can be used independently of ActiveRecord for generating secure, random
 ### Basic Usage
 
 ```ruby
-# Generate a default opaque ID (21 characters, alphanumeric)
+# Generate a default opaque ID (18 characters, slug-like)
 id = OpaqueId.generate
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 # Generate multiple IDs
 ids = 5.times.map { OpaqueId.generate }
@@ -31,15 +34,15 @@ ids = 5.times.map { OpaqueId.generate }
 ```ruby
 # Custom length
 id = OpaqueId.generate(size: 10)
-# => "V1StGXR8_Z5"
+# => "izkpm55j334u"
 
 # Custom alphabet
 id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 # Both custom length and alphabet
 id = OpaqueId.generate(size: 15, alphabet: OpaqueId::STANDARD_ALPHABET)
-# => "V1StGXR8_Z5jdHi"
+# => "izkpm55j334u8x9y"
 ```
 
 ### Built-in Alphabets
@@ -47,11 +50,11 @@ id = OpaqueId.generate(size: 15, alphabet: OpaqueId::STANDARD_ALPHABET)
 ```ruby
 # Alphanumeric alphabet (default) - A-Z, a-z, 0-9
 id = OpaqueId.generate(alphabet: OpaqueId::ALPHANUMERIC_ALPHABET)
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 # Standard alphabet - A-Z, a-z, 0-9, -, _
 id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 ```
 
 ### Custom Alphabets
@@ -70,7 +73,7 @@ id = OpaqueId.generate(size: 16, alphabet: hex_alphabet)
 # URL-safe characters
 url_safe = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
 id = OpaqueId.generate(size: 12, alphabet: url_safe)
-# => "V1StGXR8_Z5j"
+# => "izkpm55j334u8x"
 ```
 
 ## ActiveRecord Integration
@@ -91,7 +94,7 @@ end
 # Create a new user - opaque_id is automatically generated
 user = User.create!(name: "John Doe", email: "john@example.com")
 puts user.opaque_id
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 # The ID is generated before the record is saved
 user = User.new(name: "Jane Smith")
@@ -107,10 +110,10 @@ puts user.opaque_id
 
 ```ruby
 # Find by opaque_id (returns nil if not found)
-user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id("izkpm55j334u8x9y2")
 
 # Find by opaque_id (raises exception if not found)
-user = User.find_by_opaque_id!("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id!("izkpm55j334u8x9y2")
 # => ActiveRecord::RecordNotFound if not found
 
 # Use in scopes
@@ -120,7 +123,7 @@ class User < ApplicationRecord
   scope :by_opaque_id, ->(id) { where(opaque_id: id) }
 end
 
-users = User.by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+users = User.by_opaque_id("izkpm55j334u8x9y2")
 ```
 
 ### Custom Column Names
@@ -136,7 +139,7 @@ end
 # Now the methods use the custom column name
 user = User.create!(name: "John Doe")
 puts user.public_id
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 user = User.find_by_public_id("V1StGXR8_Z5jdHi6B-myT")
 ```
@@ -195,7 +198,7 @@ end
 # Create an order
 order = Order.create!(user_id: 1, total: 99.99)
 puts order.opaque_id
-# => "V1StGXR8_Z5j"
+# => "izkpm55j334u8x"
 
 # Use in URLs
 order_url(order.opaque_id)
@@ -256,7 +259,7 @@ end
 # Create a user
 user = User.create!(name: "John Doe", email: "john@example.com")
 puts user.opaque_id
-# => "V1StGXR8_Z5jdHi6B-myT" (starts with letter)
+# => "izkpm55j334u8x9y2" (starts with letter)
 
 # Use in user profiles
 user_url(user.opaque_id)

data/docs/use-cases.md

@@ -10,6 +10,9 @@ permalink: /use-cases/
 
 OpaqueId is designed for a wide range of applications where secure, unpredictable identifiers are needed. This guide covers real-world use cases with practical examples and implementation patterns.
 
+- TOC
+  {:toc}
+
 ## E-Commerce Applications
 
 ### Order Management

data/lib/opaque_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpaqueId
-  VERSION = '1.3.0'
+  VERSION = '1.6.0'
 end

data/lib/opaque_id.rb

@@ -9,6 +9,9 @@ module OpaqueId
   class GenerationError < Error; end
   class ConfigurationError < Error; end
 
+  # Slug-like alphabet for URL-safe, double-click selectable IDs (36 characters)
+  SLUG_LIKE_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+
   # Standard URL-safe alphabet (64 characters)
   STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
 
@@ -17,7 +20,7 @@ module OpaqueId
 
   class << self
     # Generate a cryptographically secure random ID
-    def generate(size: 21, alphabet: ALPHANUMERIC_ALPHABET)
+    def generate(size: 18, alphabet: SLUG_LIKE_ALPHABET)
       raise ConfigurationError, 'Size must be positive' unless size.positive?
       raise ConfigurationError, 'Alphabet cannot be empty' if alphabet.nil? || alphabet.empty?
 

data/release-please-config.json

@@ -3,7 +3,8 @@
   "packages": {
     ".": {
       "package-name": "opaque_id",
-      "version-file": "lib/opaque_id/version.rb"
+      "version-file": "lib/opaque_id/version.rb",
+      "tag-template": "v${version}"
     }
   },
   "changelog-sections": [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opaque_id
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Joe Nyaggah
@@ -156,14 +156,6 @@ files:
 - lib/opaque_id/model.rb
 - lib/opaque_id/version.rb
 - release-please-config.json
-- tasks/0001-prd-opaque-id-gem.md
-- tasks/0002-prd-publishing-release-automation.md
-- tasks/0003-prd-documentation-site.md
-- tasks/references/opaque_gem_requirements.md
-- tasks/references/original_identifiable_concern_and_nanoid.md
-- tasks/tasks-0001-prd-opaque-id-gem.md
-- tasks/tasks-0002-prd-publishing-release-automation.md
-- tasks/tasks-0003-prd-documentation-site.md
 homepage: https://github.com/nyaggah/opaque_id
 licenses:
 - MIT

data/tasks/0001-prd-opaque-id-gem.md

@@ -1,202 +0,0 @@
-# Product Requirements Document: OpaqueId Ruby Gem
-
-## Introduction/Overview
-
-The OpaqueId gem is a Ruby library that generates cryptographically secure, collision-free opaque identifiers for ActiveRecord models. This gem replaces the existing `nanoid.rb` dependency by implementing the same functionality using Ruby's built-in `SecureRandom` methods, eliminating external dependencies while maintaining the same security and performance characteristics.
-
-The primary problem this gem solves is preventing the exposure of incremental database IDs in public URLs and APIs, which can reveal business metrics, enable enumeration attacks, and expose internal system architecture. Instead, it provides opaque, non-sequential identifiers that are URL-friendly and cryptographically secure.
-
-## Goals
-
-1. **Replace nanoid.rb dependency** - Implement equivalent functionality using Ruby's built-in SecureRandom
-2. **Maintain security standards** - Provide cryptographically secure ID generation with unbiased distribution
-3. **Ensure performance** - Achieve 1M+ IDs/sec for 64-character alphabets, 180K+ IDs/sec for 36-character alphabets
-4. **Simplify integration** - Provide seamless ActiveRecord integration with minimal configuration
-5. **Enable wide adoption** - Create comprehensive documentation accessible to all Rails developers
-6. **Ensure reliability** - Implement robust collision detection and retry logic
-7. **Maintain compatibility** - Support Rails 8.0+ and Ruby 3.2+ environments
-
-## User Stories
-
-### Primary Users: Rails Developers
-
-**As a Rails developer**, I want to generate opaque IDs for my models so that I can expose public identifiers without revealing database structure.
-
-**As a Rails developer**, I want to easily integrate opaque ID generation into my existing models so that I don't have to manually implement ID generation logic.
-
-**As a Rails developer**, I want to configure ID generation parameters (length, alphabet, column name) so that I can customize the behavior for different use cases.
-
-**As a Rails developer**, I want to find records by their opaque ID so that I can build public-facing APIs and URLs.
-
-**As a Rails developer**, I want the gem to handle collision detection automatically so that I don't have to worry about duplicate IDs.
-
-**As a Rails developer**, I want comprehensive documentation and examples so that I can quickly understand and implement the gem in my project.
-
-### Secondary Users: Security-Conscious Teams
-
-**As a security-conscious developer**, I want cryptographically secure ID generation so that my public identifiers cannot be predicted or enumerated.
-
-**As a security-conscious developer**, I want unbiased character distribution so that my IDs have maximum entropy and cannot be analyzed for patterns.
-
-## Functional Requirements
-
-### Core ID Generation
-
-1. The system must generate cryptographically secure random IDs using Ruby's `SecureRandom`
-2. The system must implement rejection sampling algorithm to ensure unbiased character distribution
-3. The system must provide optimized fast path for 64-character alphabets using bitwise operations
-4. The system must support custom alphabet configurations
-5. The system must support custom ID length configurations
-6. The system must provide two predefined alphabets: ALPHANUMERIC_ALPHABET (36 chars) and STANDARD_ALPHABET (64 chars)
-
-### ActiveRecord Integration
-
-7. The system must provide `OpaqueId::Model` concern for easy ActiveRecord integration
-8. The system must automatically generate opaque IDs on model creation via `before_create` callback
-9. The system must provide `find_by_opaque_id` and `find_by_opaque_id!` class methods
-10. The system must support custom column names via `opaque_id_column` configuration
-11. The system must implement collision detection with configurable retry attempts
-12. The system must raise appropriate errors when collision resolution fails
-
-### Rails Generator (Optional Convenience Tool)
-
-13. The system must provide optional Rails generator `opaque_id:install` for creating migrations and updating models
-14. The system must generate migration files that add opaque_id column with unique index
-15. The system must automatically add `include OpaqueId::Model` to the corresponding model file
-16. The system must support custom column names via generator options
-17. The system must require explicit table name argument and show clear usage instructions when run without arguments
-18. The system must work with any existing table (new or existing models)
-19. The system must handle edge cases gracefully (missing model file, already included, different class names)
-
-### Configuration Options
-
-20. The system must support `opaque_id_column` configuration (default: `:opaque_id`)
-21. The system must support `opaque_id_length` configuration (default: `18`)
-22. The system must support `opaque_id_alphabet` configuration (default: `ALPHANUMERIC_ALPHABET`)
-23. The system must support `opaque_id_require_letter_start` configuration (default: `true`)
-24. The system must support `opaque_id_purge_chars` configuration (default: `nil`)
-25. The system must support `opaque_id_max_retry` configuration (default: `1000`)
-
-### Error Handling
-
-26. The system must raise `OpaqueId::ConfigurationError` for invalid size or empty alphabet
-27. The system must raise `OpaqueId::GenerationError` when collision resolution fails
-28. The system must provide clear error messages for debugging
-
-### Standalone Usage
-
-29. The system must provide `OpaqueId.generate` method for standalone ID generation
-30. The system must support all configuration options in standalone generation
-31. The system must maintain the same security and performance characteristics in standalone mode
-
-## Non-Goals (Out of Scope)
-
-1. **Other ORM Support** - Will not support Mongoid, Sequel, or other ORMs in initial release
-2. **Non-Rails Usage** - Will not provide standalone Ruby usage without ActiveRecord dependency
-3. **Custom Algorithms** - Will not implement alternative ID generation algorithms beyond rejection sampling
-4. **Database Migrations** - Will not provide automatic database migration for existing records
-5. **ID Validation** - Will not provide built-in ID format validation (users can implement their own)
-6. **Bulk Generation** - Will not provide optimized bulk ID generation methods
-7. **ID Prefixes/Suffixes** - Will not support adding prefixes or suffixes to generated IDs
-8. **Custom Random Sources** - Will not support custom random number generators beyond SecureRandom
-9. **Interactive Generator Mode** - Will not provide interactive prompts for generator arguments
-10. **Backward Compatibility** - Will not maintain compatibility with existing `public_id` implementations
-
-## Design Considerations
-
-### API Design
-
-- Follow Rails conventions for ActiveRecord concerns and generators
-- Use descriptive method names that clearly indicate functionality
-- Provide both safe (`find_by_opaque_id`) and unsafe (`find_by_opaque_id!`) lookup methods
-- Use class-level configuration options for easy customization
-- Follow Devise-style generator pattern for seamless integration
-
-### Performance Optimization
-
-- Implement fast path for 64-character alphabets using bitwise operations (`byte & 63`)
-- Use rejection sampling with optimal mask calculation for unbiased distribution
-- Pre-allocate string capacity to avoid memory reallocation during generation
-- Batch random byte generation to minimize SecureRandom calls
-
-### Security Considerations
-
-- Use only cryptographically secure random number generation
-- Implement proper rejection sampling to avoid modulo bias
-- Provide sufficient entropy through configurable alphabet sizes
-- Ensure IDs cannot be predicted or enumerated
-
-## Technical Considerations
-
-### Dependencies
-
-- **ActiveRecord**: >= 6.0 (targeting Rails 8.0+ compatibility)
-- **ActiveSupport**: >= 6.0 (for concern functionality)
-- **Ruby**: >= 3.2 (for modern Ruby features and performance)
-
-### Testing Framework
-
-- Use **Minitest** instead of RSpec for consistency with Rails conventions
-- Implement comprehensive unit tests for all public methods
-- Include statistical tests for character distribution uniformity
-- Add performance benchmarks to ensure performance requirements are met
-- Test edge cases including collision scenarios and error conditions
-
-### File Structure
-
-```
-lib/
-├── opaque_id.rb                 # Main module with generator
-├── opaque_id/
-│   ├── version.rb               # Version constant
-│   └── model.rb                 # ActiveRecord concern
-└── generators/
-    └── opaque_id/
-        ├── install_generator.rb  # Migration generator
-        └── templates/
-            └── migration.rb.tt   # Migration template
-```
-
-### Error Classes
-
-- `OpaqueId::Error` - Base error class
-- `OpaqueId::GenerationError` - ID generation failures
-- `OpaqueId::ConfigurationError` - Invalid configuration
-
-## Success Metrics
-
-### Performance Metrics
-
-- **Standard alphabet (64 chars)**: Achieve ~1.2M IDs/sec generation rate
-- **Alphanumeric alphabet (36 chars)**: Achieve ~180K IDs/sec generation rate
-- **Custom alphabet (20 chars)**: Achieve ~150K IDs/sec generation rate
-
-### Quality Metrics
-
-- **Test Coverage**: Achieve 95%+ code coverage
-- **Documentation**: Provide comprehensive README with examples
-- **Error Handling**: All error conditions properly tested and documented
-
-### Adoption Metrics
-
-- **Gem Downloads**: Target 1000+ downloads in first month
-- **GitHub Stars**: Target 50+ stars within 6 months
-- **Community Feedback**: Positive reception from Rails community
-
-## Open Questions
-
-1. **Version Strategy**: Should we follow semantic versioning strictly, or use a different versioning strategy for a utility gem?
-
-2. **Backward Compatibility**: How should we handle potential breaking changes in future versions, especially regarding default configurations?
-
-3. **Performance Testing**: Should we include automated performance regression testing in CI/CD, or rely on manual benchmarking?
-
-4. **Documentation Hosting**: Should we create a dedicated documentation site, or rely on GitHub README and inline documentation?
-
-5. **Community Contributions**: What level of community contribution should we expect, and how should we structure the project to encourage contributions?
-
-6. **Integration Testing**: Should we test against multiple Rails versions in CI, or focus on the target Rails 8.0+ range?
-
-7. **Security Auditing**: Should we implement any security auditing tools or processes for the random number generation?
-
-8. **Migration Path**: How should we help users migrate from nanoid.rb to opaque_id, if at all?