rails-clusterid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6dbfb92bb8859432533b75b073f0503ed9d295fa57ed63f6bd61d5ffa16b3cd9
+  data.tar.gz: e12b51e557e301536cecfae29299212b57de2ef9dd87b935907426e4f3e7446b
+SHA512:
+  metadata.gz: ae5314e6cec2279525198c1296d4c989ef3a8897a15e767da8653706b6039173dd2ce1544883431c2dccf3e0b317ff2e02580e418476cfdb4e36f16e48cdaba3
+  data.tar.gz: cca1e0a4c03ef8a969027ea4e41596836b2be77812e58506ba23c55664e86989fb49d40d7dbe79a11752212c553be6a635843c16f4fde5374bd3fdd18cb4f654

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## v0.1.0 - 2022-03-24
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Stephan Tarulli
+
+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,154 @@
+# Rails ClusterId
+A Ruby on Rails plugin for using [ClusterId](https://github.com/tinychameleon/clusterid) values as primary keys.
+
+[![Gem Version](https://badge.fury.io/rb/rails-clusterid.svg)](https://badge.fury.io/rb/rails-clusterid)
+
+## What's in the box?
+✅ Simple usage documentation written to get started fast. [Check it out!](#usage)
+
+⚡ A pretty fast implementation of Crockford32 in pure ruby. [Check it out!](#benchmarks)
+
+📚 YARD generated API documentation for the library. [Check it out!](https://tinychameleon.github.io/rails-clusterid/)
+
+🤖 RBS types for your type checking wants. [Check it out!](./sig/rails-clusterid.rbs)
+
+💎 Tests against many Ruby versions. [Check it out!](#ruby-versions)
+
+🔒 MFA protection on all gem owners. [Check it out!](https://rubygems.org/gems/rails-clusterid)
+
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-clusterid'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rails-clusterid
+
+### Compatibility
+#### Ruby Versions
+This gem is tested against the following Ruby versions:
+
+- 2.7.5
+- 3.0.3
+- 3.1.1
+
+#### Rails Versions
+This gem is tested against the following Ruby on Rails versions:
+
+- 7.0.x
+
+## Usage
+To use `ClusterId` values for all model primary keys automatically create a new initializer for your application.
+
+```ruby
+# config/initializers/clusterid.rb
+
+Rails.application.config.clusterid do |c|
+  c.add_generator(:default, ClusterId::V1::Generator.new)
+end
+
+Rails.application.config.generators do |g|
+  g.orm :active_record, primary_key_type: :clusterid
+end
+```
+
+The above configures the `rails-clusterid` plugin to use version 1 `ClusterId` values by default and configures ActiveRecord to use ClusterId values for primary keys.
+You must add a `:default` generator, and the generator itself is configurable.
+See the [ClusterId repository for information on how to configure a generator](https://github.com/tinychameleon/clusterid).
+
+Once the initializers are complete, include the `ClusterId::Rails::Model` concern into your `ApplicationRecord`.
+
+```ruby
+# app/models/application_record.rb
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  include ClusterId::Rails::Model
+end
+```
+
+Migrations are supported and will automatically use ClusterId values as primary keys and foreign keys.
+This includes join tables.
+
+### Manual Usage 
+If you would like to selectively use `ClusterId` values across your models and migrations, just manually select the `:clusterid` type.
+
+```
+$ rails g model person name:string --primary-key-type=clusterid
+```
+
+You can use it within migration files as well.
+
+```ruby
+create_table :people, id: :clusterid do |t|
+  t.string :name
+end
+```
+
+Since the type works with ActiveRecord you can also specify it as a foreign key.
+
+```ruby
+create_table :hobbies, id: :clusterid do |t|
+  t.string :name
+
+  t.references :person, null: false, foreign_key: true, type: :clusterid
+end
+```
+
+### ClusterId Ordering
+The ClusterId values are k-sortable and will be ordered by creation time before any other part of the ID.
+If you would like to read values from the ClusterId binary data stored within the database, you can deconstruct the raw data using a function.
+
+For example, to extract the timestamp data while using PostgreSQL:
+```sql
+to_timestamp(('x' || encode(substring(id for 8), 'hex'))::bit(64)::bigint / 1000.0)
+```
+
+See the [ClusterId repository for documentation about the binary representation](https://github.com/tinychameleon/clusterid).
+
+### More Information
+For more detailed information about the library [see the API documentation](https://tinychameleon.github.io/rails-clusterid/).
+
+
+## Contributing
+
+### Development
+This plugin relies heavily on Docker for development; ensure it is running to use most development commands.
+
+To get started development on this gem run the `bin/setup` command. This will build the testing Docker image and run the tests and linting commands to ensure everything is working properly.
+
+### Testing
+Use the `bundle exec rake test` command to run unit tests. To install the gem onto your local machine for general integration testing use `bundle exec rake install`.
+
+To test the gem against each supported version of Ruby and databases use `bin/test_versions`. This will create a Docker image for each version and run the tests and linting steps.
+
+### Releasing
+Do the following to release a new version of this gem:
+
+- Update the version number in [lib/rails-clusterid/version.rb](./lib/rails-clusterid/version.rb)
+- Ensure necessary documentation changes are complete
+- Ensure changes are in the [CHANGELOG.md](./CHANGELOG.md)
+- Create the new release using `bundle exec rake release`
+
+After this is done the following side-effects should be visible:
+
+- A new git tag for the version number should exist
+- Commits for the new version should be pushed to GitHub
+- The new gem should be available on [rubygems.org](https://rubygems.org).
+
+Finally, update the documentation hosted on GitHub Pages:
+
+- Check-out the `gh-pages` branch
+- Merge `main` into the `gh-pages` branch
+- Generate the documentation with `bundle exec rake yard`
+- Commit the documentation on the `gh-pages` branch
+- Push the new documentation so GitHub Pages can deploy it

data/lib/rails-clusterid/active_record/schema_statements.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ClusterId::Rails
+  # Contains method overrides for database migrations.
+  module SchemaStatements
+    # Overrides the default +create_join_table+ to provide support for ClusterId primary keys
+    # as foreign keys within join tables.
+    def create_join_table(table_1, table_2, column_options: {}, **options)
+      if ::ClusterId::Rails.clusterid_primary_keys?
+        column_options.reverse_merge!(type: ::ClusterId::Rails::DATA_TYPE, foreign_key: true)
+      end
+
+      super(table_1, table_2, column_options: column_options, **options)
+    end
+  end
+end

data/lib/rails-clusterid/application_config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ClusterId::Rails
+  # An +ActiveSupport::Concern+ which provides a method to access a {Config} object
+  # through +Rails::Configuration+.
+  module ApplicationConfiguration
+    extend ActiveSupport::Concern
+
+    included do
+      def clusterid
+        @rails_clusterid_config ||= ::ClusterId::Rails::Config.new
+        yield @rails_clusterid_config if block_given?
+        @rails_clusterid_config
+      end
+    end
+  end
+end

data/lib/rails-clusterid/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ClusterId::Rails
+  # The configuration object added to the Rails configuration registry.
+  class Config
+    # Add a generator with a name to use within models.
+    #
+    # @param name [Symbol] The name to associate with the provided generator.
+    # @param generator [ClusterId::V1::Generator] A generator to use with models.
+    #
+    # @raise [NotAGeneratorError] when +generator+ is not one of the allowed {GENERATOR_TYPES}.
+    # @return [ClusterId::V1::Generator] The added generator.
+    def add_generator(name, generator)
+      raise NotAGeneratorError, "#{generator} is not a generator" unless GENERATOR_TYPES.include?(generator.class)
+
+      @generators[name] = generator
+    end
+
+    # Get a generator by registered name.
+    #
+    # @param name [Symbol] The registered name of a generator.
+    #
+    # @raise [KeyError] when the given +name+ was not registered via {add_generator}.
+    # @return [ClusterId::V1::Generator] The registered generator with the given name.
+    def generator(name)
+      @generators.fetch(name)
+    end
+
+    def initialize
+      @generators = {}
+    end
+
+    private
+
+    # Allowed ClusterId generator types.
+    GENERATOR_TYPES = [
+      ClusterId::V1::Generator
+    ].freeze
+  end
+end

data/lib/rails-clusterid/model.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "crockford32"
+
+module ClusterId::Rails
+  # An +ActiveSupport::Concern+ allowing automatic ClusterId primary keys for ActiveRecord models.
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      attribute :id, DATA_TYPE
+
+      before_create :assign_clusterid_to_id
+
+      def friendly_id
+        Crockford32.encode(id, length: CROCKFORD32_LENGTH)
+      end
+
+      def to_param
+        friendly_id
+      end
+
+      private
+
+      def clusterid_generator
+        ::ClusterId::Rails::DEFAULT_GENERATOR_NAME
+      end
+
+      def assign_clusterid_to_id
+        g = Rails.application.config.clusterid.generator(clusterid_generator)
+        self.id = g.generate.bytes.reverse
+      end
+    end
+  end
+end

data/lib/rails-clusterid/railtie.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ClusterId::Rails
+  # A +Rails::Railtie+ containing initialization logic for the plugin.
+  class Railtie < ::Rails::Railtie
+    initializer "rails_clusterid.column_methods" do
+      ::ActiveRecord::ConnectionAdapters::TableDefinition.send(:define_column_methods, DATA_TYPE)
+    end
+
+    initializer "rails_clusterid.native_data_types" do
+      adapter = ::ActiveRecord::Type.adapter_name_from(::ActiveRecord::Base)
+      ::ActiveRecord::Base.connection.native_database_types[DATA_TYPE] = native_type(adapter)
+    end
+
+    initializer "rails_clusterid.activerecord_type" do
+      ::ActiveRecord::Type.register(DATA_TYPE, ::ClusterId::Rails::Type, override: false)
+    end
+
+    initializer "rails_clusterid.activerecord_schema_statements" do
+      ::ActiveRecord::ConnectionAdapters::SchemaStatements.prepend(::ClusterId::Rails::SchemaStatements)
+    end
+
+    initializer "rails_clusterid.configuration" do
+      ::Rails::Application::Configuration.include(ApplicationConfiguration)
+    end
+
+    private
+
+    # Converts a database adapter to a hash representing the ClusterId native database type
+    # for ActiveRecord to query.
+    #
+    # @param adapter [Symbol] A symbol representing a database adapter.
+    # @return [Hash] A hash representing the ClusterId native database type.
+    def native_type(adapter)
+      case adapter
+      when :postgresql then {name: "bytea"}
+      when :mysql2 then {name: "binary", limit: BYTE_LENGTH}
+      when :sqlite3 then {name: "blob"}
+      end
+    end
+  end
+end

data/lib/rails-clusterid/type.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "clusterid"
+
+module ClusterId::Rails
+  # The ActiveRecord-compatible type representing a ClusterId value optionally
+  # encoded using the Crockford32 algorithm.
+  class Type < ::ActiveRecord::Type::Binary
+    # Deserializes byte string ClusterId values from database reads.
+    #
+    # @param value [String, nil] The value stored in the database, possibly escaped.
+    # @return [String, nil] The unescaped ClusterId byte string.
+    def deserialize(value)
+      return value.to_s if value.is_a?(Data)
+
+      if database_adapter == :postgresql
+        ::ActiveRecord::Base.connection.unescape_bytea(value)
+      else
+        value
+      end
+    end
+
+    # Serializes byte string ClusterId values for database writes.
+    #
+    # @param value [String, nil] A ClusterId value as a byte string or the Crockford32
+    #   encoding of that byte string.
+    # @return [Data, nil] The ClusterId byte string wrapped
+    #   inside a serialization helper class.
+    def serialize(value)
+      return if value.nil?
+
+      bytes = if value.length == CROCKFORD32_LENGTH
+        Crockford32.decode(value, into: :string, length: BYTE_LENGTH)
+      else
+        value
+      end
+
+      Data.new(bytes)
+    end
+
+    # A helper class for serializing byte strings.
+    class Data < ::ActiveRecord::Type::Binary::Data; end
+
+    private
+
+    # Obtains the symbol representing the configured database adapter from
+    # +ActiveRecord::Base+.
+    def database_adapter
+      ::ActiveRecord::Type.adapter_name_from(::ActiveRecord::Base)
+    end
+  end
+end

data/lib/rails-clusterid/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ClusterId
+  module Rails
+    # The version of the gem.
+    VERSION = "0.1.0"
+  end
+end

data/lib/rails-clusterid.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# An extension to the ClusterId[https://rubygems.org/gems/clusterid] gem which integrates
+# it into Ruby on Rails.
+#
+# @since 0.1.0
+module ClusterId
+  # The extension module which contains all Ruby on Rails integrations.
+  module Rails
+    # The data type symbol for use with ActiveRecord and Migrations.
+    DATA_TYPE = :clusterid
+
+    # The symbol representing the default ClusterId generator to use.
+    DEFAULT_GENERATOR_NAME = :default
+
+    # The byte length of a ClusterI value.
+    BYTE_LENGTH = 16
+
+    # The rune length of a ClusterId value when encoded with the Crockford32 algorithm.
+    CROCKFORD32_LENGTH = 26
+
+    # The base error type for {ClusterId::Rails}.
+    class Error < StandardError; end
+
+    # An error representing an invalid generator object is present in configuration.
+    class NotAGeneratorError < Error; end
+
+    # Checks whether ClusterId values are configured as the ActiveRecord primary key type.
+    def self.clusterid_primary_keys?
+      DATA_TYPE == ::Rails.application.config.generators.options.dig(:active_record, :primary_key_type)
+    end
+  end
+end
+
+require "clusterid"
+require "crockford32"
+
+require_relative "rails-clusterid/version"
+require_relative "rails-clusterid/config"
+require_relative "rails-clusterid/application_config"
+require_relative "rails-clusterid/type"
+require_relative "rails-clusterid/model"
+require_relative "rails-clusterid/active_record/schema_statements"
+require_relative "rails-clusterid/railtie"

data/sig/rails-clusterid.rbs

@@ -0,0 +1,45 @@
+module ClusterId
+  module Rails
+    DATA_TYPE: Symbol
+    DEFAULT_GENERATOR_NAME: Symbol
+    BYTE_LENGTH: Integer
+    CROCKFORD32_LENGTH: Integer
+    VERSION: String
+
+    def self.clusterid_primary_keys?: () -> bool
+
+    class Config
+      GENERATOR_TYPES: Array[Class]
+
+      def add_generator: (Symbol, untyped) -> untyped
+      def generator: (Symbol) -> untyped
+    end
+
+    class Railtie
+    end
+
+    class Type
+      class Data
+      end
+
+      def deserialize: ((Data | String)?) -> String?
+      def serialize: (String?) -> Data?
+    end
+
+    module ApplicationConfiguration
+    end
+
+    module Model
+    end
+
+    module SchemaStatements
+      def create_join_table: (Symbol, Symbol, column_options: Hash, **Hash) -> untyped
+    end
+
+    class Error < StandardError
+    end
+
+    class NotAGeneratorError < Error
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: rails-clusterid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stephan Tarulli
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: crockford32
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: clusterid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: Use ClusterId values in Rails.
+email:
+- srt@tinychameleon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rails-clusterid.rb
+- lib/rails-clusterid/active_record/schema_statements.rb
+- lib/rails-clusterid/application_config.rb
+- lib/rails-clusterid/config.rb
+- lib/rails-clusterid/model.rb
+- lib/rails-clusterid/railtie.rb
+- lib/rails-clusterid/type.rb
+- lib/rails-clusterid/version.rb
+- sig/rails-clusterid.rbs
+homepage: https://github.com/tinychameleon/rails-clusterid
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tinychameleon/rails-clusterid
+  source_code_uri: https://github.com/tinychameleon/rails-clusterid
+  changelog_uri: https://github.com/tinychameleon/rails-clusterid/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tinychameleon/rails-clusterid/issues
+  documentation_uri: https://tinychameleon.github.io/rails-clusterid/
+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.3.3
+signing_key:
+specification_version: 4
+summary: Use ClusterId values in Rails.
+test_files: []