uuid-v9 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30c3ab5576199b652feaba4dd0b27d093b0f0ca2f360235928db75cbed640f0c
+  data.tar.gz: c3dbea2d7e23028bc48bb5a8615f92daa8d191cf5711cdba5b0e46d244174690
+SHA512:
+  metadata.gz: a8d7628ee54094f1627f42723e2953c1805ca1629e8701f485882a96e9e3c4b98106a0abc34d80b4c3c4df71a1431405ff5aec6eb5e01f96981e85388b02952c
+  data.tar.gz: 26eaa520c36ffe03a75f25edbd301989353f14e3e504b480e392a56d5e0af380e66be8ff315a93ac01480442cb6dcec2021014d724840a062a7728d399177a22

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 JHunt
+
+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,47 @@
+# UUID v9
+
+## Fast, lightweight, zero-dependency Ruby implementation of UUID version 9
+
+The v9 UUID supports both sequential (time-based) and non-sequential (random) UUIDs with an optional prefix of up to four bytes, an optional checksum, and sufficient randomness to avoid collisions. It uses the UNIX timestamp for sequential UUIDs and CRC-8 for checksums. A version digit can be added if desired, but is omitted by default.
+
+To learn more about UUID v9, please visit the website: https://uuidv9.jhunt.dev
+
+## Installation
+
+Install UUID v9 from Rubygems
+
+```bash
+gem install uuid_v9
+```
+
+## Usage
+
+```ruby
+require 'uuid_v9'
+
+ordered_id = UUIDv9::UUIDv9.generate
+prefixed_ordered_id = UUIDv9::UUIDv9.generate(prefix: 'a1b2c3d4')
+unordered_id = UUIDv9::UUIDv9.generate(timestamp: false)
+prefixed_unordered_id = UUIDv9::UUIDv9.generate(prefix: 'a1b2c3d4', timestamp: false)
+ordered_id_with_checksum = UUIDv9::UUIDv9.generate(checksum: true)
+ordered_id_with_version = UUIDv9::UUIDv9.generate(version: true)
+ordered_id_with_legacy_mode = UUIDv9::UUIDv9.generate(legacy: true)
+
+is_valid = UUIDv9::UUIDv9.valid?(ordered_id)
+is_valid_with_checksum = UUIDv9::UUIDv9.valid?(ordered_id_with_checksum, checksum: true)
+is_valid_with_version = UUIDv9::UUIDv9.valid?(ordered_id_with_version, version: true)
+```
+
+## Backward Compatibility
+
+Some UUID validators check for specific features of v1 or v4 UUIDs. This causes some valid v9 UUIDs to appear invalid. Three possible workarounds are:
+
+1) Use the built-in validator (recommended)
+2) Use legacy mode*
+3) Bypass the validator (not recommended)
+
+_*Legacy mode adds version and variant digits to immitate v1 or v4 UUIDs depending on the presence of a timestamp._
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

data/lib/uuid-v9.rb

