based_uuid 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea972425316d18c771fce81d203b5a5b9131542e5477ccc3ffa3efea68b3cf00
+  data.tar.gz: adef7fd3cd72c47a47db279c726cf85100f8e05da7e138513d3fa96d35901bca
+SHA512:
+  metadata.gz: 5821c706b57958282dd0abb1e516cd2338b5df1dfce9f9032127f881c72bcf42c7eaed0fb2ffb420cfd2fba56f270f6ead84c0d07c13b6b11dbdf3c18e7d0f24
+  data.tar.gz: 5319f5038db91a4ab6286a126f5aeb003c0e0c204bc479cac76e2356a80997110b5b699567e50d8f57f66e34b225eaa2140644f868e7a4bae70fe83635f694d0

data/.rubocop.yml

@@ -0,0 +1,25 @@
+AllCops:
+  TargetRubyVersion: 3.2
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+Naming/PredicateName:
+  Enabled: false

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) Piotr Chmolowski
+
+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,92 @@
+# BasedUUID: double-clickable, URL-friendly UUIDs for your Rails models
+
+[![Build Status](https://github.com/pch/based_uuid/workflows/Tests/badge.svg)](https://github.com/pch/based_uuid/actions) [![Gem Version](https://badge.fury.io/rb/based_uuid.svg)](https://badge.fury.io/rb/based_uuid)
+
+
+Generate “double-clickable”, URL-friendly UUIDs with (optional) prefixes:
+
+```
+user_4yoiald3wfbvpeu2sbsk7cssdi
+acc_ejwqg7b3gvaphiylb25xq545tm
+```
+
+This gem works by encoding UUIDs into 26-character lowercase strings using [Crockford’s base32](https://www.crockford.com/base32.html) encoding. The optional prefix helps you identify the model it represents.
+
+BasedUUID doesn’t affect how your ActiveRecord primary key UUIDs are stored in the database. Prefix and base32 encoding are only used for presentation.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem "based_uuid"
+```
+
+## Usage
+
+BasedUUID assumes that you have a [UUID primary key](https://guides.rubyonrails.org/v5.0/active_record_postgresql.html#uuid) in your ActiveRecord model.
+
+```ruby
+class BlogPost < ApplicationRecord
+  has_based_uuid prefix: :bpo
+end
+
+post = BlogPost.last
+post.based_uuid #=> bpo_3ah4veflijgy7de6bflk7k4ld4
+post.based_uuid(prefix: false) #=> 3ah4veflijgy7de6bflk7k4ld4
+```
+
+### Lookup
+
+BasedUUID includes a `find_by_based_uuid` model method to look up records:
+
+```ruby
+BlogPost.find_by_based_uuid("bpo_3ah4veflijgy7de6bflk7k4ld4")
+
+# or without the prefix:
+BlogPost.find_by_based_uuid("3ah4veflijgy7de6bflk7k4ld4")
+
+# there’s also the bang version:
+BlogPost.find_by_based_uuid!("3ah4veflijgy7de6bflk7k4ld4")
+```
+
+### Generic lookup
+
+The gem provides a generic lookup method to help you find the correct model for the UUID, based on prefix:
+
+```ruby
+BasedUUID.find("bpo_3ah4veflijgy7de6bflk7k4ld4")
+#=> #<BlogPost>
+BasedUUID.find("acc_ejwqg7b3gvaphiylb25xq545tm")
+#=> #<Account>
+```
+
+**⚠️ NOTE:** Rails lazy-loads models in the development environment, so this method won’t know about your models until you’ve referenced them at least once. If you’re using this method in a Rails console, you’ll need to run `BlogPost` (or any other model) before you can use it.
+
+### BasedUUID as default URL identifiers
+
+BasedUUID aims to be unintrusive and it doesn’t affect how Rails URLs are generated, so if you want to use it as default URL param, add this to your model:
+
+```ruby
+def to_param
+  based_uuid
+end
+```
+
+* * *
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pch/based_uuid.
+
+### Credits
+
+This gem is heavily inspired by [Stripe IDs](https://stripe.com/docs/api) and the [prefixed_ids](https://github.com/excid3/prefixed_ids/tree/master) gem by Chris Oliver.
+
+Parts of the base32 encoding code are borrowed from the [ulid gem](https://github.com/rafaelsales/ulid) by Rafael Sales.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/based_uuid/base32_uuid.rb

@@ -0,0 +1,48 @@
+module BasedUUID
+  module Base32UUID
+    CROCKFORDS_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz".freeze
+    CHARACTER_MAP = CROCKFORDS_ALPHABET.bytes.freeze
+
+    ENCODED_LENGTH = 26
+    BITS_PER_CHAR = 5
+    ZERO = "0".ord
+    MASK = 0x1f
+    UUID_LENGTH = 32
+
+    UUID_VALIDATION_REGEXP = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/
+    UUID_REGEXP = /\A(.{8})(.{4})(.{4})(.{4})(.{12})\z/
+    BASE32_VALIDATION_REGEXP = /\A[#{CROCKFORDS_ALPHABET}]{26}\z/
+
+    class << self
+      def encode(uuid)
+        raise ArgumentError, "Invalid UUID" if uuid !~ UUID_VALIDATION_REGEXP
+
+        input = uuid.delete("-").to_i(16)
+        encoded = Array.new(ENCODED_LENGTH, ZERO)
+        i = ENCODED_LENGTH - 1
+
+        while input > 0
+          encoded[i] = CHARACTER_MAP[input & MASK]
+          input >>= BITS_PER_CHAR
+          i -= 1
+        end
+
+        encoded.pack("c*")
+      end
+
+      def decode(str)
+        raise ArgumentError, "Invalid base32 string" if str !~ BASE32_VALIDATION_REGEXP
+
+        decoded = 0
+
+        str.each_byte do |byte|
+          value = CHARACTER_MAP.index(byte)
+          decoded = (decoded << BITS_PER_CHAR) | value
+        end
+
+        uuid = decoded.to_s(16)
+        uuid.rjust(UUID_LENGTH, "0").scan(UUID_REGEXP).join("-")
+      end
+    end
+  end
+end

data/lib/based_uuid/has_based_uuid.rb

@@ -0,0 +1,57 @@
+require "active_support/lazy_load_hooks"
+require "active_support/concern"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/class/attribute"
+require "active_record"
+
+module BasedUUID
+  module HasBasedUUID
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_based_uuid_prefix
+    end
+
+    class_methods do
+      def has_based_uuid(prefix: nil)
+        include ModelExtensions
+
+        self._based_uuid_prefix = prefix
+        BasedUUID.register_model_prefix(prefix, self) if prefix
+      end
+    end
+  end
+
+  module ModelExtensions
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def find_by_based_uuid(token)
+        prefix, uuid_base32 = BasedUUID.split(token)
+        raise ArgumentError, "Invalid prefix" if prefix && prefix.to_sym != _based_uuid_prefix
+
+        find_by(primary_key => Base32UUID.decode(uuid_base32))
+      end
+
+      def find_by_based_uuid!(token)
+        find_by_based_uuid(token) or raise ActiveRecord::RecordNotFound
+      end
+    end
+
+    def based_uuid(prefix: true)
+      raise ArgumentError, "UUID is empty" if _primary_key_value.blank?
+
+      BasedUUID.based_uuid(uuid: _primary_key_value, prefix: prefix ? self.class._based_uuid_prefix : nil)
+    end
+
+    private
+
+    def _primary_key_value
+      self[self.class.primary_key]
+    end
+  end
+end
+
+ActiveSupport.on_load :active_record do
+  include BasedUUID::HasBasedUUID
+end

data/lib/based_uuid/version.rb

@@ -0,0 +1,3 @@
+module BasedUUID
+  VERSION = "0.5.0".freeze
+end

data/lib/based_uuid.rb

@@ -0,0 +1,40 @@
+require "active_support/core_ext/module/attribute_accessors"
+
+require_relative "based_uuid/version"
+require_relative "based_uuid/base32_uuid"
+require_relative "based_uuid/has_based_uuid"
+
+module BasedUUID
+  class Error < StandardError; end
+
+  mattr_accessor :delimiter, default: "_"
+
+  class << self
+    def find(token)
+      prefix, = split(token)
+      registered_models.fetch(prefix.to_sym).find_by_based_uuid(token)
+    rescue KeyError
+      raise Error, "Unable to find model for `#{prefix}`. Registered prefixes: #{registered_models.keys.join(", ")}"
+    end
+
+    def register_model_prefix(prefix, model)
+      registered_models[prefix] = model
+    end
+
+    def registered_models
+      @registered_models ||= {}
+    end
+
+    def split(token)
+      prefix, _, uuid_base32 = token.to_s.rpartition(delimiter)
+      [prefix.presence, uuid_base32]
+    end
+
+    def based_uuid(uuid:, prefix:)
+      uuid_base32 = Base32UUID.encode(uuid)
+      return uuid_base32 unless prefix
+
+      "#{prefix}#{delimiter}#{uuid_base32}"
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: based_uuid
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Piotr Chmolowski
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-12-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description:
+email:
+- piotr@chmolowski.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/based_uuid.rb
+- lib/based_uuid/base32_uuid.rb
+- lib/based_uuid/has_based_uuid.rb
+- lib/based_uuid/version.rb
+homepage: https://github.com/pchm/based_uuid
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: URL-friendly, Base32-encoded UUIDs for Rails models
+test_files: []