actionwebservice 0.5.0

data/lib/action_web_service/base.rb

@@ -0,0 +1,41 @@
+require 'action_web_service/support/class_inheritable_options'
+require 'action_web_service/support/signature'
+
+module ActionWebService # :nodoc:
+  class ActionWebServiceError < StandardError # :nodoc:
+  end
+
+  # An Action Web Service object implements a specified API.
+  #
+  # Used by controllers operating in _Delegated_ dispatching mode.
+  #
+  # ==== Example
+  # 
+  #   class PersonService < ActionWebService::Base
+  #     web_service_api PersonAPI
+  #
+  #     def find_person(criteria)
+  #       Person.find_all [...]
+  #     end
+  #
+  #     def delete_person(id)
+  #       Person.find_by_id(id).destroy
+  #     end
+  #   end
+  #
+  #   class PersonAPI < ActionWebService::API::Base
+  #     api_method :find_person,   :expects => [SearchCriteria], :returns => [[Person]]
+  #     api_method :delete_person, :expects => [:int]
+  #   end
+  #
+  #   class SearchCriteria < ActionStruct::Base
+  #     member :firstname, :string
+  #     member :lastname,  :string
+  #     member :email,     :string
+  #   end
+  class Base
+    # Whether to report exceptions back to the caller in the protocol's exception
+    # format
+    class_inheritable_option :web_service_exception_reporting, true
+  end
+end

data/lib/action_web_service/client.rb

@@ -0,0 +1,3 @@
+require 'action_web_service/client/base'
+require 'action_web_service/client/soap_client'
+require 'action_web_service/client/xmlrpc_client'

data/lib/action_web_service/client/base.rb

@@ -0,0 +1,39 @@
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+    class ClientError < StandardError # :nodoc:
+    end
+
+    class Base # :nodoc:
+      def initialize(api, endpoint_uri)
+        @api = api
+        @endpoint_uri = endpoint_uri
+      end
+
+      def method_missing(name, *args) # :nodoc:
+        call_name = method_name(name)
+        return super(name, *args) if call_name.nil?
+        perform_invocation(call_name, args)
+      end
+
+      protected
+        def perform_invocation(method_name, args) # :nodoc:
+          raise NotImplementedError, "use a protocol-specific client"
+        end
+
+      private
+        def method_name(name)
+          if @api.has_api_method?(name.to_sym)
+            name.to_s
+          elsif @api.has_public_api_method?(name.to_s)
+            @api.api_method_name(name.to_s).to_s
+          else
+            nil
+          end
+        end
+
+        def lookup_class(klass)
+          klass.is_a?(Hash) ?  klass.values[0] : klass
+        end
+    end
+  end
+end

data/lib/action_web_service/client/soap_client.rb