@@ -0,0 +1,108 @@
+class UUIDv9
+  UUID_REGEX = /^[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}$/
+  BASE16_REGEX = /^[0-9a-fA-F]+$/
+
+  def self.calc_checksum(hex_string)
+    data = hex_string.scan(/.{1,2}/).map { |byte| byte.to_i(16) }
+    polynomial = 0x07
+    crc = 0x00
+  
+    data.each do |byte|
+      crc ^= byte
+      8.times do
+        if crc & 0x80 != 0
+          crc = (crc << 1) ^ polynomial
+        else
+          crc <<= 1
+        end
+      end
+    end
+  
+    crc &= 0xFF
+    crc.to_s(16).rjust(2, '0')
+  end
+
+  def self.verify_checksum(uuid)
+    base16_string = uuid.delete('-')[0, 30]
+    crc = calc_checksum(base16_string)
+    crc == uuid[34, 2]
+  end
+
+  def self.check_version(uuid, version = nil)
+    version_digit = uuid[14]
+    variant_digit = uuid[19]
+    (!version || version_digit == version) &&
+      (version_digit == '9' || (['1', '4'].include?(version_digit) && "89abAB".include?(variant_digit)))
+  end
+
+  def self.is_uuid?(uuid)
+    !uuid.empty? && UUID_REGEX.match?(uuid)
+  end
+
+  def self.is_valid_uuidv9?(uuid, options)
+    is_uuid?(uuid) &&
+      (!options.key?(:checksum) || !options[:checksum] || verify_checksum(uuid)) &&
+      (!options.key?(:version) || !options[:version] || check_version(uuid))
+  end
+
+  def self.random_bytes(count)
+    Array.new(count) { rand(0..15).to_s(16) }.join
+  end
+
+  def self.random_char(chars)
+    chars[rand(chars.length)]
+  end
+
+  def self.is_base16?(str)
+    BASE16_REGEX.match?(str)
+  end
+
+  def self.validate_prefix(prefix)
+    raise ArgumentError, 'Prefix must be a string' if prefix.nil?
+    raise ArgumentError, 'Prefix must be no more than 8 characters' if prefix.length > 8
+    raise ArgumentError, 'Prefix must be only hexadecimal characters' unless is_base16?(prefix)
+  end
+
+  def self.add_dashes(str)
+    "#{str[0, 8]}-#{str[8, 4]}-#{str[12, 4]}-#{str[16, 4]}-#{str[20..]}"
+  end
+
+  def self.generate(options = {})
+    prefix = options.fetch(:prefix, nil).to_s
+    timestamp = options.fetch(:timestamp, true)
+    checksum = options.fetch(:checksum, false)
+    version = options.fetch(:version, false)
+    legacy = options.fetch(:legacy, false)
+
+    if prefix && !prefix.empty?
+      validate_prefix(prefix)
+      prefix = prefix.downcase
+    end
+
+    center = case timestamp
+            when true
+              Time.now.to_i.to_s(16)
+            when Time
+              timestamp.to_i.to_s(16)
+            when Numeric, String
+              Time.at(timestamp.to_i).to_i.to_s(16)
+            else
+              ''
+            end
+
+    suffix_length = 32 - prefix.length - center.length - (checksum ? 2 : 0) - (legacy ? 2 : (version ? 1 : 0))
+    suffix = random_bytes(suffix_length)
+
+    joined = "#{prefix}#{center}#{suffix}"
+
+    if legacy
+      joined = "#{joined[0, 12]}#{center.length > 0 ? '1' : '4'}#{joined[12, 3]}#{random_char('89ab')}#{joined[15..]}"
+    elsif version
+      joined = "#{joined[0, 12]}9#{joined[12..]}"
+    end
+
+    joined += calc_checksum(joined) if checksum
+
+    add_dashes(joined)
+  end
+end

data/spec/uuid-v9_spec.rb

