locality-uuid 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTlkODUxYzI5ODllNGY3ZDAyZTdmYzVjMjk3NDVjZDkzZjA3ZTVlNg==
+  data.tar.gz: !binary |-
+    YzU3NmU5YTRlN2NkMTg2YzY5MGEyNDUwMzdhYzY3ZjM5N2FkNmY5Mw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NGJjYzBkMWY2NDUyZDViOGY4NTM1NTA3OWZiYzE2MmMzMWEzMGVkN2VjOTMx
+    NDEwYmU1NzYyOTUyZGQwNmIxYjk4MmFiODM0MzEzMTFmZDM5OTg1YjdlZTcy
+    ODIwODhhMWUxMTBhZmVmNDNlNjdmOTg4ZGJkZTlhOWQwMzJmZTE=
+  data.tar.gz: !binary |-
+    NzY0OTRhYTkxN2M5MjIwNWQ2NmFmZmY1ZGUyNTY2Y2FkZTRhNDIwMTdmZDA2
+    MGM5YmFmMzFlMjk4YjVlZTQ0ZjI5MTM3ZDNjMzZkOGIwYWYzMzFjY2FkNzEz
+    OTkyZTcxZDk2NDU2NmMzNzM3YWUzNjNhY2ZhM2M5M2RjMDE3OTU=

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,29 @@
+Copyright (c) 2013, Groupon, Inc.
+All rights reserved. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met: 
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer. 
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution. 
+
+Neither the name of GROUPON nor the names of its contributors may be
+used to endorse or promote products derived from this software without
+specific prior written permission. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,212 @@
+Locality UUID (vB) Ruby
+=======================
+
+This is a UUID class intended to help control data locality when inserting into a distributed data 
+system, such as MongoDB or HBase. There is also [a Java implementation](groupon/locality-uuid.java).
+This version does not conform to any external standard or spec. Developed at Groupon in Palo Alto
+by Peter Bakkum and Michael Craig.
+
+Problems we encountered with other UUID solutions:
+
+- Collisions when used with heavy concurrency.
+- Difficult to retrieve useful information, such as the timetamp, from the id.
+- Time-based versions (such as v1) place this component at the front, meaning all generated ids 
+    start with the same bytes for some time period. This was disadvantageous for us because all
+    of these writes were hashed to the same shards of our distributed databases. Thus, only one
+    machine was receiving writes at a given time.
+
+Solutions:
+
+- We have tested thoroughly in a concurrent environment and include both the PID and MAC Address 
+    in the UUID. In the first block of the UUID we have a counter which we increment with a large
+    primary number, ensuring that the counter in a single process takes a long time to wrap around
+    to the same value.
+- The UUID layout is very simple and documented below. Retrieving the millisecond-precision timestamp
+    is as simple as copying the last segment and converting from hex to decimal.
+- To ensure that generated ids are evenly distributed in terms of the content of their first few bytes,
+    we increment this value with a large number. This means that DB writes using these values are
+    evenly distributed across the cluster. We ALSO allow toggling into sequential mode, so that the
+    first few bytes of the UUID are consistent and writes done with these keys hash to tho same machine
+    in the cluster, when this characteristic is desireable. Thus, this library is a tool for managing
+    the locality of reads and writes of data inserted with UUID keys.
+
+This library has both Java and Ruby implementations, and is also accessible from the command line.
+
+Format
+------
+
+This generates UUIDs in the following format:
+
+```
+   wwwwwwww-xxxx-byyy-yyyy-zzzzzzzzzzzz
+
+w: highly variable counter value
+x: process id
+b: literal hex 'b' representing the UUID version
+y: fragment of machine MAC address
+z: UTC timestamp (milliseconds since epoch)
+```
+
+Example:
+
+```
+   20be0ffc-314a-bd53-7a50-013a65ca76d2
+
+counter     : 3,488,672,514
+process id  : 12,618
+MAC address : __:__:_d:53:7a:50
+timestamp   : 1,350,327,498,450 (Mon, 15 Oct 2012 18:58:18.450 UTC)
+```
+
+Example Use
+-----------
+
+Install the gem:
+
+```bash
+gem install locality-uuid
+```
+
+Use it in a program:
+
+```ruby
+require 'locality-uuid'
+
+uuid = UUID.new
+
+puts "UUID          : #{uuid.to_s}"
+puts "raw bytes     : #{uuid.bytes.unpack("H*")[0]}"
+puts "process id    : #{uuid.pid}"
+puts "MAC fragment  : #{uuid.mac}"
+puts "timestamp     : #{uuid.timestamp}"
+puts "version       : #{uuid.version}"
+
+copy = UUID.new(uuid.to_s)
+
+puts "copied        : #{(uuid == copy)}"
+```
+
+Or just run from the command line:
+
+```
+locality-uuid
+```
+
+Notes
+-----
+
+This UUID version was designed to have easily readable PID, MAC address, and
+timestamp values, with a regularly incremented count. The motivations for this
+implementation are to reduce the chance of duplicate ids, store more useful
+information in UUIDs, and ensure that the first few characters vary for successively
+generated ids, which can be important for splitting ids over a cluster. The UUID
+generator is also designed to be be thread-safe without locking.
+
+Uniqueness is supported by the millisecond precision timestamp, the MAC address
+of the generating machine, the 2 byte process id, and a 4 byte counter. Thus,
+a UUID is guaranteed to be unique in an id space if each machine allows 65,536 processes or less,
+does not share the last 28 bits of its MAC address with another machine in the id
+space, and generates fewer than 4,294,967,295 ids per millisecond in a process.
+
+___Counter___
+The counter value is reversed, such that the least significant 4-bit block is the first
+character of the UUID. This is useful because it makes the earlier bits of the UUID
+change more often. Note that the counter is not incremented by 1 each time, but rather
+by a large prime number, such that its incremental value is significantly different, but
+it takes many iterations to reach the same value.
+
+Examples of sequentially generated ids in the default counter mode:
+```
+c8c9cef9-7a7f-bd53-7a50-013e4e2afbde
+14951cfa-7a7f-bd53-7a50-013e4e2afbde
+6f5169fb-7a7f-bd53-7a50-013e4e2afbde
+ba2da6fc-7a7f-bd53-7a50-013e4e2afbde
+06f8f3fc-7a7f-bd53-7a50-013e4e2afbde
+51c441fd-7a7f-bd53-7a50-013e4e2afbde
+ac809efe-7a7f-bd53-7a50-013e4e2afbde
+f75cdbff-7a7f-bd53-7a50-013e4e2afbde
+```
+
+Note the high variability of the first few characters.
+
+The counter can also be toggled into sequential mode to effectively reverse this logic.
+This is useful because it means you can control the locality of your data as you generate
+ids across a cluster. Sequential mode works by creating an initial value based on a hash
+of the current date and hour. This means it can be discovered independently on distributed
+machines. The value is then incremented by one for each id generated. If you use key-based
+sharding, data inserted with these ids should have some locality.
+
+
+Examples of sequentially generated ids in sequential counter mode:
+```
+f5166777-7a7f-bd53-7a50-013e4e2afc26
+f5166778-7a7f-bd53-7a50-013e4e2afc26
+f5166779-7a7f-bd53-7a50-013e4e2afc26
+f516677a-7a7f-bd53-7a50-013e4e2afc26
+f516677b-7a7f-bd53-7a50-013e4e2afc26
+f516677c-7a7f-bd53-7a50-013e4e2afc26
+f516677d-7a7f-bd53-7a50-013e4e2afc26
+f516677e-7a7f-bd53-7a50-013e4e2afc26
+```
+
+___PID___
+This value is just the current process id modulo 65,536. In my experience, most linux
+machines do not allow PID numbers to go this high, but OSX machines do.
+
+___MAC Address___
+The last 28 bits of the first active MAC address found on the machine. If no active
+MAC address is found, this is filled in with zeroes.
+
+___Timestamp___
+This is the UTC milliseconds since Unix epoch. To convert to a time manually first
+copy the last segment of the UUID, convert to decimal, then use a time library to
+count up from 1970-1-1 0:00:00.000 UTC.
+
+
+API
+---
+
+__UUID.initialize__
+
+Generate a new UUID object.
+
+__UUID.initialize (String uuid)__
+
+Construct a UUID with the given String, must be of the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+where `x` matches `[0-9a-f]`.
+
+__UUID.initialize (UUID uuid)__
+
+Construct a UUID with the given UUID. This creates a copy.
+
+__UUID::use_sequential_ids()__
+
+Toggle into sequential mode, so ids are generated in order.
+
+__UUID::use_variable_ids()__
+
+Toggle into variable mode, so the first few characters of each id vary during generation. This is the default mode.
+
+__UUID.bytes() -> String__
+
+Get raw byte content of UUID.
+
+__UUID.to_s() -> String__
+
+Get UUID String in the standard format.
+
+__UUID.version() -> String__
+
+Return the UUID version character, which is 'b' for ids generated by this library.
+
+__UUID.pid() -> Fixnum__
+
+Return the PID embedded in the UUID.
+
+__UUID.timestamp() -> Time__
+
+Return timestamp embedded in UUID, which is set at generation.
+
+__UUID.mac() -> String__
+
+Get the embedded MAC Address fragment. This will be a String of hex characters.