@@ -0,0 +1,88 @@
+require 'soap/rpc/driver'
+require 'uri'
+
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+
+    # Implements SOAP client support (using RPC encoding for the messages).
+    #
+    # ==== Example Usage
+    #
+    #   class PersonAPI < ActionWebService::API::Base
+    #     api_method :find_all, :returns => [[Person]]
+    #   end
+    #
+    #   soap_client = ActionWebService::Client::Soap.new(PersonAPI, "http://...")
+    #   persons = soap_client.find_all
+    #
+    class Soap < Base
+
+      # Creates a new web service client using the SOAP RPC protocol.
+      #
+      # +api+ must be an ActionWebService::API::Base derivative, and
+      # +endpoint_uri+ must point at the relevant URL to which protocol requests
+      # will be sent with HTTP POST.
+      #
+      # Valid options:
+      # [<tt>:service_name</tt>]    If the remote server has used a custom +wsdl_service_name+
+      #                             option, you must specify it here
+      def initialize(api, endpoint_uri, options={})
+        super(api, endpoint_uri)
+        @service_name = options[:service_name] || 'ActionWebService'
+        @namespace = "urn:#{@service_name}" 
+        @mapper = ActionWebService::Protocol::Soap::SoapMapper.new(@namespace)
+        @protocol = ActionWebService::Protocol::Soap::SoapProtocol.new(@mapper)
+        @soap_action_base = options[:soap_action_base]
+        @soap_action_base ||= URI.parse(endpoint_uri).path
+        @driver = create_soap_rpc_driver(api, endpoint_uri)
+      end
+
+      protected
+        def perform_invocation(method_name, args)
+          @driver.send(method_name, *args)
+        end
+
+        def soap_action(method_name)
+          "#{@soap_action_base}/#{method_name}"
+        end
+
+      private
+        def create_soap_rpc_driver(api, endpoint_uri)
+          @mapper.map_api(api)
+          driver = SoapDriver.new(endpoint_uri, nil)
+          driver.mapping_registry = @mapper.registry
+          api.api_methods.each do |name, info|
+            public_name = api.public_api_method_name(name)
+            qname = XSD::QName.new(@namespace, public_name)
+            action = soap_action(public_name)
+            expects = info[:expects]
+            returns = info[:returns]
+            param_def = []
+            i = 1
+            if expects
+              expects.each do |klass|
+                param_name = klass.is_a?(Hash) ? klass.keys[0] : "param#{i}"
+                param_klass = lookup_class(klass)
+                mapping = @mapper.lookup(param_klass)
+                param_def << ['in', param_name, mapping.registry_mapping]
+                i += 1
+              end
+            end
+            if returns
+              mapping = @mapper.lookup(lookup_class(returns[0]))
+              param_def << ['retval', 'return', mapping.registry_mapping]
+            end
+            driver.add_method(qname, action, name.to_s, param_def)
+          end
+          driver
+        end
+
+        class SoapDriver < SOAP::RPC::Driver # :nodoc:
+          def add_method(qname, soapaction, name, param_def)
+            @proxy.add_rpc_method(qname, soapaction, name, param_def)
+            add_rpc_method_interface(name, param_def)
+          end
+        end
+    end
+  end
+end

data/lib/action_web_service/client/xmlrpc_client.rb

@@ -0,0 +1,77 @@
+require 'uri'
+require 'xmlrpc/client'
+
+module ActionWebService # :nodoc:
+  module Client # :nodoc:
+
+    # Implements XML-RPC client support
+    #
+    # ==== Example Usage
+    #
+    #   class BloggerAPI < ActionWebService::API::Base
+    #     inflect_names false
+    #     api_method :getRecentPosts, :returns => [[Blog::Post]]
+    #   end
+    #
+    #   blog = ActionWebService::Client::XmlRpc.new(BloggerAPI, "http://.../RPC", :handler_name => "blogger")
+    #   posts = blog.getRecentPosts
+    class XmlRpc < Base
+
+      # Creates a new web service client using the XML-RPC protocol.
+      #
+      # +api+ must be an ActionWebService::API::Base derivative, and
+      # +endpoint_uri+ must point at the relevant URL to which protocol requests
+      # will be sent with HTTP POST.
+      #
+      # Valid options:
+      # [<tt>:handler_name</tt>]    If the remote server defines its services inside special
+      #                             handler (the Blogger API uses a <tt>"blogger"</tt> handler name for example),
+      #                             provide it here, or your method calls will fail
+      def initialize(api, endpoint_uri, options={})
+        @api = api
+        @handler_name = options[:handler_name]
+        @client = XMLRPC::Client.new2(endpoint_uri, options[:proxy], options[:timeout])
+      end
+
+      protected
+        def perform_invocation(method_name, args)
+          args = transform_outgoing_method_params(method_name, args)
+          ok, return_value = @client.call2(public_name(method_name), *args)
+          return transform_return_value(method_name, return_value) if ok
+          raise(ClientError, "#{return_value.faultCode}: #{return_value.faultString}")
+        end
+
+        def transform_outgoing_method_params(method_name, params)
+          info = @api.api_methods[method_name.to_sym]
+          signature = info[:expects]
+          signature_length = signature.nil?? 0 : signature.length
+          if signature_length != params.length
+            raise(ProtocolError, "API declares #{public_name(method_name)} to accept " +
+                                 "#{signature_length} parameters, but #{params.length} parameters " + 
+                                 "were supplied")
+          end
+          if signature_length > 0
+            signature = Protocol::XmlRpc::XmlRpcProtocol.transform_array_types(signature)
+            (1..signature.size).each do |i|
+              i -= 1
+              params[i] = Protocol::XmlRpc::XmlRpcProtocol.ruby_to_xmlrpc(params[i], lookup_class(signature[i]))
+            end
+          end
+          params
+        end
+
+        def transform_return_value(method_name, return_value)
+          info = @api.api_methods[method_name.to_sym]
+          return true unless signature = info[:returns]
+          param_klass = lookup_class(signature[0])
+          signature = Protocol::XmlRpc::XmlRpcProtocol.transform_array_types([param_klass])
+          Protocol::XmlRpc::XmlRpcProtocol.xmlrpc_to_ruby(return_value, signature[0])
+        end
+
+        def public_name(method_name)
+          public_name = @api.public_api_method_name(method_name)
+          @handler_name ? "#{@handler_name}.#{public_name}" : public_name
+        end
+    end
+  end
+end

data/lib/action_web_service/container.rb

@@ -0,0 +1,85 @@
+module ActionWebService # :nodoc:
+  module Container # :nodoc:
+    class ContainerError < ActionWebService::ActionWebServiceError # :nodoc:
+    end
+
+    def self.append_features(base) # :nodoc:
+      super
+      base.extend(ClassMethods)
+      base.send(:include, ActionWebService::Container::InstanceMethods)
+    end
+
+    module ClassMethods
+      # Declares a web service that will provides access to the API of the given
+      # +object+. +object+ must be an ActionWebService::Base derivative.
+      #
+      # Web service object creation can either be _immediate_, where the object
+      # instance is given at class definition time, or _deferred_, where
+      # object instantiation is delayed until request time.
+      #
+      # ==== Immediate web service object example
+      #
+      #   class ApiController < ApplicationController
+      #     web_service_dispatching_mode :delegated
+      #
+      #     web_service :person, PersonService.new
+      #   end
+      #
+      # For deferred instantiation, a block should be given instead of an
+      # object instance. This block will be executed in controller instance
+      # context, so it can rely on controller instance variables being present.
+      #
+      # ==== Deferred web service object example
+      #
+      #   class ApiController < ApplicationController
+      #     web_service_dispatching_mode :delegated
+      #
+      #     web_service(:person) { PersonService.new(@request.env) }
+      #   end
+      def web_service(name, object=nil, &block)
+        if (object && block_given?) || (object.nil? && block.nil?)
+          raise(ContainerError, "either service, or a block must be given")
+        end
+        name = name.to_sym
+        if block_given?
+          info = { name => { :block => block } }
+        else
+          info = { name => { :object => object } }
+        end
+        write_inheritable_hash("web_services", info)
+        call_web_service_definition_callbacks(self, name, info)
+      end
+
+      # Whether this service contains a service with the given +name+
+      def has_web_service?(name)
+        web_services.has_key?(name.to_sym)
+      end
+
+      def web_services # :nodoc:
+        read_inheritable_attribute("web_services") || {}
+      end
+
+      def add_web_service_definition_callback(&block) # :nodoc:
+        write_inheritable_array("web_service_definition_callbacks", [block])
+      end
+
+      private
+        def call_web_service_definition_callbacks(container_class, web_service_name, service_info)
+          (read_inheritable_attribute("web_service_definition_callbacks") || []).each do |block|
+            block.call(container_class, web_service_name, service_info)
+          end
+        end
+    end
+
+    module InstanceMethods # :nodoc:
+      def web_service_object(web_service_name)
+        info = self.class.web_services[web_service_name.to_sym]
+        unless info
+          raise(ContainerError, "no such web service '#{web_service_name}'")
+        end
+        service = info[:block]
+        service ? instance_eval(&service) : info[:object]
+      end
+    end
+  end
+end

data/lib/action_web_service/dispatcher.rb

@@ -0,0 +1,2 @@
+require 'action_web_service/dispatcher/abstract'
+require 'action_web_service/dispatcher/action_controller_dispatcher'

data/lib/action_web_service/dispatcher/abstract.rb

