web_server_uid 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA512: 
+  metadata.gz: 1f4e8a55bfb690af19adc6020144a1239ce1958253d82cde98a5863735535889a451e116f12dcfd33927b3bbe8541930cc5260be1bf1c8f8021cccc09ad0b4f7
+  data.tar.gz: a5b54a5ea1c6a90cca40e472fc7909b3ae23298f6d13cd4ddf54ed23940ad85c125c659d3465e30987aefce6e0e3446e01f6e020dcda4b9cf92ce1bb85c98697
+SHA1: 
+  metadata.gz: 29eb5fec9ff2853494d6752ae159f5df63a40977
+  data.tar.gz: 7730d4f45312472340a561d486bdb960eb1a094e

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+    - "2.1.0"
+    - "2.0.0"
+    - "1.9.3"
+    - "1.8.7"
+    - "jruby-1.7.9"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in web_server_uid.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Swiftype, Inc.
+
+MIT License
+
+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,128 @@
+# WebServerUid
+
+WebServerUid is a small gem that can be used to represent "UIDs" in your application, where a "UID" is a unique ID
+generated by Apache's [`mod_uid`](http://www.lexa.ru/programs/mod-uid-eng.html) or nginx's
+[`http_userid_module`](http://nginx.org/en/docs/http/ngx_http_userid_module.html). Using these modules, you can
+generate a unique ID for each visitor to your website, before they log in, and add it to all logged data, from database
+rows to application logs to web-server logs to anything else you may desire.
+
+Generating a unique ID for each visitor is not terribly difficult and can easily be done within (_e.g._) Rails, by
+simply creating a large unique value (like a UUID) and assigning it to a cookie. However, there is one huge caveat to
+this approach: the very first request the visitor makes to your site will _not_ be tagged in your web-server logs
+with this unique ID, because they will not have had the cookie present in their browser when they made the request.
+This initial request is critical, because it contains the HTTP referer (_i.e._, how the user _got_ to your site in the
+first place) and the landing page (what first page were they directed to?), and this is extremely valuable
+information.
+
+By using `mod_uid` or `http_userid_module`, the web server itself can generate the user ID and log it even on this
+very first request. For example, we can easily configure `nginx` to do this with something like:
+
+    userid on;
+    userid_name brid;
+    userid_domain 'foo.com';
+    userid_path /;
+    userid_expires max;
+    userid_mark S;
+
+You can then pass it to your Rails application by doing something like this (in nginx, for example):
+
+    proxy_set_header X-Nginx-Browser-ID-Got $uid_got;
+    proxy_set_header X-Nginx-Browser-ID-Set $uid_set;
+
+...and then you'll get data like the following:
+
+    request.env['HTTP_X_NGINX_BROWSER_ID_GOT'] # => brid=0100007FE7D7F35241946D1E02030303
+
+or
+
+    request.env['HTTP_X_NGINX_BROWSER_ID_SET'] # => brid=0100007FE7D7F35241946D1E02030303
+
+Specifically, you'll get `HTTP_X_NGINX_BROWSER_ID_SET` (but not `_GOT`) on the very first request, and then
+`HTTP_X_NGINX_BROWSER_ID_GOT` on each subsequent request. You'll _also_ get a cookie — `cookies[:brid]` —
+that will look like `fwAAAVLz1+cebZRBAwMDAgS=`; this is a Base64-encoded, endianness-reversed version of the exact
+same data.
+
+WebServerUid can help you easily parse the data above, return either form from any input, return a
+pure-binary version of this data (which is only 16 bytes long — the shortest possible form if you want to store
+the data in a database or in log files). It also compares correctly (meaning `<`, `>=`, `==`, `!=`, `eql?`, and so on
+work properly), and hashes correctly (meaning you can store it in a Hash, and find it again, even if searching via a
+different actual object that is in fact equal to the original key).
+
+Because these UIDs also have internal structure (including the IP address of the server that generated them and the
+time at which they were generated, among other), WebServerUid also has methods that will return this data for you.
+
+**NOTE**: You'll probably be happier if you actually term this a _browser ID_ in your application, because that's what
+it actually is (the implied "user" from `uid` notwithstanding); these cookies get set uniquely per browser, and never
+cleared (unless you manually clear them &mdash; and then the web server will just re-set them, anyway). Having a
+per-browser unique ID is an incredibly valuable thing for your analytics, and nicely orthogonal to your concept of
+user &mdash; it's just important that you keep the distinction clear in your mind.
+
+WebServerUid supports:
+
+* Ruby 1.8.7, 1.9.3, 2.0.0, 2.1.0, or JRuby 1.7.9
+
+These are, however, just the versions it's tested against; WebServerUid contains no code that should be at all
+particularly dependent on exact Ruby versions, and should be compatible with a broad set of versions.
+
+Current build status: ![Current Build Status](https://api.travis-ci.org/swiftype/web_server_uid.png?branch=master)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'web_server_uid'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install web_server_uid
+
+## Usage
+
+For the most common case &mdash; you can parse a WebServerUid out of one of those `request.env` lines by doing:
+
+    uid = WebServerUid.from_header(request.env['HTTP_X_NGINX_BROWSER_ID_GOT'], 'brid')
+
+You can parse it from a cookie by doing:
+
+    uid = WebServerUid.from_base64(cookies[:brid])
+
+Generally, you want to try all three sources; you can define a method like this, in your `ApplicationController`
+(but make sure the headers and cookie names are correct for your purposes):
+
+    def web_server_uid
+      [ WebServerUid.from_header(request.env['HTTP_X_NGINX_BROWSER_ID_SET'], 'brid'),
+        WebServerUid.from_header(request.env['HTTP_X_NGINX_BROWSER_ID_GOT'], 'brid'),
+        WebServerUid.from_base64(cookies[:brid]) ].compact.first
+    end
+
+(These methods properly just return `nil`, rather than failing, if passed `nil`, so this is safe to do.) This will
+return the first value that's set from the set. (While, theoretically, this will never return `nil`, you don't want to
+rely on this, based on experience; automated ping checks, misconfigured front-end servers, and so forth mean that at
+some point you'll almost certainly get a request that somehow has none of the above set.)
+
+These methods will raise `ArgumentError` if the data passed in is incorrectly-formatted; it's up to you to decide
+whether you want to allow this to propagate, or swallow it and proceed without a UID.
+
+Once you have a WebServerUid, you can call these methods on it:
+
+    web_server_uid.to_hex_string    # => "0100007FE7D7F35241946D1E02030303"
+    web_server_uid.to_base64_string # => "fwAAAVLz1+cebZRBAwMDAg=="
+    web_server_uid.to_binary_string # => "\177\000\000\001R\363\327\347\036m\224A\003\003\003\002"
+
+This should give you pretty much any data you could want to work with these values. Note that there are also class
+methods `from_binary` and `from_base64` that will accept strings of those formats, too.
+
+All the ordinary comparison operators &mdash; `<`, `<=`, `>`, `>=`, `<=>`, `==`, `!=`, and `eql?` &mdash; work
+properly on values of this class; it also hashes properly, so feel free to use it as a hash key.
+
+## Contributing
+
+1. Fork it ( http://github.com/swiftype/web_server_uid/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/web_server_uid/version.rb

@@ -0,0 +1,3 @@
+class WebServerUid
+  VERSION = "1.0.0"
+end

data/lib/web_server_uid.rb

@@ -0,0 +1,297 @@
+require "base64"
+require "ipaddr"
+require "web_server_uid/version"
+
+# A WebServerUid represents a UID token, as issued by web browsers like Apache
+# (mod_uid, http://www.lexa.ru/programs/mod-uid-eng.html) or nginx (http_userid_module,
+# http://nginx.org/en/docs/http/ngx_http_userid_module.html).
+#
+# (Note that while this is called a "UID", it is almost certainly better understood as a "browser ID", because it is
+# unique to each browser and very unlikely to be managed in the same way as any "current user" concept you have.)
+#
+# UID tokens can be very useful when tracking visitors to your site, and more so than just setting a unique cookie
+# from your Rails app, for exactly one reason: since your front-end web server can issue and set the cookie directly,
+# it means that you can get the UID logged on the very first request visitors make to your site -- which is often a
+# really critical one, since it tells you how they got there in the first place (the HTTP referer) and which page
+# they first viewed (the landing page).
+#
+# So, generally, you'll want to do this:
+#
+# * Turn on +mod_uid+ or +http_userid_module+.
+# * Add the UID to the logs -- in nginx, you'll want to log _both_ +$uid_got+ and +$uid_set+, to handle both the case
+#   where you've already seen the browser before and the case where you haven't.
+# * In your Rails application,
+class WebServerUid
+  # This contains all Base64 characters from all possible variants of Base64, according to
+  # http://en.wikipedia.org/wiki/Base64 -- this is so that we accept Base64-encoded UID cookies,
+  # no matter what their source.
+  BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/-_\\.:!"
+  # This is, similarly, all characters that can be used as Base64 padding
+  BASE64_PADDING = "=-"
+  # This is a Regexp that matches any valid Base64 data
+  BASE64_REGEX = Regexp.new("^[#{BASE64_ALPHABET}]+[#{BASE64_PADDING}]*$")
+
+  # How long is the raw binary data required to be (in bytes) after we decode it?
+  RAW_BINARY_LENGTH = 16
+  # By default, how much extra binary data (in bytes) should we allow?
+  DEFAULT_ALLOWED_EXTRA_BINARY_DATA = 1
+
+  class << self
+    # Creates a new instance from a hex string; see #initialize for more details. Nicely returns nil if passed nil.
+    def from_hex(h, options = { })
+      new(h, :hex, options) if h
+    end
+
+    # Creates a new instance from a binary string; see #initialize for more details. Nicely returns nil if passed nil.
+    def from_binary(b, options = { })
+      new(b, :binary, options) if b
+    end
+
+    # Creates a new instance from a base64 string; see #initialize for more details. Nicely returns nil if passed nil.
+    def from_base64(b, options = { })
+      new(b, :base64, options) if b
+    end
+
+    # Given a string like "st_brid=0100007FE7D7F35241946D1E02030303", and the expected name of the ID cookie
+    # (_e.g._, +st_brid+), returns a WebServerUid if one is found, and nil otherwise. Also returns nil if input is nil.
+    # This is the exact format you get in a request.env header if you have lines like these in your nginx config:
+    #
+    #     proxy_set_header X-Nginx-Browser-ID-Got $uid_got;
+    #     proxy_set_header X-Nginx-Browser-ID-Set $uid_set;
+    #
+    # This is just a simple little method to make your parsing a bit easier.
+    def from_header(s, expected_name)
+      if s && s =~ /#{expected_name}\s*\=\s*([0-9A-F]{32})/i
+        from_hex($1)
+      end
+    end
+
+    # Generates a brand-new instance, from scratch. This follows exactly the algorithm in nginx-1.5.10:
+    #
+    # * The first four bytes are the local IP address (entire if IPv4, four LSB if IPv6);
+    # * The next four bytes are the current time, as a Unix epoch time;
+    # * The next two bytes are a function of the start time of the process, but LSBs in microseconds;
+    # * The next two bytes are the PID of the process;
+    # * The next three bytes are a sequence value, starting at 0x030303;
+    # * The last byte is 2, for version 2.
+    #
+    # +options+ can contain:
+    #
+    # [:ip_address] Must be an IPAddr object to use as the IP address of this machine, in lieu of autodetection
+    #               (see #find_local_ip_address, below).
+    def generate(options = { })
+      # Yes, global variables. What what?
+      #
+      # Well, in certain cases (like under Rails), this class may get unloaded and reloaded. (Yes, it's in a gem, so
+      # theoretically this shouldn't happen, but we want to be really, really careful.) Because we need to be really
+      # sure to maintain uniqueness, we use global variables, which, unlike class variables, won't get reset if this
+      # class gets loaded or unloaded
+      $_web_server_uid_start_value ||= ((Time.now.usec / 20) << 16) | (Process.pid & 0xFFFF)
+      $_web_server_uid_sequencer ||= 0x030302
+      $_web_server_uid_sequencer += 1
+      $_web_server_uid_sequencer &= 0xFFFFFF
+
+      extra = options.keys - [ :ip_address ]
+      if extra.length > 0
+        raise ArgumentError, "Unknown keys: #{extra.inspect}"
+      end
+
+      ip_address = if options[:ip_address]
+        IPAddr.new(options[:ip_address])
+      else
+        find_local_ip_address
+      end
+
+      components = [
+        ip_address.to_i & 0xFFFFFFFF,
+        Time.now.to_i,
+        $_web_server_uid_start_value,
+        ($_web_server_uid_sequencer << 8) | 0x2
+      ]
+
+      binary = components.pack("NNNN")
+      from_binary(binary)
+    end
+
+    private
+    # Finds the local IP address. This looks like evil voodoo, but it isn't -- no actual network traffic or connection
+    # is made. 8.8.8.8 is, famously, one of Google's DNS servers; this tells Ruby to open a UDP socket bound to it --
+    # but, unlike TCP, opening a UDP socket doesn't actually do anything until you send something on it. The clever bit
+    # is that this will magically find whatever interface your machine would send traffic to Google on, which almost
+    # everybody is going to have (even if it's firewalled off somewhere out there on the network), and return the IP
+    # address of that.
+    #
+    # Note that this could be an IPv6 address. This works properly; we grab the four LSB, above.
+    #
+    # (Much credit to http://coderrr.wordpress.com/2008/05/28/get-your-local-ip-address/.)
+    def find_local_ip_address
+      @local_ip_address ||= begin
+        require 'socket'
+        ipaddr_string = UDPSocket.open {|s| s.connect('8.8.8.8', 1); s.addr.last }
+        IPAddr.new(ipaddr_string)
+      end
+    end
+  end
+
+  # Creates a new WebServerUid object. +raw_data+ must be a String, in one of the following formats:
+  #
+  # * Hex-encoded -- the format nginx renders them in logs; _e.g._, <tt>0100007FE7D7F35241946D1E02030303</tt>.
+  #   This is a hex encoding of four *little-endian* four-byte integers underneath.
+  # * Base64.encoded -- the format of the actual cookie in client browsers; _e.g._, <tt>fwAAAVLz1+cebZRBAwMDAgS=</tt>.
+  #   This is a Base64 encoding of four *big-endian* four-byte integers.
+  # * Raw binary -- the hex-decoded or Base64-decoded version of above; _e.g._, <tt>\x01\x00\x00\x7F\xE7\xD7\xF3RA\x94m\x1E\x02\x03\x03\x03</tt>.
+  #   This is expected to be four *big-endian* four-byte integers.
+  #
+  # ...and +type+ must be the corresponding format -- one of :binary, :hex, or :base64. (It is not possible to guess
+  # the format 100% reliably from the inbound +raw_data+, since raw binary can happen to look like one of the others.)
+  #
+  # +options+ can contain:
+  #
+  # [:max_allowed_extra_binary_data] If more data is present in the input string than is necessary for the UID to
+  #                                  be parsed, this determines how much extra is allowed before an exception is raised;
+  #                                  this defaults to 1, since, if you use nginx's +userid_mark+ directive, you'll
+  #                                  get exactly that character in the Base64 at the end, and this will translate to
+  #                                  extra data.
+  def initialize(raw_data, type, options = { })
+    raise ArgumentError, "Type must be one of :binary, :hex, or :base64, not #{type.inspect}" unless [ :binary, :hex, :base64 ].include?(type)
+    @input_type = type
+
+    @binary_components = case type
+    when :hex then
+      @raw_binary_data = [ raw_data ].pack("H*")
+      @raw_binary_data.unpack("VVVV")
+    when :base64 then
+      @raw_binary_data = Base64.decode64(raw_data)
+      @raw_binary_data.unpack("NNNN")
+    when :binary then
+      @raw_binary_data = raw_data
+      @raw_binary_data.unpack("NNNN")
+    else
+      raise "wrong type: #{type.inspect}; need to add support for it?"
+    end
+
+    @extra_binary_data = @raw_binary_data[RAW_BINARY_LENGTH..-1]
+    @raw_binary_data = @raw_binary_data[0..(RAW_BINARY_LENGTH - 1)]
+
+    if @raw_binary_data.length < RAW_BINARY_LENGTH
+      raise ArgumentError, "This UID cookie does not appear to be long enough; its raw binary data is of length #{@raw_binary_data.length}, which is less than #{RAW_BINARY_LENGTH.inspect}: #{raw_data.inspect} (became #{@raw_binary_data.inspect})"
+    end
+
+    if @extra_binary_data.length > (options[:max_allowed_extra_binary_data] || DEFAULT_ALLOWED_EXTRA_BINARY_DATA)
+      raise ArgumentError, "This UID cookie has #{@extra_binary_data.length} bytes of extra binary data at the end: #{@raw_binary_data.inspect} adds #{@extra_binary_data.inspect}"
+    end
+  end
+
+  # This, plus Comparable, implements all the equality and comparison operators we could ever need.
+  def <=>(other)
+    other_components = other.binary_components
+    binary_components.each_with_index do |our_component, index|
+      other_component = other_components[index]
+      out = our_component <=> other_component
+      return out unless out == 0
+    end
+    0
+  end
+
+  include Comparable
+
+  # ...well, except for this one. ;)
+  def eql?(other)
+    self == other
+  end
+
+  # Let's make sure we hash ourselves correctly, so we, well, work inside a Hash. :)
+  def hash
+    binary_components.hash
+  end
+
+  # Returns the hex-encoded variant of the UID -- exactly the string that nginx logs to disk or puts in
+  # a header created with $uid_got, etc.
+  #
+  # This will be identical for two equivalent UIDs, no matter what representations they were parsed from.
+  def to_hex_string
+    @binary_components.pack("VVVV").bytes.map { |b| "%02X" % b }.join("")
+  end
+
+  # Returns the Base64-encoded variant of the UID -- exactly the string that ends up in a cookie in client browsers.
+  #
+  # This will be identical for two equivalent UIDs, no matter what representations they were parsed from.
+  def to_base64_string
+    Base64.encode64(@binary_components.pack("NNNN"))
+  end
+
+  # Returns a pure-binary string for this UID.
+  #
+  # This will be identical for two equivalent UIDs, no matter what representations they were parsed from.
+  def to_binary_string
+    @binary_components.pack("NNNN")
+  end
+
+  # Returns an Array of length 4; each component will be a single, four-byte Integer, in big-endian byte order,
+  # representing the underlying UID.
+  def binary_components
+    @binary_components
+  end
+
+  # Returns any extra binary data that was supplied (and successfully ignored) past the end of the input string.
+  def extra_binary_data
+    @extra_binary_data
+  end
+
+  # This is the "service number" -- the first byte of the UID string. Typically, this is the IP address of the
+  # server that generated the UID.
+  def service_number
+    @binary_components[0]
+  end
+
+  # Returns the "service number" as an IPAddr object; you can call #to_s on this to get a string in dotted notation.
+  def service_number_as_ip
+    IPAddr.new(service_number, Socket::AF_INET)
+  end
+
+  # This is the "issue time" -- the time at which the UID was generated, as a Un*x epoch time -- as an integer.
+  def issue_time
+    @binary_components[1]
+  end
+
+  # This is the issue time, as a Time object.
+  def issue_time_as_time
+    Time.at(issue_time)
+  end
+
+  # This is the "process ID" component -- the third four bytes. While this is documented as simply being the process ID
+  # of the server process, realistically, servers add more entropy to avoid collisions (and because PIDs are often
+  # only two bytes long). Nginx sets the top two bytes to the two least-significant bytes of the current time in
+  # microseconds, for example. So we have #pid_component, here, that returns the whole thing, and #pid that returns
+  # just the actual PID.
+  def pid_component
+    @binary_components[2]
+  end
+
+  # As explained above, this is just the PID itself from the third comppnent.
+  def pid
+    pid_component & 0xFFFF
+  end
+
+  # This is the "sequencer" component -- the last four bytes, which contains both a cookie version number (the LSB)
+  # and a sequence number (the three MSBs).
+  def sequencer_component
+    @binary_components[3]
+  end
+
+  # The actual sequencer value.
+  def sequencer
+    sequencer_component >> 8
+  end
+
+  # The sequencer value, as a six-byte hex string, which is a much easier way of looking at it (since it's oddly
+  # defined to start at 0x030303.)
+  def sequencer_as_hex
+    "%06x" % sequencer
+  end
+
+  # The version number of the cookie -- the LSB of the sequencer_component.
+  def cookie_version_number
+    @binary_components[3] & 0xFF
+  end
+end

data/spec/web_server_uid_spec.rb

@@ -0,0 +1,309 @@
+require 'web_server_uid'
+
+describe WebServerUid do
+  describe "class methods" do
+    it "should return nil if given nil" do
+      expect(WebServerUid.from_hex(nil)).to be_nil
+      expect(WebServerUid.from_binary(nil)).to be_nil
+      expect(WebServerUid.from_base64(nil)).to be_nil
+    end
+
+    it "should return a value if given one" do
+      expect(WebServerUid.from_hex("0100007FE7D7F35241946D1E02030303").to_hex_string).to eq("0100007FE7D7F35241946D1E02030303")
+      expect(WebServerUid.from_binary("\177\000\000\001R\363\327\347\036m\224A\003\003\003\002").to_hex_string).to eq("0100007FE7D7F35241946D1E02030303")
+      expect(WebServerUid.from_base64("fwAAAVLz1+cebZRBAwMDAgS=").to_hex_string).to eq("0100007FE7D7F35241946D1E02030303")
+    end
+
+    it "should be able to parse a value from a header" do
+      expect(WebServerUid.from_header("st_brid=0100007FE7D7F35241946D1E02030303", "st_brid").to_hex_string).to eq("0100007FE7D7F35241946D1E02030303")
+      expect(WebServerUid.from_header("baz=0100007FE7D7F35241946D1E02030303", "st_brid")).to be_nil
+      expect(WebServerUid.from_header("st_brid=0100007FE7D7F35241946D1E0203030Q", "st_brid")).to be_nil
+      expect(WebServerUid.from_header("st_brid=0100007FE7D7F35241946D1E020303", "st_brid")).to be_nil
+    end
+  end
+
+  describe "generating a brand-new instance" do
+    before :each do
+      @generated = WebServerUid.generate
+    end
+
+    it "should be able to create a new instance" do
+      expect(@generated).to be_instance_of(WebServerUid)
+    end
+
+    it "should have the right time" do
+      expect((Time.now.to_i - @generated.issue_time.to_i).abs).to be < 300
+    end
+
+    it "should have the right IP" do
+      require 'socket'
+      expected_ipaddr_string = UDPSocket.open {|s| s.connect('8.8.8.8', 1); s.addr.last }
+      expected_ipaddr = IPAddr.new(expected_ipaddr_string)
+
+      expect(@generated.service_number_as_ip).to eq(expected_ipaddr)
+    end
+
+    it "should let you override the IP" do
+      @generated = WebServerUid.generate(:ip_address => "127.0.0.1")
+      expect(@generated.to_hex_string).to match(/^0100007F/)
+    end
+
+    it "should fail if passed unknown options" do
+      expect { WebServerUid.generate(:foo => :bar) }.to raise_error(ArgumentError)
+    end
+
+    it "should fail if passed something that isn't an IP address" do
+      expect { WebServerUid.generate(:ip_address => /foobar/) }.to raise_error(ArgumentError)
+    end
+
+    it "should have the right PID" do
+      expect(@generated.pid).to eq(Process.pid)
+    end
+
+    it "should have the right sequencer" do
+      expect(@generated.sequencer).to be >= 0x030303
+      expect(@generated.sequencer).to be <= (0x030303 + 50)
+    end
+
+    it "should have the right version" do
+      expect(@generated.cookie_version_number).to eq(2)
+    end
+
+    it "should never generate the same ID twice" do
+      ids = [ ]
+      1000.times { ids << WebServerUid.generate }
+      expect(ids.map(&:to_hex_string).uniq.length).to eq(1000)
+    end
+  end
+
+  describe "known examples" do
+    { :hex => '0100007FE7D7F35241946D1E02030303', :base64 => 'fwAAAVLz1+cebZRBAwMDAgS=',
+      :binary => "\177\000\000\001R\363\327\347\036m\224A\003\003\003\002" }.each do |type, raw|
+      describe type.to_s do
+        let(:raw) { @raw }
+        let(:uid) { WebServerUid.new(raw, type) }
+
+        it "should have the right hex string" do
+          expect(uid.to_hex_string).to eq('0100007FE7D7F35241946D1E02030303')
+        end
+
+        it "should have the right Base64 string" do
+          expect(uid.to_base64_string).to eq("fwAAAVLz1+cebZRBAwMDAg==\n")
+        end
+
+        it "should have the right binary string" do
+          actual = uid.to_binary_string
+          actual.force_encoding(Encoding::BINARY) if actual.respond_to?(:force_encoding)
+          expected = "\177\000\000\001R\363\327\347\036m\224A\003\003\003\002"
+          expected.force_encoding(Encoding::BINARY) if expected.respond_to?(:force_encoding)
+
+          expect(actual).to eq(expected)
+          if uid.to_binary_string.respond_to?(:encoding)
+            expect(uid.to_binary_string.encoding).to eq(Encoding::BINARY)
+          end
+        end
+
+        it "should have the right binary components" do
+          expect(uid.binary_components).to eq([ 2130706433, 1391712231, 510497857, 50529026 ])
+        end
+
+        it "should have the right extra binary data" do
+          if type == :base64
+            expect(uid.extra_binary_data).to eq("\004")
+          else
+            expect(uid.extra_binary_data).to eq("")
+          end
+        end
+
+        it "should have the right service number" do
+          expect(uid.service_number).to eq(2130706433)
+        end
+
+        it "should have the right server IP" do
+          expect(uid.service_number_as_ip).to eq(IPAddr.new('127.0.0.1'))
+        end
+
+        it "should have the right issue time" do
+          expect(uid.issue_time).to eq(1391712231)
+        end
+
+        it "should have the right issue time as time" do
+          expect(uid.issue_time_as_time).to eq(Time.parse('Thu Feb 06 10:43:51 -0800 2014'))
+        end
+
+        it "should have the right PID component" do
+          expect(uid.pid_component).to eq(510497857)
+        end
+
+        it "should have the right PID" do
+          expect(uid.pid).to eq(37953)
+        end
+
+        it "should have the right sequencer component" do
+          expect(uid.sequencer_component).to eq(50529026)
+        end
+
+        it "should have the right sequencer value" do
+          expect(uid.sequencer).to eq(197379)
+        end
+
+        it "should have the right sequencer, as hex" do
+          expect(uid.sequencer_as_hex).to eq("030303")
+        end
+
+        it "should have the right cookie version number" do
+          expect(uid.cookie_version_number).to eq(2)
+        end
+      end
+    end
+  end
+
+  describe "comparison and hashing" do
+    let(:example_1) { WebServerUid.from_hex('0100007FE7D7F35241946D1E02030303') }
+    let(:example_2) { WebServerUid.from_hex('0100007FE7D7F35241946D1E02030304') }
+    let(:example_3) { WebServerUid.from_hex('0100007FE7D7F35241946D1E02030303') }
+    let(:example_4) { WebServerUid.from_hex('0100006FE7D7F35241946D1E02030303') }
+
+    it "should compare itself with <=> correctly" do
+      expect(example_1 <=> example_2).to be < 0
+      expect(example_1 <=> example_3).to eq(0)
+      expect(example_1 <=> example_4).to be > 0
+      expect(example_2 <=> example_3).to be > 0
+      expect(example_2 <=> example_4).to be > 0
+      expect(example_3 <=> example_4).to be > 0
+
+      expect(example_2 <=> example_1).to be > 0
+      expect(example_3 <=> example_1).to eq(0)
+      expect(example_4 <=> example_1).to be < 0
+      expect(example_3 <=> example_2).to be < 0
+      expect(example_4 <=> example_2).to be < 0
+      expect(example_4 <=> example_3).to be < 0
+
+      expect(example_1.eql?(example_1)).to be_true
+      expect(example_1.eql?(example_3)).to be_true
+      expect(example_3.eql?(example_1)).to be_true
+      expect(example_1.eql?(example_2)).to_not be_true
+      expect(example_2.eql?(example_1)).to_not be_true
+    end
+
+    it "should hash itself correctly" do
+      expect(example_1.hash).to eq(example_1.hash)
+      expect(example_1.hash).to eq(example_3.hash)
+      expect(example_2.hash).to eq(example_2.hash)
+      expect(example_3.hash).to eq(example_3.hash)
+      expect(example_4.hash).to eq(example_4.hash)
+    end
+  end
+
+  (0..99).each do |index|
+    describe "random example #{index}" do
+      before :each do
+        @service_number = rand(2**32)
+        @issue_time = rand(2**31)
+        @issue_time_as_time = Time.at(@issue_time)
+        @pid_high = rand(2**16)
+        @pid = rand(2**16)
+        @sequencer = rand(2**24)
+        @version = rand(256)
+        @extra = rand(2) == 0 || true ? (65 + rand(26)).chr : ''
+
+        @components = [
+          @service_number,
+          @issue_time,
+          (@pid_high << 16) | @pid,
+          (@sequencer << 8) | @version
+        ]
+
+        @binary = @components.pack("NNNN")
+        @hex = @components.pack("VVVV").bytes.map { |b| "%02X" % b}.join("")
+        @base64_base = Base64.encode64(@components.pack("NNNN"))
+        @base64 = begin
+          out = @base64_base.dup
+          if @extra.length > 0
+            if out =~ /^(.*?)(=*)$/
+              out = "#{$1}#{@extra}#{$2}"
+            end
+          end
+          out
+        end
+      end
+
+      [ :hex, :base64, :binary ].each do |type|
+        describe type.to_s do
+          before :each do
+            @raw = instance_variable_get("@#{type}")
+            @uid = WebServerUid.new(@raw, type)
+          end
+
+          it "should have the right hex string" do
+            expect(@uid.to_hex_string).to eq(@hex)
+          end
+
+          it "should have the right Base64 string" do
+            expect(@uid.to_base64_string).to eq(@base64_base)
+          end
+
+          it "should have the right binary string" do
+            expect(@uid.to_binary_string).to eq(@binary)
+            if @uid.to_binary_string.respond_to?(:encoding)
+              expect(@uid.to_binary_string.encoding).to eq(Encoding::BINARY)
+            end
+          end
+
+          it "should have the right binary components" do
+            expect(@uid.binary_components).to eq(@components)
+          end
+
+          it "should have the right extra binary data" do
+            if type == :base64 && @extra.length > 0
+              actual_extra = Base64.decode64(@base64)[16..-1]
+              expect(@uid.extra_binary_data).to eq(actual_extra)
+            else
+              expect(@uid.extra_binary_data).to eq("")
+            end
+          end
+
+          it "should have the right service number" do
+            expect(@uid.service_number).to eq(@service_number)
+          end
+
+          it "should have the right server IP" do
+            expect(@uid.service_number_as_ip).to eq(IPAddr.new(@service_number, Socket::AF_INET))
+          end
+
+          it "should have the right issue time" do
+            expect(@uid.issue_time).to eq(@issue_time)
+          end
+
+          it "should have the right issue time as time" do
+            expect(@uid.issue_time_as_time).to eq(@issue_time_as_time)
+          end
+
+          it "should have the right PID component" do
+            expect(@uid.pid_component).to eq(@components[2])
+          end
+
+          it "should have the right PID" do
+            expect(@uid.pid).to eq(@pid)
+          end
+
+          it "should have the right sequencer component" do
+            expect(@uid.sequencer_component).to eq(@components[3])
+          end
+
+          it "should have the right sequencer value" do
+            expect(@uid.sequencer).to eq(@sequencer)
+          end
+
+          it "should have the right sequencer, as hex" do
+            expect(@uid.sequencer_as_hex).to eq("%06x" % @sequencer)
+          end
+
+          it "should have the right cookie version number" do
+            expect(@uid.cookie_version_number).to eq(@version)
+          end
+        end
+      end
+    end
+  end
+end

data/web_server_uid.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'web_server_uid/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "web_server_uid"
+  spec.version       = WebServerUid::VERSION
+  spec.authors       = ["Andrew Geweke"]
+  spec.email         = ["ageweke@swiftype.com"]
+  spec.summary       = %q{Parse and represent UID tokens from Apache's mod_uid / nginx's ngx_http_userid_module in Ruby.}
+  spec.homepage      = "http://www.github.com/swiftype/web_server_uid"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14"
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: web_server_uid
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Andrew Geweke
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2014-02-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.5"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - &id004 
+      - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.14"
+  type: :development
+  version_requirements: *id003
+description: 
+email: 
+- ageweke@swiftype.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/web_server_uid.rb
+- lib/web_server_uid/version.rb
+- spec/web_server_uid_spec.rb
+- web_server_uid.gemspec
+homepage: http://www.github.com/swiftype/web_server_uid
+licenses: 
+- MIT
+metadata: {}
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id004
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id004
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Parse and represent UID tokens from Apache's mod_uid / nginx's ngx_http_userid_module in Ruby.
+test_files: 
+- spec/web_server_uid_spec.rb