@@ -0,0 +1,133 @@
+require 'rspec/autorun'
+require_relative '../lib/uuid-v9'
+
+UUID_REGEX = /^[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}$/
+UUID_V1_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-1[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/
+UUID_V4_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/
+UUID_V9_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-9[0-9a-fA-F]{3}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+
+describe 'UUIDv9' do
+  it 'should validate as a UUID' do
+    id1 = UUIDv9.generate()
+    id2 = UUIDv9.generate({ prefix: 'a1b2c3d4' })
+    id3 = UUIDv9.generate({ prefix: 'a1b2c3d4', timestamp: false })
+    id4 = UUIDv9.generate({ prefix: 'a1b2c3d4', checksum: true })
+    id5 = UUIDv9.generate({ prefix: 'a1b2c3d4', checksum: true, version: true })
+    id6 = UUIDv9.generate({ prefix: 'a1b2c3d4', checksum: true, legacy: true })
+
+    expect(UUID_REGEX.match?(id1)).to be true
+    expect(UUID_REGEX.match?(id2)).to be true
+    expect(UUID_REGEX.match?(id3)).to be true
+    expect(UUID_REGEX.match?(id4)).to be true
+    expect(UUID_REGEX.match?(id5)).to be true
+    expect(UUID_REGEX.match?(id6)).to be true
+  end
+
+  it 'should generate sequential UUIDs' do
+    id1 = UUIDv9.generate()
+    sleep(1)
+    id2 = UUIDv9.generate()
+    sleep(1)
+    id3 = UUIDv9.generate()
+
+    expect(id1 < id2).to be true
+    expect(id2 < id3).to be true
+  end
+
+  it 'should generate sequential UUIDs with a prefix' do
+    id1 = UUIDv9.generate({ prefix: 'a1b2c3d4' })
+    sleep(1)
+    id2 = UUIDv9.generate({ prefix: 'a1b2c3d4' })
+    sleep(1)
+    id3 = UUIDv9.generate({ prefix: 'a1b2c3d4' })
+
+    expect(id1 < id2).to be true
+    expect(id2 < id3).to be true
+    expect(id1[0, 8]).to eq 'a1b2c3d4'
+    expect(id2[0, 8]).to eq 'a1b2c3d4'
+    expect(id3[0, 8]).to eq 'a1b2c3d4'
+    expect(id1[9, 8]).to eq id2[9, 8]
+    expect(id2[9, 8]).to eq id3[9, 8]
+  end
+
+  it 'should generate non-sequential UUIDs' do
+    id_s = UUIDv9.generate({ timestamp: false })
+    sleep(1)
+    id_ns = UUIDv9.generate({ timestamp: false })
+
+    expect(id_s[0, 4]).not_to eq id_ns[0, 4]
+  end
+
+  it 'should generate non-sequential UUIDs with a prefix' do
+    id_s = UUIDv9.generate({ prefix: 'a1b2c3d4', timestamp: false })
+    sleep(1)
+    id_ns = UUIDv9.generate({ prefix: 'a1b2c3d4', timestamp: false })
+
+    expect(id_s[0, 8]).to eq 'a1b2c3d4'
+    expect(id_ns[0, 8]).to eq 'a1b2c3d4'
+    expect(id_s[9, 8]).not_to eq id_ns[9, 8]
+  end
+
+  it 'should generate UUIDs with a checksum' do
+    id1 = UUIDv9.generate({ checksum: true })
+    id2 = UUIDv9.generate({ timestamp: false, checksum: true })
+
+    expect(UUID_REGEX.match?(id1)).to be true
+    expect(UUID_REGEX.match?(id2)).to be true
+    expect(UUIDv9.verify_checksum(id1)).to be true
+    expect(UUIDv9.verify_checksum(id2)).to be true
+  end
+
+  it 'should generate UUIDs with a version' do
+    id1 = UUIDv9.generate({ version: true })
+    id2 = UUIDv9.generate({ timestamp: false, version: true })
+
+    expect(UUID_REGEX.match?(id1)).to be true
+    expect(UUID_REGEX.match?(id2)).to be true
+    expect(UUID_V9_REGEX.match?(id1)).to be true
+    expect(UUID_V9_REGEX.match?(id2)).to be true
+  end
+
+  it 'should generate backward compatible UUIDs' do
+    id1 = UUIDv9.generate({ checksum: true, legacy: true })
+    id2 = UUIDv9.generate({ prefix: 'a1b2c3d4', legacy: true })
+    id3 = UUIDv9.generate({ timestamp: false, legacy: true })
+    id4 = UUIDv9.generate({ prefix: 'a1b2c3d4', timestamp: false, legacy: true })
+
+    expect(UUID_REGEX.match?(id1)).to be true
+    expect(UUID_REGEX.match?(id2)).to be true
+    expect(UUID_REGEX.match?(id3)).to be true
+    expect(UUID_REGEX.match?(id4)).to be true
+    expect(UUID_V1_REGEX.match?(id1)).to be true
+    expect(UUID_V1_REGEX.match?(id2)).to be true
+    expect(UUID_V4_REGEX.match?(id3)).to be true
+    expect(UUID_V4_REGEX.match?(id4)).to be true
+  end
+
+  it 'should correctly validate and verify checksum' do
+    id1 = UUIDv9.generate({ checksum: true })
+    id2 = UUIDv9.generate({ timestamp: false, checksum: true })
+    id3 = UUIDv9.generate({ prefix: 'a1b2c3d4', checksum: true })
+    id4 = UUIDv9.generate({ prefix: 'a1b2c3d4', timestamp: false, checksum: true })
+    id5 = UUIDv9.generate({ checksum: true, version: true })
+    id6 = UUIDv9.generate({ checksum: true, legacy: true })
+    id7 = UUIDv9.generate({ timestamp: false, checksum: true, legacy: true })
+
+    expect(UUIDv9.is_uuid?(id1)).to be true
+    expect(UUIDv9.is_uuid?('not-a-real-uuid')).to be false
+    expect(UUIDv9.is_valid_uuidv9?(id1, { checksum: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id2, { checksum: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id3, { checksum: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id4, { checksum: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id5, { checksum: true, version: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id6, { checksum: true, version: true })).to be true
+    expect(UUIDv9.is_valid_uuidv9?(id7, { checksum: true, version: true })).to be true
+    expect(UUIDv9.verify_checksum(id1)).to be true
+    expect(UUIDv9.verify_checksum(id2)).to be true
+    expect(UUIDv9.verify_checksum(id3)).to be true
+    expect(UUIDv9.verify_checksum(id4)).to be true
+    expect(UUIDv9.verify_checksum(id5)).to be true
+    expect(UUIDv9.verify_checksum(id6)).to be true
+    expect(UUIDv9.verify_checksum(id7)).to be true
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: uuid-v9
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- JHunt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-17 00:00:00.000000000 Z
+dependencies: []
+description: '"The v9 UUID supports both sequential (time-based) and non-sequential
+  (random) UUIDs with an optional prefix of up to four bytes, an optional checksum,
+  and sufficient randomness to avoid collisions. It uses the UNIX timestamp for sequential
+  UUIDs and CRC-8 for checksums. A version digit can be added if desired, but is omitted
+  by default."'
+email:
+- hello@jhunt.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/uuid-v9.rb
+- spec/uuid-v9_spec.rb
+homepage: https://uuidv9.jhunt.dev
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: '"Fast, lightweight, zero-dependency Ruby implementation of UUID version
+  9"'
+test_files: []