noid 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 50e4fa485ed73bb6f4d313b5fda35a6ecfeb08e7
-  data.tar.gz: 763d9e2e9f279a0afa7461b9f2ddee88d00e1318
+  metadata.gz: acd76906cdc40cfe6803fcf7ca54bf88ce0ca981
+  data.tar.gz: 90961988a2c041a1c7946cb57c61923fa303f3ac
 SHA512:
-  metadata.gz: b5d19a31918d22133f8c282e3deb6baab51e27cbe7fb65797a503bffff474b34964bef5d9e81d657f591653d807e0be33b5ab2bab644ac633a9904561fecf66c
-  data.tar.gz: 48e622908ddedc36c1296ecdbb9818694f7f3a680f5d610fc9115254d630bcb6489519bf00903ad1f6d751254fa5816ab4c989a93014b73439b1d99c8dae73d9
+  metadata.gz: 3c481bd56ec9435a09875416e0e24751f07f348eebf1234ede326bef81a031582e9574fa51e457507d231696724cc167e1978e39aeb88c6672a625766e58ea6e
+  data.tar.gz: c93b2e4e8a68a6bc7c17bafbe8131dbe479fdfcaff85954aa0712a050882a1fcbbd6c4c3118ba6637859f908b7600639a56d84df62cc866d19268989ffa5c2d4

data/VERSION

@@ -1 +1 @@
-0.7.2
+0.8.0

data/lib/noid/minter.rb

@@ -1,19 +1,58 @@
 module Noid
+  # Minters come in two varieties: stateful and stateless. A stateless minter --
+  # typically used with random rather than sequential templates, since minting
+  # in a sequence requires state to know the current position in the sequence --
+  # mints random identifiers and **will** mint duplicates eventually, depending
+  # upon the size of the identifier space in the provided template.
+  #
+  # A stateful minter is a minter that has been initialized with parameters
+  # reflecting its current state. (A common way to store state between mintings
+  # is to call the minter `#dump` method which serializes the necessary parts of
+  # minter state to a hash, which may be persisted on disk or in other
+  # back-ends.) The parameters that are included are:
+  #
+  #  * template, a string setting the identifier pattern
+  #  * counters, a hash of "buckets" each with a current and max value
+  #  * seq, an integer reflecting how far into the sequence the minter is
+  #  * rand, a random number generator
+  #
+  # Minters using random templates use a number of containers, each with a
+  # similar number of identifiers to split the identifier space into manageable
+  # chunks (or "buckets") and to increase the appearance of randomness in the
+  # identifiers.
+  #
+  # As an example, let's assume a random identifier template that has 100
+  # possible values. It might have 10 buckets, each with 10 identifiers that
+  # look similar because they have similar numeric values. Every call to `#mint`
+  # will use the random number generator stored in the minter's state to select
+  # a bucket at random. Stateless minters will select a bucket at random as
+  # well.
+  #
+  # The difference between stateless and stateful minters in this context is
+  # that stateful random minters are *replayable* as long as you have persisted
+  # the minter's state, which includes a random number generator part of which
+  # is its original seed, which may be used over again in the future to replay
+  # the sequence of identifiers in this minter
   class Minter
-    attr_reader :seed, :seq, :template
+    attr_reader :template, :seq
     attr_writer :counters
 
     def initialize(options = {})
-      if options[:state]
-        # Only set the sequence ivar if this is a stateful minter
-        @seq = options[:seq]
-      else
-        @max_counters = options[:max_counters]
-        @after_mint = options[:after_mint]
-      end
-      @counters = options[:counters]
       @template = Template.new(options[:template])
-      seed(options[:seed], options[:seq])
+
+      @counters = options[:counters]
+      @max_counters = options[:max_counters]
+
+      # callback when an identifier is minted
+      @after_mint = options[:after_mint]
+
+      # used for random minters
+      @rand = options[:rand] if options[:rand].is_a? Random
+      @rand ||= Marshal.load(options[:rand]) if options[:rand]
+      @rand ||= Random.new(options[:seed] || Random.new_seed)
+
+      # used for sequential minters
+      @seq = options[:seq] || 0
     end
 
     ##
@@ -21,10 +60,19 @@ module Noid
     def mint
       n = next_in_sequence
       id = template.mint(n)
+      next_sequence if random?
       @after_mint.call(self, id) if @after_mint
       id
     end
 
+    ##
+    # Reseed the RNG
+    def seed(seed_number, sequence = 0)
+      @rand = Random.new(seed_number)
+      sequence.times { next_random }
+      @rand
+    end
+
     ##
     # Is the identifier valid under the template string and checksum?
     # @param [String] id
@@ -34,25 +82,18 @@ module Noid
     end
 
     ##
-    # Seed the random number generator with a seed and sequence offset
-    # @return [Random]
-    def seed(seed_number = nil, seq = 0)
-      @rand = seed_number ? Random.new(seed_number) : Random.new
-      @seed = @rand.seed
-      @seq = seq || 0
-
-      seq.times { next_random } if seq
-
-      @rand
+    # Returns the number of identifiers remaining in the minter
+    # @return [Fixnum]
+    def remaining
+      return Float::INFINITY if unbounded?
+      template.max - seq
     end
 
     def next_in_sequence
-      n = @seq
-      @seq += 1
-      if template.generator == 'r'
+      if random?
         next_random
       else
-        n
+        next_sequence
       end
     end
 
@@ -65,6 +106,10 @@ module Noid
       n
     end
 
+    def next_sequence
+      seq.tap { @seq += 1 }
+    end
+
     def random_bucket
       @rand.rand(counters.size)
     end
@@ -73,7 +118,7 @@ module Noid
     # Counters to use for quasi-random NOID sequences
     def counters
       return @counters if @counters
-      return [] unless template.generator == 'r'
+      return [] unless random?
 
       percounter = template.max / (@max_counters || Noid::MAX_COUNTERS) + 1
       t = 0
@@ -93,7 +138,20 @@ module Noid
     end
 
     def dump
-      { state: true, seq: @seq, seed: @seed, template: template.template, counters: Marshal.load(Marshal.dump(counters)) }
+      {
+        template: template.template,
+        counters: Marshal.load(Marshal.dump(counters)),
+        seq: seq,
+        rand: Marshal.dump(@rand) # we would Marshal.load this too, but serializers don't persist the internal state correctly
+      }
+    end
+
+    def random?
+      template.generator == 'r'
+    end
+
+    def unbounded?
+      template.generator == 'z'
     end
   end
 end

data/spec/lib/minter_spec.rb

@@ -164,7 +164,7 @@ describe Noid::Minter do
       minter = described_class.new(template: '.rddd')
       d = minter.dump
       expect(d[:seq]).to eq 0
-      expect(d[:seed]).to eq(minter.instance_variable_get('@seed'))
+      expect(described_class.new(d).instance_variable_get('@rand').seed).to eq(minter.instance_variable_get('@rand').seed)
     end
 
     it "allows a random identifier minter to be 'replayed' accurately" do
@@ -198,6 +198,69 @@ describe Noid::Minter do
     end
   end
 
+  describe '#remaining' do
+    context 'with a sequential template' do
+      subject { described_class.new(template: '.sed') }
+      context 'with a new minter' do
+        it 'returns 290' do
+          expect(subject.remaining).to eq 290
+        end
+      end
+      context 'with an in-progress minter' do
+        before { 100.times { subject.mint } }
+        it 'returns 190' do
+          expect(subject.remaining).to eq 190
+        end
+      end
+      context 'with an exhausted minter' do
+        before { 290.times { subject.mint } }
+        it 'returns 0' do
+          expect(subject.remaining).to eq 0
+        end
+      end
+    end
+    context 'with a random template' do
+      subject { described_class.new(template: '.reek') }
+      context 'with a new minter' do
+        it 'returns 841' do
+          expect(subject.remaining).to eq 841
+        end
+      end
+      context 'with an in-progress minter' do
+        before { 441.times { subject.mint } }
+        it 'returns 400' do
+          expect(subject.remaining).to eq 400
+        end
+      end
+      context 'with an exhausted minter' do
+        before { 841.times { subject.mint } }
+        it 'returns 0' do
+          expect(subject.remaining).to eq 0
+        end
+      end
+    end
+    context 'with an unlimited template' do
+      subject { described_class.new(template: '.zdd') }
+      context 'with a new minter' do
+        it 'returns unlimited ' do
+          expect(subject.remaining).to eq Float::INFINITY
+        end
+      end
+      context 'with an in-progress minter' do
+        before { 51.times { subject.mint } }
+        it 'returns unlimited' do
+          expect(subject.remaining).to eq Float::INFINITY
+        end
+      end
+      context 'with a minter that appears to be exhausted' do
+        before { 101.times { subject.mint } }
+        it 'returns unlimited' do
+          expect(subject.remaining).to eq Float::INFINITY
+        end
+      end
+    end
+  end
+
   describe 'multithreading-safe example' do
     def stateful_minter
       File.open('minter-state', File::RDWR | File::CREAT, 0644) do |f|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noid
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Chris Beer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-03 00:00:00.000000000 Z
+date: 2015-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler