actionwebservice 0.5.0 → 0.6.0

data/{ChangeLog → CHANGELOG}

@@ -1,3 +1,23 @@
+*0.6.0* (7th March, 2005)
+
+* Add action_controller/test_invoke, used for integrating AWS with the Rails testing infrastructure
+
+* Allow passing through options to the SOAP RPC driver for the SOAP client
+
+* Make the SOAP WS marshaler use #columns to decide which fields to marshal as well, avoids providing attributes brought in by associations
+  
+* Add <tt>ActionWebService::API::Base.allow_active_record_expects</tt> option, with a default of false. Setting this to true will allow specifying ActiveRecord::Base model classes in <tt>:expects</tt>. API writers should take care to validate the received ActiveRecord model objects when turning it on, and/or have an authentication mechanism in place to reduce the security risk.
+
+* Improve error message reporting. Bugs in either AWS or the web service itself will send back a protocol-specific error report message if possible, otherwise, provide as much detail as possible.
+
+* Removed type checking of received parameters, and perform casting for XML-RPC if possible, but fallback to the received parameters if casting fails, closes #677
+
+* Refactored SOAP and XML-RPC marshaling and encoding into a small library devoted exclusively to protocol specifics, also cleaned up the SOAP marshaling approach, so that array and custom type marshaling should be a bit faster.
+
+* Add namespaced XML-RPC method name support, closes #678
+
+* Replace '::' with '..' in fully qualified type names for marshaling and WSDL. This improves interoperability with .NET, and closes #676.
+
 *0.5.0* (24th February, 2005)
 
 	* lib/action_service/dispatcher*: replace "router" fragments with

data/README

@@ -114,7 +114,7 @@ For this example, protocol requests for +Add+ and +Remove+ methods sent to
 === Delegated dispatching
 
 This mode can be turned on by setting the +web_service_dispatching_mode+ option
-in a controller.
+in a controller to <tt>:delegated</tt>.
 
 In this mode, the controller contains one or more web service objects (objects
 that implement an ActionWebService::API::Base definition). These web service
