pod4 0.10.6 → 1.0.0

data/lib/pod4/version.rb

@@ -1,3 +1,3 @@
 module Pod4 
-  VERSION = '0.10.6'
+  VERSION = '1.0.0'
 end

data/md/breaking_changes.md

@@ -0,0 +1,80 @@
+A list of breaking / major changes by version.
+
+1.0
+===
+
+Interfaces Can Now Note If Their ID Autoincrements
+--------------------------------------------------
+
+Autoincrement defaults to true if missing. So any models without auto-incrementing keys will need
+to change to specifically name them as such.
+
+You can now add the id field to `attr_columns` even if the ID field autoincrements. Which means
+that you can refer to the id field by name as an attribute instead of using `@model_id`, if you
+want.
+
+Some minor changes that arise from this:
+
+* #to_ot now always includes the ID field, whether or not it is named in `attr_columns`.
+
+* If you manually update the ID field even though autoincrement is true, that change will not be
+  stored in the database / whatever. We don't pass that on.
+
+* If you change the ID field in a non-autoincrement model, `@model_id` is now updated to reflect
+  that when you call #update.  (This was not true before 1.0.)
+
+Connection Objects
+------------------
+
+This is technically not a breaking change. No existing code needs to be rewritten; interfaces
+create connection objects for you if you don't use them.  But, this is a really big change
+internally, and as such I would be surprised if it didn't effect existing < 1.0 code.
+
+This counts double if you use PgInterface and TdsInterface, since these are now being served one
+connection per thread and are finally really threadsafe.
+
+NullInterface
+-------------
+
+The behaviour of NullInterface has changed.  Prior to 1.0 it did not simulate an auto-incrementing
+ID field.  Now it does, and that behaviour is the default.
+
+Existing code that assumes the previous behaviour should be fixed by setting the id_ai attribute to
+false:
+
+```
+ifce = NullInterface.new(:code, :name, [])
+ifce.id_ai = false
+set_interface ifce
+```
+
+DSL To Declare a Custom List Method
+-----------------------------------
+
+This is provided by the new Tweaking mixin, so it's not a breaking change.
+
+Model Status :empty
+-------------------
+
+This has been renamed to :unknown to reflect that it is also the status of objects created by #list;
+:unknown means that validation has not been run yet. This definitely counts as a breaking change,
+although you would only be effected if you were testing for :empty in a model...
+
+
+0.10.1
+======
+
+Validate Method Takes A Parameter
+---------------------------------
+
+You now need to give your #validate method a parameter, the operation that is being validated --
+one of :create :read :update or :delete.
+
+In fact you could optionally do this since 0.9.  But in 0.10.1 we removed the slightly confusing
+feature where if validation failed on a #delete, we deleted the record anyway.  So 0.10.1 marks the
+point where, for all practical purposes, you have to give your method a parameter and check it at
+least for :delete.
+
+Models that don't do this will not allow deletion of records that fail validation, which presumably
+is an anti-feature for you.
+

data/spec/common/basic_model_spec.rb

@@ -1,10 +1,10 @@
-require 'octothorpe'
+require "octothorpe"
 
-require 'pod4/basic_model'
-require 'pod4/null_interface'
+require "pod4/basic_model"
+require "pod4/null_interface"
 
 
-describe 'WeirdModel' do
+describe "BasicModel" do
 
   ##
   # We define a model class to test, since in normal operation we would never use Model directly,
@@ -15,7 +15,7 @@ describe 'WeirdModel' do
   # unless we specifically say `.and_call_original` instead of `.and_return`. 
   #
   # This is actually quite nice, but more than a little confusing when you see it for the first
-  # time. Its use isn't spelled out in the RSpec docs AFAICS. 
+  # time. Its use isn"t spelled out in the RSpec docs AFAICS. 
   #
   let(:weird_model_class) do
     Class.new Pod4::BasicModel do
@@ -32,104 +32,105 @@ describe 'WeirdModel' do
   let(:model) { weird_model_class.new(20) }
 
 
-  describe 'Model.set_interface' do
-    it 'requires an Interface object' do
+  describe "Model.set_interface" do
+
+    it "requires an Interface object" do
       expect( weird_model_class ).to respond_to(:set_interface).with(1).argument
     end
 
-    # it 'sets interface' - covered by the interface test
+    # it "sets interface" - covered by the interface test
   end
-  ##
 
   
-  describe 'Model.interface' do
-    it 'is the interface object' do
+  describe "Model.interface" do
+
+    it "is the interface object" do
       expect( weird_model_class.interface ).to be_a_kind_of NullInterface
       expect( weird_model_class.interface.id_fld ).to eq :id
     end
+
   end
-  ##
 
 
-  describe '#new' do
+  describe "#new" do
 
-    it 'takes an optional ID' do
+    it "takes an optional ID" do
       expect{ weird_model_class.new    }.not_to raise_exception
       expect{ weird_model_class.new(1) }.not_to raise_exception
     end
 
-    it 'sets the ID attribute' do
+    it "sets the ID attribute" do
       expect( weird_model_class.new(23).model_id ).to eq 23
     end
 
-    it 'sets the status to empty' do
-      expect( weird_model_class.new.model_status ).to eq :empty
+    it "sets the status to unknown" do
+      expect( weird_model_class.new.model_status ).to eq :unknown
     end
 
-    it 'initializes the alerts attribute' do
+    it "initializes the alerts attribute" do
       expect( weird_model_class.new.alerts ).to eq([])
     end
 
-    it 'doesn''t freak out if the ID is not an integer' do
+    it "doesn""t freak out if the ID is not an integer" do
       expect{ weird_model_class.new("france") }.not_to raise_exception
       expect( weird_model_class.new("france").model_id ).to eq "france"
     end
 
-  end
-  ##
+  end # of #new
+
 
+  describe "#interface" do
 
-  describe '#interface' do
-    it 'returns the interface set in the class definition, again' do
+    it "returns the interface set in the class definition, again" do
       expect( weird_model_class.new.interface ).to be_a_kind_of NullInterface
       expect( weird_model_class.new.interface.id_fld ).to eq :id
     end
-  end
-  ##
+
+  end # of #interface
 
 
-  describe '#alerts' do
-    it 'returns the list of alerts against the model' do
+  describe "#alerts" do
+
+    it "returns the list of alerts against the model" do
       cm = weird_model_class.new
-      cm.fake_an_alert(:warning, :foo, 'one')
-      cm.fake_an_alert(:error,   :bar, 'two')
+      cm.fake_an_alert(:warning, :foo, "one")
+      cm.fake_an_alert(:error,   :bar, "two")
 
       expect( cm.alerts.size ).to eq 2
       expect( cm.alerts.map{|a| a.message} ).to match_array(%w|one two|)
     end
-  end
-  ##
 
+  end # of #alerts
 
-  describe '#add_alert' do
-    # add_alert is a protected method, which is only supposed to be called
-    # within the validate method of a subclass of Method. So we test it by
-    # calling our alert faking method
 
-    it 'requires type, message or type, field, message' do
+  describe "#add_alert" do
+    # add_alert is a private method, which is only supposed to be called within the a subclass of
+    # Method. So we test it by calling our alert faking method
+
+    it "requires type, message or type, field, message" do
       expect{ model.fake_an_alert        }.to raise_exception ArgumentError
       expect{ model.fake_an_alert(nil)   }.to raise_exception ArgumentError
-      expect{ model.fake_an_alert('foo') }.to raise_exception ArgumentError
+      expect{ model.fake_an_alert("foo") }.to raise_exception ArgumentError
 
-      expect{ model.fake_an_alert(:error, 'foo') }.not_to raise_exception
-      expect{ model.fake_an_alert(:warning, :name, 'bar') }.
+      expect{ model.fake_an_alert(:error, "foo") }.not_to raise_exception
+      expect{ model.fake_an_alert(:warning, :name, "bar") }.
         not_to raise_exception
 
     end
 
-    it 'only allows valid types' do
+    it "only allows valid types" do
       [:brian, :werning, nil, :alert, :danger].each do |l|
-        expect{ model.fake_an_alert(l, 'foo') }.to raise_exception ArgumentError
+        expect{ model.fake_an_alert(l, "foo") }.to raise_exception ArgumentError
       end
 
       [:warning, :error, :success, :info].each do |l|
-        expect{ model.fake_an_alert(l, 'foo') }.not_to raise_exception
+        expect{ model.fake_an_alert(l, "foo") }.not_to raise_exception
       end
 
     end
 
-    it 'creates an Alert and adds it to @alerts' do
-      lurch = 'Dnhhhhhh'
+    it "creates an Alert and adds it to @alerts" do
+      lurch = "Dnhhhhhh"
       model.fake_an_alert(:error, :price, lurch)
 
       expect( model.alerts.size ).to eq 1
@@ -137,80 +138,76 @@ describe 'WeirdModel' do
       expect( model.alerts.first.message ).to eq lurch
     end
 
-    it 'sets @model_status if the type is worse than @model_status' do
-      model.fake_an_alert(:warning, :price, 'xoo')
+    it "sets @model_status if the type is worse than @model_status" do
+      model.fake_an_alert(:warning, :price, "xoo")
       expect( model.model_status ).to eq :warning
 
-      model.fake_an_alert(:success, :price, 'flom')
+      model.fake_an_alert(:success, :price, "flom")
       expect( model.model_status ).to eq :warning
 
-      model.fake_an_alert(:info, :price, 'flom')
+      model.fake_an_alert(:info, :price, "flom")
       expect( model.model_status ).to eq :warning
 
-      model.fake_an_alert(:error, :price, 'qar')
+      model.fake_an_alert(:error, :price, "qar")
       expect( model.model_status ).to eq :error
 
-      model.fake_an_alert(:warning, :price, 'drazq')
+      model.fake_an_alert(:warning, :price, "drazq")
       expect( model.model_status ).to eq :error
     end
 
-    it 'ignores a new alert if identical to an existing one' do
-      lurch = 'Dnhhhhhh'
+    it "ignores a new alert if identical to an existing one" do
+      lurch = "Dnhhhhhh"
       2.times { model.fake_an_alert(:error, :price, lurch) }
 
       expect( model.alerts.size ).to eq 1
     end
 
-  end
-  ##
+  end # of #add_alert
 
 
-  describe '#clear_alerts' do
+  describe "#clear_alerts" do
     before do
       model.fake_an_alert(:error, "bad stuff")
       model.clear_alerts
     end
 
-    it 'resets the @alerts array' do
+    it "resets the @alerts array" do
       expect( model.alerts ).to eq([])
     end
 
-    it 'sets model_status to :okay' do
+    it "sets model_status to :okay" do
       expect( model.model_status ).to eq :okay
     end
 
-
-  end
-  ##
+  end # of #clear_alerts
 
 
-  describe '#raise_exceptions' do
+  describe "#raise_exceptions" do
 
-    it 'is also known as .or_die' do
+    it "is also known as .or_die" do
       cm = weird_model_class.new
       expect( cm.method(:raise_exceptions) ).to eq( cm.method(:or_die) )
     end
 
-    it 'raises ValidationError if model status is :error' do
-      model.fake_an_alert(:error, :price, 'qar')
+    it "raises ValidationError if model status is :error" do
+      model.fake_an_alert(:error, :price, "qar")
       expect{ model.raise_exceptions }.to raise_exception Pod4::ValidationError
     end
 
-    it 'does nothing if model status is not :error' do
+    it "does nothing if model status is not :error" do
       expect{ model.raise_exceptions }.not_to raise_exception
 
-      model.fake_an_alert(:info, :price, 'qar')
+      model.fake_an_alert(:info, :price, "qar")
       expect{ model.raise_exceptions }.not_to raise_exception
 
-      model.fake_an_alert(:success, :price, 'qar')
+      model.fake_an_alert(:success, :price, "qar")
       expect{ model.raise_exceptions }.not_to raise_exception
 
-      model.fake_an_alert(:warning, :price, 'qar')
+      model.fake_an_alert(:warning, :price, "qar")
       expect{ model.raise_exceptions }.not_to raise_exception
     end
 
-  end
-  ##
+  end # of #raise_exceptions
 
 
 end

data/spec/common/connection_pool_parallelism_spec.rb

