badged_ids 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d4e44d20b4fe1ff726d0311f0d9d528d4622c8fa1e0bdd4397bdaf217b43a94
+  data.tar.gz: b53e26dad7bb2cd5e822c7df83ea837e6cc2ce28368fefb66160ac395d3bf291
+SHA512:
+  metadata.gz: e2c1b8beca316c503319691e34cdbb60f1751ed2eec83eefe552b26c9a317cfe9c4ad60cb94a8d45d5d966df34ef4966e9316236b6f149d9e5ad780db93d83cb
+  data.tar.gz: 5b56ff1d8efb74cb2cdc9e132a0eb36be059553fa3d5410bfd0a80893d4c4f1f63e7def719ea4382a0657db6fdee6f26b860cfc32c98f1b11384bf7c62104443

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Fabian Schwarz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# Badged IDs
+
+### Descriptive and Secure IDs for your Rails Models
+[![Build Status](https://github.com/fabian12943/badged_ids/workflows/CI/badge.svg)](https://github.com/fabian12943/badged_ids/actions)
+
+Badged IDs makes it simple to create descriptive and secure identifiers for your Rails
+models.
+
+By combining a badge with a randomly generated string, it helps you to prevent
+[vulnerabilities associated with sequential IDs]() while keeping your IDs relatively short (e.g. compared to
+[UUIDs](https://developer.mozilla.org/en-US/docs/Glossary/UUID)). Additionally,
+it allows you to clearly identify the type of record, even when the ID is seen out of context,
+enhancing both readability and traceability. 
+
+#### Example:
+
+```ruby
+Order.create(/* ... */).id
+# => "ord_24t6pjz7wpecix5"
+
+Order.find("ord_24t6pjz7wpecix5")
+# => #<Order id: "ord_24t6pjz7wpecix5", ...>
+
+BadgedIds.find("ord_24t6pjz7wpecix5")
+# => #<Order id: "ord_24t6pjz7wpecix5", ...>
+```
+
+The ID generation is highly configurable, enabling you to customize the badge, delimiter, length,
+character set, and much more to suit your application’s needs.
+
+Inspired by [Stripe's prefixed IDs](https://stripe.com/docs/api) and [Chris Oliver's prefixed_ids
+gem](https://github.com/excid3/prefixed_ids).
+
+## Installation
+
+1. Add the following line to your app's `Gemfile`:
+
+    ```ruby
+    gem 'badged_ids'
+    ```
+2. Run the following command to install it:
+
+    ```bash
+    $ bundle install
+    ```
+
+## Usage
+
+### Prerequisites
+
+Ensure that the primary key of your model (typically `id`), or the field where you intend to store 
+the badged ID, is of type string.
+
+To set the primary key for a new table to a string, you can use the following migration:
+
+```ruby
+create_table :orders, id: :string do |t|
+  # Add your columns here
+end
+```
+
+If you like the generator to use string primary keys by default, add this to your `config/application.rb`:
+
+```ruby
+# config/application.rb
+config.generators do |g|
+  g.orm :active_record, primary_key_type: :string
+end
+```
+
+### Basic Usage
+
+To enable Badged IDs for your model, simplfy include the `has_badged_id` method and specify a badge
+for your model. The badge is a short prefix that helps you to quickly identify the type of a record.
+
+That's it! Now, whenever you create a new record, a unique Badged ID is automatically generated and
+assigned to the primary key column of the record.
+
+```ruby
+class Order < ApplicationRecord
+  has_badged_id :ord
+end
+
+Order.create(/* ... */).id
+# => "ord_24t6pjz7wpecix5"
+```
+
+> [!NOTE]
+> This basic setup uses the default configuration settings, but you can customize them
+> *globally* or *per-model* to better suit your application's needs. For more information on configuring
+> Badged IDs, refer to the [Configuration](#configuration) section.
+
+### Find any record by Badged ID
+
+You can easily find any record by its Badged ID using `BadgedIds.find`. Just provide the full badged ID (including the badge) to retrieve the corresponding record.
+
+```ruby
+BadgedIds.find("ord_24t6pjz7wpecix5")
+# => #<Order id: "ord_24t6pjz7wpecix5", ...>
+
+BadgedIds.find("usr_y0m4ud4iy94sq2y")
+# => #<User id: "usr_y0m4ud4iy94sq2y", ...>
+```
+
+### Manually generate Badged IDs for a model
+
+If you need to generate Badged IDs manually—such as when performing batch inserts or processing
+records in bulk—you can use the `generate_badged_id` method.
+
+```ruby
+Order.generate_badged_id
+# => "ord_24t6pjz7wpecix5"
+```
+
+## Configuration
+
+### Global Configuration
+
+Various configuration options are available to adjust the behavior to your application's needs. 
+You can define global settings by creating or modifying the `config/initializers/badged_ids.rb` file 
+in your Rails application.
+
+#### Example
+
+```ruby
+# config/initializers/badged_ids.rb
+BadgedIds.configure do |config|
+  config.alphabet = "abc123"
+  config.delimiter = "-"
+  config.minimum_length = 20
+  config.max_generation_attempts = 3
+  config.skip_uniqueness_check = false
+  config.implicit_order_column = :created_at
+end 
+```
+
+#### Available Configuration Options
+
+The table below details all available configuration options and their default values:
+
+| Config                   | Description                                                                   | Default                                  |
+| ------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------- |
+| alphabet                 | Characters used to generate the random part of the ID.                        | `"abcdefghijklmnopqrstuvwxyz0123456789"` |
+| delimiter                | String separating the badge from the random string in the ID.                 | `"_"`                                    |
+| minimum_length           | Length of the random part of the ID, excluding the badge and delimiter.       | `15`                                     |
+| max_generation_attempts¹ | Maximum attempts to generate a unique ID before raising an error.             | `1`                                      |
+| skip_uniqueness_check²   | Skip uniqueness check and retry mechanism when generating a new ID.           | `false`                                  |
+| implicit_order_column    | Default column used for ordering records of model, if not explicitly defined. | `nil`                                    |
+
+¹ It is recommended to leave this value as-is. If you encounter collisions, it's likely that the
+`minimum_length` is too short and/or the `alphabet` contains too few unique characters. 
+When configured properly, the chances of a collision are virtually zero. 
+If you're uncertain, it's best to stick with the default values.
+
+² You can skip the uniqueness check if you're confident that the combination of `minimum_length` 
+and `alphabet` ensures that collisions are virtually impossible. This improves performance when creating thousands 
+of records at once (see [Benchmarks](#benchmarks)).
+
+### Model Overrides
+
+When defining a model with `has_badged_id`, you can override specific settings for that model. These
+options allow you to fine-tune the ID generation without affecting the global configuration.
+
+#### Example
+
+```ruby
+class Order < ApplicationRecord
+  has_badged_id :ord, id_field: :public_id, alphabet: "ABCDEF0123456789", minimum_length: 20
+end
+
+Order.create(/* ... */).public_id
+# => "ord_E19D5E5ADB476416C1F6"
+```
+
+#### Available Model Overrides
+
+The table below details all available options that can be overridden on a per-model basis and their default values:
+
+| Option                  | Description                                                               |  Default                             |
+| ----------------------- | ----------------------------------------------------------------------------- | ---------------------------------- |
+| id_field                | Database field used for storing the ID. Must be of type `string`.             | `model.primary_key` (usually `id`) |
+| alphabet                | Characters used to generate the random part of the ID.                        | `config.alphabet`                  |
+| minimum_length          | Length of the random part of the ID, excluding the badge and delimiter.       | `config.minimum_length`            |
+| max_generation_attempts | Maximum attempts to generate a unique ID before raising an error.             | `config.max_generation_attempts`   |
+| skip_uniqueness_check   | Skip uniqueness check and retry mechanism when generating a new ID.           | `config.skip_uniqueness_check`     |
+| implicit_order_column   | Default column used for ordering records of model, if not explicitly defined. | `config.implicit_order_column`     |
+
+### Configuration Validation
+
+Both global and model-specific configurations are validated at two critical points: during 
+application startup and immediately before generating a new ID. If any configuration is invalid, 
+an error is raised with a detailed message on how to resolve the issue.
+
+## Benchmarks
+
+The following benchmarks compare the performance of Badged IDs with other common ID generation
+methods when creating 20,000 simple records on my local machine.
+
+|                                               | user      | system   | total     | real      |
+| --------------------------------------------- | --------- | -------- | --------- | --------- |
+| Sequential integer id                         | 15.266384 | 1.211182 | 16.477566 | 21.128873 |
+| UUIDv4                                        | 15.324471 | 1.315743 | 16.640214 | 21.262059 |
+| Badged ID<br>(`skip_uniqueness_check: true`)  | 15.898291 | 1.245899 | 17.144190 | 21.599303 |
+| Badged ID<br>(`skip_uniqueness_check: false`) | 22.520556 | 1.696816 | 24.217372 | 30.400110 |
+
+### Conclusion
+
+When using Badged IDs with `skip_uniqueness_check: true`, the performance is slightly slower than 
+that of sequential integer IDs or UUIDs, but the difference is minimal. This configuration is ideal
+when the `alphabet` and `minimum_length` ensure that collisions are virtually impossible.
+
+When using Badged IDs with `skip_uniqueness_check: false`, the performance is notably slower
+than that of sequential integer IDs or UUIDs. This configuration is only recommended when the risk 
+of collision is a realistic concern due to a short `alphabet` and/or `minimum_length` that, for 
+whatever reason, cannot be adjusted. In such cases, verifying the uniqueness of the generated ID 
+before saving and retrying in the event of a collision becomes necessary.
+
+For most use cases, especially when not creating thousands of records at once,
+the performance impact is negligible, regardless of the `skip_uniqueness_check` config.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/lib/badged_ids/badged_id.rb

@@ -0,0 +1,44 @@
+module BadgedIds
+  class BadgedId
+    attr_reader :badge, :id_field, :config
+
+    def initialize(model, badge, options = {})
+      @badge = badge.to_s
+      @id_field = options.fetch(:id_field, model.primary_key).to_s
+      @config = build_config(options)
+    end
+
+    def generate_id
+      validate!
+      "#{badge}#{config.delimiter}#{generate_random_part}"
+    end
+
+    def validate!
+      config.validate!
+      validate_badge_delimiter_combination
+      true
+    end
+
+    private
+
+    def build_config(options)
+      BadgedIds.config.dup.tap do |config|
+        options.slice(*Configuration::OVERRIDABLE_CONFIGS_PER_MODEL).each do |key, value|
+          config.public_send("#{key}=", value)
+        end
+      end
+    end
+
+    def generate_random_part
+      SecureRandom.alphanumeric(config.minimum_length, chars: config.alphabet.chars)
+    end
+
+    def validate_badge_delimiter_combination
+      overlapping_chars = badge.chars & config.delimiter.chars
+      return if overlapping_chars.empty?
+
+      formatted_chars = overlapping_chars.map { |char| "`#{char}`" }.join(", ")
+      raise ConfigError, "Badge and delimiter cannot share characters: #{formatted_chars}."
+    end
+  end
+end

data/lib/badged_ids/configuration.rb

@@ -0,0 +1,66 @@
+module BadgedIds
+  class Configuration
+    CONFIG_DEFAULTS = {
+      delimiter: "_",
+      alphabet: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+      minimum_length: 24,
+      implicit_order_column: nil,
+      max_generation_attempts: 1,
+      skip_uniqueness_check: false
+    }.freeze
+
+    OVERRIDABLE_CONFIGS_PER_MODEL = CONFIG_DEFAULTS.keys - %i[delimiter]
+
+    attr_accessor(*CONFIG_DEFAULTS.keys)
+
+    def initialize
+      CONFIG_DEFAULTS.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    def validate!
+      %i[
+        validate_delimiter
+        validate_alphabet
+        validate_alphabet_delimiter_combination
+        validate_minimum_length
+        validate_max_generation_attempts
+      ].each { |method| send(method) }
+      true
+    end
+
+    def to_h
+      CONFIG_DEFAULTS.keys.each_with_object({}) { |key, hash| hash[key] = public_send(key) }
+    end
+
+    def reset_to_defaults!
+      CONFIG_DEFAULTS.each { |key, value| public_send("#{key}=", value) }
+    end
+
+    private
+
+    def validate_delimiter
+      raise ConfigError, "Delimiter cannot be blank." if delimiter.to_s.strip.empty?
+    end
+
+    def validate_alphabet
+      raise ConfigError, "Alphabet cannot be blank." if alphabet.to_s.strip.empty?
+      raise ConfigError, "Alphabet must contain at least two unique characters." if alphabet.chars.uniq.size < 2
+    end
+
+    def validate_alphabet_delimiter_combination
+      overlapping_chars = delimiter.chars & alphabet.chars
+      return if overlapping_chars.empty?
+
+      formatted_chars = overlapping_chars.map { |char| "`#{char}`" }.join(", ")
+      raise ConfigError, "Alphabet and delimiter cannot share characters: #{formatted_chars}."
+    end
+
+    def validate_minimum_length
+      raise ConfigError, "Minimum length must be greater than 0." if minimum_length < 1
+    end
+
+    def validate_max_generation_attempts
+      raise ConfigError, "Max generation attempts must be greater than 0." if max_generation_attempts < 1
+    end
+  end
+end

data/lib/badged_ids/errors.rb

@@ -0,0 +1,5 @@
+module BadgedIds
+  class Error < StandardError; end
+  class RegistryError < Error; end
+  class ConfigError < Error; end
+end

data/lib/badged_ids/rails.rb

@@ -0,0 +1,47 @@
+require "badged_ids/badged_id"
+
+module BadgedIds
+  module Rails
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_badged_id
+    end
+
+    class_methods do
+      def has_badged_id(badge, **options)
+        self._badged_id = BadgedId.new(self, badge, **options)
+        Registry.register(badge, self)
+
+        before_create { self[_badged_id.id_field] ||= self.class.generate_badged_id }
+
+        if _badged_id.config.implicit_order_column.present? && implicit_order_column.nil?
+          self.implicit_order_column = _badged_id.config.implicit_order_column
+        end
+
+        define_singleton_method(:generate_badged_id) do
+          return _badged_id.generate_id if _badged_id.config.skip_uniqueness_check
+
+          generated_ids = Set.new
+          attempts = 0
+
+          loop do
+            generated_id = _badged_id.generate_id
+
+            unless generated_ids.include?(generated_id)
+              generated_ids.add(generated_id)
+              return generated_id unless exists?(id: generated_id)
+            end
+
+            if (attempts += 1) >= _badged_id.config.max_generation_attempts
+              raise Error, <<~MESSAGE.squish
+                Failed to generate a unique badged ID within #{_badged_id.config.max_generation_attempts} attempts.
+                Consider increasing the minimum length or the unique characters in the alphabet.
+              MESSAGE
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badged_ids/railtie.rb

@@ -0,0 +1,9 @@
+module BadgedIds
+  class Railtie < ::Rails::Railtie
+    initializer "badged_ids.extend_active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include BadgedIds::Rails
+      end
+    end
+  end
+end

data/lib/badged_ids/registry.rb

@@ -0,0 +1,29 @@
+module BadgedIds
+  class Registry
+    mattr_accessor :models, default: {}
+
+    class << self
+      def register(badge, model)
+        badge = badge.to_s
+        if models.key?(badge) && models[badge] != model
+          raise RegistryError, "Badge `#{badge}` is already assigned to `#{models[badge]}`."
+        end
+
+        models[badge] = model
+      end
+
+      def find_model(badge)
+        models.fetch(badge.to_s) do
+          raise RegistryError, <<~MESSAGE.squish
+            No model with the badge `#{badge}` registered.
+            Available badges are: #{registered_badges.join(", ")}.
+          MESSAGE
+        end
+      end
+
+      def registered_badges
+        models.keys
+      end
+    end
+  end
+end

data/lib/badged_ids/version.rb

@@ -0,0 +1,3 @@
+module BadgedIds
+  VERSION = "1.0.0"
+end

data/lib/badged_ids.rb

@@ -0,0 +1,33 @@
+require "badged_ids/version"
+require "badged_ids/railtie"
+require "badged_ids/errors"
+require "badged_ids/registry"
+require "badged_ids/rails"
+require "badged_ids/configuration"
+
+module BadgedIds
+  @config = Configuration.new
+
+  class << self
+    def config
+      if block_given?
+        yield @config
+        @config.validate!
+      else
+        @config
+      end
+    end
+
+    def find(badged_id)
+      badge, _id = split_id(badged_id)
+      Registry.find_model(badge).find(badged_id)
+    end
+
+    private
+
+    def split_id(badged_id, delimiter = config.delimiter)
+      badge, _, id = badged_id.to_s.rpartition(delimiter)
+      [ badge, id ]
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: badged_ids
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Fabian Schwarz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description: Badged-IDs generates and persists unguessable IDs with friendly prefixes
+  for your models
+email:
+- fabian12943@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/badged_ids.rb
+- lib/badged_ids/badged_id.rb
+- lib/badged_ids/configuration.rb
+- lib/badged_ids/errors.rb
+- lib/badged_ids/rails.rb
+- lib/badged_ids/railtie.rb
+- lib/badged_ids/registry.rb
+- lib/badged_ids/version.rb
+homepage: https://github.com/fabian12943/badged_ids
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fabian12943/badged_ids
+  source_code_uri: https://github.com/fabian12943/badged_ids
+  changelog_uri: https://github.com/fabian12943/badged_ids/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Badged-IDs generates and persists unguessable IDs with friendly prefixes
+  for your models
+test_files: []