ksuid 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d7e3d2e87bfbd69ce702f4dcc0d7067394f39fe7
-  data.tar.gz: 8159913d3848e49c9e41143db7e1fc4fb115deee
+SHA256:
+  metadata.gz: 39789ed89a8ef5f2a949dc5cf716ef87f98904902dd8262e123b325408e6e69c
+  data.tar.gz: e0d3f66c83acab156cc260d063c0a69921b880a83dce3ca32edd0635ed230579
 SHA512:
-  metadata.gz: a298ed92c64c0398c14853de8d246fc0e78b29aca724dde716fe8c67640e37621db09f62f4a76da86de0576d64a2be7d8265f1cdb692056244a0838efe9a1da9
-  data.tar.gz: 5282c1bfe4bc4a09761510fd4a330c7e8429626e67c245e62af3d41b7b391be2470c598fa91aaf6a5ebe7df51a0aec8a0e3a7f46ac01afc5afbbf733e51e1dd8
+  metadata.gz: c4a500c7863252cbe4a55a898ee941e800757676ae3a78c5f191a61173267768ea5b8352609e3689295eb233e14551fea87333fe3f0158208154aed17d9035b4
+  data.tar.gz: de9846561e6d4a2282bbbdf16ea524f6160198916e4cee8292968cb58d378cd66b2ea4699a0698a3f95db69070d3307118bb000726cb6ce05192eac20ed73a90

data/CHANGELOG.md

@@ -4,12 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2017-11-05
+## [0.2.0](https://github.com/michaelherold/ksuid/compare/v0.1.0...v0.2.0) - 2020-11-11
+
+### Added
+
+- The ability to configure the random generator for the gem via `KSUID.configure`. This allows you to set up random generation to the specifications you need, whether that is for speed or for security.
+- Support for ActiveRecord. You can now use `KSUID::ActiveRecord[:my_field]` to define a KSUID field using the Rails 5 Attributes API. There is also two new column types for migrations: `ksuid` and `ksuid_binary`. The first stores your KSUID as a string in the database, the latter as binary data.
+
+### Changed
+
+- The `KSUID::Type#inspect` method now makes it much easier to see what you're looking at in the console when you're debugging.
+
+## [0.1.0](https://github.com/michaelherold/ksuid/tree/v0.1.0) - 2017-11-05
 
 ### Added
 
 - Basic `KSUID.new` interface.
 - Parsing of bytes through `KSUID.from_bytes`.
 - Parsing of strings through `KSUID.from_base62`.
-
-[0.1.0]: https://github.com/michaelherold/interactor-contracts/tree/v0.1.0

data/CONTRIBUTING.md

@@ -28,14 +28,13 @@ Ideally, a bug report should include a pull request with failing specs.
 1. [Fork the repository].
 2. [Create a topic branch].
 3. Add specs for your unimplemented feature or bug fix.
-4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+4. Run `appraisal rake spec`. If your specs pass, return to step 3.
 5. Implement your feature or bug fix.
-6. Run `bundle exec rake`. If your specs or any of the linters fail, return to step 5.
+6. Run `appraisal rake`. If your specs or any of the linters fail, return to step 5.
 7. Open `coverage/index.html`. If your changes are not completely covered by your tests, return to step 3.
 8. Add documentation for your feature or bug fix.
-9. Run `bundle exec inch`. If your changes are below a B in documentation, go back to step 8.
-10. Commit and push your changes.
-11. [Submit a pull request].
+9. Commit and push your changes.
+10. [Submit a pull request].
 
 [Create a topic branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
 [Fork the repository]: http://learn.github.com/p/branching.html

data/README.md

@@ -92,6 +92,123 @@ If you need to generate a KSUID for a specific timestamp, use:
 ksuid = KSUID.new(time: time)  # where time is a Time-like object
 ```
 
+If you need to use a faster or more secure way of generating the random payloads (or if you want the payload to be non-random data), you can configure the gem for those use cases:
+
+```ruby
+KSUID.configure do |config|
+  config.random_generator = -> { Random.new.bytes(16) }
+end
+```
+
+### ActiveRecord
+
+Whether you are using ActiveRecord inside an existing project or in a new project, usage is simple. Additionally, you can use it with or without Rails.
+
+#### Adding to an existing model
+
+Within a Rails project, it is very easy to get started using KSUIDs within your models. You can use the `ksuid` column type in a Rails migration to add a column to an existing model:
+
+    rails generate migration add_ksuid_to_events ksuid:ksuid
+
+This will generate a migration like the following:
+
+```ruby
+class AddKsuidToEvents < ActiveRecord::Migration[5.2]
+  def change
+    add_column :events, :unique_id, :ksuid
+  end
+end
+```
+
+Then, to add proper handling to the field, you will want to mix a module into the model:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:unique_id]
+end
+```
+
+#### Creating a new model
+
+To create a new model with a `ksuid` field that is stored as a KSUID, use the `ksuid` column type. Using the Rails generators, this looks like:
+
+    rails generate model Event my_field_name:ksuid
+
+If you would like to add a KSUID to an existing model, you can do so with the following:
+
+```ruby
+class AddKsuidToEvents < ActiveRecord::Migration[5.2]
+  change_table :events do |table|
+    table.ksuid :my_field_name
+  end
+end
+```
+
+Once you have generated the table that you will use for your model, you will need to include a module into the model class, as follows:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name]
+end
+```
+
+##### With a KSUID primary key
+
+You can also use a KSUID as the primary key on a table, much like you can use a UUID in vanilla Rails. To do so requires a little more finagling than you can manage through the generators. When hand-writing the migration, it will look like this:
+
+```ruby
+class CreateEvents < ActiveRecord::Migration[5.2]
+  create_table :events, id: false do |table|
+    table.ksuid :id, primary_key: true
+  end
+end
+```
+
+You will need to mix in the module into your model as well:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:id]
+end
+```
+
+#### Outside of Rails
+
+Outside of Rails, you cannot rely on the Railtie to load the appropriate files for you automatically. Toward the start of your application's boot process, you will want to require the following:
+
+```ruby
+require 'ksuid/activerecord'
+
+# If you will be using the ksuid column type in a migration
+require 'ksuid/activerecord/table_definition'
+```
+
+Once you have required the file(s) that you need, everything else will work as it does above.
+
+#### Binary vs. String KSUIDs
+
+These examples all store your identifier as a string-based KSUID. If you would like to use binary KSUIDs instead, use the `ksuid_binary` column type. Unless you need to be super-efficient with your database, we recommend using string-based KSUIDs because it makes looking at the data while in the database a little easier to understand.
+
+When you include the KSUID module into your model, you will want to pass the `:binary` option as well:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name, binary: true]
+end
+```
+
+#### Use the KSUID as your `created_at` timestamp
+
+Since KSUIDs include a timestamp as well, you can infer the `#created_at` timestamp from the KSUID. The module builder enables that option automatically with the `:created_at` option, like so:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name, created_at: true]
+end
+```
+
+This allows you to be efficient in your database design if that is a constraint you need to satisfy.
+
 ## Contributing
 
 So you’re interested in contributing to KSUID? Check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to do that.
@@ -100,9 +217,9 @@ So you’re interested in contributing to KSUID? Check out our [contributing gui
 
 This library aims to support and is [tested against][travis] the following Ruby versions:
 
-* Ruby 2.3
-* Ruby 2.4
-* JRuby 9.1
+* Ruby 2.5
+* Ruby 2.6
+* JRuby 9.2
 
 If something doesn't work on one of these versions, it's a bug.
 

data/ksuid.gemspec

@@ -18,5 +18,5 @@ Gem::Specification.new do |spec|
   spec.files += Dir['lib/**/*.rb']
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'bundler', '>= 1.15'
 end

data/lib/ksuid.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'ksuid/configuration'
 require_relative 'ksuid/type'
 require_relative 'ksuid/version'
 
@@ -74,6 +75,57 @@ module KSUID
   # @return [String]
   MAX_STRING_ENCODED = 'aWgEPTl1tmebfsQzFP4bxwgy80V'
 
+  # Converts a KSUID-compatible value into an actual KSUID
+  #
+  # @api public
+  #
+  # @example Converts a base 62 KSUID string into a KSUID
+  #   KSUID.call('15Ew2nYeRDscBipuJicYjl970D1')
+  #
+  # @param ksuid [String, Array<Integer>, KSUID::Type] the KSUID-compatible value
+  # @return [KSUID::Type] the converted KSUID
+  # @raise [ArgumentError] if the value is not KSUID-compatible
+  def self.call(ksuid)
+    return unless ksuid
+
+    case ksuid
+    when KSUID::Type then ksuid
+    when Array then KSUID.from_bytes(ksuid)
+    when String then cast_string(ksuid)
+    else
+      raise ArgumentError, "Cannot convert #{ksuid.inspect} to KSUID"
+    end
+  end
+
+  # The configuration for creating new KSUIDs
+  #
+  # @api private
+  #
+  # @return [KSUID::Configuration] the gem's configuration
+  def self.config
+    @config ||= KSUID::Configuration.new
+  end
+
+  # Configures the KSUID gem by passing a block
+  #
+  # @api public
+  #
+  # @example Override the random generator with a null data generator
+  #   KSUID.configure do |config|
+  #     config.random_generator = -> { "\x00" * KSUID::BYTES[:payload] }
+  #   end
+  #
+  # @example Override the random generator with the faster, but less secure, Random
+  #   KSUID.configure do |config|
+  #     config.random_generator = -> { Random.new.bytes(KSUID::BYTES[:payload]) }
+  #   end
+  #
+  # @return [KSUID::Configuration] the gem's configuration
+  def self.configure
+    yield config if block_given?
+    config
+  end
+
   # Converts a base 62-encoded string into a KSUID
   #
   # @api public
@@ -98,7 +150,7 @@ module KSUID
   # @example Parse a KSUID byte string into an object
   #   KSUID.from_bytes("\x06\x83\xF7\x89\x04\x9C\xC2\x15\xC0\x99\xD4+xM\xBE\x994\e\xD7\x9C")
   #
-  # @param bytes [String|Array<Integer>] the byte string or array to convert into an object
+  # @param bytes [String, Array<Integer>] the byte string or array to convert into an object
   # @return [KSUID::Type] the KSUID generated from the bytes
   def self.from_bytes(bytes)
     bytes = bytes.bytes if bytes.is_a?(String)
@@ -131,10 +183,27 @@ module KSUID
   # @example Generate a new KSUID for a given timestamp
   #   KSUID.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
   #
-  # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+  # @param payload [String, Array<Integer>, nil] the payload for the KSUID
   # @param time [Time] the timestamp to use for the KSUID
   # @return [KSUID::Type] the generated KSUID
   def self.new(payload: nil, time: Time.now)
     Type.new(payload: payload, time: time)
   end
+
+  # Casts a string into a KSUID
+  #
+  # @api private
+  #
+  # @param ksuid [String] the string to convert into a KSUID
+  # @return [KSUID::Type] the converted KSUID
+  def self.cast_string(ksuid)
+    if Base62.compatible?(ksuid)
+      KSUID.from_base62(ksuid)
+    else
+      KSUID.from_bytes(ksuid)
+    end
+  end
+  private_class_method :cast_string
 end
+
+require 'ksuid/railtie' if defined?(Rails)

data/lib/ksuid/activerecord.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ksuid/activerecord/binary_type'
+require 'ksuid/activerecord/type'
+
+module KSUID
+  # Enables an Active Record model to have a KSUID attribute
+  #
+  # @api public
+  module ActiveRecord
+    # Builds a module to include into the model
+    #
+    # @api public
+    #
+    # @example Add a `#ksuid` attribute to a model
+    #   class Event < ActiveRecord::Base
+    #     include KSUID::ActiveRecord[:ksuid]
+    #   end
+    #
+    # @example Add a `#remote_id` attribute to a model and overrides `#created_at` to use the KSUID
+    #   class Event < ActiveRecord::Base
+    #     include KSUID::ActiveRecord[:remote_id, created_at: true]
+    #   end
+    #
+    # @param field [String, Symbol] the name of the field to use as a KSUID
+    # @param created_at [Boolean] whether to override the `#created_at` method
+    # @param binary [Boolean] whether to store the KSUID as a binary or a string
+    # @return [Module] the module to include into the model
+    def self.[](field, created_at: false, binary: false)
+      Module
+        .new
+        .tap do |mod|
+          define_attribute(field, mod, binary)
+          define_created_at(field, mod) if created_at
+        end
+    end
+
+    # Defines the attribute method that will be written in the module
+    #
+    # @api private
+    #
+    # @param field [String, Symbol] the name of the field to set as an attribute
+    # @param mod [Module] the module to extend
+    # @return [void]
+    def self.define_attribute(field, mod, binary)
+      type = 'ksuid'
+      type = 'ksuid_binary' if binary
+
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.included(base)
+          base.__send__(:attribute, :#{field}, :#{type}, default: -> { KSUID.new })
+        end
+      RUBY
+    end
+    private_class_method :define_attribute
+
+    # Defines the `#created_at` method that will be written in the module
+    #
+    # @api private
+    #
+    # @param field [String, Symbol] the name of the KSUID attribute field
+    # @param mod [Module] the module to extend
+    # @return [void]
+    def self.define_created_at(field, mod)
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def created_at
+          return unless #{field}
+
+          #{field}.to_time
+        end
+      RUBY
+    end
+    private_class_method :define_created_at
+  end
+end

data/lib/ksuid/activerecord/binary_type.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # A binary-serialized KSUID for storage within an ActiveRecord database
+    #
+    # @api private
+    #
+    # @example Set an attribute as a KSUID using the verbose syntax
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, KSUID::ActiveRecord::BinaryType.new, default: -> { KSUID.new }
+    #   end
+    #
+    # @example Set an attribute as a KSUID using the pre-registered type
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, :ksuid_binary, default: -> { KSUID.new }
+    #   end
+    class BinaryType < ::ActiveRecord::Type::Binary
+      # Casts a value from user input into a KSUID
+      #
+      # Type casting happens via the attribute setter and can take input from
+      # many places, including:
+      #
+      #   1. The Rails form builder
+      #   2. Directly from the attribute setter
+      #   3. From the model initializer
+      #
+      # @param value [String, Array<Integer>, KSUID::Type] the value to cast into a KSUID
+      # @return [KSUID::Type] the type-casted value
+      def cast(value)
+        KSUID.call(value)
+      end
+
+      # Converts a value from database input to a KSUID
+      #
+      # @param value [String, nil] the database-serialized KSUID to convert
+      # @return [KSUID::Type] the deserialized KSUID
+      def deserialize(value)
+        return unless value
+
+        value = value.to_s if value.is_a?(::ActiveRecord::Type::Binary::Data)
+        KSUID.call(value)
+      end
+
+      # Casts the value from a KSUID into a database-understandable format
+      #
+      # @param value [KSUID::Type, nil] the KSUID in Ruby format
+      # @return [String, nil] the base 62-encoded KSUID for storage in the database
+      def serialize(value)
+        return unless value
+
+        super(KSUID.call(value).to_bytes)
+      end
+
+      # The identifier to use within ActiveRecord's type registry
+      #
+      # @api private
+      # @return [Symbol]
+      def type
+        :ksuid_binary
+      end
+    end
+  end
+end
+
+ActiveRecord::Type.register(:ksuid_binary, KSUID::ActiveRecord::BinaryType)

data/lib/ksuid/activerecord/table_definition.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # Extends ActiveRecord's table definition language for KSUIDs
+    module TableDefinition
+      # Defines a field as a string-based KSUID
+      #
+      # @example Define a KSUID field as a non-primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true do |table|
+      #       table.ksuid :ksuid, index: true, unique: true
+      #     end
+      #   end
+      #
+      # @example Define a KSUID field as a primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true, id: false do |table|
+      #       table.ksuid :id, primary_key: true
+      #     end
+      #   end
+      #
+      # @param args [Array<Symbol>] the list of fields to define as KSUIDs
+      # @param options [Hash] see {ActiveRecord::ConnectionAdapters::TableDefinition}
+      # @return [void]
+      def ksuid(*args, **options)
+        args.each { |name| column(name, :string, **options.merge(limit: 27)) }
+      end
+
+      # Defines a field as a binary-based KSUID
+      #
+      # @example Define a KSUID field as a non-primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true do |table|
+      #       table.ksuid_binary :ksuid, index: true, unique: true
+      #     end
+      #   end
+      #
+      # @example Define a KSUID field as a primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true, id: false do |table|
+      #       table.ksuid_binary :id, primary_key: true
+      #     end
+      #   end
+      #
+      # @param args [Array<Symbol>] the list of fields to define as KSUIDs
+      # @param options [Hash] see {ActiveRecord::ConnectionAdapters::TableDefinition}
+      # @return [void]
+      def ksuid_binary(*args, **options)
+        args.each { |name| column(name, :binary, **options.merge(limit: 20)) }
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::TableDefinition.include(KSUID::ActiveRecord::TableDefinition)

data/lib/ksuid/activerecord/type.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # A string-serialized KSUID for storage within an ActiveRecord database
+    #
+    # @api private
+    #
+    # @example Set an attribute as a KSUID using the verbose syntax
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, KSUID::ActiveRecord::Type.new, default: -> { KSUID.new }
+    #   end
+    #
+    # @example Set an attribute as a KSUID using the pre-registered type
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, :ksuid, default: -> { KSUID.new }
+    #   end
+    class Type < ::ActiveRecord::Type::String
+      # Casts a value from user input into a KSUID
+      #
+      # Type casting happens via the attribute setter and can take input from
+      # many places, including:
+      #
+      #   1. The Rails form builder
+      #   2. Directly from the attribute setter
+      #   3. From the model initializer
+      #
+      # @param value [String, Array<Integer>, KSUID::Type] the value to cast into a KSUID
+      # @return [KSUID::Type] the type-casted value
+      def cast(value)
+        KSUID.call(value)
+      end
+
+      # Converts a value from database input to a KSUID
+      #
+      # @param value [String, nil] the database-serialized KSUID to convert
+      # @return [KSUID::Type] the deserialized KSUID
+      def deserialize(value)
+        return unless value
+
+        KSUID.from_base62(value)
+      end
+
+      # Casts the value from a KSUID into a database-understandable format
+      #
+      # @param value [KSUID::Type, nil] the KSUID in Ruby format
+      # @return [String, nil] the base 62-encoded KSUID for storage in the database
+      def serialize(value)
+        return unless value
+
+        KSUID.call(value).to_s
+      end
+
+      # The identifier to use within ActiveRecord's type registry
+      #
+      # @api private
+      # @return [Symbol]
+      def type
+        :ksuid
+      end
+    end
+  end
+end
+
+ActiveRecord::Type.register(:ksuid, KSUID::ActiveRecord::Type)

data/lib/ksuid/base62.rb

@@ -20,6 +20,19 @@ module KSUID
     # @api private
     BASE = CHARSET.size
 
+    # Checks whether a string is a base 62-compatible string
+    #
+    # @api public
+    #
+    # @example Checks a KSUID for base 62 compatibility
+    #   KSUID::Base62.compatible?("15Ew2nYeRDscBipuJicYjl970D1") #=> true
+    #
+    # @param string [String] the string to check for compatibility
+    # @return [Boolean]
+    def self.compatible?(string)
+      string.each_char.all? { |char| CHARSET.include?(char) }
+    end
+
     # Decodes a base 62-encoded string into an integer
     #
     # @api public
@@ -71,7 +84,7 @@ module KSUID
     #      255, 255, 255, 255, 255, 255, 255, 255, 255, 255]
     #   )
     #
-    # @param bytes [String|Array<Integer>] the bytes to encode
+    # @param bytes [String, Array<Integer>] the bytes to encode
     # @return [String] the encoded bytes as a base 62 string
     def self.encode_bytes(bytes)
       encode(Utils.int_from_bytes(bytes))

data/lib/ksuid/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KSUID
+  # Encapsulates the configuration for the KSUID gem as a whole.
+  #
+  # You can override the generation of the random payload data by setting the
+  # {#random_generator} value to a valid random payload generator. This should
+  # be done via the module-level {KSUID.configure} method.
+  #
+  # The gem-level configuration lives at the module-level {KSUID.config}.
+  #
+  # @api semipublic
+  class Configuration
+    # Raised when the gem is misconfigured.
+    ConfigurationError = Class.new(StandardError)
+
+    # The default generator for generating random payloads
+    #
+    # @api private
+    #
+    # @return [Proc]
+    def self.default_generator
+      -> { SecureRandom.random_bytes(BYTES[:payload]) }
+    end
+
+    # Instantiates a new KSUID configuration
+    #
+    # @api private
+    #
+    # @return [KSUID::Configuration] the new configuration
+    def initialize
+      self.random_generator = self.class.default_generator
+    end
+
+    # The method for generating random payloads in the gem
+    #
+    # @api private
+    #
+    # @return [#call] a callable that returns 16 bytes
+    attr_reader :random_generator
+
+    # Override the method for generating random payloads in the gem
+    #
+    # @api semipublic
+    #
+    # @example Override the random generator with a null data generator
+    #   KSUID.configure do |config|
+    #     config.random_generator = -> { "\x00" * KSUID::BYTES[:payload] }
+    #   end
+    #
+    # @example Override the random generator with the faster, but less secure, Random
+    #   KSUID.configure do |config|
+    #     config.random_generator = -> { Random.new.bytes(KSUID::BYTES[:payload]) }
+    #   end
+    #
+    # @param generator [#call] a callable that returns 16 bytes
+    # @return [#call] a callable that returns 16 bytes
+    def random_generator=(generator)
+      assert_generator_is_callable(generator)
+      assert_payload_size(generator)
+
+      @random_generator = generator
+    end
+
+    private
+
+    # Raises an error if the assigned generator is not callable
+    #
+    # @api private
+    #
+    # @raise [ConfigurationError] if the generator is not callable
+    # @return [nil]
+    def assert_generator_is_callable(generator)
+      return if generator.respond_to?(:call)
+
+      raise ConfigurationError, "Random generator #{generator} is not callable"
+    end
+
+    # Raises an error if the assigned generator generates the wrong size
+    #
+    # @api private
+    #
+    # @raise [ConfigurationError] if the generator generates the wrong size payload
+    # @return [nil]
+    def assert_payload_size(generator)
+      return if (length = generator.call.length) == (expected_length = BYTES[:payload])
+
+      raise ConfigurationError, 'Random generator generates the wrong number of bytes ' \
+        "(#{length} generated, #{expected_length} expected)"
+    end
+  end
+end

data/lib/ksuid/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KSUID
+  # Enables the usage of KSUID types within ActiveRecord when Rails is loaded
+  #
+  # @api private
+  class Railtie < ::Rails::Railtie
+    initializer 'ksuid' do
+      ActiveSupport.on_load :active_record do
+        require 'ksuid/activerecord'
+        require 'ksuid/activerecord/table_definition'
+      end
+    end
+  end
+end

data/lib/ksuid/type.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'securerandom'
 require_relative 'base62'
 require_relative 'utils'
 
@@ -31,11 +30,11 @@ module KSUID
     # @example Generate a new KSUID for a given timestamp
     #   KSUID::Type.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
     #
-    # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+    # @param payload [String, Array<Integer>, nil] the payload for the KSUID
     # @param time [Time] the timestamp to use for the KSUID
     # @return [KSUID::Type] the generated KSUID
     def initialize(payload: nil, time: Time.now)
-      payload ||= SecureRandom.random_bytes(BYTES[:payload])
+      payload ||= KSUID.config.random_generator.call
       byte_encoding = Utils.int_to_bytes(time.to_i - EPOCH_TIME)
 
       @uid = byte_encoding.bytes + payload.bytes
@@ -64,6 +63,18 @@ module KSUID
       other.to_s == to_s
     end
 
+    # Prints the KSUID for debugging within a console
+    #
+    # @api public
+    #
+    # @example Show the maximum KSUID
+    #   KSUID.max.inspect  #=> "<KSUID(aWgEPTl1tmebfsQzFP4bxwgy80V)>"
+    #
+    # @return [String]
+    def inspect
+      "<KSUID(#{self})>"
+    end
+
     # The payload for the KSUID, as a hex-encoded string
     #
     # This is generally useful for comparing against the Go tool
@@ -121,9 +132,7 @@ module KSUID
     #
     # @return [Integer] the Unix timestamp for the event (without the epoch shift)
     def to_i
-      unix_time = Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
-
-      unix_time
+      Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
     end
 
     # The KSUID as a base 62-encoded string

data/lib/ksuid/utils.rb

@@ -15,20 +15,19 @@ module KSUID
 
     # Converts a byte string or byte array into a hex-encoded string
     #
-    # @param bytes [String|Array<Integer>] the byte string or array
+    # @param bytes [String, Array<Integer>] the byte string or array
     # @return [String] the byte string as a hex-encoded string
     def self.bytes_to_hex_string(bytes)
       bytes = bytes.bytes if bytes.is_a?(String)
 
       byte_string_from_array(bytes)
-        .unpack('H*')
-        .first
+        .unpack1('H*')
         .upcase
     end
 
     # Converts a byte string or byte array into an integer
     #
-    # @param bytes [String|Array<Integer>] the byte string or array
+    # @param bytes [String, Array<Integer>] the byte string or array
     # @return [Integer] the resulting integer
     def self.int_from_bytes(bytes)
       bytes = bytes.bytes if bytes.is_a?(String)

data/lib/ksuid/version.rb

@@ -4,5 +4,5 @@ module KSUID
   # The version of the KSUID gem
   #
   # @return [String]
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: ksuid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Herold
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-11-05 00:00:00.000000000 Z
+date: 2020-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
 description: Ruby implementation of the K-Sortable Unique IDentifier
@@ -37,7 +37,13 @@ files:
 - README.md
 - ksuid.gemspec
 - lib/ksuid.rb
+- lib/ksuid/activerecord.rb
+- lib/ksuid/activerecord/binary_type.rb
+- lib/ksuid/activerecord/table_definition.rb
+- lib/ksuid/activerecord/type.rb
 - lib/ksuid/base62.rb
+- lib/ksuid/configuration.rb
+- lib/ksuid/railtie.rb
 - lib/ksuid/type.rb
 - lib/ksuid/utils.rb
 - lib/ksuid/version.rb
@@ -45,7 +51,7 @@ homepage: https://github.com/michaelherold/ksuid
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -60,10 +66,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
-signing_key: 
+rubygems_version: 3.0.6
+signing_key:
 specification_version: 4
 summary: Ruby implementation of the K-Sortable Unique IDentifier
 test_files: []
-has_rdoc: