uuid7 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b24060fdf8c607bf359e96657d4f160151726fffd5c08a34c72f2bd1043ac0d
+  data.tar.gz: d767c79de58c110731b009c74952a14b4ba15c42daaa8efaa761eb7a6e79ce51
+SHA512:
+  metadata.gz: c36b7c1219d9f57c8e5dc1a5a9b8d314731daff3ac173e8225710508d86ec653a91d4f1b30461ee1955638179ba3919a3dd38df875b4400d73bf4d24fd4b1eff
+  data.tar.gz: fe600303dfb8942c46f2fb978f8037786d9c6214a485032d40f95249924bd2813f41c4c69c72b39292d08e85519bea836a05f8daf82350ab18e9ffca544e071d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2021 Alexander Obukhov
+
+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,46 @@
+# UUID7
+
+Implementation of [UUIDv7](https://github.com/uuid6/uuid6-ietf-draft) in [Ruby](https://www.ruby-lang.org/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'uuid7'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install uuid7
+
+## Usage
+
+```
+UUID7.generate
+```
+
+## Performance
+
+| Library | Iterations/second     |
+|--------:|----------------------:|
+|  UUIDv7 | 412.324k (± 0.5%) i/s |
+|  UUIDv4 | 483.110k (± 0.7%) i/s |
+|    ULID | 156.675k (± 0.7%) i/s |
+|   KSUID | 108.075k (± 0.9%) i/s |
+
+See [examples](https://github.com/sprql/uuid7-ruby/examples/bench.rb)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sprql/uuid7-ruby.

data/lib/uuid7/generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module UUID7
+  # UUIDv7 with millisecond precision layout
+  #
+  # @api private
+  #
+  # 32 bits for unix timestamp seconds
+  # 12 bits for millisecond precision
+  # 62 bits for random data
+  #
+  module Generator
+    VERSION_7 = 0x7000
+    VARIANT_RFC4122 = 0x8000
+
+    # Instantiates a new layout
+    #
+    # @example Generate a new UUID v7 layout for the millisecond and sequence count
+    #   UUID::V7.generate(timestamp, sequence)
+    #
+    # @param timestamp [Integer] the timestamp to use for the layout
+    # @param seq [Integer] the sequence to use for the layout
+    # @return [Array<Integer>] the generated UUID v7 layout
+    def self.generate(timestamp, seq)
+      unixts = timestamp / 1_000 # seconds of unix timestamp
+      unixts1 = (unixts >> 4) & 0xffffffff # take 32 most significant bits of 36
+      unixts2 = (unixts & 0xf) << 12 # take 4 least significant bits of 36
+
+      msec = timestamp % 1_000 # milliseconds of unix timestamp
+      msec &= 0xfff # take 12 bits of 16
+
+      rand1, rand2, rand3 = SecureRandom.gen_random(8).unpack("nnN")
+      rand1 &= 0x3fff # take 14 bits of 16
+
+      # https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-01#section-4.4.4.1
+      #
+      #  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+      # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      # |                            unixts1                            |
+      # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      # |unixts2|         msec          |  ver  |          seq          |
+      # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      # |var|           rand1           |             rand2             |
+      # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      # |                             rand3                             |
+      # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      [
+        unixts1,
+        (unixts2 | msec),
+        (VERSION_7 | seq),
+        (VARIANT_RFC4122 | rand1),
+        rand2,
+        rand3
+      ]
+    end
+  end
+end

data/lib/uuid7/sequencer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module UUID7
+  # Monotonic clock sequence counter
+  class Sequencer
+    def self.sequence(time)
+      @sequencer ||= new
+      @sequencer.sequence(time)
+    end
+
+    def initialize
+      @sequence = 0
+      @last_timestamp = 0
+      @mutex = Mutex.new
+    end
+
+    def sequence(timestamp)
+      @mutex.synchronize do
+        @sequence = if timestamp <= @last_timestamp
+                      # TODO: handle overflow
+                      ((@sequence + 1) & 0xfff) # 12 bits
+                    else
+                      0
+                    end
+        @last_timestamp = timestamp
+      end
+
+      [timestamp, @sequence]
+    end
+  end
+end

data/lib/uuid7/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UUID7
+  VERSION = "0.1.0"
+end

data/lib/uuid7.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("uuid7" => "UUID7")
+loader.setup
+
+# UUID v7 Generator
+#
+module UUID7
+  # Generate a new UUID v7
+  #
+  # @api public
+  #
+  # @example Generate a new UUID v7 for the current timestamp
+  #   UUID7.generate
+  #
+  # @param timestamp [Integer] the timestamp to use for UUID v7
+  # @return [String] the generated UUID v7 string
+  def self.generate(timestamp: Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond))
+    format("%08x-%04x-%04x-%04x-%04x%08x", *Generator.generate(*Sequencer.sequence(timestamp)))
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: uuid7
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexander Obukhov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-09-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: Implementation of UUID v7
+email:
+- dev@sprql.space
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/uuid7.rb
+- lib/uuid7/generator.rb
+- lib/uuid7/sequencer.rb
+- lib/uuid7/version.rb
+homepage: https://github.com/sprql/uuid7-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sprql/uuid7-ruby
+  source_code_uri: https://github.com/sprql/uuid7-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: UUID v7 generator
+test_files: []