em-pg-client-helper 0.2.0 → 0.3.0

data/lib/em-pg-client-helper.rb

@@ -48,17 +48,16 @@ module PG::EM::Client::Helper
 	#
 	# Calling this method opens up a transaction (by executing `BEGIN`), and
 	# then runs the supplied block, passing in a transaction object which you
-	# can use to execute SQL commands.  You *must* call `txn.commit` or
-	# `txn.callback` yourself as your inner-most callback, otherwise you will
-	# leave the connection in a weird limbo state.
+	# can use to execute SQL commands.  Once the transaction is finished,
+	# `COMMIT` or `ROLLBACK` will be sent to the DB server to complete the
+	# transaction, depending on whether or not any errors (query failures or
+	# Ruby exceptions) appeared during the transaction.  You can also
+	# manually call `txn.rollback(reason)` if you want to signal that the
+	# transaction should be rolled back.
 	#
-	# Since `db_transaction` returns a deferrable, you should use `#callback`
-	# to specify what to run after the transaction completes.
-	#
-	# If an SQL error occurs during the transaction, the block's execution
-	# will be aborted, a `ROLLBACK` will be executed, and the `#errback`
-	# block (if defined) on the deferrable that `db_transaction` returns will
-	# be executed (rather than the `#callback` block).
+	# You should use `#callback` and `#errback` against the deferrable that
+	# `db_transaction` returns to specify what to run after the transaction
+	# completes successfully or fails, respectively.
 	#
 	# Arguments:
 	#
@@ -72,10 +71,7 @@ module PG::EM::Client::Helper
 	#    of the transaction.  This block will be passed a
 	#    `PG::EM::Client::Helper::Transaction` instance, which has methods to
 	#    allow you to commit or rollback the transaction, and execute SQL
-	#    statements within the context of the transaction.  This block *must*
-	#    return a deferrable.  When that returned deferrable completes, a
-	#    COMMIT will be triggered automatically.  If that deferrable fails,
-	#    a ROLLBACK will be sent, instead.
+	#    statements within the context of the transaction.
 	#
 	# Returns a deferrable object, on which you can call `#callback` and
 	# `#errback` to define what to do when the transaction succeeds or fails,
@@ -98,74 +94,8 @@ module PG::EM::Client::Helper
 	def quote_identifier(id)
 		"\"#{id.gsub(/"/, '""')}\""
 	end
+end
 
-	class Transaction
-		include ::PG::EM::Client::Helper
-		include ::EventMachine::Deferrable
-		
-		# Create a new transaction.  You shouldn't have to call this yourself;
-		# `db_transaction` should create one and pass it to your block.
-		def initialize(conn, opts, &blk)
-			@conn       = conn
-			@opts       = opts
-			@active     = true
-			
-			conn.exec_defer("BEGIN").callback do
-				blk.call(self)
-			end.errback { |ex| rollback(ex) }
-		end
-
-		# Signal the database to commit this transaction.  You must do this
-		# once you've completed your queries, it won't be called automatically
-		# for you.  Once you've committed the transaction, you cannot use it
-		# again; if you execute a query against a committed transaction, an
-		# exception will be raised.
-		#
-		def commit
-			@conn.exec_defer("COMMIT").callback do
-				self.succeed
-				@active = false
-			end.errback { |ex| rollback(ex) }
-		end
-
-		# Signal the database to abort this transaction.  You only need to
-		# call this method if you need to rollback for some business logic
-		# reason -- a rollback will be automatically performed for you in the
-		# event of a database error or other exception.
-		#
-		def rollback(ex)
-			if @active
-				@conn.exec_defer("ROLLBACK") do
-					@active = false
-					self.fail(ex)
-				end
-			end
-		end
-
-		# Insert a row of data into the database table `tbl`, using the keys
-		# from the `params` hash as the field names, and the values from the
-		# `params` hash as the field data.  Once the query has completed,
-		# `blk` will be called to allow the transaction to continue.
-		#
-		def insert(tbl, params, &blk)
-			exec(*insert_sql(tbl, params), &blk)
-		end
-
-		# Execute an arbitrary block of SQL in `sql` within the transaction. 
-		# If you need to pass dynamic values to the query, those should be
-		# given in `values`, and referenced in `sql` as `$1`, `$2`, etc.  The
-		# given block will be called if and when the query completes
-		# successfully.
-		#
-		def exec(sql, values=[], &blk)
-			unless @active
-				raise RuntimeError,
-				      "Cannot execute a query in a transaction that has been closed"
-			end
+require_relative 'em-pg-client-helper/transaction'
+require_relative 'em-pg-client-helper/deferrable_group'
 
-			@conn.exec_defer(sql, values).
-			        errback { |ex| rollback(ex) }.
-			        tap { |df| df.callback(&blk) if blk }
-		end
-	end
-end

data/lib/em-pg-client-helper/deferrable_group.rb