@@ -0,0 +1,154 @@
+require "pod4/connection_pool"
+
+
+##
+# These tests cover how connection pool handles being called by simultaneous threads.  Note that
+# none of these tests _can ever_ fail when running under MRI, because of the GIL.
+#
+# Under jRuby, though, they can fail. Probably!  We're relying on >1 thread making the same call
+# simultaneously, with 50 threads all trying to act at the same time. That's not actually _certain_
+# to happen.  Without the Mutex in ConnectionPool::Pool, these seem to fail MOST of the time.  For
+# me.
+#
+# These tests are in a seperate spec file because they screw up the test suite.  One of two things
+# happens: 
+#
+# * A timeout waiting for threads to be "done" or be killed
+# * A Stomp timeout error(!?)
+#
+# You can duplicate this by running these three tests, in this order:
+#
+# 1. This one
+# 2. NebulousInterface
+# 3. SequelInterface (pg)
+#
+# (It passes when you run it on its own.)
+#
+# My working theory is that we just run out of threads, somehow? It might be something to do with
+# this jRuby bug: https://github.com/jruby/jruby/issues/5476
+#
+# For the time being I've renamed this test file `_spoc` instead of `_spec` so that it's not part
+# of the test suite. 
+#
+describe Pod4::ConnectionPool do
+
+  def make_threads(count, connection, interface)
+    threads = []
+
+    1.upto(count) do |idx|
+      threads << Thread.new do 
+        # Set things up and wait
+        Thread.current[:idx] = idx # might be useful for debugging
+        Thread.stop
+
+        # wait for the given sync time;  call #client; signal done; then wait
+        sleep 0.1 until Time.now >= Thread.current[:time]
+        connection.client(interface)
+        Thread.current[:done1] = true
+        Thread.stop 
+
+        # call #close; signal done; then wait
+        connection.close(interface)
+        Thread.current[:done2] = true
+        Thread.stop
+      end
+    end
+
+    threads
+  end
+
+  let(:ifce_class) do
+    Class.new Pod4::Interface do
+      def initialize;                  end
+      def close_connection;            end
+      def new_connection(opts); @conn; end
+
+      def set_conn(c); @conn = c; end
+    end
+  end
+
+
+  describe "(Parallelism)" do
+
+    before(:each) do
+      # If a thread suffers an exception, that's probably because of a race condition somewhere.
+      # eg: without the Mutex on ConnectionPool::Pool, nils get assigned to the pool somehow.
+      Thread.abort_on_exception = true
+
+      @connection = ConnectionPool.new(interface: ifce_class, max_clients: 55)
+      @connection.data_layer_options = "meh"
+      @interface = ifce_class.new
+      @interface.set_conn "floom"
+
+      # Set up 50 threads to call things at the same time.
+      @threads = make_threads(50, @connection, @interface)
+    end
+
+    after(:each) { @threads.each{|t| t.kill} }
+     
+    it "assigns new items to the pool from multiple threads successfully" do
+      test_start = Time.now
+
+      # Ask all the threads to restart, calling #client all at the same time
+      # (Unfortunately it's in the hands of Ruby's scheduler whether the thread gets restarted)
+      at = Time.now + 2
+      @threads.each{|t| t[:time] = at }
+      @threads.each{|t| t.run }
+      sleep 0.1 until (@threads.all?{|t| t[:done1] } || Time.now >= test_start + 5)
+
+      # We have no control over whether the scheduler will actually restart each thread!
+      # Best we can do is count the number of threads that ran
+      count = @threads.count{|t| t[:done1] }
+
+      expect( @connection._pool.size                               ).to eq count
+      expect( @connection._pool.select{|x| x.thread_id.nil? }.size ).to eq 0
+    end
+
+    #
+    # Note that we don't have to test the safety of the operation of retrieving the client for an
+    # already assigned thread, or for freeing that client for use by other threads -- since only
+    # one thread can ever access that pool item...
+    #
+
+    it "reassigns items to new threads from multiple threads successfully" do
+      test_start = Time.now
+
+      # ask all the threads to connect -- again, the scheduler might let us down.
+      at = Time.now
+      @threads.each{|t| t[:time] = at }
+      @threads.each{|t| t.run }
+      sleep 0.1 until (@threads.all?{|t| t[:done1] } || Time.now >= test_start + 5)
+      count1 = @threads.count{|t| t[:done1] }
+
+      # Release all the connections (that got run in the connect phase...)
+      # (Again, just because we ask a thread to run, that doesn't mean it does!)
+      @threads.select{|t| t[:done1] }.each{|t| t.run }
+      sleep 0.1 until (@threads.all?{|t| t[:done2] } || Time.now >= test_start + 10)
+      count2 = @threads.count{|t| t[:done2] }
+
+      # Make some new threads. These should reuse connections from the pool. Make a couple less
+      # than should be free.
+      newthreads = make_threads(count2 - 2, @connection, @interface)
+
+      at = Time.now + 2
+      newthreads.each{|t| t[:time] = at }
+      newthreads.each{|t| t.run }
+      sleep 0.1 until (newthreads.all?{|t| t[:done1] } || Time.now >= test_start + 15)
+
+      count3 = newthreads.count{|t| t[:done1] }
+
+      # So at this point count1 is the number of threads in @threads that were connected; count2
+      # the number that were then released; count3 the number of threads in newthreads that were
+      # (re-)connected.
+      expect( @connection._pool.size                               ).to eq count1
+      expect( @connection._pool.select{|x| x.thread_id.nil? }.size ).to eq(count1 - count3)
+
+      # tidy up
+      newthreads.each{|t| t.kill }
+    end
+    
+  end # of (Parallelism)
+  
+  
+end
+