oversip-mod-mysql 0.0.1

data/AUTHORS

@@ -0,0 +1,5 @@
+MAIN AUTHOR
+===========
+
+- Iñaki Baz Castillo <ibc@aliax.net> (Github @ibc)
+

data/LICENSE

@@ -0,0 +1,25 @@
+Name: oversip-mod-mysql
+Maintainer: Iñaki Baz Castillo <ibc@aliax.net>
+Copyright (c) 2012 Iñaki Baz Castillo <ibc@aliax.net>
+
+
+License: The 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,176 @@
+# 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.
+
+
+## API
+
+
+### Method `OverSIP:M:Mysql.add_pool(options, db_data)`
+
+Creates a MySQL connection pool. Parameters:
+
+* `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).
+
+*NOTE:* There is no need to pass the option `:async => true` in `db_data`. That is automatically done by the library.
+
+
+### Method `OverSIP:M:Mysql.pool(name)`
+
+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.
+
+
+
+
+## Pure async style usage
+
+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
+
+On top of `/etc/oversip/server.rb`:
+
+```
+require "oversip-mod-mysql"
+
+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
+    }
+  )
+end
+```
+
+Somewhere within the `OverSIP::SipEvents.on_request()` method in `/etc/oversip/server.rb`:
+
+```
+pool = OverSIP::M::Mysql.pool(:my_async_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
+  end
+
+rescue ::Mysql2::Error => e
+  log_error "DB async query error:"
+  log_error e
+  request.reply 500, "DB async query error"
+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
+```
+
+
+## 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.
+
+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).
+
+
+## Installation
+
+```
+~$ gem install oversip-mod-mysql
+```
+
+
+## Author
+
+Iñaki Baz Castillo <ibc@aliax.net> (Github [@ibc](https://github.com/ibc)).

data/lib/oversip-mod-mysql.rb

@@ -0,0 +1,71 @@
+require "mysql2/em"
+
+require "oversip-mod-mysql/version.rb"
+require "oversip-mod-mysql/mysql2_em_client.rb"
+
+
+module OverSIP
+  module Modules
+
+    module Mysql
+
+      extend ::OverSIP::Logger
+
+      DEFAULT_POOL_SIZE = 10
+      DEFAULT_SYNCHRONY = false
+
+      @log_id = "Mysql module"
+      @pools = {}
+
+      def self.add_pool options, db_data
+        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
+
+        raise ::ArgumentError, "`options[:name]' must be a Symbol"  unless 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
+
+        # 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_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
+
+        # 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
+          end
+        end
+      end  # def self.add_pool
+
+      def self.pool name
+        pool = @pools[name]
+        raise ::ArgumentError, "no pool with `name' #{name.inspect}"  unless pool
+        pool
+      end
+
+    end  # module Mysql
+
+  end
+end

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

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

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

@@ -0,0 +1,17 @@
+module OverSIP
+  module Modules
+
+    module Mysql
+      module Version
+        MAJOR = 0
+        MINOR = 0
+        TINY  = 1
+        DEVEL = nil  # Set to nil for stable releases.
+      end
+
+      VERSION = [Version::MAJOR, Version::MINOR, Version::TINY].join(".")
+      VERSION << ".#{Version::DEVEL}"  if Version::DEVEL
+    end
+
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: oversip-mod-mysql
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Inaki Baz Castillo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oversip
+  requirement: &16825480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *16825480
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: &17963820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        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).
+
+'
+email:
+- ibc@aliax.net
+executables: []
+extensions: []
+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
+homepage: https://github.com/versatica/oversip-mod-mysql
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: MySQL connector module for OverSIP
+test_files: []
+has_rdoc: false