@@ -0,0 +1,43 @@
+# Fire a callback/errback when all of a group of deferrables is finished.
+#
+# Essentially a "barrier" for deferrables; you define the set of
+# deferrables you want to group together, and when they're all finished,
+# only *then* does the callback(s) or errback(s) on this deferrable fire.
+#
+class PG::EM::Client::Helper::DeferrableGroup
+	include ::EventMachine::Deferrable
+
+	def initialize
+		@failed = false
+		@first_failure = nil
+		@outstanding = []
+		yield(self) if block_given?
+	end
+
+	def add(df)
+		@outstanding << df
+		df.callback { completed(df) }.errback { |ex| failed(df, ex) }
+	end
+
+	def completed(df)
+		@outstanding.delete(df)
+		maybe_done
+	end
+
+	def failed(df, ex)
+		@first_failure ||= ex
+		@failed = true
+		completed(df)
+	end
+
+	private
+	def maybe_done
+		if @outstanding.empty?
+			if @failed
+				fail(@first_failure)
+			else
+				succeed
+			end
+		end
+	end
+end

data/lib/em-pg-client-helper/transaction.rb

@@ -0,0 +1,77 @@
+class PG::EM::Client::Helper::Transaction
+	include ::PG::EM::Client::Helper
+	include ::EventMachine::Deferrable
+
+	# Create a new transaction.  You shouldn't have to call this yourself;
+	# `db_transaction` should create one and pass it to your block.
+	def initialize(conn, opts, &blk)
+		@conn       = conn
+		@opts       = opts
+		@active     = true
+
+		DeferrableGroup.new do |dg|
+			@dg = dg
+			dg.add(
+				conn.exec_defer("BEGIN").callback do
+					blk.call(self)
+				end.errback { |ex| rollback(ex) }
+			)
+		end.callback { commit }.errback { |ex| rollback(ex) }
+	end
+
+	# Signal the database to commit this transaction.  You must do this
+	# once you've completed your queries, it won't be called automatically
+	# for you.  Once you've committed the transaction, you cannot use it
+	# again; if you execute a query against a committed transaction, an
+	# exception will be raised.
+	#
+	def commit
+		if @active
+			@conn.exec_defer("COMMIT").callback do
+				@active = false
+				self.succeed
+			end.errback { |ex| rollback(ex) }
+		end
+	end
+
+	# Signal the database to abort this transaction.  You only need to
+	# call this method if you need to rollback for some business logic
+	# reason -- a rollback will be automatically performed for you in the
+	# event of a database error or other exception.
+	#
+	def rollback(ex)
+		if @active
+			@conn.exec_defer("ROLLBACK") do
+				@active = false
+				self.fail(ex)
+			end
+		end
+	end
+
+	# Insert a row of data into the database table `tbl`, using the keys
+	# from the `params` hash as the field names, and the values from the
+	# `params` hash as the field data.  Once the query has completed,
+	# `blk` will be called to allow the transaction to continue.
+	#
+	def insert(tbl, params, &blk)
+		exec(*insert_sql(tbl, params), &blk)
+	end
+
+	# Execute an arbitrary block of SQL in `sql` within the transaction.
+	# If you need to pass dynamic values to the query, those should be
+	# given in `values`, and referenced in `sql` as `$1`, `$2`, etc.  The
+	# given block will be called if and when the query completes
+	# successfully.
+	#
+	def exec(sql, values=[], &blk)
+		unless @active
+			raise RuntimeError,
+					"Cannot execute a query in a transaction that has been closed"
+		end
+
+		@dg.add(
+			@conn.exec_defer(sql, values).
+					  tap { |df| df.callback(&blk) if blk }
+		)
+	end
+end

data/spec/db_transaction_spec.rb

@@ -1,76 +1,145 @@
 require_relative './spec_helper'
 
 describe "PG::EM::Client::Helper#db_transaction" do
-	def mock_query_chain(queries, fail_on = -1, &blk)
-		mock_conn = double(PG::EM::Client)
+	let(:mock_conn) { double(PG::EM::Client) }
 
-		queries.each_with_index do |q, i|
-			df = EM::DefaultDeferrable.new
+	def expect_query_failure(q, args=nil, exec_time = 0.001)
+		expect_query(q, args, exec_time, :fail)
+	end
 
-			ex = expect(mock_conn).
-			  to receive(:exec_defer).
-			  with(*q).
-			  and_return(df)
+	def expect_query(q, args=nil, exec_time = 0.001, disposition = :succeed)
+		df = EM::DefaultDeferrable.new
 
-			# Rollback expects a yield
-			if q == ["ROLLBACK"]
-				ex.and_yield()
-			end
-			
-			if i == fail_on
-				df.fail
-			else
-				df.succeed
-			end
+		ex = expect(mock_conn).
+		  to receive(:exec_defer).
+		  with(*[q, args].compact).
+		  and_return(df).
+		  ordered
+
+		# Rollback expects a yield
+		if q == "ROLLBACK"
+			ex.and_yield()
 		end
 