@@ -153,6 +153,50 @@ Other controller actions (actions that aren't the target of a +web_service+ call
 are ignored for ActionWebService purposes, and can do normal action tasks.
 
 
+=== Layered dispatching
+
+This mode can be turned on by setting the +web_service_dispatching_mode+ option
+in a controller to <tt>:layered</tt>.
+
+This mode is similar to _delegated_ mode, in that multiple web service objects
+can be attached to one controller, however, all protocol requests are sent to a
+single endpoint.
+
+This mode is only usable by XML-RPC. In this mode, method names can contain
+_prefixes_, which will indicate which web service object implements the API
+identified by that prefix.
+
+The _prefix_ can be any word, followed by a period.
+
+==== Layered dispatching example
+
+
+  class ApiController < ApplicationController
+    web_service_dispatching_mode :layered
+
+    web_service :mt, MovableTypeService.new
+    web_service :blogger, BloggerService.new
+    web_service :metaWeblog, MetaWeblogService.new
+  end
+
+  class MovableTypeService < ActionWebService::Base
+    ...
+  end
+
+  class BloggerService < ActionWebService::Base
+    ...
+  end
+
+  class MetaWeblogService < ActionWebService::API::Base
+    ...
+  end
+
+
+For this example, a remote call for a method with a name like
+<tt>mt.getCategories</tt> will be dispatched as the <tt>getCategories</tt>
+method on the <tt>:mt</tt> service.
+
+
 == Using the client support
 
 Action Web Service includes client classes that can use the same API

data/Rakefile

@@ -9,7 +9,7 @@ require 'fileutils'
 
 PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
 PKG_NAME      = 'actionwebservice'
-PKG_VERSION   = '0.5.0' + PKG_BUILD
+PKG_VERSION   = '0.6.0' + PKG_BUILD
 PKG_FILE_NAME   = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_DESTINATION = ENV["RAILS_PKG_DESTINATION"] || "../#{PKG_NAME}"
 
@@ -20,7 +20,7 @@ task :default => [ :test ]
 # Run the unit tests
 Rake::TestTask.new { |t|
   t.libs << "test"
-  t.pattern = 'test/*_test.rb'
+  t.test_files = Dir['test/*_test.rb'] + Dir['test/ws/*_test.rb']
   t.verbose = true
 }
 
@@ -31,12 +31,14 @@ Rake::RDocTask.new { |rdoc|
   rdoc.title    = "Action Web Service -- Web services for Action Pack"
   rdoc.options << '--line-numbers --inline-source --main README --accessor class_inheritable_option=RW'
   rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('CHANGELOG')
   rdoc.rdoc_files.include('lib/action_web_service.rb')
   rdoc.rdoc_files.include('lib/action_web_service/*.rb')
   rdoc.rdoc_files.include('lib/action_web_service/api/*.rb')
   rdoc.rdoc_files.include('lib/action_web_service/client/*.rb')
-  rdoc.rdoc_files.include('lib/action_web_service/protocol/*.rb')
+  rdoc.rdoc_files.include('lib/action_web_service/container/*.rb')
   rdoc.rdoc_files.include('lib/action_web_service/dispatcher/*.rb')
+  rdoc.rdoc_files.include('lib/action_web_service/protocol/*.rb')
   rdoc.rdoc_files.include('lib/action_web_service/support/*.rb')
 }
 
@@ -54,16 +56,16 @@ spec = Gem::Specification.new do |s|
   s.rubyforge_project = "aws"
   s.homepage = "http://www.rubyonrails.org"
 
-  s.add_dependency('actionpack', '= 1.5.0' + PKG_BUILD)
-  s.add_dependency('activerecord', '= 1.7.0' + PKG_BUILD)
-  s.add_dependency('activesupport', '= 1.0.0' + PKG_BUILD)
+  s.add_dependency('actionpack', '>= 1.5.1' + PKG_BUILD)
+  s.add_dependency('activerecord', '>= 1.8.0' + PKG_BUILD)
+  s.add_dependency('activesupport', '>= 1.0.1' + PKG_BUILD)
 
   s.has_rdoc = true
   s.requirements << 'none'
   s.require_path = 'lib'
   s.autorequire = 'action_web_service'
 
-  s.files = [ "Rakefile", "setup.rb", "README", "TODO", "ChangeLog", "MIT-LICENSE" ]
+  s.files = [ "Rakefile", "setup.rb", "README", "TODO", "CHANGELOG", "MIT-LICENSE" ]
   s.files = s.files + Dir.glob( "examples/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
   s.files = s.files + Dir.glob( "lib/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
   s.files = s.files + Dir.glob( "test/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
@@ -85,7 +87,7 @@ end
 # Publish documentation
 desc "Publish the API documentation"
 task :pdoc => [:rdoc] do 
-  Rake::SshDirPublisher.new("davidhh@comox.textdrive.com", "public_html/as", "doc").upload
+  Rake::SshDirPublisher.new("davidhh@comox.textdrive.com", "public_html/aws", "doc").upload
 end
 
 
@@ -94,7 +96,7 @@ def each_source_file(*args)
 	prefix ||= File.dirname(__FILE__)
 	open_file = true if open_file.nil?
 	includes ||= %w[lib\/action_web_service\.rb$ lib\/action_web_service\/.*\.rb$]
-	excludes ||= %w[]
+	excludes ||= %w[lib\/action_web_service\/vendor]
 	Find.find(prefix) do |file_name|
 		next if file_name =~ /\.svn/
 		file_name.gsub!(/^\.\//, '')
@@ -123,7 +125,7 @@ def each_source_file(*args)
 	end
 end
 
-desc "Count lines of the source code"
+desc "Count lines of the AWS source code"
 task :lines do
   total_lines = total_loc = 0
   puts "Per File:"

data/TODO

@@ -1,13 +1,12 @@
-= Low priority tasks
-  - add better type mapping tests for XML-RPC
-  - add tests for ActiveRecord support (with mock objects?)
+= 0.7.0
+  - WS Test Integration
+  - WS Scaffolding
+  - WS Generators
 
-= Refactoring
-  - Find an alternative way to map interesting types for SOAP (like ActiveRecord
-    model classes) that doesn't require creation of a sanitized copy object with data
-    copied from the real one. Ideally this would let us get rid of
-    ActionWebService::Struct altogether and provide a block that would yield the
-    attributes and values. "Filters" ?  Not sure how to integrate with SOAP though.
+= 0.8.0
+  - Consumption of WSDL services
   
+= Refactoring
+  - Port dispatcher tests to use test_invoke
   - Don't have clean way to go from SOAP Class object to the xsd:NAME type
     string -- NaHi possibly looking at remedying this situation

data/lib/action_web_service.rb

@@ -32,7 +32,10 @@ rescue LoadError
   require_gem 'activerecord', '>= 1.6.0'
 end
 
-$:.unshift(File.dirname(__FILE__))
+$:.unshift(File.dirname(__FILE__) + "/action_web_service/vendor/")
+
+require 'action_web_service/support/class_inheritable_options'
+require 'action_web_service/vendor/ws'
 
 require 'action_web_service/base'
 require 'action_web_service/client'
@@ -41,20 +44,21 @@ require 'action_web_service/api'
 require 'action_web_service/struct'
 require 'action_web_service/container'
 require 'action_web_service/protocol'
+require 'action_web_service/struct'
 require 'action_web_service/dispatcher'
 
 ActionWebService::Base.class_eval do
-  include ActionWebService::API
+  include ActionWebService::Container::Direct
   include ActionWebService::Invocation
 end
 
 ActionController::Base.class_eval do
-  include ActionWebService::Container
-  include ActionWebService::Protocol::Registry
+  include ActionWebService::Protocol::Discovery
   include ActionWebService::Protocol::Soap
   include ActionWebService::Protocol::XmlRpc
-  include ActionWebService::API
-  include ActionWebService::API::ActionController
+  include ActionWebService::Container::Direct
+  include ActionWebService::Container::Delegated
+  include ActionWebService::Container::ActionController
   include ActionWebService::Dispatcher
   include ActionWebService::Dispatcher::ActionController
 end

data/lib/action_web_service/api.rb

@@ -1,2 +1 @@
-require 'action_web_service/api/abstract'
-require 'action_web_service/api/action_controller'
+require 'action_web_service/api/base'

data/lib/action_web_service/api/{abstract.rb → base.rb}

@@ -1,70 +1,5 @@
 module ActionWebService # :nodoc:
   module API # :nodoc:
-    class APIError < ActionWebService::ActionWebServiceError # :nodoc:
-    end
-
-    def self.append_features(base) # :nodoc:
-      super
-      base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-      # Attaches ActionWebService API +definition+ to the calling class.
-      #
-      # Action Controllers can have a default associated API, removing the need
-      # to call this method if you follow the Action Web Service naming conventions.
-      #
-      # A controller with a class name of GoogleSearchController will
-      # implicitly load <tt>app/apis/google_search_api.rb</tt>, and expect the
-      # API definition class to be named <tt>GoogleSearchAPI</tt> or
-      # <tt>GoogleSearchApi</tt>.
-      #
-      # ==== Service class example
-      #
-      #   class MyService < ActionWebService::Base
-      #     web_service_api MyAPI
-      #   end
-      #
-      #   class MyAPI < ActionWebService::API::Base
-      #     ...
-      #   end
-      #
-      # ==== Controller class example
-      #
-      #   class MyController < ActionController::Base
-      #     web_service_api MyAPI
-      #   end
-      #
-      #   class MyAPI < ActionWebService::API::Base
-      #     ...
-      #   end
-      def web_service_api(definition=nil)
-        if definition.nil?
-          read_inheritable_attribute("web_service_api")
-        else
-          if definition.is_a?(Symbol)
-            raise(APIError, "symbols can only be used for #web_service_api inside of a controller")
-          end
-          unless definition.respond_to?(:ancestors) && definition.ancestors.include?(Base)
-            raise(APIError, "#{definition.to_s} is not a valid API definition")
-          end
-          write_inheritable_attribute("web_service_api", definition)
-          call_web_service_api_callbacks(self, definition)
-        end
-      end
-
-      def add_web_service_api_callback(&block) # :nodoc:
-        write_inheritable_array("web_service_api_callbacks", [block])
-      end
-
-      private
-        def call_web_service_api_callbacks(container_class, definition)
-          (read_inheritable_attribute("web_service_api_callbacks") || []).each do |block|
-            block.call(container_class, definition)
-          end
-        end
-    end
-
     # A web service API class specifies the methods that will be available for
     # invocation for an API. It also contains metadata such as the method type
     # signature hints.
@@ -78,6 +13,12 @@ module ActionWebService # :nodoc:
       # Whether to transform the public API method names into camel-cased names 
       class_inheritable_option :inflect_names, true
 
+      # Whether to allow ActiveRecord::Base models in <tt>:expects</tt>.
+      # The default is +false+, you should be aware of the security implications
+      # of allowing this, and ensure that you don't allow remote callers to
+      # easily overwrite data they should not have access to.
+      class_inheritable_option :allow_active_record_expects, false
+
       # If present, the name of a method to call when the remote caller
       # tried to call a nonexistent method. Semantically equivalent to
       # +method_missing+.
@@ -87,8 +28,6 @@ module ActionWebService # :nodoc:
       private_class_method :new, :allocate
       
       class << self
-        include ActionWebService::Signature
-
         # API methods have a +name+, which must be the Ruby method name to use when
         # performing the invocation on the web service object.
         #
@@ -125,13 +64,13 @@ module ActionWebService # :nodoc:
             expects = options[:expects]
             returns = options[:returns]
           end
-          expects = canonical_signature(expects) if expects
-          returns = canonical_signature(returns) if returns
+          expects = canonical_signature(expects)
+          returns = canonical_signature(returns)
           if expects
             expects.each do |param|
-              klass = signature_parameter_class(param)
+              klass = WS::BaseTypes.canonical_param_type_class(param)
               klass = klass[0] if klass.is_a?(Array)
-              if klass.ancestors.include?(ActiveRecord::Base)
+              if klass.ancestors.include?(ActiveRecord::Base) && !allow_active_record_expects
                 raise(ActionWebServiceError, "ActiveRecord model classes not allowed in :expects")
               end
             end
@@ -186,6 +125,10 @@ module ActionWebService # :nodoc:
             end
           end
 
+          def canonical_signature(signature)
+            return nil if signature.nil?
+            signature.map{|spec| WS::BaseTypes.canonical_param_type_spec(spec)}
+          end
       end
     end
   end

data/lib/action_web_service/base.rb

@@ -1,6 +1,3 @@
-require 'action_web_service/support/class_inheritable_options'
-require 'action_web_service/support/signature'
-
 module ActionWebService # :nodoc:
   class ActionWebServiceError < StandardError # :nodoc:
   end

data/lib/action_web_service/client/base.rb

@@ -12,28 +12,17 @@ module ActionWebService # :nodoc:
       def method_missing(name, *args) # :nodoc:
         call_name = method_name(name)
         return super(name, *args) if call_name.nil?
-        perform_invocation(call_name, args)
+        self.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

@@ -24,17 +24,36 @@ module ActionWebService # :nodoc:
       # 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
+      # [<tt>:type_namespace</tt>]    If the remote server has used a custom namespace to
+      #                               declare its custom types, you can specify it here
+      # [<tt>:method_namespace</tt>]  If the remote server has used a custom namespace to
+      #                               declare its methods, you can specify it here
+      # [<tt>:driver_options</tt>]    If you want to supply any custom SOAP RPC driver
+      #                               options, you can provide them as a Hash here
+      #
+      # The <tt>:driver_options</tt> option can be used to configure the backend SOAP
+      # RPC driver. An example of configuring the SOAP backend to do
+      # client-certificate authenticated SSL connections to the server:
+      #
+      #   opts = {}
+      #   opts['protocol.http.ssl_config.verify_mode'] = 'OpenSSL::SSL::VERIFY_PEER'
+      #   opts['protocol.http.ssl_config.client_cert'] = client_cert_file_path
+      #   opts['protocol.http.ssl_config.client_key'] = client_key_file_path
+      #   opts['protocol.http.ssl_config.ca_file'] = ca_cert_file_path
+      #   client = ActionWebService::Client::Soap.new(api, 'https://some/service', :driver_options => opts)
       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)
+        @type_namespace = options[:type_namespace] || 'urn:ActionWebService'
+        @method_namespace = options[:method_namespace] || 'urn:ActionWebService'
+        @driver_options = options[:driver_options] || {}
+        @marshaler = WS::Marshaling::SoapMarshaler.new @type_namespace
+        @encoder = WS::Encoding::SoapRpcEncoding.new @method_namespace
         @soap_action_base = options[:soap_action_base]
         @soap_action_base ||= URI.parse(endpoint_uri).path
         @driver = create_soap_rpc_driver(api, endpoint_uri)
+        @driver_options.each do |name, value|
+          @driver.options[name.to_s] = value.to_s
+        end
       end
 
       protected
@@ -48,35 +67,48 @@ module ActionWebService # :nodoc:
 
       private
         def create_soap_rpc_driver(api, endpoint_uri)
-          @mapper.map_api(api)
+          register_api(@marshaler, api)
           driver = SoapDriver.new(endpoint_uri, nil)
-          driver.mapping_registry = @mapper.registry
+          driver.mapping_registry = @marshaler.registry
           api.api_methods.each do |name, info|
             public_name = api.public_api_method_name(name)
-            qname = XSD::QName.new(@namespace, public_name)
+            qname = XSD::QName.new(@method_namespace, public_name)
             action = soap_action(public_name)
             expects = info[:expects]
             returns = info[:returns]
             param_def = []
-            i = 1
+            i = 0
             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]
+              expects.each do |spec|
+                param_name = spec.is_a?(Hash) ? spec.keys[0].to_s : "param#{i}"
+                type_binding = @marshaler.register_type(spec)
+                param_def << ['in', param_name, type_binding.mapping]
                 i += 1
               end
             end
             if returns
-              mapping = @mapper.lookup(lookup_class(returns[0]))
-              param_def << ['retval', 'return', mapping.registry_mapping]
+              type_binding = @marshaler.register_type(returns[0])
+              param_def << ['retval', 'return', type_binding.mapping]
             end
             driver.add_method(qname, action, name.to_s, param_def)
           end
           driver
         end
 
+        def register_api(marshaler, api)
+          type_bindings = []
+          api.api_methods.each do |name, info|
+            expects, returns = info[:expects], info[:returns]
+            if expects
+              expects.each{|type| type_bindings << marshaler.register_type(type)}
+            end
+            if returns
+              returns.each{|type| type_bindings << marshaler.register_type(type)}
+            end
+          end
+          type_bindings
+        end
+
         class SoapDriver < SOAP::RPC::Driver # :nodoc:
           def add_method(qname, soapaction, name, param_def)
             @proxy.add_rpc_method(qname, soapaction, name, param_def)