uuidx 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2e41b677c8a6cb523605c6f10620796d1b5831ad511a32b49e8d98415629677
+  data.tar.gz: 8e8935a0b62e6538a5de355ec22119a0cba5242a3c76767bb720d5d13192431d
+SHA512:
+  metadata.gz: ff313efefe5c2ccca58479e2e208cd98d636b74e5311f5e29de20faaf5207f47baf708c304c2e15275fa2a75b26d0f050f7c38174ddeaadcbf8e9449e9dd8a1c
+  data.tar.gz: 4def103fd92484499eef8474454eed8e7f6bc2a0e975e7f22deabe986d02f12d957b7bf2457b8d6c6101e66c4789cffaf3844812b6b0e973c95950e7b7abfbf5

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Unreleased
+
+# Stable Releases
+
+## 1.0.0 – ???
+
+# Alpha Releases
+
+## 0.9.0 – 2023-02-11
+- Swap gem name to shorter uuidx
+- Main documentation written
+- Add type signatures
+- Add monotonic batch support to simple API.
+
+## 0.8.0 – 2023-02-10
+- Add simple Uuid generation API
+- Generator classes are now lock-free
+- Remove UUID value type
+
+## 0.7.0 – 2023-02-10
+- Generator APIs now return opaque string values for UUIDs
+- Add faster UUID v4 implementation
+
+## 0.6.0 – 2023-02-04
+- Convert generator modules to classes
+- Fix clock ID references in UUID v7
+- Pass tests on all supported versions of Ruby
+
+## 0.5.0 – 2023-01-31
+- Threading safety for clock sequence in UUID v6
+- Clock drift detection in UUID v6
+
+## 0.4.0 – 2023-01-26
+- Add clock resolution verification methods
+- UUID v6 and v7 are now thread-safe
+
+## 0.3.0 – 2023-01-25
+- New, faster design of UUID generator modules
+- Removal of old implementations
+
+## 0.2.0 – 2023-01-22
+- UUID v6, v7, and v8 implemented quickly
+- Some performance optimization done
+
+## 0.1.0 – 2023-01-18
+- Initial release without design considerations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 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,195 @@
+<h1 align="center">uuidx</h1>
+<p align="center">Fast Ruby implementations of UUID versions 4, 6, 7, and 8 🪪</p> 
+
+---
+
+## What's in the box?
+
+✅ Simple usage documentation written to get started fast. [30 seconds and you're off.](#usage)
+
+📚 API documentation for the library. [Read the docs.](https://tinychameleon.github.io/uuidx/)
+
+⚡ A reasonably fast, zero dependency implementation of the new UUID standards.
+
+🤖 RBS types for your type checking wants. [Typed goodness.](./sig)
+
+💎 Tests against Ruby 2.7, 3.0, 3.1, and 3.2.
+
+🔒 MFA protection on gem owners.
+
+---
+
+## Installation
+
+### Using Bundler
+
+Run `bundle add uuidx` to update your `Gemfile` and install the gem. You may
+also add the gem to your `Gemfile` manually and then run `bundle install`.
+
+### Manual
+
+Use `gem install uuidx` to install the gem from [RubyGems](https://rubygems.org).
+
+## Usage
+
+To get started using the default generators for UUID v4, v6, or v7 `require`
+the library and call the associated method.
+
+```ruby
+require "uuidx"
+
+Uuid.v4 # => "2b54639d-e43e-489f-9c64-30ecdcac3c95"
+Uuid.v6 # => "1eda9761-9f6f-6414-8c5f-fd61f1239907"
+Uuid.v7 # => "01863d24-6d1e-78ba-92ee-6e80c79c4e28"
+```
+
+These methods all use default generators and are thread-safe. However, if you
+are using child processes (like Puma's clustered mode) you should also reset
+the generators you are using when each child process starts.
+
+```ruby
+# Puma example that resets all default generators.
+on_worker_boot do
+  Uuid.reset_v4!
+  Uuid.reset_v6!
+  Uuid.reset_v7!
+end
+```
+
+This way you will get thread-safe state access per process without requiring
+IPC.
+
+### Monotonicity & Batching
+The simple API provided by `Uuid` also supports monotonic batches. Provide the
+batch size and you will receive an array of UUID values back.
+
+```ruby
+Uuid.batch_v4(10) # => ["2b54639d-e43e-489f-9c64-30ecdcac3c95", ...]
+Uuid.batch_v6(10) # => ["1eda9761-9f6f-6414-8c5f-fd61f1239907", ...]
+Uuid.batch_v7(10) # => ["01863d24-6d1e-78ba-92ee-6e80c79c4e28", ...]
+```
+
+### Advanced Usage
+If you require multiple generators you can drop below the simple API presented
+above to create generators directly.
+
+```ruby
+v6 = Uuid::Version6.new
+v6.generate # => "1eda9adc-2ed9-629e-9a02-4d2ccc87c569"
+```
+
+These generators are lock-free, so if you use them to obtain higher throughput
+keep in mind that you must ensure they are never shared between threads.
+
+For typical MRI Ruby workloads using multi-process worker strategies state will
+be cloned and modified using copy-on-write and the thread safety provided by
+the simple API is adequate.
+
+#### UUID v8
+UUID v8 is a special case of advanced usage that always requires you to build
+a generator directly. It takes a single parameter to its constructor which must
+be the class name of your UUID v8 definition.
+
+```ruby
+v8 = Uuid::Version8.new(MyV8Definition)
+v8.generate # => "..."
+```
+
+The definition class should implement the methods `custom_a`, `custom_b`, and
+`custom_c` in order to fill out the UUID data [according to the draft](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-uuid-version-8).
+
+See the [documentation for Version8](https://tinychameleon.github.io/uuidx/Uuid/Version8.html) for precise details.
+
+#### Batching
+Any custom UUID v8 generators can also participate in thread-safe batching by using
+the `batch` method.
+
+```ruby
+Uuid.batch(v8, 10) # => ["<a v8 uuid>", ...]
+```
+
+### Clock Resolution
+If you have need to verify the clock resolution for UUID v6 or v7 you can call
+the `verify_clock_resolution!` method on either class. A `ClockResolutionError`
+is raised if the system has insufficient precision.
+
+```ruby
+begin
+  Uuid::Version6.verify_clock_resolution! # or Uuid::Version7
+rescue Uuid::ClockResolutionError
+  # ...
+end
+```
+
+The API documentation has details about what the clock resolution must be for
+each of the UUID versions. See the
+[Version 6](https://tinychameleon.github.io/uuidx/Uuid/Version6.html) and
+[Version 7](https://tinychameleon.github.io/uuidx/Uuid/Version7.html)
+documentation for details.
+
+### A Note on Clock Timings
+The API documentation contains specific details around how the implementations
+deal with clock drift. See the
+[Uuid](https://tinychameleon.github.io/uuidx/Uuid.html),
+[Version 6](https://tinychameleon.github.io/uuidx/Uuid/Version6.html), and
+[Version 7](https://tinychameleon.github.io/uuidx/Uuid/Version7.html)
+documentation for more information.
+
+## Performance
+This performance data was captured using `benchmark/ips`. It uses the following
+Ruby version
+
+    ruby 3.2.0 (2022-12-25 revision a528908271) [arm64-darwin22]
+
+and is run on a Macbook Pro with an M1 Max CPU.
+
+    ❯ bundle exec ruby test/benchmarks/simple_api.rb 
+    Warming up --------------------------------------
+                  stdlib    60.617k i/100ms
+                   uuid4   106.927k i/100ms
+                   uuid6   111.417k i/100ms
+                   uuid7   103.551k i/100ms
+    Calculating -------------------------------------
+                  stdlib    626.957k (± 0.3%) i/s -      3.152M in   5.027633s
+                   uuid4      1.077M (± 1.2%) i/s -      5.453M in   5.065726s
+                   uuid6      1.121M (± 0.2%) i/s -      5.682M in   5.067392s
+                   uuid7      1.027M (± 1.3%) i/s -      5.178M in   5.041666s
+    
+    Comparison:
+                   uuid6:  1121344.6 i/s
+                   uuid4:  1076662.4 i/s - 1.04x  (± 0.00) slower
+                   uuid7:  1027127.8 i/s - 1.09x  (± 0.00) slower
+                  stdlib:   626957.1 i/s - 1.79x  (± 0.00) slower
+
+
+As reported, the `stdlib` version of `SecureRandom.uuid` is at least 1.70x
+slower than the simple API implementation of UUID v4.
+
+These timings are good enough that they shouldn't get in the way of any web
+frameworks.
+
+## Development
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To run tests across all supported Ruby versions on Debian and Alpine Linux run
+`make test-all`. To run a specific version use `make test-[version]`;
+for example, `make test-3.2.0`.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version:
+
+1. ensure the documentation and changelog are ready
+2. run `bundle exec rake rdoc` to generate the new documentation and commit it
+3. update the version number in `lib/uuid/gem_version.rb`
+4. run `bundle install` to update the `Gemfile.lock`
+5. create a release commit with the version updates
+6. run `bundle exec rake release` to tag and push the version to RubyGems
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/tinychameleon/uuidx.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/uuid/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Uuid
+  # Top-level error for all Uuid errors.
+  class Error < StandardError
+  end
+
+  # Raised when the clock resolution is insufficient for a UUID Version.
+  class ClockResolutionError < Error
+  end
+end

data/lib/uuid/gem_version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Uuid
+  # The gem version.
+  VERSION = "0.9.0"
+end

data/lib/uuid/version4.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Uuid
+  # UUID Version 7 defined by the
+  # {RFC 4122 BIS-01 Draft}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-uuid-version-4].
+  #
+  # To construct a new UUID v4 value create a generator, then use #generate.
+  #   g = Uuid::Version4.new
+  #   g.generate # => "2b54639d-e43e-489f-9c64-30ecdcac3c95"
+  #
+  # The implementation will cache 1024 bytes of random data from +SecureRandom+ to facilitate faster construction.
+  class Version4
+    VERSION_VARIANT = (0x4 << 76) | (0x2 << 62) # :nodoc:
+    BUFFER_SIZE = 64 # :nodoc:
+    NEEDED_BYTES = BUFFER_SIZE * 16 # :nodoc:
+    UNPACK_FORMAT = "QQ" * BUFFER_SIZE # :nodoc:
+    RANDOM_AB_MASK = 0xffffffff_ffff0fff # :nodoc:
+    AB_SHIFT = 64 # :nodoc:
+    RANDOM_C_MASK = 0x3fffffff_ffffffff # :nodoc:
+
+    # Construct a UUID v4 generator.
+    def initialize
+      @pool = []
+    end
+
+    # Construct a UUID v4 value.
+    def generate
+      @pool = SecureRandom.bytes(NEEDED_BYTES).unpack(UNPACK_FORMAT) if @pool.empty?
+      ab, c = @pool.pop(2)
+
+      Uuid.format(VERSION_VARIANT | ((ab & RANDOM_AB_MASK) << AB_SHIFT) | (c & RANDOM_C_MASK))
+    end
+  end
+end

data/lib/uuid/version6.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Uuid
+  # UUID Version 6 defined by the
+  # {RFC 4122 BIS-01 Draft}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-uuid-version-6].
+  #
+  # To construct a new UUID v6 value create a generator, then use #generate.
+  #   g = Uuid::Version6.new
+  #   g.generate # => "1eda9761-9f6f-6414-8c5f-fd61f1239907"
+  #
+  # The implementation will use +SecureRandom+ to populate the Node and Clock Sequence bits with a random value
+  # at module load time.
+  #
+  # Generation is thread-safe, but if you are using multi-process clusters you should call #reset! at the start
+  # of each process to reduce the chance of two processes generating the same value.
+  #
+  # If you have need to make sure that the clock resolution is sufficient for the v6 specification
+  # you can call ::verify_clock_resolution! and handle the ClockResolutionError as you see fit.
+  #
+  #   begin
+  #     Uuid::Version6.verify_clock_resolution!
+  #   rescue Uuid::ClockResolutionError
+  #     # ...
+  #   end
+  #
+  # The necessary clock resolution for v6 is 100ns.
+  #
+  # ===== A Note on Clock Timings
+  # To combat clock drift, leap-second smearing, and other clock value changes that can appear without
+  # requiring additional compute cost this implementation always increments the clock sequence number.
+  class Version6
+    VERSION_VARIANT = (0x6 << 76) + (0x2 << 62) # :nodoc:
+    GREGORIAN_MICROSECOND_TENTHS = 122_192_928_000_000_000 # :nodoc:
+    CLOCK_SEQ_SHIFT = 48 # :nodoc:
+    CLOCK_SEQ_INCREMENT = 1 << CLOCK_SEQ_SHIFT # :nodoc:
+    CLOCK_SEQ_MASK = 0x3fff << CLOCK_SEQ_SHIFT # :nodoc:
+    TS_NS_FACTOR = 100 # :nodoc:
+    TS_LOW_MASK = 0xfff # :nodoc:
+    TS_HIGH_MID_MASK = 0xffffffff_ffff0000 # :nodoc:
+    TS_MASK_SHIFT = 4 # :nodoc:
+    TS_POSITIONAL_SHIFT = 64 # :nodoc:
+    NODE_ID_MASK   = 0xffff_ffffffff # :nodoc:
+    NODE_ID_MC_BIT = 0x0100_00000000 # :nodoc:
+
+    # Construct a new UUID v6 generator.
+    def initialize
+      reset!
+    end
+
+    # Construct a UUID v6 value.
+    def generate
+      @clock_sequence = (@clock_sequence + CLOCK_SEQ_INCREMENT) & CLOCK_SEQ_MASK
+
+      ts = GREGORIAN_MICROSECOND_TENTHS + (Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond) / TS_NS_FACTOR)
+      ts = ((ts << TS_MASK_SHIFT) & TS_HIGH_MID_MASK) | (ts & TS_LOW_MASK)
+
+      Uuid.format(VERSION_VARIANT | (ts << TS_POSITIONAL_SHIFT) | @clock_sequence | @node_id)
+    end
+
+    # Reset the generator with a new random node ID and clock sequence.
+    #
+    # This method is not thread-safe and should only be called at application or child process start.
+    def reset!
+      @node_id = (SecureRandom.bytes(8).unpack1("Q") & NODE_ID_MASK) | NODE_ID_MC_BIT
+      @clock_sequence = SecureRandom.bytes(4).unpack1("L") << CLOCK_SEQ_SHIFT
+    end
+
+    # Verify that the clock resolution is capable of 100ns resolution.
+    #
+    # Raises ClockResolutionError when the clock resolution is insufficient.
+    def self.verify_clock_resolution!
+      ns_res = Process.clock_getres(Process::CLOCK_REALTIME, :nanosecond)
+      raise ClockResolutionError, "Detected #{ns_res}ns resolution, need <= 100ns" if ns_res > 100
+
+      true
+    end
+  end
+end

data/lib/uuid/version7.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Uuid
+  # UUID Version 7 defined by the
+  # {RFC 4122 BIS-01 Draft}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-uuid-version-7].
+  #
+  # To construct a new UUID v7 value create a generator, then use #generate.
+  #   g = Uuid::Version7.new
+  #   g.generate # => "01863d24-6d1e-78ba-92ee-6e80c79c4e28"
+  #
+  # The implementation will cache 640 bytes of random data from +SecureRandom+ to facilitate faster construction.
+  #
+  # If you have need to make sure that the clock resolution is sufficient for the v7 specification
+  # you can call ::verify_clock_resolution! and handle the ClockResolutionError as you see fit.
+  #
+  #   begin
+  #     Uuid::Version7.verify_clock_resolution!
+  #   rescue Uuid::ClockResolutionError
+  #     # ...
+  #   end
+  #
+  # The necessary clock resolution for v6 is 1ms.
+  #
+  # ===== A Note on Clock Timings
+  # To combat clock drift, leap-second smearing, and other clock value changes that can appear without
+  # requiring additional compute cost this implementation relies on secure random data to have sufficient
+  # variation such that all generated UUIDs within 1ms have a low probability of collision.
+  #
+  # For a 0.001% chance of collision, the 74 bits of random data will require between 6.1×10^6 and 4.0×10^11
+  # UUIDs to be generated in 1ms.
+  class Version7
+    VERSION_VARIANT = (0x7 << 76) | (0x2 << 62) # :nodoc:
+    BUFFER_SIZE = 64 # :nodoc:
+    NEEDED_BYTES = BUFFER_SIZE * 10 # :nodoc:
+    UNPACK_FORMAT = "SQ" * BUFFER_SIZE # :nodoc:
+    TS_MASK = 0xffff_ffffffff # :nodoc:
+    RAND_A_MASK = 0xfff # :nodoc:
+    RAND_B_MASK = 0x3fffffff_ffffffff # :nodoc:
+    TS_SHIFT = 16 # :nodoc:
+    HIGH_SHIFT = 64 # :nodoc:
+
+    # Construct a UUID v7 generator.
+    def initialize
+      @pool = []
+    end
+
+    # Construct a UUID v7 value.
+    def generate
+      @pool = SecureRandom.bytes(NEEDED_BYTES).unpack(UNPACK_FORMAT) if @pool.empty?
+      a, b = @pool.pop(2)
+      ts = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) & TS_MASK
+      high = (ts << TS_SHIFT) | (a & RAND_A_MASK)
+
+      Uuid.format(VERSION_VARIANT | (high << HIGH_SHIFT) | (b & RAND_B_MASK))
+    end
+
+    # Verify that the clock resolution is capable of 1ms resolution.
+    #
+    # Raises ClockResolutionError when the clock resolution is insufficient.
+    def self.verify_clock_resolution!
+      ms_res = Process.clock_getres(Process::CLOCK_REALTIME, :millisecond)
+      raise ClockResolutionError, "Detected #{ms_res}ms resolution, need <= 1ms" if ms_res > 1
+
+      true
+    end
+  end
+end

data/lib/uuid/version8.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Uuid
+  # UUID Version 8 defined by the
+  # {RFC 4122 BIS-01 Draft}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-uuid-version-8].
+  #
+  # Since UUID v8 is entirely custom to your application, first create a generator definition class.
+  #   class MyGeneratorDefinition
+  #     def custom_a
+  #       1
+  #     end
+  #
+  #     def custom_b
+  #       2
+  #     end
+  #
+  #     def custom_c
+  #       3
+  #     end
+  #   end
+  #
+  # The requirements for each method are:
+  #
+  # - +custom_a+ should generate a 48-bit value which will be the most significant 6 octets.
+  # - +custom_b+ should generate a 12-bit value which is placed between the version and variant bits.
+  # - +custom_c+ should generate a 62-bit value which acts as the remaining least significant octets.
+  #
+  # Then create a UUID v8 generator by passing in the class, and call #generate.
+  #   g = Uuid::Version8.new(MyGeneratorDefinition)
+  #   g.generate # => "00000000-0001-8002-8000-000000000003"
+  #
+  # The implementation will truncate the results of each generator module method so that they abide by the bit lengths
+  # of the UUID specification. The thread safety of UUID v8 depends entirely on your implementation.
+  #
+  # There is no default implementation of UUID v8.
+  class Version8
+    VERSION_VARIANT = (0x8 << 76) | (0x2 << 62) # :nodoc:
+    CUSTOM_A_MASK = 0xffff_ffffffff # :nodoc:
+    CUSTOM_B_MASK = 0xfff # :nodoc:
+    CUSTOM_C_MASK = 0x3fffffff_ffffffff # :nodoc:
+    A_SHIFT = 16 # :nodoc:
+    HIGH_SHIFT = 64 # :nodoc:
+
+    # Construct a UUID v8 generator.
+    def initialize(definition_class)
+      @definition = definition_class.new
+    end
+
+    # Construct a UUID v8 value.
+    def generate
+      a = @definition.custom_a & CUSTOM_A_MASK
+      b = @definition.custom_b & CUSTOM_B_MASK
+      high = (a << A_SHIFT) | b
+      c = @definition.custom_c & CUSTOM_C_MASK
+
+      Uuid.format(VERSION_VARIANT | (high << HIGH_SHIFT) | c)
+    end
+  end
+end

data/lib/uuid.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "uuid/gem_version"
+require_relative "uuid/errors"
+require_relative "uuid/version4"
+require_relative "uuid/version6"
+require_relative "uuid/version7"
+require_relative "uuid/version8"
+
+# The Uuid module contains a simple API to generate v4, v6, and v7 UUIDs
+# without needing to create generators manually.
+#
+# The simple API is exposed as a set of methods ::v4, ::v6, and ::v7 which
+# handle thread-safety and generator creation.
+#
+#   Uuid.v4 # => "2b54639d-e43e-489f-9c64-30ecdcac3c95"
+#   Uuid.v6 # => "1eda9761-9f6f-6414-8c5f-fd61f1239907"
+#   Uuid.v7 # => "01863d24-6d1e-78ba-92ee-6e80c79c4e28"
+#
+# See the Version4, Version6, and Version7 classes for details on how to create
+# generators manually.
+#
+# ===== Monotonic Batching
+# The simple API also provides thread-safe monotonic batch methods which expect
+# an amount.
+#
+#   Uuid.batch_v4(10) # => ["2b54639d-e43e-489f-9c64-30ecdcac3c95", ...]
+#   Uuid.batch_v6(10) # => ["1eda9761-9f6f-6414-8c5f-fd61f1239907", ...]
+#   Uuid.batch_v7(10) # => ["01863d24-6d1e-78ba-92ee-6e80c79c4e28", ...]
+#
+# Monotonicity has little meaning with UUID v4, but the batches are ordered for
+# consistency.
+#
+# ===== A Note on Clock Timings
+# This library uses the +Process::CLOCK_REALTIME+ clock ID to obtain the current
+# time. While the specification allows for implementations to manipulate time
+# values, this library does not. Any system-based smearing or drift will appear
+# within the timestamp values.
+#
+# See the Version6 and Version7 documentation for manifestation details.
+module Uuid
+  # The nil UUID as defined by
+  # {§5.10 of RFC 4122 BIS-01}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-nil-uuid].
+  #
+  # This UUID is written as +00000000-0000-0000-0000-000000000000+ and is less than all other UUIDs in comparisons.
+  # It does not act as +nil+.
+  def self.nil_uuid
+    "00000000-0000-0000-0000-000000000000"
+  end
+
+  # The maximum UUID as defined by
+  # {§5.10 of RFC 4122 BIS-01}[https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-01.html#name-max-uuid].
+  #
+  # This UUID is written as +ffffffff-ffff-ffff-ffff-ffffffffffff+ and is greater than all other UUIDs in comparisons.
+  def self.max_uuid
+    "ffffffff-ffff-ffff-ffff-ffffffffffff"
+  end
+
+  # Generate a new UUID v4 value using the default generator.
+  def self.v4
+    @lock4.synchronize { @uuid4.generate }
+  end
+
+  # Generate a new UUID v6 value using the default generator.
+  def self.v6
+    @lock6.synchronize { @uuid6.generate }
+  end
+
+  # Generate a new UUID v7 value using the default generator.
+  def self.v7
+    @lock7.synchronize { @uuid7.generate }
+  end
+
+  # Create a batch of UUID v4 values using the default generator.
+  def self.batch_v4(amount)
+    @lock4.synchronize { batch(@uuid4, amount) }
+  end
+
+  # Create a batch of UUID v6 values using the default generator.
+  def self.batch_v6(amount)
+    @lock6.synchronize { batch(@uuid6, amount) }
+  end
+
+  # Create a batch of UUID v7 values using the default generator.
+  def self.batch_v7(amount)
+    @lock7.synchronize { batch(@uuid7, amount) }
+  end
+
+  # Reset the UUID v4 default generator.
+  def self.reset_v4!
+    @lock4 = Mutex.new
+    @uuid4 = Version4.new
+  end
+
+  # Reset the UUID v6 default generator.
+  def self.reset_v6!
+    @lock6 = Mutex.new
+    @uuid6 = Version6.new
+  end
+
+  # Reset the UUID v7 default generator.
+  def self.reset_v7!
+    @lock7 = Mutex.new
+    @uuid7 = Version7.new
+  end
+
+  # Create a batch of UUIDs from a generator.
+  #
+  # This can be useful for custom Version8 generators.
+  def self.batch(generator, amount)
+    s = Set.new
+    s << generator.generate while s.length < amount
+    s.sort
+  end
+
+  reset_v4!
+  reset_v6!
+  reset_v7!
+
+  # :nodoc:
+  def self.format(value)
+    b = +value.to_s(16).rjust(32, "0")
+    b.insert(8, "-")
+    b.insert(13, "-")
+    b.insert(18, "-")
+    b.insert(23, "-")
+    b.freeze
+  end
+end

data/sig/uuid/errors.rbs

@@ -0,0 +1,7 @@
+module Uuid
+  class Error < StandardError
+  end
+
+  class ClockResolutionError < Error
+  end
+end

data/sig/uuid/version4.rbs

@@ -0,0 +1,6 @@
+module Uuid
+  class Version4
+    def initialize: () -> void
+    def generate: () -> uuid
+  end
+end

data/sig/uuid/version6.rbs

@@ -0,0 +1,11 @@
+module Uuid
+  class Version6
+    public
+
+    def initialize: () -> void
+    def generate: () -> uuid
+    def reset!:() -> void
+
+    def self.verify_clock_resolution!: () -> true
+  end
+end

data/sig/uuid/version7.rbs

@@ -0,0 +1,10 @@
+module Uuid
+  class Version7
+    public
+
+    def initialize: () -> void
+    def generate: () -> uuid
+
+    def self.verify_clock_resolution!: () -> true
+  end
+end

data/sig/uuid/version8.rbs

@@ -0,0 +1,14 @@
+module Uuid
+  class Version8
+    public
+
+    interface _GeneratorDefinition
+      def custom_a: () -> Integer
+      def custom_b: () -> Integer
+      def custom_c: () -> Integer
+    end
+
+    def initialize: [Definition < _GeneratorDefinition] (Definition) -> void
+    def generate: () -> uuid
+  end
+end

data/sig/uuid.rbs

@@ -0,0 +1,30 @@
+# See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+module Uuid
+  VERSION: String
+
+  type uuid = String
+
+  public
+
+  interface _Generator
+    def generate: () -> uuid
+  end
+
+  def self.nil_uuid: () -> uuid
+  def self.max_uuid: () -> uuid
+  def self.v4: () -> uuid
+  def self.v6: () -> uuid
+  def self.v7: () -> uuid
+  def self.batch_v4: (Integer) -> Array[uuid]
+  def self.batch_v6: (Integer) -> Array[uuid]
+  def self.batch_v7: (Integer) -> Array[uuid]
+  def self.reset_v4!: () -> void
+  def self.reset_v6!: () -> void
+  def self.reset_v7!: () -> void
+  def self.batch: (_Generator, Integer) -> Array[uuid]
+
+  private
+
+  def self.format: (Integer) -> uuid
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: uuidx
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Stephan Tarulli
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-02-11 00:00:00.000000000 Z
+dependencies: []
+description: "A fast Ruby implementation of UUID versions 4, 6, 7, and 8 \U0001FAAA"
+email:
+- srt@tinychameleon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/uuid.rb
+- lib/uuid/errors.rb
+- lib/uuid/gem_version.rb
+- lib/uuid/version4.rb
+- lib/uuid/version6.rb
+- lib/uuid/version7.rb
+- lib/uuid/version8.rb
+- sig/uuid.rbs
+- sig/uuid/errors.rbs
+- sig/uuid/version4.rbs
+- sig/uuid/version6.rbs
+- sig/uuid/version7.rbs
+- sig/uuid/version8.rbs
+homepage: https://github.com/tinychameleon/uuidx
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/tinychameleon/uuidx
+  source_code_uri: https://github.com/tinychameleon/uuidx
+  changelog_uri: https://github.com/tinychameleon/uuidx/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tinychameleon/uuidx/issues
+  documentation_uri: https://tinychameleon.github.io/uuidx/
+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.4.3
+signing_key:
+specification_version: 4
+summary: "A fast Ruby implementation of UUID versions 4, 6, 7, and 8 \U0001FAAA"
+test_files: []