oversip-mod-mysql 0.0.1 → 0.1.0

data/README.md

@@ -1,167 +1,99 @@
 # oversip-mod-mysql
 
-`oversip-mod-mysql` provides an easy to use MySQL connector for [OverSIP](http://www.oversip.net) proxy based on [mysql2](https://github.com/brianmario/mysql2) driver. The library allows both pure async style (via callbacks) or serial style (by using [em-synchrony](https://github.com/igrigorik/em-synchrony/) Gem).
-
-Check the [mysql2 documentation](https://github.com/brianmario/mysql2/blob/master/README.md) for the exact syntax and usage of the MySQL queries.
+## Overview
 
+`oversip-mod-mysql` provides an easy to use MySQL connector for [OverSIP](http://www.oversip.net) proxy based on [mysql2](https://github.com/brianmario/mysql2) driver.
 
-## API
+Starting from version 0.1.0 `oversip-mod-mysql` depends on [OverSIP](http://www.oversip.net) >= 1.3.0 which enforces the usage of "sync" style coding via [em-synchrony](https://github.com/igrigorik/em-synchrony/) Gem.
 
+* For more information about `em-synchrony` usage check [Untangling Evented Code with Ruby Fibers](http://www.igvita.com/2010/03/22/untangling-evented-code-with-ruby-fibers/).
 
-### Method `OverSIP:M:Mysql.add_pool(options, db_data)`
-
-Creates a MySQL connection pool. Parameters:
+Check the [mysql2 documentation](https://github.com/brianmario/mysql2/blob/master/README.md) for the exact syntax and usage of the MySQL queries.
 
-* `options`: A mandatory `Hash` with the following fields:
-   * `:name`: Mandatory field. Must be a `Symbol` with the name for this pool.
-   * `:pool_size`: The number of parallel MySQL connections to perform. By default 10.
-   * `:synchrony`: Whether to use [em-synchrony](https://github.com/igrigorik/em-synchrony/) or not. By default `false`.
 
-* `db_data`: A mandatory `Hash` that will be passed to [`Mysql2::EM::Client.new`](https://github.com/brianmario/mysql2#connection-options).
+## API
 
-*NOTE:* There is no need to pass the option `:async => true` in `db_data`. That is automatically done by the library.
 
+### Method `OverSIP::Modules::Mysql.add_pool(options)`
 
-### Method `OverSIP:M:Mysql.pool(name)`
+Creates a MySQL connection pool by receiving a mandatory `options` (a `Hash`) with the following fields:
+* `:pool_name`: Mandatory field. Must be a `Symbol` with the name for this pool.
+* `:pool_size`: The number of parallel MySQL connections to perform. By default 10.
+* The rest of the fields will be passed to each [`Mysql2::EM::Client.new`](https://github.com/brianmario/mysql2#connection-options) being created.
 
-Retrieves a previously created pool with the given name. Raises an `ArgumentError` if the given name does not exist in the list of created pools.
+The method allows passing a block which would be later called by passing as argument each generated `Mysql2::EM::Client` instance.
 
+The created connection pool is an instance of [`EventMachine::Synchrony::ConnectionPool`](https://github.com/igrigorik/em-synchrony/blob/master/lib/em-synchrony/connection_pool.rb).
 
 
+### Method `OverSIP::Modules::Mysql.pool(pool_name)`
 
-## Pure async style usage
+Retrieves a previously created pool with the given name. Raises an `ArgumentError` if the given name does not exist in the list of created pools.
 
-When creating a pool with `options[:synchrony] => false` (default behaviour) the obtained pool is a [`EventMachine::Pool`](https://github.com/ibc/EventMachine-LE/blob/master/lib/em/pool.rb) instance and thus, it requires the following usage:
 
 
-### Example
+## Usage Example
 
 On top of `/etc/oversip/server.rb`:
 
 ```
 require "oversip-mod-mysql"
+```
+
+
+Within the `OverSIP::SipEvents.on_initialize()` method in `/etc/oversip/server.rb`:
 
+```
 def (OverSIP::SystemEvents).on_initialize
-  OverSIP::M::Mysql.add_pool(
-    {
-      :name => :my_async_db,
-      :pool_size => 5,
-      :synchrony => false
-    },
-    {
-      :host => "localhost",
-      :username => "oversip",
-      :password => "xxxxxx",
-      :database => "oversip",
-      :cast_booleans => true,
-      :symbolize_keys => true
-    }
-  )
+  OverSIP::M::Mysql.add_pool({
+    :pool_name => :my_db,
+    :pool_size => 5,
+    :host => "localhost",
+    :username => "oversip",
+    :password => "xxxxxx",
+    :database => "oversip"
+  }) {|conn| log_info "MySQL created connection: #{conn.inspect}" }
 end
 ```
 
 Somewhere within the `OverSIP::SipEvents.on_request()` method in `/etc/oversip/server.rb`:
 
 ```
-pool = OverSIP::M::Mysql.pool(:my_async_db)
+pool = OverSIP::M::Mysql.pool(:my_db)
 
 begin
-  pool.perform do |db_conn|
-    query = db_conn.aquery "SELECT * FROM users WHERE user = \'#{request.from.user}\'"
-
-    query.callback do |result|
-      log_info "DB async query result: #{result.to_a.inspect}"
-      if result.any?
-        # Add a X-Header with value the 'custom_header' field of the table row:
-        request.set_header "X-Header", result.first["custom_header"]
-        proxy = ::OverSIP::SIP::Proxy.new
-        proxy.route request
-      else
-        request.reply 404, "User not found in DB"
-      end
-    end
-
-    query.errback do |error|
-      log_error "DB async query error: #{error.inspect}"
-      request.reply 500, "DB async query error"
-    end
+  result = pool.query "SELECT * FROM users WHERE user = \'#{request.from.user}\'"
+  log_info "DB query result: #{result.to_a.inspect}"
+  if result.any?
+    # Add a X-Header with value the 'custom_header' field of the table row:
+    request.set_header "X-Header", result.first["custom_header"]
+    proxy = ::OverSIP::SIP::Proxy.new :proxy_out
+    proxy.route request
+    return
+  else
+    request.reply 404, "User not found in DB"
+    return
   end
 
 rescue ::Mysql2::Error => e
-  log_error "DB async query error:"
+  log_error "DB query error:"
   log_error e
-  request.reply 500, "DB async query error"
+  request.reply 500, "DB query error"
+  return
 end
 ```
 
 
-## Sync style usage with `em-synchrony`
-
-When creating a pool with `options[:synchrony] => true`  the obtained pool is a [`EventMachine::Synchrony::ConnectionPool`](https://github.com/igrigorik/em-synchrony/blob/master/lib/em-synchrony/connection_pool.rb) instance.
-
-Please ensure you properly understand how [em-synchrony](https://github.com/igrigorik/em-synchrony/) works. Specially take into account that just the code within the `EM.synchrony do [...] end` block is executed serially. Code placed after that block is executed immediately, this is, *before* the serial code is executed. So if you want to use serial style coding write all your logic code within a `EM.synchrony do [...] end` block.
-
-* For more information about `em-synchrony` usage check [Untangling Evented Code with Ruby Fibers](http://www.igvita.com/2010/03/22/untangling-evented-code-with-ruby-fibers/).
-
-
-### Example
-
-On top of `/etc/oversip/server.rb`:
-
-```
-require "oversip-mod-mysql"
-
-def (OverSIP::SystemEvents).on_initialize
-  OverSIP::M::Mysql.add_pool(
-    {
-      :name => :my_sync_db,
-      :pool_size => 5,
-      :synchrony => true
-    },
-    {
-      :host => "localhost",
-      :username => "oversip",
-      :password => "xxxxxx",
-      :database => "oversip",
-      :cast_booleans => true,
-      :symbolize_keys => true
-    }
-  )
-end
-```
-
-Somewhere within the `OverSIP::SipEvents.on_request()` method in `/etc/oversip/server.rb`:
-
-```
-EM.synchrony do
-  pool = OverSIP::M::Mysql.pool(:my_sync_db)
-
-  begin
-    result = pool.query "SELECT * FROM users WHERE user = \'#{request.from.user}\'"
-    log_info "DB sync query result: #{result.to_a.inspect}"
-    if result.any?
-      # Add a X-Header with value the 'custom_header' field of the table row:
-      request.set_header "X-Header", result.first["custom_header"]
-      proxy = ::OverSIP::SIP::Proxy.new :proxy_out
-      proxy.route request
-    else
-      request.reply 404, "User not found in DB"
-    end
-
-  rescue ::Mysql2::Error => e
-    log_error "DB sync query error:"
-    log_error e
-    request.reply 500, "DB sync query error"
-  end
-end
-```
+## Limitations
 
+[mysql2](https://github.com/brianmario/mysql2) driver has auto reconnection support (which is forced by `oversip-mod-mysql` by setting the field `options[:reconnect] => true`). Unfortunatelly the auto reconnect feature of `mysql2` driver is blocking which means that, in case the MySQL server goes down, OverSIP will get frozen during the auto reconnection attempt.
 
-## Using sync and async styles together
 
-A pool created with `OverSIP:M:Mysql.add_pool()` method must be sync or async. However the user can set two pools, the first one sync and the second one sync.
+## Dependencies
 
-When a sync pool is created, the library loads `em-synchrony/mysql2` which overrides the `Mysql2::EM::Client#query()` method. So if *at least* one of your pools uses sync style then you must use the `Mysql2::EM::Client#aquery()` method for the async pool (which is an alias of the original `query()` method).
+* Ruby > 1.9.2.
+* [oversip](http://www.oversip.net) Gem >= 1.3.0.
+* MySQL development library (the package `libmysqlclient-dev` in Debian/Ubuntu).
 
 
 ## Installation
@@ -173,4 +105,6 @@ When a sync pool is created, the library loads `em-synchrony/mysql2` which overr
 
 ## Author
 
-Iñaki Baz Castillo <ibc@aliax.net> (Github [@ibc](https://github.com/ibc)).
+Iñaki Baz Castillo
+* Mail: ibc@aliax.net
+* Github profile: [@ibc](https://github.com/ibc)

data/lib/oversip-mod-mysql.rb

@@ -1,7 +1,7 @@
-require "mysql2/em"
-
 require "oversip-mod-mysql/version.rb"
-require "oversip-mod-mysql/mysql2_em_client.rb"
+
+require "em-synchrony"
+require "em-synchrony/mysql2"
 
 
 module OverSIP
@@ -12,58 +12,46 @@ module OverSIP
       extend ::OverSIP::Logger
 
       DEFAULT_POOL_SIZE = 10
-      DEFAULT_SYNCHRONY = false
 
       @log_id = "Mysql module"
       @pools = {}
 
-      def self.add_pool options, db_data
+      def self.add_pool options
         raise ::ArgumentError, "`options' must be a Hash"  unless options.is_a? ::Hash
-        raise ::ArgumentError, "`db_data' must be a Hash"  unless db_data.is_a? ::Hash
 
-        name, pool_size, synchrony = options.values_at(:name, :pool_size, :synchrony)
-        pool_size ||= DEFAULT_POOL_SIZE
-        synchrony ||= DEFAULT_SYNCHRONY
+        pool_name = options.delete(:pool_name)
+        pool_size = options.delete(:pool_size) || DEFAULT_POOL_SIZE
 
-        raise ::ArgumentError, "`options[:name]' must be a Symbol"  unless name.is_a? ::Symbol
+        raise ::ArgumentError, "`options[:pool_name]' must be a Symbol"  unless pool_name.is_a? ::Symbol
         raise ::ArgumentError, "`options[:pool_size]' must be a positive Fixnum"  unless pool_size.is_a? ::Fixnum and pool_size > 0
 
-        # Forcing DB autoreconnect.
-        db_data[:reconnect] = true
+        block = ::Proc.new  if block_given?
 
-        # Use em-synchrony for serial coding.
-        if synchrony
-          begin
-            require "em-synchrony"
-            require "em-synchrony/mysql2"
-          rescue ::LoadError
-            OverSIP::Launcher.fatal "em-synchrony not installed: gem install em-synchrony"
-          end
+        ::OverSIP::SystemCallbacks.on_started do
+          log_info "Adding MySQL connection pool (name: #{pool_name.inspect}, size: #{pool_size})..."
+          @pools[pool_name] = ::EM::Synchrony::ConnectionPool.new(size: pool_size) do
+            # Avoid the hash to be modified internally.
+            new_options = options.clone
+            # Force DB autoreconnect.
+            new_options[:reconnect] = true
 
-          OverSIP::SystemCallbacks.on_started do
-            log_system_info "Adding a sync pool with name #{name.inspect}..."
-            @pools[name] = ::EM::Synchrony::ConnectionPool.new(size: pool_size) do
-              ::Mysql2::EM::Client.new(db_data)
-            end
-          end
+            conn = ::Mysql2::EM::Client.new(new_options)
 
-        # Don't use em-synchrony but pure callbacks.
-        else
-          OverSIP::SystemCallbacks.on_started do
-            log_system_info "Adding an async pool with name #{name.inspect}..."
-            pool = @pools[name] = ::EM::Pool.new
-            pool_size.times do
-              pool.add ::Mysql2::EM::Client.new(db_data)
-            end
+            # Call the given block by passing conn as argument.
+            block.call(conn)  if block
+            conn
           end
         end
       end  # def self.add_pool
 
-      def self.pool name
-        pool = @pools[name]
-        raise ::ArgumentError, "no pool with `name' #{name.inspect}"  unless pool
+      def self.pool pool_name
+        pool = @pools[pool_name]
+        raise ::ArgumentError, "no pool with `name' #{pool_name.inspect}"  unless pool
         pool
       end
+      class << self
+        alias :get_pool :pool
+      end
 
     end  # module Mysql
 

data/lib/oversip-mod-mysql/version.rb

@@ -4,8 +4,8 @@ module OverSIP
     module Mysql
       module Version
         MAJOR = 0
-        MINOR = 0
-        TINY  = 1
+        MINOR = 1
+        TINY  = 0
         DEVEL = nil  # Set to nil for stable releases.
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oversip-mod-mysql
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,22 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-04 00:00:00.000000000 Z
+date: 2012-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oversip
-  requirement: &16825480 !ruby/object:Gem::Requirement
+  requirement: &7556920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.3.0
   type: :runtime
   prerelease: false
-  version_requirements: *16825480
+  version_requirements: *7556920
 - !ruby/object:Gem::Dependency
   name: mysql2
-  requirement: &17963820 !ruby/object:Gem::Requirement
+  requirement: &7556360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,12 +32,9 @@ dependencies:
         version: 0.3.11
   type: :runtime
   prerelease: false
-  version_requirements: *17963820
-description: ! 'oversip-mod-mysql provides an easy to use MySQL connector for OverSIP
-  proxy. The library allows both pure async style (via callbacks) or serial style
-  (by using ''em-synchrony'' Gem).
-
-'
+  version_requirements: *7556360
+description: oversip-mod-mysql provides an easy to use MySQL connector for OverSIP
+  proxy.
 email:
 - ibc@aliax.net
 executables: []
@@ -46,7 +43,6 @@ extra_rdoc_files: []
 files:
 - lib/oversip-mod-mysql.rb
 - lib/oversip-mod-mysql/version.rb
-- lib/oversip-mod-mysql/mysql2_em_client.rb
 - README.md
 - AUTHORS
 - LICENSE

data/lib/oversip-mod-mysql/mysql2_em_client.rb

@@ -1,8 +0,0 @@
-module Mysql2
-  module EM
-    class Client
-      # Allow the aquery() method even if 'em-synchrony' is not loaded.
-      alias :aquery :query
-    end
-  end
-end