qrpc 0.1.1 → 0.2.0

data/CHANGES.txt

@@ -0,0 +1,11 @@
+
+0.2.0 (2011-02-04)
+* client implemented
+* switch to em-jack
+
+0.1.1 (2011-01-29)
+* small unimportant bug while destroying corrected
+* some constants move between modules
+
+0.1.0 (2011-01-18) 
+* initial version (implemented server only)

data/Gemfile

@@ -1,9 +1,9 @@
 source "http://rubygems.org"
 # Add dependencies required to use your gem here.
 # Example:
-   gem "json-rpc-objects", ">= 0.1.2"
+   gem "json-rpc-objects", ">= 0.3.1"
    gem "depq", ">= 0.4"
-   gem "em-beanstalk", ">= 0.0.10"
+   gem "em-jack", ">= 0.1.3"
    gem "eventmachine", ">= 0.12.10"
 
 # Add dependencies to develop your gem here.

data/Gemfile.lock

@@ -1,26 +1,26 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.2.2)
+    addressable (2.2.4)
     depq (0.4)
-    em-beanstalk (0.0.10)
+    em-jack (0.1.3)
       eventmachine
     eventmachine (0.12.10)
     git (1.2.5)
-    hash-utils (0.3.0)
+    hash-utils (0.4.1)
     jeweler (1.5.2)
       bundler (~> 1.0.0)
       git (>= 1.2.5)
       rake
-    json-rpc-objects (0.1.3)
+    json-rpc-objects (0.3.1)
       addressable (>= 2.2.2)
       hash-utils (>= 0.3.0)
       multitype-introspection (>= 0.1.0)
       types (>= 0.1.0)
       yajl-ruby (>= 0.7.8)
-    multitype-introspection (0.1.0)
+    multitype-introspection (0.1.2)
     rake (0.8.7)
-    types (0.1.0)
+    types (0.1.2)
       multitype-introspection (>= 0.1.0)
     yajl-ruby (0.7.9)
 
@@ -30,7 +30,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.0.0)
   depq (>= 0.4)
-  em-beanstalk (>= 0.0.10)
+  em-jack (>= 0.1.3)
   eventmachine (>= 0.12.10)
   jeweler (~> 1.5.2)
-  json-rpc-objects (>= 0.1.2)
+  json-rpc-objects (>= 0.3.1)

data/README.md

@@ -1,10 +1,10 @@
 QRPC
 ====
 
-**QRPC** currently implements queued JSON-RPC server which works as 
-normal RPC server, but through queue interface, so allows highly 
-scalable, distributed and asynchronous remote API implementation and 
-fast data processing. 
+**QRPC** currently implements queued JSON-RPC both client and server 
+which works as normal RPC server, but through queue interface, so allows 
+highly scalable, distributed and asynchronous remote API implementation 
+and fast data processing. 
 
 It's based on [eventmachine][1] and [beanstalkd][2] so it's fast and 
 thread safe. 
@@ -55,7 +55,7 @@ And in case of exception:
                 "backtrace" => <array of Base64 encoded strings>,
                 "dump" => {
                     "raw" => <Base 54 encoded marshaled exception object>,
-                    "format" => "Ruby"
+                    "format" => "ruby"
                 }
             }
         },
@@ -69,7 +69,7 @@ And in case of exception:
 Both `backtrace` and `dump` members are optional.
 
     
-### Usage
+### Server Usage
 
 Usage is simple. Look example:
 
@@ -81,8 +81,8 @@ Usage is simple. Look example:
         end
     end
 
-    server = QRPC::Server::new(Foo::new)
-    server.listen! QRPC::Locator::new("test")
+    server = QRPC::Server::new Foo::new
+    server.listen! QRPC::Locator::new "test"
     
 This creates an instance of `Foo` which will serve as API, creates
 locator of the queue *test* at default server *localhost:11300*. Queue 
@@ -98,7 +98,29 @@ or `#start_listening`.
 
 Reponse will be put to the same queue server, to queue named 
 `qrpc-<client identifier>-output`, with structure described above. 
-Client isn't implemented at this time.
+
+### Client Usage
+
+Client usage is simple too. Look example:
+
+    require "eventmachine"
+    require "qrpc/client"
+    
+    EM::run do
+        client = QRPC::Client::new QRPC::Locator::new "test"
+        client.subtract(2, 3) { |result| puts result }  # prints out -1
+    end
+    
+This connects to the *test* queue at default server *localhost:11300*,
+puts request to the real queue name *qrpc-test-input* and waits and then
+prints the result from `qrpc-<client-id>-output` queue. In case of 
+multiple requests should be noted, results can arrive in any order 
+because, of sure, QRPC is pseudo-fibered and asynchronous from 
+its principle.
+    
+Client is implemented as [evented][1] too, but in case of need you can 
+implement another one with non-evented interface using whatever 
+[beanstalkd][2] client you like of sure.
 
 Contributing
 ------------

data/Rakefile

@@ -16,7 +16,7 @@ Jeweler::Tasks.new do |gem|
   gem.name = "qrpc"
   gem.homepage = "http://github.com/martinkozak/qrpc"
   gem.license = "MIT"
-  gem.summary = 'Queued JSON-RPC server. Works as normal RPC server, but through queue interface, so allows highly scalable, distributed and asynchronous remote API implementation and fast data processing. It\'s based on eventmachine and beanstalkd, so it\'s fast and thread safe.'
+  gem.summary = 'Queued JSON-RPC client and server. Works as normal RPC server, but through queue interface, so allows highly scalable, distributed and asynchronous remote API implementation and fast data processing. It\'s based on eventmachine and beanstalkd, so it\'s fast and thread safe.'
   gem.email = "martinkozak@martinkozak.net"
   gem.authors = ["Martin Kozák"]
   # Include your dependencies below. Runtime dependencies are required when using your gem,

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/qrpc/client.rb

@@ -0,0 +1,277 @@
+# encoding: utf-8
+require "em-jack"
+require "uuid"
+require "qrpc/general"
+require "qrpc/client/job"
+require "json-rpc-objects/response"
+
+##
+# General QRPC module.
+#
+
+module QRPC
+    
+    ##
+    # Queue RPC client.
+    # @since 0.2.0
+    #
+    
+    class Client
+    
+        ##
+        # Holds locator of the target queue.
+        #
+        
+        @locator
+        
+        ##
+        # Holds client session ID.
+        #
+        
+        @id
+        
+        ##
+        # Holds input queue name.
+        #
+        
+        @input_name
+        
+        ##
+        # Holds input queue instance.
+        #
+        
+        @input_queue
+        
+        ##
+        # Holds output queue name.
+        #
+        
+        @output_name
+        
+        ##
+        # Holds output queue instance.
+        #
+        
+        @output_queue
+        
+        ##
+        # Indicates, results pooling is ran.
+        #
+        
+        @pooling
+        
+        ##
+        # Holds clients for finalizing.
+        #
+        
+        @@clients = { }
+        
+        
+        ##
+        # Constructor.
+        # @param [QRPC::Locator] locator of the output queue
+        #
+        
+        def initialize(locator)
+            @locator = locator
+            @pooling = false
+            @jobs = { }
+        
+            # Destructor
+            ObjectSpace.define_finalizer(self, self.class.method(:finalize).to_proc)
+            @@clients[self.object_id] = self
+        end
+        
+        ##
+        # Finalizer handler.
+        # @param [Integer] id id of finalized instance
+        #
+        
+        def self.finalize(id)
+            if @@clients.has_key? id
+                @@clients[id].finalize!
+            end
+        end
+        
+        ##
+        # Destructor.
+        #
+        
+        def finalize!
+            if not @input_queue.nil?
+                @input_queue.watch("default") do
+                    @input_queue.ignore(@input_name.to_s) do
+                        @input_queue.close
+                    end
+                end
+            end
+            
+            if not @output_queue.nil?
+                @output_queue.use("default") do
+                    @output_queue.close
+                end
+            end
+        end
+        
+        ##
+        # Handles call to RPC. (*********)
+        #
+        # Be warn, arguments will be serialized to JSON, so they should
+        # be serializable nativelly or implement +#to_json+ method.
+        #
+        # @param [Symbol] name name of the called methods
+        # @param [Array] args arguments of the called methods
+        # @param [Proc] block callback for returning result
+        #
+        
+        def method_missing(name, *args, &block)
+            self.put(self.create_job(name, args, &block))
+        end
+        
+        ##
+        # Creates job associated to this client session.
+        # 
+        # @param [Symbol] name name of the method of the job
+        # @param [Array] args arguments of the method call
+        # @param [Integer] priority job priority
+        # @param [Proc] block result returning callback
+        # @return [QRPC::Client::Job] new job
+        #
+        
+        def create_job(name, args, priority = QRPC::DEFAULT_PRIORITY, &block)
+            Client::Job::new(self.id, name, args, priority, &block)
+        end
+        
+        ##
+        # Puts job to client.
+        # @param [QRPC::Client::Job] job  job for put to output queue
+        
+        def put(job)
+            if not job.notification?
+                @jobs[job.id] = job
+            end
+            
+            self.output_queue do |queue|
+                queue.put(job.to_json)
+            end
+            
+            if (not @pooling) and (@jobs.length > 0)
+                self.pool!
+            end
+        end
+     
+        ##
+        # Starts input (results) pooling.
+        #
+        
+        def pool!
+            
+            # Results processing logic
+            processor = Proc::new do |job|
+                response = JsonRpcObjects::Response::parse(job.body)
+                id = response.id.to_sym
+                job.delete()
+                
+                if @jobs.include? id
+                    @jobs[id].assign_result(response)
+                end
+                
+                @jobs.delete(id)
+            end
+            
+            # Runs processor for each job            
+            parent = self
+            worker = EM.spawn do
+                parent.input_queue { |q| q.each_job(&processor) }
+            end
+            
+            ##
+            
+            worker.run
+            @pooling = true
+            
+        end
+        
+        ##
+        # Returns input name.
+        # @return [Symbol] input queue name
+        #
+        
+        def input_name
+            if @input_name.nil?
+                @input_name = (QRPC::QUEUE_PREFIX.dup << "-" << self.id.to_s << "-" << QRPC::QUEUE_POSTFIX_OUTPUT).to_sym
+            end
+            
+            return @input_name
+        end
+        
+        ##
+        # Returns input queue.
+        # @param [Proc] block block to which will be input queue given
+        #
+        
+        def input_queue(&block)
+            if @input_queue.nil?
+                @input_queue = EMJack::Connection::new(:host => @locator.host, :port => @locator.port)
+                @input_queue.watch(self.input_name.to_s) do
+                    @input_queue.ignore("default") do
+
+                        # Results pooler error handler
+                        @input_queue.on_error do |error|
+                            raise Exception::new("Beanstalk error: " << error.to_s)
+                        end
+                        
+                        # Returns
+                        block.call(@input_queue)
+                        
+                    end
+                end
+            else
+                block.call(@input_queue)
+            end
+        end
+        
+        ##
+        # Returns output name.
+        # @return [Symbol] output queue name
+        #
+        
+        def output_name
+            if @output_name.nil?
+                @output_name = (QRPC::QUEUE_PREFIX.dup << "-" << @locator.queue << "-" << QRPC::QUEUE_POSTFIX_INPUT).to_sym
+            end
+            
+            return @output_name
+        end
+        
+        ##
+        # Returns output queue.
+        # @param [Proc] block block to which will be output queue given
+        #
+        
+        def output_queue(&block)
+            if @output_queue.nil?
+                @output_queue = EMJack::Connection::new(:host => @locator.host, :port => @locator.port)
+                @output_queue.use(self.output_name.to_s) do
+                    block.call(@output_queue)
+                end
+            else
+                block.call(@output_queue)
+            end
+        end
+        
+        ##
+        # Returns client (or maybe session is better) ID.
+        # @return [Symbol] client (session) ID
+        #
+        
+        def id
+            if @id.nil?
+                @id = UUID.generate.to_sym
+            end
+            
+            return @id
+        end
+                
+    end
+end

data/lib/qrpc/client/exception.rb

@@ -0,0 +1,72 @@
+# encoding: utf-8
+require "qrpc/protocol/exception-data"
+
+##
+# General QRPC module.
+#
+
+module QRPC
+    
+    ##
+    # Queue RPC client.
+    #
+    
+    class Client
+    
+        ##
+        # Queue RPC client exception.
+        # @since 0.2.0
+        #
+        
+        class Exception < ::Exception
+
+            ##
+            # Gets one from protocol exception object.
+            # Returns marshalled original or reconstructed version.
+            #
+            # @param [JsonRpcObjects::Generic::Error] proto JSON-RPC error object
+            # @return [Exception, QRPC::Client::Exception] exception according
+            #   to sucessfullness of the unmarshaling
+            #
+            
+            def self.get(proto)
+            
+                # Converts protocol exception to exception data object
+                proto = QRPC::Protocol::ExceptionData::new(proto.data)
+            
+                # Tries to unmarshall
+                if proto.dump.format == :ruby
+                    begin
+                        exception = Marshal.load(Base64.decode64(proto.dump.raw))
+                    rescue
+                        # pass
+                    end
+                end
+                
+                # If unsuccessfull, creates from data
+                if exception.nil?
+                    exception = self::new(proto)
+                end
+
+                return exception
+            end
+            
+            ##
+            # Constructor.
+            # Initializes from protocol exception data object.
+            #
+            # @param [QRPC::Protocol::ExceptionData] data exception data object
+            #
+            
+            def initialize(data)
+                message = data.name.dup << ": " << data.message
+                backtrace = data.backtrace.map { |i| Base64.decode64(i) }
+                backtrace.reject! { |i| i.empty? }
+                
+                super(message)
+                self.set_backtrace(backtrace)
+            end
+            
+        end
+    end
+end