hoov_vin 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89cea6349464b8a846d7278e95ceb71f633dd8e86b33963eace43993b7c9a577
+  data.tar.gz: eee44128336e248e192cfcdd702954625b50db1da7a8a17137de644a2e5c5f0d
+SHA512:
+  metadata.gz: 02a46a71bc71764d28c745af2966a057d25fb2638f30c8ca0cbcced195210276f63d67a1a32ec573d6cd3e4d282274b968abea057053ab3eab42b9cde587b680
+  data.tar.gz: ee32ff79ef7106ca1ab4685f081a8e18f02b03a68873f146ce42a6e3681b75cfb46e6721f0c94f12fc24aa99a30620ffb1f17571b01b61ab9ac675a136aac348

data/README.md

@@ -0,0 +1,287 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark-mode.png">
+    <source media="(prefers-color-scheme: light)" srcset="docs/logo-light-mode.png">
+    <img width=200>
+  </picture>
+  <h1>VIN</h1>
+  <p><i>noun ‧ <strong>V</strong>ersatile <strong>I</strong>dentification <strong>N</strong>umber</i></p>
+  <p><strong>A customizable Redis-powered Ruby client for generating unique, monotonically-increasing integer IDs, for use in distributed systems and databases.</strong></p>
+  <a href="https://github.com/hoovbr/vin/releases">
+    <img alt="Latest Release" src="https://img.shields.io/github/v/release/hoovbr/vin?sort=semver">
+  </a>
+  <a href="https://codeclimate.com/github/hoovbr/vin/maintainability">
+    <img src="https://api.codeclimate.com/v1/badges/790449fb5d05f6a134a5/maintainability" />
+  </a>
+  <a href="https://codeclimate.com/github/hoovbr/vin/test_coverage">
+    <img src="https://api.codeclimate.com/v1/badges/790449fb5d05f6a134a5/test_coverage" />
+  </a>
+  <a href="https://github.com/hoovbr/vin/actions/workflows/push.yml">
+    <img alt="Tests & Linter" src="https://github.com/hoovbr/vin/actions/workflows/push.yml/badge.svg">
+  </a>
+  <a href="https://github.com/hoovbr/vin/issues">
+    <img alt="Issues" src="https://img.shields.io/github/issues/hoovbr/vin?color=#86D492" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=hoovbr">
+    <img src="https://img.shields.io/twitter/follow/hoovbr?&logo=twitter" alt="Follow on Twitter">
+  </a>
+  <img src="https://views.whatilearened.today/views/github/hoovbr/vin.svg">
+
+  <p align="center">
+    <a href="#demo">View Demo</a>
+    ·
+    <a href="https://github.com/hoovbr/vin/issues/new/choose">Report Bug</a>
+    ·
+    <a href="https://github.com/hoovbr/vin/issues/new/choose">Request Feature</a>
+  </p>
+</div>
+
+A customizable Redis-powered Ruby client for generating unique, monotonically-increasing integer IDs, for use in distributed systems and databases. Based heavily off of [Icicle](https://github.com/intenthq/icicle/), [Twitter Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID), and [Dogtag](https://github.com/zillyinc/dogtag).
+
+# Requirements
+
+- Ruby 3+
+- Redis 5+
+- If you are going to store the ID in a database you'll need to make sure it can store 64-bit integers, (e.g. PostgreSQL, MySQL, etc.)
+
+## Demo
+
+<details><summary>Click here to view a simple demo</summary>
+<p>
+
+The gif below demonstrates how the ID generation works:
+
+<div align="center">
+  <img alt="Demo" src="https://github.com/hoovbr/vin/assets/8419048/dc9fe71f-7d6d-4ba5-bd8e-fe81a280928a">
+</div>
+
+</p>
+</details>
+
+# Installation
+
+Add this gem to your `Gemfile`:
+
+```ruby
+gem "hoov_vin"
+```
+
+And then run `bundle install` to install it.
+
+# Usage
+
+Follow the steps below to get started with VIN in your Ruby on Rails project. These steps assume your project is not yet live in production, so that you're free to make changes to your database schema and drop your existing database records.
+
+1. Make sure the primary key type is set to `:bigint` when generating new models
+
+To achieve this, create or update your `config/initializers/generators.rb` file:
+
+```ruby
+Rails.application.config.generators do |g|
+  g.orm :active_record, primary_key_type: :bigint
+end
+```
+
+This [happens to be the default](https://edgeguides.rubyonrails.org/active_record_basics.html#schema-conventions) for PostgreSQL and MySQL, but it's not the default for SQLite, so it's good to always be explicit.
+
+2. Set up the VIN generator
+
+Update your `config/application.rb` file to initialize the VIN generator singleton:
+
+```ruby
+…
+require "vin"
+
+class YourApp
+  class Application < Rails::Application
+    …
+    # CAUTION: Avoid modifying the values below without fully understanding the implications in past IDs.
+    config.id_generator = VIN.new(config: VIN::Config.new(
+      custom_epoch: 1_672_531_200_000,
+      timestamp_bits: 40,
+      logical_shard_id_bits: 3,
+      data_type_bits: 9,
+      sequence_bits: 11,
+      logical_shard_id_range: 0..0,
+    ))
+  end
+end
+```
+
+To understand what each of these values mean, see the [Configuration](#configuration) section below.
+
+3. Automatically generate and assign the VIN to models before saving them to the database
+
+Create a new file in `app/models/concerns/has_vin.rb`:
+
+```ruby
+module HasVin
+  extend ActiveSupport::Concern
+
+  included do
+    before_create :set_vin_if_needed
+  end
+
+  private
+
+  def set_vin_if_needed
+    id_generator = Rails.application.config.id_generator
+    self.id ||= id_generator.generate_id(self.class::VIN_DATA_TYPE)
+  end
+end
+```
+
+This will guarantee that the VIN is generated and assigned to the model before it's saved to the database. The `VIN_DATA_TYPE` constant is used to differentiate between different types of models, so that they don't share the same ID space. For example, you might want to use a different `VIN_DATA_TYPE` for `User` models than you would for `Post` models.
+
+Note that this assumes all your models are using a primary key named `id`. If you're not following the Rails convention of using `id` as the primary key, or if you're using composite primary keys, you'll need to modify this code to work with your specific setup. This could be one way to do it:
+
+```ruby
+…
+def set_vin_if_needed
+  # If using composite primary keys in Rails 7.1 and later
+  return if defined?(self.class.primary_key) && self.class.primary_key.is_a?(Array)
+  # If using composite primary keys in Rails 7.0 and earlier
+  return if defined?(self.class.primary_keys)
+  id_generator = Rails.application.config.id_generator
+  self.id ||= id_generator.generate_id(self.class::VIN_DATA_TYPE)
+end
+…
+```
+
+4. Include the `HasVin` module in your base `ApplicationRecord` class
+
+Create or update your base ActiveRecord abstract class, such as `app/models/application_record.rb`:
+
+```
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true # If targetting Rails 6 or earlier
+  primary_abstract_class # If targetting Rails 7 or later
+  include HasVin
+end
+```
+
+This will make sure the `HasVin` module is included in all your models.
+
+>_**Note:** If you already have an existing codebase and database records, make sure you write the appropriate migration to change the primary key type to `:bigint` across the board, as well as migrate your existing records' IDs to VIN IDs._
+
+## Usage outside of ActiveRecord/Rails context
+
+```ruby
+vin = VIN.new
+data_type = 0
+vin.generate_id(data_type) # => 63801071700541441
+```
+
+```ruby
+count = 100
+vin.generate_ids(data_type, count) # => [63801199693922306, 63801199693922307, … 98 other IDs … ]
+```
+
+```ruby
+id_number = vin.generate_id(data_type) # => 63801532235120742
+id = VIN::Id.new(id: id_number) # => #<VIN::Id:0x0000000108452ff0…>
+id.data_type # => 0
+id.sequence # => 102
+id.logical_shard_id # => 0
+id.custom_timestamp # => 7605735330, time since custom epoc in milliseconds
+id.timestamp.to_time # 2023-09-27 22:16:15.33 -0300 (Ruby Time object)
+id.timestamp.epoch #=> 1688258040000, time since UNIX epoch in milliseconds
+```
+
+# Configuration
+
+The VIN generator can be configured with the following parameters:
+
+- `custom_epoch` or `VIN_CUSTOM_EPOCH` env var: The custom epoch is the timestamp that will be used as the starting point for generating VINs. It's expressed in milliseconds since the UNIX epoch (Jan 1st, 1970, 12:00 AM UTC). Example value: `1_672_531_200_000` (Jan 1st, 2023, 12:00 AM UTC). This value shouldn't be in the future, and should never be changed after its first config.
+- `timestamp_bits` or `VIN_TIMESTAMP_BITS` env var: The number of bits to use for the timestamp. The more bits you use, the more time you'll have before the timestamp overflows. Example value: `40` (40 bits gives us 1099511627776 milliseconds, or 34.8 years, enough time any of us to retire 😇).
+- `logical_shard_id_bits` or `VIN_LOGICAL_SHARD_ID_BITS` env var: The number of bits to use for the logical shard ID. The more bits you use, the more machines generating IDs you'll be able to have. Example value: `3` (3 bits gives us 8 logical shards, which means you can have 8 different servers generating ids).
+- `data_type_bits` or `VIN_DATA_TYPE_BITS`: The number of bits to use for the data type. The more bits you use, the more different types of models (tables) you'll be able to have. Example value: `9` (9 bits gives us 512 different data types).
+- `sequence_bits` or `VIN_SEQUENCE_BITS`: The number of bits to use for the sequence. The more bits you use, the more IDs you'll be able to generate per millisecond per logical shard. Example value: `11` (11 bits gives us 2048 ids per millisecond per logical shard).
+- `logical_shard_id_range` or `VIN_LOGICAL_SHARD_ID_RANGE_MIN` + `VIN_LOGICAL_SHARD_ID_RANGE_MAX` env vars: The range of logical shard IDs to use. Example value: `0..7` (8 logical shards, numbered 0 through 7). Note that this must conform with the `logical_shard_id_bits` value. This parameter is optional, and defaults to `0..0` (a single logical shard with ID 0).
+- `VIN_REDIS_URL` or `REDIS_URL` env var: The Redis URL to use for the Redis connection. Example value: `redis://localhost:6379/0`. This parameter is optional, and defaults to `redis://127.0.0.1:6379`.
+
+**Note:** the sum of the `timestamp_bits`, `logical_shard_id_bits`, `data_type_bits`, and `sequence_bits` values must be 63. The remaining bit is used for the sign bit.
+
+# FAQ
+
+## Why not use incremental IDs?
+
+Using incremental IDs in databases can have its drawbacks and limitations. One key reason to reconsider their use is the potential for data leakage and security vulnerabilities. Incremental IDs are predictable and sequential, making it easier for malicious actors to guess or access sensitive data by simply incrementing the ID. This can compromise data privacy and expose confidential information about the system, how many records exist, etc. Additionally, when databases are distributed or sharded, managing incremental IDs across multiple servers can lead to synchronization challenges and performance bottlenecks. Moreover, if records are ever deleted or the database is restructured, gaps in the sequence may arise, causing inconsistencies and complicating data analysis. Lastly, incremental IDs are not universally unique, which inevitably leads to collisions amongst different database tables, and can cause confusion or mistakes when debugging, analyzing, or manipulating data.
+
+## Why not use UUIDs?
+
+UUIDs (Universally Unique Identifiers) solve the problem of predictability and security, and also the generation of IDs in distributed systems, but they are long and complex, which can increase storage requirements and slow down indexing and query performance. Storing them as strings can also make them difficult to work with, and takes up more space than storing integer IDs. Although they can be encoded as integers too, they still take up 128 bits of storage when in integer format. Lastly, sorting them doesn't provide any usefulness, and their meaningless nature doesn't help with debugging or data analysis.
+
+## Why not use ULIDs?
+
+Using ULIDs (Universally Unique Lexicographically Sortable Identifiers) are the second best alternative, as they are sortable by time, don't impose immediate generation problems in distributed systems, and can also be encoded as integers. However, there are still a few drawbacks, such as they taking up 128 bits of storage, which may not be necessary if they are being used as database primary keys. Lastly, time is the only useful information encoded in them, so they don't provide any additional context or meaning to the data.
+
+## Why use VINs?
+
+At this point you can probably guess why we created VINs. They are the best at solving each weakness of the options listed above:
+
+- VINs are not predictable, thus they don't impose the security and privacy vulnerabilities that comes with incremental IDs.
+- VINs has zero collision probability, making them universally unique across the entire database.
+    - This comes with the drawback of a self-imposed bottleneck on the generation. However, this is only an issue at absurd scales (thousands of record creations per milisecond, per server), and can be easily overcome by increasing the number of sequence bits or shards.
+- VINs are 64-bit integers, making them more space-efficient than UUIDs and ULIDs, which take 128 bits at best.
+- VINs can be sorted, earning a chronologically sorted list, thanks to the monotonically-increasing nature of the IDs.
+- VINs encode additional context and meaning to the data it stores, such as the timestamp, data type, and shard ID, which can be used to identify the source of the data, optimizing distributed systems and debugging.
+- VINs are fully customizable. As you could see in the [Configuration](#configuration) section, you can customize the number of bits used for each component of the VIN, allowing you to optimize the VIN for your specific use case.
+
+## How does it work?
+
+### How are the IDs generated?
+
+The IDs are composed by 64 bits, which are divided into 4 components: timestamp, shard ID (aka machine ID), data type, and sequence. It's important that it starts with the timestamp component, as that's what guarantees the IDs are sortable by time.
+
+The number of bits that each of these components take up can be customized as seen in the [Configuration](#configuration), but for the sake of this example, we'll use 40 bits for the timestamp, 3 bits for the shard ID, 9 bits for the data type, and 11 bits for the sequence. This adds up 63 bits, but since we're working with a signed integer, the first bit is reserved for the bit sign. This results in this binary representation:
+
+```no-highlight
++----------------------+----------+--------------+----------------+
+|      Timestamp       | Shard ID |  Data Type   |    Sequence    |
+|      (40 bits)       | (3 bits) |   (9 bits)   |    (11 bits)   |
++----------------------+----------+--------------+----------------+
+```
+
+This is then converted to a decimal number, which is what we use as the ID. The timestamp is the number of milliseconds since the custom epoch defined by you during the configuration. The shard ID is a number that uniquely identifies the machine that generated the ID. The data type is a number that uniquely identifies the model that this ID will belong to. The sequence is a number that is incremented every time an ID is generated, and is reset to 0 every millisecond, a strategy used to avoid collisions.
+
+### How are the IDs automatically assigned to records?
+
+In Rails, when you create a new record, the `create` method is called on the model class, which creates the record in memory and then calls `save` on it. The `save` method will either call `create` or `update` depending on whether the record is new or not. If the record is not new, it will already have an ID assigned to it, in which case our method `set_vin_if_needed` in `HasVin` won't do anything. However, if the record is new, it will not have an ID assigned to it, in which case our method will generate and assign a VIN to it. This happens before the record gets sent to the database, so the database will not generate an ID for it.
+
+## What about the performance?
+
+Compared to the benefits of having VINs, the performance impact is negligible. The only performance impact is the time it takes to generate the VIN, which is around ~0.039ms (yes, that's not a typo, it's less than 1/25th of a millisecond).
+
+## Any issues I should be aware of?
+
+Be careful of using VIN IDs with JavaScript, since it [doesn't handle 64 bit integers well](http://stackoverflow.com/questions/9643626/javascript-cant-handle-64-bit-integers-can-it). You'll probably want to work with them as strings.
+
+Also, when two IDs are generated within the same millisecond, their order is only guaranteed to be the same if they're generated by the same machine, for the same data type. This expected and is due to the very nature of the order of the bits, after all, the IDs are only sortable by time.
+
+# Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To bump the lib's version, run `bundle exec rake bump[1.2.3]` (replacing the value with the desired version).
+
+To release a new version, update the version number (via `bundle exec rake bump` as explained above), 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).
+
+# TODO
+
+- Support multiple Redis servers
+- Replace the lua script with Ruby code.
+
+# Contributing
+
+If you spot something wrong, missing, or if you'd like to propose improvements to this project, please open an Issue or a Pull Request with your ideas and we promise to get back to you within 24 hours! 😇
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+For a list of issues worth tackling check out: https://github.com/hoovbr/vin/issues
+
+# Popularity
+
+<img width=500 src="https://api.star-history.com/svg?repos=hoovbr/vin&type=Date">

data/lib/vin/config.rb

@@ -0,0 +1,94 @@
+class VIN
+  class Config
+    # Expressed in milliseconds.
+    attr_reader :custom_epoch
+
+    # For instance, 40 bits gives us 1099511627776 milliseconds, or 34.8 years. Enough time to last us until 2057, enough time for any of us to retire.
+    attr_reader :timestamp_bits
+
+    # For instance, 3 bits gives us 8 logical shards, which means we can have 8 different servers generating ids.
+    attr_reader :logical_shard_id_bits
+
+    # For instance, 9 bits gives us 512 different data types.
+    attr_reader :data_type_bits
+
+    # For instance, 11 bits gives us 2048 ids per millisecond per logical shard.
+    attr_reader :sequence_bits
+
+    # Defaults to allowing all logical shard ids to be generated by this server.
+    attr_reader :logical_shard_id_range
+
+    def initialize(
+      custom_epoch: nil,
+      timestamp_bits: nil,
+      logical_shard_id_bits: nil,
+      data_type_bits: nil,
+      sequence_bits: nil,
+      logical_shard_id_range: nil
+    )
+      @custom_epoch = custom_epoch || ENV.fetch("VIN_CUSTOM_EPOCH").to_i
+      @timestamp_bits = timestamp_bits || ENV.fetch("VIN_TIMESTAMP_BITS").to_i
+      @logical_shard_id_bits = logical_shard_id_bits || ENV.fetch("VIN_LOGICAL_SHARD_ID_BITS").to_i
+      @data_type_bits = data_type_bits || ENV.fetch("VIN_DATA_TYPE_BITS").to_i
+      @sequence_bits = sequence_bits || ENV.fetch("VIN_SEQUENCE_BITS").to_i
+      @logical_shard_id_range = logical_shard_id_range || fetch_allowed_range!
+    end
+
+    def min_logical_shard_id
+      0
+    end
+
+    def max_logical_shard_id
+      @max_logical_shard_id ||= ~(-1 << logical_shard_id_bits)
+    end
+
+    def logical_shard_id_allowed_range
+      @logical_shard_id_allowed_range ||= (min_logical_shard_id..max_logical_shard_id)
+    end
+
+    def min_data_type
+      0
+    end
+
+    def max_data_type
+      @max_data_type ||= ~(-1 << data_type_bits)
+    end
+
+    def data_type_allowed_range
+      @data_type_allowed_range ||= (min_data_type..max_data_type)
+    end
+
+    def max_sequence
+      @max_sequence ||= ~(-1 << sequence_bits)
+    end
+
+    def sequence_shift
+      0
+    end
+
+    def data_type_shift
+      @data_type_shift ||= sequence_bits
+    end
+
+    def logical_shard_id_shift
+      @logical_shard_id_shift ||= (sequence_bits + data_type_bits)
+    end
+
+    def timestamp_shift
+      @timestamp_shift ||= (sequence_bits + data_type_bits + logical_shard_id_bits)
+    end
+
+    def fetch_allowed_range!
+      range = Range.new(
+        ENV.fetch("VIN_LOGICAL_SHARD_ID_RANGE_MIN", 0).to_i,
+        ENV.fetch("VIN_LOGICAL_SHARD_ID_RANGE_MAX", 0).to_i,
+      )
+      # rubocop:disable Style/BitwisePredicate
+      unless (logical_shard_id_allowed_range.to_a & range.to_a) == range.to_a
+        raise(ArgumentError, "VIN_LOGICAL_SHARD_ID_RANGE_MIN and VIN_LOGICAL_SHARD_ID_RANGE_MAX env vars compose a range outside the allowed range of #{logical_shard_id_allowed_range} defined by the number of bits in VIN_LOGICAL_SHARD_ID_BITS env var.")
+      end
+      # rubocop:enable Style/BitwisePredicate
+      range
+    end
+  end
+end

data/lib/vin/generator.rb

@@ -0,0 +1,73 @@
+require "vin/config"
+
+class VIN
+  class Generator
+    attr_reader :data_type, :count, :config, :custom_timestamp
+
+    def initialize(config:)
+      @config = config
+    end
+
+    def generate_ids(data_type, count = 1, timestamp: nil)
+      raise(ArgumentError, "data_type must be an integer") unless data_type.is_a?(Integer)
+
+      unless config.data_type_allowed_range.include?(data_type)
+        raise(ArgumentError, "data_type is outside the allowed range of #{config.data_type_allowed_range}")
+      end
+
+      raise(ArgumentError, "count must be an integer") unless count.is_a?(Integer)
+      raise(ArgumentError, "count must be a positive number") if count < 1
+
+      if timestamp
+        validate_timestamp!(timestamp)
+      end
+
+      @data_type = data_type
+      @count = count
+      @custom_timestamp = timestamp
+
+      result = response.sequence.map do |sequence|
+        (
+          shifted_timestamp |
+          shifted_logical_shard_id |
+          shifted_data_type |
+          (sequence << config.sequence_shift)
+        )
+      end
+      # After generating a batch of IDs, we reset the response object so that it generates new IDs later with a new request.
+      @response = nil
+      result
+    end
+
+    private
+
+    def shifted_timestamp
+      timestamp = if custom_timestamp
+        # Custom timestamp is in Unix milliseconds (absolute time)
+        # Convert it to be relative to custom epoch
+        milliseconds_from_custom_epoch = custom_timestamp - config.custom_epoch
+        Timestamp.new(milliseconds_from_custom_epoch, epoch: config.custom_epoch)
+      else
+        Timestamp.from_redis(response.seconds, response.microseconds_part)
+      end
+      timestamp.with_epoch(config.custom_epoch).milliseconds << config.timestamp_shift
+    end
+
+    def validate_timestamp!(timestamp)
+      raise(ArgumentError, "timestamp must be an integer (milliseconds)") unless timestamp.is_a?(Integer)
+      raise(ArgumentError, "timestamp cannot be before the custom epoch (#{config.custom_epoch}ms since Unix epoch)") if timestamp < config.custom_epoch
+    end
+
+    def shifted_data_type
+      data_type << config.data_type_shift
+    end
+
+    def shifted_logical_shard_id
+      response.logical_shard_id << config.logical_shard_id_shift
+    end
+
+    def response
+      @response ||= Request.new(config, data_type, count, custom_timestamp: custom_timestamp).response
+    end
+  end
+end

data/lib/vin/id.rb

@@ -0,0 +1,48 @@
+class VIN
+  class Id
+    attr_reader :id, :config
+
+    def initialize(id:, config: nil)
+      @id = id
+      @config = config || VIN::Config.new
+    end
+
+    def custom_timestamp
+      (id & timestamp_map) >> config.timestamp_shift
+    end
+
+    def timestamp
+      @timestamp ||= Timestamp.new(custom_timestamp, epoch: config.custom_epoch)
+    end
+
+    def logical_shard_id
+      (id & logical_shard_id_map) >> config.logical_shard_id_shift
+    end
+
+    def data_type
+      (id & data_type_map) >> config.data_type_shift
+    end
+
+    def sequence
+      (id & sequence_map) >> config.sequence_shift
+    end
+
+    private
+
+    def sequence_map
+      ~(-1 << config.sequence_bits) << config.sequence_shift
+    end
+
+    def data_type_map
+      ~(-1 << config.data_type_bits) << config.data_type_shift
+    end
+
+    def logical_shard_id_map
+      (~(-1 << config.logical_shard_id_bits)) << config.logical_shard_id_shift
+    end
+
+    def timestamp_map
+      ~(-1 << config.timestamp_bits) << config.timestamp_shift
+    end
+  end
+end

data/lib/vin/lua_script.rb

@@ -0,0 +1,24 @@
+require "erb"
+require "vin/config"
+
+class VIN
+  module LuaScript
+    LUA_SCRIPT_PATH = "lua/id-generation.lua.erb".freeze
+
+    def self.generate_file(config: nil)
+      config ||= VIN::Config.new
+      binding = binding()
+      binding.local_variable_set(:config, config)
+      @generate_file ||= ERB.new(
+        File.read(
+          File.expand_path("../../#{LUA_SCRIPT_PATH}", File.dirname(__FILE__)),
+        ),
+      ).result(binding)
+    end
+
+    # Used in tests to ensure that the file is regenerated.
+    def self.reset_cache
+      @generate_file = nil
+    end
+  end
+end

data/lib/vin/mixins/redis.rb

@@ -0,0 +1,14 @@
+class VIN
+  module Mixins
+    module Redis
+      DEFAULT_REDIS_URL = "redis://127.0.0.1:6379".freeze
+
+      def redis
+        # TODO: Redis config for multiple servers
+        @redis ||= ::Redis.new(
+          url: ENV["VIN_REDIS_URL"] || ENV["REDIS_URL"] || DEFAULT_REDIS_URL,
+        )
+      end
+    end
+  end
+end

data/lib/vin/request.rb

@@ -0,0 +1,59 @@
+class VIN
+  class Request
+    include VIN::Mixins::Redis
+
+    MAX_TRIES = 5
+
+    attr_reader :data_type, :count, :config, :custom_timestamp
+
+    def initialize(config, data_type, count = 1, custom_timestamp: nil)
+      raise(ArgumentError, "data_type must be a number") unless data_type.is_a?(Numeric)
+      unless config.data_type_allowed_range.include?(data_type)
+        raise(ArgumentError, "data_type is outside the allowed range of #{config.data_type_allowed_range}")
+      end
+      raise(ArgumentError, "count must be a number") unless count.is_a?(Numeric)
+      raise(ArgumentError, "count must be greater than zero") unless count.positive?
+
+      @tries = 0
+      @data_type = data_type
+      @count = count
+      @config = config
+      @custom_timestamp = custom_timestamp
+    end
+
+    def response
+      Response.new(try_redis_response)
+    end
+
+    private
+
+    def lua_script_sha
+      @@lua_script_sha ||= redis.script(:load, LuaScript.generate_file(config: config))
+    end
+
+    def lua_keys
+      @lua_keys ||= [data_type, count, custom_timestamp].compact
+    end
+
+    # NOTE: If too many requests come in inside of a millisecond the Lua script
+    # will lock for 1ms and throw an error. This is meant to retry in those cases.
+    def try_redis_response
+      @tries += 1
+      redis_response
+    rescue Redis::CommandError => e
+      raise(e) unless @tries < MAX_TRIES
+
+      # Clear out the cache of the Lua script SHA to force a reload. This
+      # is necessary after a Redis restart
+      @@lua_script_sha = nil
+
+      # Exponentially sleep more and more on each try
+      sleep((@tries * @tries).to_f / 900)
+      retry
+    end
+
+    def redis_response
+      @redis_response ||= redis.evalsha(lua_script_sha, keys: lua_keys)
+    end
+  end
+end

data/lib/vin/response.rb

@@ -0,0 +1,41 @@
+class VIN
+  class Response
+    START_SEQUENCE_INDEX = 0
+    END_SEQUENCE_INDEX = 1
+    LOGICAL_SHARD_ID_INDEX = 2
+    SECONDS_INDEX = 3
+    MICROSECONDS_INDEX = 4
+
+    def initialize(redis_response)
+      @redis_response = redis_response
+    end
+
+    def sequence
+      start_sequence..end_sequence
+    end
+
+    def start_sequence
+      redis_response[START_SEQUENCE_INDEX]
+    end
+
+    def end_sequence
+      redis_response[END_SEQUENCE_INDEX]
+    end
+
+    def logical_shard_id
+      redis_response[LOGICAL_SHARD_ID_INDEX]
+    end
+
+    def seconds
+      redis_response[SECONDS_INDEX]
+    end
+
+    def microseconds_part
+      redis_response[MICROSECONDS_INDEX]
+    end
+
+    private
+
+    attr_reader :redis_response
+  end
+end

data/lib/vin/timestamp.rb

@@ -0,0 +1,48 @@
+class VIN
+  class Timestamp
+    ONE_SECOND_IN_MILLIS = 1_000
+    ONE_MILLI_IN_MICRO_SECS = 1_000
+
+    attr_reader :milliseconds, :epoch
+
+    def initialize(milliseconds, epoch: 0)
+      @milliseconds = milliseconds
+      @epoch = epoch
+    end
+
+    def seconds
+      (milliseconds / ONE_SECOND_IN_MILLIS).floor
+    end
+
+    def microseconds_part
+      (milliseconds - (seconds * ONE_SECOND_IN_MILLIS)) * ONE_MILLI_IN_MICRO_SECS
+    end
+
+    alias to_i milliseconds
+
+    def to_time
+      Time.at(with_unix_epoch.seconds, with_unix_epoch.microseconds_part)
+    end
+
+    def with_unix_epoch
+      @with_unix_epoch ||= with_epoch(0)
+    end
+
+    def with_epoch(new_epoch)
+      new_milliseconds = milliseconds - (new_epoch - epoch)
+
+      self.class.new(new_milliseconds, epoch: new_epoch)
+    end
+
+    def self.from_redis(seconds_part, microseconds_part)
+      # NOTE: we're dropping the microseconds here because we don't need that
+      # level of precision
+      milliseconds = (
+        (seconds_part * ONE_SECOND_IN_MILLIS) +
+        (microseconds_part / ONE_MILLI_IN_MICRO_SECS)
+      )
+
+      new(milliseconds)
+    end
+  end
+end

data/lib/vin/version.rb

@@ -0,0 +1,3 @@
+class VIN
+  VERSION = "1.0.0".freeze
+end

data/lib/vin.rb

@@ -0,0 +1,41 @@
+require "redis"
+require "vin/mixins/redis"
+
+class VIN
+  extend VIN::Mixins::Redis
+
+  def initialize(config: nil)
+    @config = config || VIN::Config.new
+  end
+
+  def generate_id(data_type, timestamp: nil)
+    generator.generate_ids(data_type, 1, timestamp: timestamp).first
+  end
+
+  def generate_ids(data_type, count, timestamp: nil)
+    ids = []
+    # The Lua script can't always return as many IDs as you may want. So we loop
+    # until we have the exact amount.
+    while ids.length < count
+      initial_id_count = ids.length
+      ids += generator.generate_ids(data_type, count - ids.length, timestamp: timestamp)
+      # Ensure the ids array keeps growing as infinite loop insurance
+      return ids unless ids.length > initial_id_count
+    end
+    ids
+  end
+
+  private
+
+  def generator
+    @generator ||= Generator.new(config: @config)
+  end
+end
+
+require "vin/generator"
+require "vin/id"
+require "vin/lua_script"
+require "vin/request"
+require "vin/response"
+require "vin/timestamp"
+require "vin/config"

data/lua/id-generation.lua.erb

@@ -0,0 +1,93 @@
+local last_logical_shard_id_key = 'vin-generator-last-logical-shard-id'
+local max_sequence = <%= config.max_sequence %>
+
+local data_type = tonumber(KEYS[1])
+local num_ids = tonumber(KEYS[2])
+local custom_timestamp = tonumber(KEYS[3]) -- Optional custom timestamp in Unix milliseconds (absolute time)
+
+-- Allow one server to acts as multiple shards
+local logical_shard_id_min = <%= config.logical_shard_id_range.min %>
+local logical_shard_id_max = <%= config.logical_shard_id_range.max %>
+
+local logical_shard_id = nil
+if redis.call('EXISTS', last_logical_shard_id_key) == 0 then
+  logical_shard_id = logical_shard_id_min
+else
+  local last_shard_id = tonumber(redis.call('GET', last_logical_shard_id_key))
+
+  if last_shard_id >= logical_shard_id_max or last_shard_id < logical_shard_id_min then
+    logical_shard_id = logical_shard_id_min
+  else
+    logical_shard_id = last_shard_id + 1
+  end
+end
+
+redis.call('SET', last_logical_shard_id_key, logical_shard_id)
+
+--[[
+Scope lock and sequence keys to the specific data_type being requested.
+Ideally, we'd also use the logical_shard_id in the keys so that any per-millisecond limitations would only be per-shard,
+but unfortunately the whole "pure function" limitation keeps us from using a random shard_id here. The best solution may
+be to round robin the shard ID by incrementing a Redis key on each call.
+]]--
+local lock_key = 'vin-generator-lock-' .. logical_shard_id .. '-' .. data_type
+local sequence_key = 'vin-generator-sequence-' .. logical_shard_id .. '-' .. data_type
+
+if redis.call('EXISTS', lock_key) == 1 then
+  redis.log(redis.LOG_NOTICE, 'VIN: Cannot generate ID, waiting for lock to expire.')
+  return redis.error_reply('VIN: Cannot generate ID, waiting for lock to expire.')
+end
+
+-- Increment by a set number
+local end_sequence = redis.call('INCRBY', sequence_key, num_ids)
+local start_sequence = end_sequence - num_ids + 1
+
+if end_sequence >= max_sequence then
+  --[[
+  As the sequence is about to roll around, we can't generate another ID until we're sure we're not in the same
+  millisecond since we last rolled. This is because we may have already generated an ID with the same time and
+  sequence, and we cannot allow even the smallest possibility of duplicates. It's also because if we roll the sequence
+  around, we will start generating IDs with smaller values than the ones previously in this millisecond - that would
+  break our k-ordering guarantees!
+
+  The only way we can handle this is to block for a millisecond, as we can't store the time due the purity constraints
+  of Redis Lua scripts.
+
+  In addition to a neat side-effect of handling leap seconds (where milliseconds will last a little bit longer to bring
+  time back to where it should be) because Redis uses system time internally to expire keys, this prevents any duplicate
+  IDs from being generated if the rate of generation is greater than the maximum sequence per millisecond.
+
+  Note that it only blocks even it rolled around *not* in the same millisecond; this is because unless we do this, the
+  IDs won't remain ordered.
+  --]]
+  redis.log(redis.LOG_NOTICE, 'VIN: Rolling sequence back to the start, locking for 1ms.')
+  redis.call('SET', sequence_key, '-1')
+  redis.call('PSETEX', lock_key, 1, 'lock')
+  end_sequence = max_sequence
+end
+
+--[[
+The TIME command MUST be called after anything that mutates state, or the Redis server will error the script out.
+This is to ensure the script is "pure" in the sense that randomness or time based input will not change the
+outcome of the writes.
+
+See the "Scripts as pure functions" section at http://redis.io/commands/eval for more information.
+--]]
+local seconds, microseconds
+if custom_timestamp then
+  -- Custom timestamp is already in Unix milliseconds (absolute time)
+  seconds = math.floor(custom_timestamp / 1000)
+  microseconds = (custom_timestamp % 1000) * 1000
+else
+  local time = redis.call('TIME')
+  seconds = tonumber(time[1])
+  microseconds = tonumber(time[2])
+end
+
+return {
+  start_sequence,
+  end_sequence, -- Doesn't need conversion, the result of INCR or the variable set is always a number.
+  logical_shard_id,
+  seconds,
+  microseconds
+}

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: hoov_vin
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Roger Oba
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-08-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: A customizable Redis-powered Ruby client for generating unique, monotonically-increasing
+  integer IDs, for use in distributed systems and databases. Powered by Redis, drawing
+  heavy inspiration from Icicle, Twitter Snowflake, and Dogtag.
+email: roger@hoov.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/vin.rb
+- lib/vin/config.rb
+- lib/vin/generator.rb
+- lib/vin/id.rb
+- lib/vin/lua_script.rb
+- lib/vin/mixins/redis.rb
+- lib/vin/request.rb
+- lib/vin/response.rb
+- lib/vin/timestamp.rb
+- lib/vin/version.rb
+- lua/id-generation.lua.erb
+homepage: https://github.com/hoovbr/vin
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hoovbr/vin
+  source_code_uri: https://github.com/hoovbr/vin
+  changelog_uri: https://github.com/hoovbr/vin/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+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: A Redis-powered Ruby ID generation client
+test_files: []