data/bin/locality-uuid

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+# Copyright (c) 2013, Groupon, Inc.
+# All rights reserved. 
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met: 
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer. 
+# 
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution. 
+# 
+# Neither the name of GROUPON nor the names of its contributors may be
+# used to endorse or promote products derived from this software without
+# specific prior written permission. 
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'locality-uuid'
+puts UUID.new.to_s
+

data/lib/locality-uuid.rb

@@ -0,0 +1,184 @@
+# Copyright (c) 2013, Groupon, Inc.
+# All rights reserved. 
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met: 
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer. 
+# 
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution. 
+# 
+# Neither the name of GROUPON nor the names of its contributors may be
+# used to endorse or promote products derived from this software without
+# specific prior written permission. 
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'macaddr'
+require 'atomic'
+require 'digest/md5'
+
+class UUID
+  GEMVERSION      = '1.0.0'
+  @@VERSION       = 'b'
+  @@MAC           = Mac.addr[7..-1].gsub(/:/, '')
+  @@MIDDLE        = @@VERSION + @@MAC
+  @@PRIME         = 198491317
+  @@COUNTER_MAX   = 4294967295
+  @@PID_MAX       = 65536
+  @@PID           = $$ % @@PID_MAX
+  @@REGEX         = /^[0-9a-zA-Z]{8}\-[0-9a-zA-Z]{4}\-[0-9a-zA-Z]{4}\-[0-9a-zA-Z]{4}\-[0-9a-zA-Z]{12}$/
+
+  @@sequential    = false
+  @@counter       = Atomic.new(Random.rand(@@COUNTER_MAX))
+  
+  def initialize input = nil
+    if input == nil
+      generate
+    elsif input.is_a? String
+      parse input
+    elsif input.is_a? UUID
+      @content = input.bytes
+    else
+      raise "could not construct UUID with input #{input}"
+    end
+  end
+
+  def self.use_sequential_ids
+    if !@@sequential
+      # get a string that changes every 10 minutes
+      String date = Time.now.utc.strftime("%Y%m%d%H%M").slice(0, 11)
+
+      # run an md5 hash of the string, no reason this needs to be secure
+      digest = Digest::MD5.hexdigest date
+
+      # get first 4 bytes of digest, reverse, and turn into int
+      x = [digest[0...8]].pack("H*").unpack("l")[0]
+      @@counter.update { |curr| x }
+    end
+    @@sequential = true
+  end
+
+  def self.use_variable_ids
+    @@sequential = false
+  end
+
+  def bytes
+    String.new @content
+  end
+
+  def to_s
+    s = @content.unpack('H*')[0]
+    x = '________-____-____-____-____________'
+    x[0 ] = s[0 ]
+    x[1 ] = s[1 ]
+    x[2 ] = s[2 ]
+    x[3 ] = s[3 ]
+    x[4 ] = s[4 ]
+    x[5 ] = s[5 ]
+    x[6 ] = s[6 ]
+    x[7 ] = s[7 ]
+    
+    x[9 ] = s[8 ]
+    x[10] = s[9 ]
+    x[11] = s[10]
+    x[12] = s[11]
+
+    x[14] = s[12]
+    x[15] = s[13]
+    x[16] = s[14]
+    x[17] = s[15]
+
+    x[19] = s[16]
+    x[20] = s[17]
+    x[21] = s[18]
+    x[22] = s[19]
+
+    x[24] = s[20]
+    x[25] = s[21]
+    x[26] = s[22]
+    x[27] = s[23]
+    x[28] = s[24]
+    x[29] = s[25]
+    x[30] = s[26]
+    x[31] = s[27]
+    x[32] = s[28]
+    x[33] = s[29]
+    x[34] = s[30]
+    x[35] = s[31]
+    return x
+  end
+
+  def == other
+    return false unless other && other.is_a?(UUID)
+    return (self.bytes == other.bytes)
+  end
+
+  def version
+    @content[6].unpack('H')[0]
+  end
+
+  def pid
+    raise "incorrect UUID version: #{version}" unless version == @@VERSION
+    @content[4..5].unpack('S>')[0]
+  end
+
+  def timestamp
+    i = ("\x00\x00" + @content[10..15]).unpack('Q>')[0]
+    Time.at((i / 1000), (i % 1000 * 1000)).utc
+  end
+
+  def mac
+    '_____' + @content[6..9].unpack('H*')[0][1..-1]
+  end
+
+  private
+
+  def generate
+    time = (Time.now.utc.to_f * 1000).to_i
+    count = 0
+
+    if !@@sequential
+      countn = @@counter.update do |x| 
+        c = x + @@PRIME
+        (c >= @@COUNTER_MAX ? c - @@COUNTER_MAX : c)
+      end
+
+      count  = (((countn & 0xF) << 28) | ((countn & 0xF0) << 20))
+      count |= (((countn & 0xF00) << 12) | ((countn & 0xF000) << 4))
+      count |= (((countn & 0xF0000) >> 4) | ((countn & 0xF00000) >> 12))
+      count |= (((countn & 0xF000000) >> 20) | ((countn & 0xF0000000) >> 28))
+    else
+      countn = @@counter.update do |x| 
+        c = x + 1
+        (c >= @@COUNTER_MAX ? 0 : c)
+      end
+
+      count = countn
+    end
+
+    @content = [count, @@PID, @@MIDDLE, time >> 32, time].pack('NS>H*S>N')
+  end
+
+  def parse input
+    raise 'input must be a string' unless input.is_a? String
+    raise "invalid uuid: #{input}" unless input =~ @@REGEX
+
+    input = input.gsub(/\-/, '')
+    @content = [input].pack('H*')
+  end
+end

