clusterid 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b662076bc46a6188f0d587292d36cae6fb54b179d4b5e9077b114c8c36b6c1a
+  data.tar.gz: 9135abab52b8494ee37f0958d34dbceb9122e3b1babe6e5aa0113d76addb0d80
+SHA512:
+  metadata.gz: 262e9dfefed1d936a8f5d406dc2d3d1cd0df8bf3508a4d72ba9cc085adc897035f5e93717594cffabf47289eaeff9d90d0923b195d4a1aa7961affad5ba54867
+  data.tar.gz: eed23a12338f989ca94729a64179a6965bb7b3fc8cfa4db6608a766b77ace168bfe6b2d6bced72e68eee86d4669e6e68071a0f96b4420768854b047d0d102043

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## v1.0.0 - 2022-02-26
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 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,283 @@
+# ClusterID
+Create unique identifiers for entities in distributed systems.
+
+[![Gem Version](https://badge.fury.io/rb/clusterid.svg)](https://badge.fury.io/rb/clusterid)
+
+## What's in the Box?
+✅ Simple usage documentation written to get started fast. [Check it out!](#usage)
+
+⚡ A fast implementation in pure ruby. [Check it out!](#benchmarks)
+
+📚 YARD generated API documentation for the library. [Check it out!](https://tinychameleon.github.io/clusterid/)
+
+🤖 RBS types for your type checking wants. [Check it out!](./sig/clusterid.rbs)
+
+💎 Tests against many Ruby versions. [Check it out!](#ruby-versions)
+
+🔒 MFA protection on all gem owners. [Check it out!](https://rubygems.org/gems/clusterid)
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clusterid'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install clusterid
+
+### Ruby Versions
+This gem is tested against the following Ruby versions:
+
+- 2.6.0
+- 2.6.9
+- 2.7.0
+- 2.7.5
+- 3.0.0
+- 3.0.3
+- 3.1.0
+- 3.1.1
+
+
+## Usage
+Create an intance of `ClusterId::V1::Generator` and then use the `generate` method to create `ClusterId::V1::Value` instances.
+
+```ruby
+generator = ClusterId::V1::Generator.new
+id = generator.generate
+```
+
+This kind of quick usage will use the default byte generator, clock, and serialization classes. The default serialization
+classes are null objects which will:
+
+- return `nil` for deserializing any data centre, environment, or type ID
+- serialize any value for data centre, environment, or type ID as `0`.
+
+If you would like to take advantage of these custom attributes see the [Custom Attributes & Serialization section below](#custom-attributes--serialization).
+
+### Values
+The `ClusterId::V1::Value` objects that are created have a small API which allows read access to the individual components
+which make up the byte string. For example, to access the byte string for storage:
+
+```ruby
+value = generator.generate
+puts value.bytes
+```
+
+[See the API docs for the full method reference](https://tinychameleon.github.io/clusterid/ClusterId/V1/Value.html).
+
+### Values are `Comparable`
+The `ClusterId::V1::Value` class implements the `Comparable` interface, so you can sort them, check for equality, and use the typical comparison operators.
+
+### Reconstituting `ClusterId::V1::Value` Objects
+If you've saved the byte string from one of these objects somewhere, you can manually create it again if you have a `ClusterId::V1::Deserializer`
+or a `ClusterId::V1::Generator`.
+
+With a generator configured with the correct `Deserializer`, you can use the `from_byte_string` method:
+
+```ruby
+byte_string = "..." # From storage, perhaps.
+generator = ... # Some existing generator with the correct configuration.
+value = generator.from_byte_string(byte_string)
+```
+
+Without a generator, you need to provide the `Deserializer` instance yourself:
+
+```ruby
+byte_string = "..." # From storage, perhaps.
+deserializer = ClusterId::V1::NullDeserializer.new
+value = ClusterId::V1::Value.new(byte_string, deserializer)
+```
+
+### Custom Attributes & Serialization
+You can create subclasses of `ClusterId::V1::Serializer` and `ClusterId::V1::Deserializer` to represent your custom values for data centre, environment, and type IDs.
+The `Serializer` will need to accept your application's types for the custom attributes and return integer values, while the `Deserializer` should do the opposite.
+
+You can use any type as long as you implement the serialization and deserialization steps. For example, here are two simple classes that use only `Symbols`.
+
+```ruby
+class ExampleDeserializer < ClusterId::V1::Deserializer
+  def to_data_centre(i)
+    return :north_america if i == 1
+    :global
+  end
+
+  def to_environment(i)
+    return :production if i == 3
+    :non_production
+  end
+
+  def to_type_id(i)
+    return :user if i == 1
+    return :settings if i == 2
+    :unknown
+  end
+end
+
+class ExampleSerializer < ClusterId::V1::Serializer
+  def from_data_centre(s)
+    return 1 if s == :north_america
+    2
+  end
+
+  def from_environment(s)
+    return 3 if s == :production
+    1
+  end
+
+  def from_type_id(s)
+    return 1 if s == :user
+    return 2 if s == :settings
+    99
+  end
+end
+
+# Then pass them to the Generator constructor
+g = ClusterId::V1::Generator.new(serializer: ExampleSerializer.new, deserializer: ExampleDeserializer.new)
+```
+
+Once you've implemented these custom classes you can provide your custom attributes to the `generate` method:
+
+```ruby
+v = g.generate(data_centre: :north_america, environment: :production, type_id: :user)
+puts v.type_id # Output: :user
+```
+
+#### NOTE
+When you implement custom serialization classes you become responsible for ensuring the bit length requirements for each
+attribute are correct. [See the API documentation for details](https://tinychameleon.github.io/clusterid/ClusterId/V1/Value.html).
+
+### Custom Byte Generators
+If you need to use a byte generator other than the default of `SecureRandom` you can implement your own.
+The only requirement is to have a `bytes(n)` method which returns a byte string. For example:
+
+```ruby
+module GuaranteedRandom
+  DICE_ROLL = [4].cycle
+
+  def bytes(n)
+    DICE_ROLL.take(n).pack("C")
+  end
+end
+```
+
+Once you have a custom byte generator you can provide it to the `ClusterId::V1::Generator` constructor:
+
+```ruby
+g = ClusterId::V1::Generator(byte_generator: GuaranteedRandom)
+```
+
+### Custom Clock
+If you need to implement a custom clock for millisecond timestamps you can implement your own.
+The only requirement is to have a `now_ms` method which returns the millisecond time as an `Integer`.
+For example:
+
+```ruby
+module UltraAccurateClock
+  def now_ms
+    expensive_hardware.get_time_ms
+  end
+end
+```
+
+Once you have created a custom clock you can provide it to the `ClusterId::V1::Generator` constructor:
+
+```ruby
+g = ClusterId::V1::Generator(clock: UltraAccurateClock)
+```
+
+
+## Contributing
+
+### Development
+To get started development on this gem run the `bin/setup` command. This will install dependencies and run the tests and linting tasks to ensure everything is working.
+
+For an interactive console with the gem loaded run `bin/console`.
+
+
+### Testing
+Use the `bundle exec rake test` command to run unit tests. To install the gem onto your local machine for general integration testing use `bundle exec rake install`.
+
+To test the gem against each supported version of Ruby use `bin/test_versions`. This will create a Docker image for each version and run the tests and linting steps.
+
+
+### Releasing
+Do the following to release a new version of this gem:
+
+- Update the version number in [lib/clusterid/version.rb](./lib/clusterid/version.rb)
+- Ensure necessary documentation changes are complete
+- Ensure changes are in the [CHANGELOG.md](./CHANGELOG.md)
+- Create the new release using `bundle exec rake release`
+
+After this is done the following side-effects should be visible:
+
+- A new git tag for the version number should exist
+- Commits for the new version should be pushed to GitHub
+- The new gem should be available on [rubygems.org](https://rubygems.org).
+
+Finally, update the documentation hosted on GitHub Pages:
+
+- Check-out the `gh-pages` branch
+- Merge `main` into the `gh-pages` branch
+- Generate the documentation with `bundle exec rake yard`
+- Commit the documentation on the `gh-pages` branch
+- Push the new documentation so GitHub Pages can deploy it
+
+## Benchmarks
+Benchmarking is tricky and the goal of a benchmark should be clear before attempting performance improvements. The goal of this library for performance is as follows:
+
+> This library should be capable of generating new values and instantiating existing values at a rate which does not make it a bottleneck for the majority of web APIs.
+
+Given the above goal statement, these benchmarks run on the following environment:
+
+| Attribute | Value |
+|:--|--:|
+| Ruby Version | 3.1.0 |
+| MacOS Version | Catalina 10.15.7 (19H1615) |
+| MacOS Model Identifier | MacBookPro10,1 |
+| MacOS Processor Name | Quad-Core Intel Core i7 |
+| MacOS Processor Speed | 2.7 GHz |
+| MacOS Number of Processors | 1 |
+| MacOS Total Number of Cores | 4 |
+| MacOS L2 Cache (per Core) | 256 KB |
+| MacOS L3 Cache | 6 MB |
+| MacOS Hyper-Threading Technology | Enabled |
+| MacOS Memory | 16 GB |
+
+### `ClusterId::V1`
+The performance is approximately as follows when run using:
+
+- The default byte generator and clock
+- Simple serializer and deserializer classes
+- A constant 16 bytes of data for `Value` instantiation
+
+```
+~/…/clusterid› bundle exec rake benchmark
+date; bundle exec ruby test/benchmarks/current.rb
+Sat Feb 26 17:47:17 PST 2022
+Warming up --------------------------------------
+            generate    23.924k i/100ms
+    from_byte_string   129.369k i/100ms
+               value   135.606k i/100ms
+Calculating -------------------------------------
+            generate    241.890k (± 2.8%) i/s -      1.220M in   5.048294s
+    from_byte_string      1.270M (± 5.2%) i/s -      6.339M in   5.004944s
+               value      1.358M (± 6.2%) i/s -      6.780M in   5.014634s
+```
+
+Being conservative in estimation and assuming:
+
+- all nodes in a cluster have identical millisecond timestamp values
+- 240 generated clusterid values per millisecond
+- approximately 150,000 values generated for a 5 byte value yields a 1% collision rate
+
+The `generate` method supports approximately 625 machines in a given cluster before the chance of a value collision reaches 1%.
+The `value` instantiation has ample performance and should not be a bottleneck for generation of new values.
+The `from_byte_string` API is nearly as fast as the value constructor and therefore should also not be a bottleneck.

data/lib/clusterid/constants.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ClusterId
+  # The expected byte size of {ClusterId} values.
+  BYTE_SIZE = 16
+end

data/lib/clusterid/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ClusterId
+  # The base error for all errors in {ClusterId}.
+  class Error < StandardError; end
+
+  # An error representing an invalid byte length for a value.
+  class InvalidByteLengthError < Error
+    # @param length [Integer] the byte length considered invalid
+    def initialize(length)
+      super("Expected #{BYTE_SIZE} bytes, got #{length}")
+    end
+  end
+
+  # An error representing an invalid data format version for a value.
+  class InvalidVersionError < Error
+    # @param expected [Integer] the expected data format version
+    # @param received [Integer] the received data format version
+    def initialize(expected, received)
+      super("Expected version #{expected}, got #{received}")
+    end
+  end
+end

data/lib/clusterid/v1/clock.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ClusterId
+  module V1
+    # A millisecond clock which extracts time information from the +Process+
+    # module.
+    class Clock
+      # @return [Integer] A millisecond timestamp since the Unix epoch
+      def self.now_ms
+        Process.clock_gettime Process::CLOCK_REALTIME, :millisecond
+      end
+    end
+  end
+end

data/lib/clusterid/v1/generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module ClusterId
+  module V1
+    # Create instances of {Value} objects based on time, random data, and serializable
+    # values for data centre, environment, and type IDs.
+    class Generator
+      # @note It is the caller's responsibility to ensure the serializer and deserializer
+      #       follow the expected bit lengths for custom types. No overflow checks are done.
+      #       Overflow will either be discarded or overwrite other bits. See the {Value}
+      #       class for allowed bit lengths.
+      #
+      # @param serializer [Serializer] an object which serializes {Value} attributes
+      # @param deserializer [Deserializer] an object which deserializes {Value} attributes
+      # @param byte_generator [#bytes(n)] an object which provides random bytes
+      # @param clock [#now_ms] an object which provides millisecond timestamps
+      def initialize(serializer: NullSerializer.new, deserializer: NullDeserializer.new, byte_generator: SecureRandom, clock: Clock)
+        @serializer = serializer
+        @deserializer = deserializer
+        @byte_generator = byte_generator
+        @clock = clock
+      end
+
+      # Generate a {Value} for a given data centre, environment, and type ID.
+      #
+      # @param data_centre [D] a serializable value representing the data centre the {Value} is generated within
+      # @param environment [E] a serializable value representing the environment the {Value} is generated within
+      # @param type_id [T] a serializable value representing the type of entity for a generated {Value}
+      # @return [Value] a time-based, partially random value to identify an entity
+      def generate(data_centre: nil, environment: nil, type_id: nil)
+        raw_data = +""
+        # Nonce
+        raw_data += @byte_generator.bytes(5)
+        # Type ID
+        raw_data += [@serializer.from_type_id(type_id)].pack("S")
+        # Details (Version, Data Centre, Environment)
+        raw_data += [
+          (FORMAT_VERSION << 5) +
+            (@serializer.from_data_centre(data_centre) << 2) +
+            @serializer.from_environment(environment)
+        ].pack("C")
+        # Timestamp
+        raw_data += [@clock.now_ms].pack("Q")
+
+        Value.new(raw_data.freeze, @deserializer)
+      end
+
+      # @return [Value] the {Value} represented by +s+
+      def from_byte_string(s)
+        Value.new(s, @deserializer)
+      end
+    end
+  end
+end

data/lib/clusterid/v1/null_serialization.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClusterId
+  module V1
+    # A default {Deserializer} that returns +nil+ for all attributes.
+    class NullDeserializer < Deserializer
+      # Null method which ignores all data centre values.
+      # @return [nil]
+      def to_data_centre(_)
+        nil
+      end
+
+      # Null method which ignores all environment values.
+      # @return [nil]
+      def to_environment(_)
+        nil
+      end
+
+      # Null method which ignores all type ID values.
+      # @return [nil]
+      def to_type_id(_)
+        nil
+      end
+    end
+
+    # A default {Serializer} that returns +0+ for all attributes.
+    class NullSerializer < Serializer
+      # Zero method which ignores all data centre values.
+      # @return [0]
+      def from_data_centre(_)
+        0
+      end
+
+      # Zero method which ignores all environment values.
+      # @return [0]
+      def from_environment(_)
+        0
+      end
+
+      # Zero method which ignores all type ID values.
+      # @return [0]
+      def from_type_id(_)
+        0
+      end
+    end
+  end
+end

data/lib/clusterid/v1/serialization.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClusterId
+  module V1
+    # The abstract base class of all custom serialization logic.
+    class Serializer
+      # @param t [T] the environment
+      # @return [Integer] the serialized environment
+      def from_environment(t)
+        raise NotImplementedError
+      end
+
+      # @param t [T] the data centre
+      # @return [Integer] the serialized data centre
+      def from_data_centre(t)
+        raise NotImplementedError
+      end
+
+      # @param t [T] the type ID
+      # @return [Integer] the serialized type ID
+      def from_type_id(t)
+        raise NotImplementedError
+      end
+    end
+
+    # The abstract base class of all custom deserializtion logic.
+    class Deserializer
+      # @param i [Integer] the serialized environment
+      # @return [T] the deserialized environment
+      def to_environment(i)
+        raise NotImplementedError
+      end
+
+      # @param i [Integer] the serialized data centre
+      # @return [T] the deserialized data centre
+      def to_data_centre(i)
+        raise NotImplementedError
+      end
+
+      # @param i [Integer] the serialized type ID
+      # @return [T] the deserialized type ID
+      def to_type_id(i)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/clusterid/v1/value.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "date"
+
+module ClusterId
+  # Data format version 1 for {ClusterId} identifiers. This format supports
+  # custom value serialization for data centre, environment, and type IDs.
+  #
+  # @see Value
+  # @see Generator
+  module V1
+    # The data format version
+    FORMAT_VERSION = 1
+
+    # A {ClusterId} version 1 format value.
+    #
+    # A {Value} contains the following accessible properties:
+    #
+    # - a 64-bit millisecond timestamp as a +DateTime+
+    # - a 3-bit version number
+    # - a 3-bit data centre identifier
+    # - a 2-bit environment identifier
+    # - a 16-bit type identifier
+    # - a 40-bit random nonce
+    #
+    # It also provides access to the underlying bytes.
+    #
+    # Instances of {Value} are +Comparable+ based on the timestamp.
+    #
+    # === Random Nonce
+    # A 5 byte random nonce supports generating approximately 150,000 values before
+    # reaching a 1% chance of collision. This applies to each millisecond.
+    #
+    # === Data Layout
+    # The byte layout of a version 1 value in little-endian is:
+    #  o-------------------------------------------------------------------------------o
+    #  | byte 01 | byte 02 | byte 03 | byte 04 | byte 05 | byte 06 | byte 07 | byte 08 |
+    #  |-------------------------------------------------------------------------------|
+    #  |                   random nonce                  |      type id      | details |
+    #  |-------------------------------------------------------------------------------|
+    #  | byte 09 | byte 10 | byte 11 | byte 12 | byte 13 | byte 14 | byte 15 | byte 16 |
+    #  |-------------------------------------------------------------------------------|
+    #  |                                   timestamp                                   |
+    #  o-------------------------------------------------------------------------------o
+    # With the +details+ byte encoding the following data:
+    #  o---------------------------------------------------------------o
+    #  | bit 8 | bit 7 | bit 6 | bit 5 | bit 4 | bit 3 | bit 2 | bit 1 |
+    #  |---------------------------------------------------------------|
+    #  |        version        |      data centre      |  environment  |
+    #  o---------------------------------------------------------------o
+    class Value
+      include Comparable
+
+      # @return [String] the underlying value bytes
+      attr_reader :bytes
+
+      # [RUBY 2.6][RUBY 2.7]
+      # Referencing undefined instance variables causes warnings to be emitted,
+      # so +instance_variable_defined?+ is used to determine memoization status.
+
+      # @return [DateTime] the value's creation datetime
+      def datetime
+        return @dt if instance_variable_defined? :@dt
+        @dt = DateTime.strptime(bytes[8..].unpack1("Q").to_s, "%Q")
+      end
+
+      # @return [Integer] the value's random nonce
+      def nonce
+        return @nonce if instance_variable_defined? :@nonce
+        @nonce = (bytes[0..4] + "\x00\x00\x00").unpack1("Q")
+      end
+
+      # @return [Integer] the value's version
+      def version
+        FORMAT_VERSION
+      end
+
+      # @return [T] the value's deserialized environment
+      def environment
+        return @env if instance_variable_defined? :@env
+        @env = @deserializer.to_environment bytes[7].unpack1("C") & 0x03
+      end
+
+      # @return [T] the value's deserialized data centre
+      def data_centre
+        return @dc if instance_variable_defined? :@dc
+        @dc = @deserializer.to_data_centre (bytes[7].unpack1("C") & 0x1c) >> 2
+      end
+
+      # @return [T] the value's deserialized type ID
+      def type_id
+        return @tid if instance_variable_defined? :@tid
+        @tid = @deserializer.to_type_id bytes[5..6].unpack1("S")
+      end
+
+      # @param bytes [String] the value as a byte string
+      # @param deserializer [Deserializer] a {Deserializer} to decode custom value attributes
+      # @raise [InvalidByteLengthError] when the length of bytes is not {BYTE_SIZE}
+      # @raise [InvalidVersionError] when the data format version is not {FORMAT_VERSION}
+      def initialize(bytes, deserializer)
+        raise InvalidByteLengthError, bytes.length unless bytes.length == BYTE_SIZE
+
+        version = (bytes[7].unpack1("C") & 0xe0) >> 5
+        raise InvalidVersionError.new(FORMAT_VERSION, version) unless version == FORMAT_VERSION
+
+        @bytes = bytes
+        @deserializer = deserializer
+      end
+
+      # Compares {Value} objects using {#datetime}
+      #
+      # @param other [Value] the object to compare against
+      # @return [-1, 0, 1] -1 when less than +other+, 0 when equal to +other+, 1 when greater than +other+
+      def <=>(other)
+        datetime <=> other.datetime
+      end
+    end
+  end
+end

data/lib/clusterid/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Create unique identifiers for entities in distributed systems.
+# @since 1.0.0
+module ClusterId
+  # The gem version.
+  VERSION = "1.0.0"
+end

data/lib/clusterid.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "clusterid/version"
+require_relative "clusterid/constants"
+require_relative "clusterid/errors"
+
+require_relative "clusterid/v1/serialization"
+require_relative "clusterid/v1/null_serialization"
+require_relative "clusterid/v1/clock"
+require_relative "clusterid/v1/value"
+require_relative "clusterid/v1/generator"

data/sig/clusterid.rbs

@@ -0,0 +1,67 @@
+module ClusterId
+  VERSION: String
+  BYTE_SIZE: 16
+
+  class Error < StandardError
+  end
+
+  class InvalidByteLengthError < Error
+    def initialize: (Integer) -> void
+  end
+
+  class InvalidVersionError < Error
+    def initialize: (Integer, Integer) -> void
+  end
+
+  module V1
+    FORMAT_VERSION: 1
+
+    class Deserializer[D, E, T]
+      def to_data_centre: (Integer) -> D
+      def to_environment: (Integer) -> E
+      def to_type_id: (Integer) -> T
+    end
+
+    class Serializer[D, E, T]
+      def from_data_centre: (D) -> Integer
+      def from_environment: (E) -> Integer
+      def from_type_id: (T) -> Integer
+    end
+
+    interface _ByteSource
+      def bytes: (Integer) -> String
+    end
+
+    interface _Clock
+      def now_ms: () -> Integer
+    end
+
+    class Value[D, E, T]
+      attr_reader bytes: String
+      def datetime: () -> DateTime
+      def nonce: () -> Integer
+      def version: () -> Integer
+      def environment: () -> E
+      def data_centre: () -> D
+      def type_id: () -> T
+
+      def initialize: (String, Deserializer[D, E, T]) -> void
+    end
+
+    class Generator[D, E, T]
+      def generate: (data_centre: D, environment: E, type_id: T) -> Value[D, E, T]
+
+      def initialize: (?serializer: Serializer[D, E, T], ?deserializer: Deserializer[D, E, T], ?byte_generator: _ByteSource, ?clock: _Clock) -> void
+    end
+
+    class Clock
+      include _Clock
+    end
+
+    class NullSerializer < Serializer[top, top, top]
+    end
+
+    class NullDeserializer < Deserializer[nil, nil, nil]
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: clusterid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Stephan Tarulli
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-02-27 00:00:00.000000000 Z
+dependencies: []
+description: Create unique identifiers for entities in distributed systems
+email:
+- srt@tinychameleon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/clusterid.rb
+- lib/clusterid/constants.rb
+- lib/clusterid/errors.rb
+- lib/clusterid/v1/clock.rb
+- lib/clusterid/v1/generator.rb
+- lib/clusterid/v1/null_serialization.rb
+- lib/clusterid/v1/serialization.rb
+- lib/clusterid/v1/value.rb
+- lib/clusterid/version.rb
+- sig/clusterid.rbs
+homepage: https://github.com/tinychameleon/clusterid
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tinychameleon/clusterid
+  source_code_uri: https://github.com/tinychameleon/clusterid
+  changelog_uri: https://github.com/tinychameleon/clusterid/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tinychameleon/clusterid/issues
+  documentation_uri: https://tinychameleon.github.com/clusterid/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Create unique identifiers for entities in distributed systems
+test_files: []