@@ -0,0 +1,150 @@
+require 'benchmark'
+
+module ActionWebService # :nodoc:
+  module Dispatcher # :nodoc:
+    class DispatcherError < ActionWebService::ActionWebServiceError # :nodoc:
+    end
+
+    def self.append_features(base) # :nodoc:
+      super
+      base.class_inheritable_option(:web_service_dispatching_mode, :direct)
+      base.class_inheritable_option(:web_service_exception_reporting, true)
+      base.send(:include, ActionWebService::Dispatcher::InstanceMethods)
+    end
+
+    module InstanceMethods # :nodoc:
+      private
+        def dispatch_web_service_request(action_pack_request)
+          protocol_request = protocol_response = nil
+          bm = Benchmark.measure do
+            protocol_request = probe_request_protocol(action_pack_request)
+            protocol_response = dispatch_protocol_request(protocol_request)
+          end
+          [protocol_request, protocol_response, bm.real, nil]
+        rescue Exception => e
+          protocol_response = prepare_exception_response(protocol_request, e) 
+          [protocol_request, prepare_exception_response(protocol_request, e), nil, e]
+        end
+      
+        def dispatch_protocol_request(protocol_request)
+          case web_service_dispatching_mode
+          when :direct
+            dispatch_direct_request(protocol_request)
+          when :delegated
+            dispatch_delegated_request(protocol_request)
+          else
+            raise(ContainerError, "unsupported dispatching mode :#{web_service_dispatching_mode}")
+          end
+        end
+
+        def dispatch_direct_request(protocol_request)
+          request = prepare_dispatch_request(protocol_request)
+          return_value = direct_invoke(request)
+          protocol_request.marshal(return_value)
+        end
+
+        def dispatch_delegated_request(protocol_request)
+          request = prepare_dispatch_request(protocol_request)
+          return_value = delegated_invoke(request)
+          protocol_request.marshal(return_value)
+        end
+
+        def direct_invoke(request)
+          return nil unless before_direct_invoke(request)
+          return_value = send(request.method_name)
+          after_direct_invoke(request)
+          return_value
+        end
+
+        def before_direct_invoke(request)
+          @method_params = request.params
+        end
+
+        def after_direct_invoke(request)
+        end
+
+        def delegated_invoke(request)
+          cancellation_reason = nil
+          web_service = request.web_service
+          return_value = web_service.perform_invocation(request.method_name, request.params) do |x|
+            cancellation_reason = x
+          end
+          if cancellation_reason
+            raise(DispatcherError, "request canceled: #{cancellation_reason}")
+          end
+          return_value
+        end
+
+        def prepare_dispatch_request(protocol_request)
+          api = method_name = web_service_name = web_service = params = nil
+          public_method_name = protocol_request.public_method_name
+          case web_service_dispatching_mode
+          when :direct
+            api = self.class.web_service_api
+          when :delegated
+            web_service_name = protocol_request.web_service_name
+            web_service = web_service_object(web_service_name)
+            api = web_service.class.web_service_api
+          end
+          method_name  = api.api_method_name(public_method_name)
+          signature = nil
+          if method_name
+            signature = api.api_methods[method_name]
+            protocol_request.type = Protocol::CheckedMessage
+            protocol_request.signature = signature[:expects]
+            protocol_request.return_signature = signature[:returns]
+          else
+            method_name = api.default_api_method
+            if method_name
+              protocol_request.type = Protocol::UncheckedMessage
+            else
+              raise(DispatcherError, "no such method #{web_service_name}##{public_method_name}")
+            end
+          end
+          params = protocol_request.unmarshal
+          DispatchRequest.new(
+            :api                => api,
+            :public_method_name => public_method_name,
+            :method_name        => method_name,
+            :signature          => signature,
+            :web_service_name   => web_service_name,
+            :web_service        => web_service,
+            :params             => params)
+        end
+
+        def prepare_exception_response(protocol_request, exception)
+          if protocol_request && exception
+            case web_service_dispatching_mode
+            when :direct
+              if web_service_exception_reporting
+                return protocol_request.protocol.marshal_exception(exception)
+              end
+            when :delegated
+              web_service = web_service_object(protocol_request.web_service_name)
+              if web_service && web_service.class.web_service_exception_reporting
+                return protocol_request.protocol.marshal_exception(exception)
+              end
+            end
+          else
+            protocol_request.protocol.marshal_exception(RuntimeError.new("missing protocol request or exception"))
+          end
+        rescue Exception
+          nil
+        end
+
+        class DispatchRequest
+          attr :api
+          attr :public_method_name
+          attr :method_name
+          attr :signature
+          attr :web_service_name
+          attr :web_service
+          attr :params
+
+          def initialize(values={})
+            values.each{|k,v| instance_variable_set("@#{k.to_s}", v)}
+          end
+        end
+    end
+  end
+end