-		EM.run_block do
-			db_transaction(mock_conn, &blk)
+		EM.add_timer(exec_time) do
+			df.__send__(disposition)
+		end
+	end
+
+	def in_transaction(&blk)
+		db_transaction(mock_conn, &blk).callback { EM.stop }.errback { EM.stop }
+	end
+
+	def in_em
+		EM.run do
+			EM.add_timer(1) { EM.stop; raise "test timeout" }
+			yield
 		end
 	end
 
 	it "runs a BEGIN/COMMIT cycle by default" do
-		mock_query_chain([["BEGIN"], ["COMMIT"]]) do
-			EM::DefaultDeferrable.new.tap { |df| df.succeed }
+		in_em do
+			expect_query("BEGIN")
+			expect_query("COMMIT")
+			in_transaction do
+				# Nothing
+			end
 		end
 	end
-	
+
 	it "rolls back if BEGIN fails" do
-		mock_query_chain([["BEGIN"], ["ROLLBACK"]], 0) do
-			EM::DefaultDeferrable.new.tap { |df| df.succeed }
+		in_em do
+			expect_query_failure("BEGIN")
+			expect_query("ROLLBACK")
+			in_transaction do
+				# Nothing
+			end
 		end
 	end
-	
+
 	it "rolls back if COMMIT fails" do
-		mock_query_chain([["BEGIN"], ["COMMIT"], ["ROLLBACK"]], 1) do
-			EM::DefaultDeferrable.new.tap { |df| df.succeed }
+		in_em do
+			expect_query("BEGIN")
+			expect_query_failure("COMMIT")
+			expect_query("ROLLBACK")
+			in_transaction do
+				# Nothing
+			end
 		end
 	end
 
-	it "runs a simple INSERT" do
-		mock_query_chain([
-		  ["BEGIN"],
-		  ['INSERT INTO "foo" ("bar") VALUES ($1)',
-		   ["baz"]
-		  ],
-		  ["COMMIT"]
-		]) do |txn|
-			txn.insert("foo", :bar => 'baz')
+	it "runs a simple INSERT correctly" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
+			expect_query("COMMIT")
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz')
+			end
 		end
 	end
 
 	it "rolls back after a failed INSERT" do
-		mock_query_chain(
-		  [
-		    ["BEGIN"],
-		    ['INSERT INTO "foo" ("bar") VALUES ($1)',
-		     ["baz"]
-		    ],
-		    ["ROLLBACK"]
-		  ],
-		  1
-		) do |txn|
-			txn.insert("foo", :bar => 'baz')
+		in_em do
+			expect_query("BEGIN")
+			expect_query_failure('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
+			expect_query("ROLLBACK")
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz')
+			end
+		end
+	end
+
+	it "runs nested inserts in the right order" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['baz'])
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['wombat'])
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['quux'])
+			expect_query("COMMIT")
+
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz') do
+					txn.insert("foo", :bar => 'wombat') do
+						txn.insert("foo", :bar => 'quux')
+					end
+				end
+			end
+		end
+	end
+
+	it "is robust against slow queries" do
+		# All tests up to now *could* have just passed "by accident", because
+		# the queries were running fast enough to come out in order, even if
+		# we weren't properly synchronising.  However, by making the second
+		# insert run slowly, we should be able to be confident that we're
+		# properly running the queries in order.
+		in_em do
+			expect_query("BEGIN")
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['baz'])
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['wombat'], 0.1)
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ['quux'])
+			expect_query("COMMIT")
+
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz') do
+					txn.insert("foo", :bar => 'wombat') do
+						txn.insert("foo", :bar => 'quux')
+					end
+				end
+			end
+		end
+	end
+
+	it "doesn't COMMIT if we rolled back" do
+		in_em do
+			expect_query("BEGIN")
+			expect_query('INSERT INTO "foo" ("bar") VALUES ($1)', ["baz"])
+			expect_query("ROLLBACK")
+			in_transaction do |txn|
+				txn.insert("foo", :bar => 'baz')
+				txn.rollback("Because I can")
+			end
 		end
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-pg-client-helper
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-23 00:00:00.000000000 Z
+date: 2014-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git-version-bump
@@ -218,6 +218,8 @@ files:
 - Rakefile
 - em-pg-client-helper.gemspec
 - lib/em-pg-client-helper.rb
+- lib/em-pg-client-helper/deferrable_group.rb
+- lib/em-pg-client-helper/transaction.rb
 - spec/db_insert_spec.rb
 - spec/db_transaction_spec.rb
 - spec/insert_sql_spec.rb
@@ -236,7 +238,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3974973386782984490
+      hash: 2182591116081055210
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -245,7 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3974973386782984490
+      hash: 2182591116081055210
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23