data/locality-uuid.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+# Copyright (c) 2013, Groupon, Inc.
+# All rights reserved. 
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met: 
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer. 
+# 
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution. 
+# 
+# Neither the name of GROUPON nor the names of its contributors may be
+# used to endorse or promote products derived from this software without
+# specific prior written permission. 
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require File.expand_path('../lib/locality-uuid.rb', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.add_development_dependency 'mocha'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'autotest-standalone'
+  gem.add_runtime_dependency 'macaddr'
+  gem.add_runtime_dependency 'atomic'
+
+  gem.authors = ["Peter Bakkum"]
+  gem.bindir = 'bin'
+  gem.description = %q{This is a UUID class intended to help control data locality when inserting into a distributed data system, such as MongoDB or HBase. There is also a Java implementation. This version does not conform to any external standard or spec. Developed at Groupon in Palo Alto by Peter Bakkum and Michael Craig.}
+  gem.email = ['pbb7c@virginia.edu']
+  gem.executables = ['locality-uuid']
+  gem.extra_rdoc_files = ['README.md', 'LICENSE.md']
+  gem.files = Dir['README.md', 'LICENSE.md', 'locality-uuid.gemspec', 'Gemfile', '.rspec', 'spec/**/*', 'lib/*', 'bin/*']
+  gem.homepage = 'http://github.com/groupon/locality-uuid.rb'
+  gem.name = 'locality-uuid'
+  gem.rdoc_options = ["--charset=UTF-8"]
+  gem.require_paths = ['lib']
+  gem.required_rubygems_version = Gem::Requirement.new(">= 1.3.6")
+  gem.summary = %q{UUID for data locality in distributed systems.}
+  gem.test_files = Dir['spec/**/*']
+  gem.version = UUID::GEMVERSION
+  gem.license = 'MIT'
+end
+
+

data/spec/lib/locality-uuid_spec.rb

@@ -0,0 +1,189 @@
+# Copyright (c) 2013, Groupon, Inc.
+# All rights reserved. 
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met: 
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer. 
+# 
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution. 
+# 
+# Neither the name of GROUPON nor the names of its contributors may be
+# used to endorse or promote products derived from this software without
+# specific prior written permission. 
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'spec_helper'
+require 'locality-uuid'
+
+describe UUID do
+  it 'should have the correct structure' do
+    r = /^[0-9a-zA-Z]{8}\-[0-9a-zA-Z]{4}\-b[0-9a-zA-Z]{3}\-[0-9a-zA-Z]{4}\-0[0-9a-zA-Z]{11}$/
+    UUID.new.to_s.should =~ r
+  end
+
+  it 'should parse uuid values' do
+    x1 = UUID.new
+    x2 = UUID.new x1.to_s
+    x1.should == x2
+    x1.timestamp.should == x2.timestamp
+    x1.bytes.should == x2.bytes
+
+    expect {UUID.new 'aoeuaoeu'}.to raise_error
+  end
+
+  it 'should accept uuid in the constructor' do
+    x1 = UUID.new
+    x2 = UUID.new x1
+    x1.should == x2
+    x1.bytes.should == x2.bytes
+  end
+
+  it 'should switch modes' do
+    n = 1000
+    ids = []
+
+    for i in 0..(n-1)
+      ids << UUID.new.to_s
+    end
+
+    for i in 1..(n-1)
+      ids[i-1][0].should_not == ids[i][0]
+    end
+
+    UUID.use_sequential_ids
+    initial_counter = UUID.new.to_s.split('-')[0]
+    UUID.use_variable_ids
+    UUID.use_sequential_ids
+    second_counter = UUID.new.to_s.split('-')[0]
+    initial_counter.should == second_counter
+
+    ids = []
+
+    for i in 0..(n-1)
+      ids << UUID.new.to_s
+    end
+
+    for i in 1..(n-1)
+      ids[i-1][0].should == ids[i][0]
+      ids[i-1][1].should == ids[i][1]
+      ids[i-1][2].should == ids[i][2]
+      
+      a = ids[i-1][7].to_s
+      b = ids[i][7].to_s
+
+      (((a.ord + 1).chr == b) || (a == '9' && b == 'a') || (a == 'f' && b == '0')).should == true
+    end
+
+    UUID.use_variable_ids
+    ids = []
+
+    for i in 0..(n-1)
+      ids << UUID.new.to_s
+    end
+
+    for i in 1..(n-1)
+      ids[i-1][0].should_not == ids[i][0]
+    end
+  end
+
+  it 'should be immutable' do
+    x = UUID.new
+    s1 = x.to_s
+    b = x.bytes
+    b[0] = 'x'
+    b[1] = 'x'
+    b[2] = 'x'
+    b[3] = 'x'
+    b[4] = 'x'
+
+    s2 = x.to_s
+    s1.should == s2
+  end
+
+  it 'should be immutable on the construction value' do
+    str = '00000000-0000-0000-0000-000000000000'
+    x = UUID.new str
+    s1 = x.to_s
+    str = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
+    s1.should == x.to_s
+  end
+
+  it 'should return the UUID version' do
+    UUID.new.version.should == 'b'
+    UUID.new('20be0ffc-314a-bd53-7a50-013a65ca76d2').version.should == 'b'
+    UUID.new('20be0ffc-314a-7d53-7a50-013a65ca76d2').version.should == '7'
+  end
+
+  it 'should return the UUID pid' do
+    UUID.new.pid.should == $$ % 65536
+    UUID.new('20be0ffc-314a-bd53-7a50-013a65ca76d2').pid.should == 12618
+    expect {UUID.new('20be0ffc-314a-7d53-7a50-013a65ca76d2').pid}.to raise_error
+  end
+
+  it 'should return the UUID timestamp' do
+    start = Time.now.utc.to_f.round(3)
+    time = UUID.new.timestamp
+    time.to_f.should be >= start - 0.01
+    time.to_f.should be < start + 0.01
+  end
+
+  it 'should return the MAC address fragment' do
+    UUID.new.mac.should == '_____' + Mac.addr[7..-1].gsub(/:/, '')
+    UUID.new('20be0ffc-314a-bd53-7a50-013a65ca76d2').mac.should == '_____d537a50'
+  end
+
+  it 'should not generate dups' do
+    n = 100000
+    a = Array.new n
+    s = Set.new
+
+    for i in 0..n
+      a[i] = UUID.new
+    end
+
+    a.each { |x| s.add x }
+
+    a.size.should == s.size
+  end
+
+  it 'should handle concurrent generation' do
+    n = 100000
+    nthreads = 10
+    effective_n = (n / nthreads).to_i * nthreads
+    threads = []
+    
+    a = Array.new effective_n
+    s = Set.new
+
+    for i in 0..nthreads
+      threads << Thread.new(i) do |i|
+        for j in 0..(n / nthreads).to_i
+          u = UUID.new
+          a[nthreads * j + i] = u
+        end
+      end
+    end
+
+    threads.each { |thread| thread.join }
+    a.each { |x| s.add x }
+
+    s.size.should == a.size
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,42 @@
+# Copyright (c) 2013, Groupon, Inc.
+# All rights reserved. 
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met: 
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer. 
+# 
+# Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution. 
+# 
+# Neither the name of GROUPON nor the names of its contributors may be
+# used to endorse or promote products derived from this software without
+# specific prior written permission. 
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rubygems'
+require 'rspec'
+require 'mocha/api'
+
+RSpec.configure do |config|
+  config.mock_with :mocha
+  config.fail_fast = true
+end
+
+

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: locality-uuid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Peter Bakkum
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: autotest-standalone
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: macaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: atomic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This is a UUID class intended to help control data locality when inserting
+  into a distributed data system, such as MongoDB or HBase. There is also a Java implementation.
+  This version does not conform to any external standard or spec. Developed at Groupon
+  in Palo Alto by Peter Bakkum and Michael Craig.
+email:
+- pbb7c@virginia.edu
+executables:
+- locality-uuid
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.md
+files:
+- README.md
+- LICENSE.md
+- locality-uuid.gemspec
+- Gemfile
+- .rspec
+- spec/lib/locality-uuid_spec.rb
+- spec/spec_helper.rb
+- lib/locality-uuid.rb
+- bin/locality-uuid
+homepage: http://github.com/groupon/locality-uuid.rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+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: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: UUID for data locality in distributed systems.
+test_files:
+- spec/lib/locality-uuid_spec.rb
+- spec/spec_helper.rb
+has_rdoc: