snowflakes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80ad868878f31b343d0e8c5c923e34d522a3cf35
+  data.tar.gz: b0edc0f6abce38e7a69c7464fff5c50953453a16
+SHA512:
+  metadata.gz: 81f8391c160f8380cd33a9b8ff39eb07f3ecf99825055fd125214fbeefb68c3c2a9e2e7d5321c3bf1ed3330bc43439309e519e280695caee227fa1512db73a65
+  data.tar.gz: 6d80c750027a844a0e4130317581d2f5233960024cc73c212f9b66953649a80aa8fe6b3d15f5b8c9718b0f311195b87273d79a52f8356d46d08275f55af07610

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Yang Sheng Han
+
+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,62 @@
+# Snowflakes
+
+Snowflakes is a [Ruby](https://www.ruby-lang.org/) gem that provides:
+ * A simple 128-bit id generator.
+ * Methods to convert snowflakes ID into string
+
+Snowflakes produces 128-bit and time-ordered ids. They run one on each node in infrastructure and will generate conflict-free ids on-demand without coordination.
+
+The project is inspired by [Twitter's Snowflake](https://github.com/twitter/snowflake) and [Go implementation of Discord](https://github.com/bwmarrin/snowflake) but extended to 128-bit and not compatible with Twitter's Snowflake. This library provides a basis for id generation but not a service for handing out ids nor node id coordination.
+
+## Getting Started
+
+### Installation
+
+```sh
+gem install snowflakes
+```
+
+Or via bundler:
+```
+source 'https://rubygems.org'
+
+gem 'snowflakes'
+```
+
+### Usage
+
+```ruby
+node = Snowflakes::Node.new(ENV['SNOWFLAKE_ID'])
+
+some_id = node.next.to_hex
+```
+
+### Format
+
+Snowflakes ids are 128-bits wide described here from most significant to least significant bits:
+* timestamp (64-bit) - milliseconds since the epoch (Jan 1 1970)
+* node id(48-bit) - a configurable node id
+* sequence (16-bit) - usually 0, increasing when more than one request in the same millisecond and reset to 0 when clock ticks forward
+
+#### System Clock Dependency
+
+You should use NTP to keep your system clock accurate. Snowflakes holds requests when non-monotonic clock detected. To run in a mode where NTP not move the clock backwards, see http://wiki.dovecot.org/TimeMovedBackwards#Time_synchronization for tips on how to do this.
+
+## Related Projects
+
+* [progamesigner/snowflakes-php](https://github.com/progamesigner/snowflakes-php)
+
+## Maintainers
+
+[@progamesigner](https://github.com/progamesigner).
+
+## Contribute
+
+ 1. **Fork** the repo on GitHub
+ 2. **Clone** the project to your own machine
+ 3. **Commit** changes to your own branch
+ 4. **Push** your work back up to your fork
+ 5. Submit a **Pull request** so that I can review your changes
+
+## License
+[MIT](LICENSE) © Yang Sheng Han

data/lib/snowflakes.rb

@@ -0,0 +1,125 @@
+module Snowflakes
+  class OverflowError < StandardError
+    def initialize(topic, current, maximum)
+      formats = {
+        topic: topic,
+        current: current,
+        maximum: maximum
+      }
+
+      if current < 0
+        super('Invalid %{topic} (${current} < 0)' % formats)
+      else
+        super('Invalid %{topic} (${current} > ${maximum})' % formats)
+      end
+    end
+  end
+
+  class InvalidSystemClockError < StandardError
+    def initialize(time, last)
+      super('Time goes backward! (%{time} < %{last})' % { time: time, last: last })
+    end
+  end
+
+  class Snowflake
+    def initialize(u, l)
+      @u = u
+      @l = l
+    end
+
+    def to_hex
+      '%016x%016x' % [@u, @l]
+    end
+  end
+
+  class Node
+    STEP_BITS = 16
+    NODE_BITS = 48
+
+    MAX_STEPS = (1 << STEP_BITS)
+    MAX_NODES = (1 << NODE_BITS)
+
+    def initialize(id, step = 0, since = 0)
+      if not id.is_a? Integer or id < 0 or id >= MAX_NODES
+        raise OverflowError.new('id', id, MAX_NODES)
+      end
+
+      if not step.is_a? Integer or step < 0 or step >= MAX_STEPS
+        raise OverflowError.new('step', step, MAX_STEPS)
+      end
+
+      @id = id
+      @last = 0
+      @step = step
+      @since = since
+    end
+
+    def next
+      time = now
+
+      if time < @last
+        raise InvalidSystemClockError.new(time, @last)
+      end
+
+      if time == @last
+        @step = (@step + 1) % MAX_STEPS
+        if @step == 0
+          time = waitUntilNextMillisecond(time)
+        end
+      else
+        @step = 0
+      end
+
+      @last = time
+
+      generate(time, @id, @step)
+    end
+
+    def now
+      (Time.now.to_f * 1000).to_i - @since
+    end
+
+    def parse
+    end
+
+    private
+
+    def generate(time, id, step)
+      Snowflake.new(time, id << (STEP_BITS) + step)
+    end
+
+    def waitUntilNextMillisecond(time)
+      t = time
+      while t < time
+        t = now
+      end
+      t
+    end
+  end
+end
+
+# node = Snowflakes::Node.new(10)
+
+# puts node.next.to_hex
+
+# require 'benchmark'
+
+# puts Benchmark.measure {
+#   65_536.times do
+#     node.next.to_hex
+#   end
+# }
+
+# # (1/65535)*1e6 = 15.2590218967
+# puts '%.12f nanoseconds' % (1_000_000_000 * Benchmark.realtime {
+#   65_536.times do
+#     node.next.to_hex
+#   end
+# } / 65_536)
+
+# require 'ruby-prof'
+# RubyProf::FlatPrinter.new(RubyProf.profile do
+#   65_536.times do
+#     node.next
+#   end
+# end).print(STDOUT)

data/lib/snowflakes/version.rb

@@ -0,0 +1,14 @@
+module Snowflakes
+  def self.version
+    Gem::Version.new VERSION::STRING
+  end
+
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    MICRO = 0
+    SURFIX = nil
+
+    STRING = [MAJOR, MINOR, MICRO, SURFIX].compact.join('.')
+  end
+end

data/snowflakes.gemspec

@@ -0,0 +1,25 @@
+require File.expand_path("../lib/snowflakes/version", __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name = 'snowflakes'
+  spec.version = Snowflakes.version
+  spec.license = 'MIT'
+
+  spec.authors = [
+    'Yang Sheng Han'
+  ]
+  spec.email = [
+    'progamesigner@gmail.com'
+  ]
+  spec.homepage = 'https://github.com/progamesigner/snowflakes-gem'
+
+  spec.summary = 'A decentralized, k-ordered UUID generator in Ruby'
+  spec.description = 'Snowflakes produces 128-bit and time-ordered ids. They run one on each node in infrastructure and will generate conflict-free ids on-demand without coordination.'
+
+  spec.files = Dir[
+    'README.md',
+    'LICENSE',
+    'snowflakes.gemspec',
+    'lib/**/*.rb'
+  ]
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: snowflakes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yang Sheng Han
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-07 00:00:00.000000000 Z
+dependencies: []
+description: Snowflakes produces 128-bit and time-ordered ids. They run one on each
+  node in infrastructure and will generate conflict-free ids on-demand without coordination.
+email:
+- progamesigner@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/snowflakes.rb
+- lib/snowflakes/version.rb
+- snowflakes.gemspec
+homepage: https://github.com/progamesigner/snowflakes-gem
+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: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: A decentralized, k-ordered UUID generator in Ruby
+test_files: []