actionwebservice 0.6.2 → 0.7.0

data/CHANGELOG

@@ -1,3 +1,24 @@
+*0.7.0* (19th April, 2005)
+
+* When casting structured types, don't try to send obj.name= unless obj responds to it, causes casting to be less likely to fail for XML-RPC
+
+* Add scaffolding via ActionController::Base.web_service_scaffold for quick testing using a web browser
+
+* ActionWebService::API::Base#api_methods now returns a hash containing ActionWebService::API::Method objects instead of hashes. However, ActionWebService::API::Method defines a #[]() backwards compatibility method so any existing code utilizing this will still work.
+
+* The :layered dispatching mode can now be used with SOAP as well, allowing you to support SOAP and XML-RPC clients for APIs like the metaWeblog API
+
+* Remove ActiveRecordSoapMarshallable workaround, see #912 for details
+
+* Generalize casting code to be used by both SOAP and XML-RPC (previously, it was only XML-RPC)
+
+* Ensure return value is properly cast as well, fixes XML-RPC interoperability with Ecto and possibly other clients
+
+* Include backtraces in 500 error responses for failed request parsing, and remove "rescue nil" statements obscuring real errors for XML-RPC
+
+* Perform casting of struct members even if the structure is already of the correct type, so that the type we specify for the struct member is always the type of the value seen by the API implementation
+
+
 *0.6.2* (27th March, 2005)
 
 * Allow method declarations for direct dispatching to declare parameters as well. We treat an arity of < 0 or > 0 as an indication that we should send through parameters. Closes #939.

data/README

@@ -162,11 +162,10 @@ 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.
+Use this mode when you want to share code between XML-RPC and SOAP clients,
+for APIs where the XML-RPC method names have prefixes. An example of such
+a method name would be <tt>blogger.newPost</tt>.
 
-The _prefix_ can be any word, followed by a period.
 
 ==== Layered dispatching example
 
@@ -192,11 +191,56 @@ The _prefix_ can be any word, followed by a period.
   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>
+For this example, an XML-RPC call for a method with a name like
+<tt>mt.getCategories</tt> will be sent to the <tt>getCategories</tt>
 method on the <tt>:mt</tt> service.
 
 
+== Testing your APIs
+
+
+=== Functional testing
+
+You can perform testing of your APIs by creating a functional test for the
+controller dispatching the API, and calling #invoke in the test case to
+perform the invocation.
+
+Example:
+
+  class PersonApiControllerTest < Test::Unit::TestCase
+    def setup
+      @controller = PersonController.new
+      @request    = ActionController::TestRequest.new
+      @response   = ActionController::TestResponse.new
+    end
+
+    def test_add
+      result = invoke :remove, 1
+      assert_equal true, result
+    end
+  end
+
+This example invokes the API method <tt>test</tt>, defined on 
+the PersonController, and returns the result.
+
+
+=== Scaffolding
+
+You can also test your APIs with a web browser by attaching scaffolding
+to the controller.
+
+Example:
+
+  class PersonController
+    web_service_scaffold :invocation
+  end
+
+This creates an action named <tt>invocation</tt> on the PersonController.
+
+Navigating to this action lets you select the method to invoke, supply the parameters,
+and view the result of the invocation.
+
+
 == 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.6.2' + PKG_BUILD
+PKG_VERSION   = '0.7.0' + PKG_BUILD
 PKG_FILE_NAME   = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_DESTINATION = ENV["RAILS_PKG_DESTINATION"] || "../#{PKG_NAME}"
 
@@ -25,7 +25,7 @@ task :default => [ :test ]
 # Run the unit tests
 Rake::TestTask.new { |t|
   t.libs << "test"
-  t.test_files = Dir['test/*_test.rb'] + Dir['test/ws/*_test.rb']
+  t.test_files = Dir['test/*_test.rb']
   t.verbose = true
 }
 
@@ -62,9 +62,9 @@ spec = Gem::Specification.new do |s|
   s.rubyforge_project = "aws"
   s.homepage = "http://www.rubyonrails.org"
 
-  s.add_dependency('actionpack', '= 1.7.0' + PKG_BUILD)
-  s.add_dependency('activerecord', '= 1.9.1' + PKG_BUILD)
-  s.add_dependency('activesupport', '= 1.0.3' + PKG_BUILD)
+  s.add_dependency('actionpack', '= 1.8.0' + PKG_BUILD)
+  s.add_dependency('activerecord', '= 1.10.0' + PKG_BUILD)
+  s.add_dependency('activesupport', '= 1.0.4' + PKG_BUILD)
 
   s.has_rdoc = true
   s.requirements << 'none'
@@ -86,14 +86,14 @@ end
 # Publish beta gem
 desc "Publish the API documentation"
 task :pgem => [:package] do 
-  Rake::SshFilePublisher.new("davidhh@comox.textdrive.com", "public_html/gems/gems", "pkg", "#{PKG_FILE_NAME}.gem").upload
-  `ssh davidhh@comox.textdrive.com './gemupdate.sh'`
+  Rake::SshFilePublisher.new("davidhh@wrath.rubyonrails.com", "public_html/gems/gems", "pkg", "#{PKG_FILE_NAME}.gem").upload
+  `ssh davidhh@wrath.rubyonrails.com './gemupdate.sh'`
 end
 
 # Publish documentation
 desc "Publish the API documentation"
 task :pdoc => [:rdoc] do 
-  Rake::SshDirPublisher.new("davidhh@comox.textdrive.com", "public_html/aws", "doc").upload
+  Rake::SshDirPublisher.new("davidhh@wrath.rubyonrails.com", "public_html/aws", "doc").upload
 end
 
 
@@ -264,4 +264,4 @@ task :release => [:package] do
       first_file = false
     end
   end
-end
+end

data/TODO

@@ -1,11 +1,11 @@
-= 0.7.0
-  - WS Dynamic Scaffolding
-  - WS Scaffolding Generators
-
 = 0.8.0
-  - Consumption of WSDL services
+  - Allow locking down a controller to only accept messages for a particular protocol.
+    This will allow us to generate fully conformant error messages in cases where we
+    currently fudge it if we don't know the protocol.
+
+  - Allow AWS user to participate in typecasting, so they can centralize workarounds
+    for buggy input in one place
   
 = 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

@@ -35,17 +35,17 @@ end
 $:.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/support/signature_types'
 require 'action_web_service/base'
 require 'action_web_service/client'
 require 'action_web_service/invocation'
 require 'action_web_service/api'
+require 'action_web_service/casting'
 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'
+require 'action_web_service/scaffolding'
 
 ActionWebService::Base.class_eval do
   include ActionWebService::Container::Direct
@@ -61,4 +61,5 @@ ActionController::Base.class_eval do
   include ActionWebService::Container::ActionController
   include ActionWebService::Dispatcher
   include ActionWebService::Dispatcher::ActionController
+  include ActionWebService::Scaffolding
 end

data/lib/action_web_service/api.rb

@@ -1 +1,248 @@
-require 'action_web_service/api/base'
+module ActionWebService # :nodoc:
+  module API # :nodoc:
+    # 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.
+    #
+    # It is not intended to be instantiated.
+    #
+    # It is attached to web service implementation classes like
+    # ActionWebService::Base and ActionController::Base derivatives by using
+    # ClassMethods#web_service_api.
+    class Base
+      # 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+.
+      class_inheritable_option :default_api_method
+
+      # Disallow instantiation
+      private_class_method :new, :allocate
+      
+      class << self
+        include ActionWebService::SignatureTypes
+
+        # API methods have a +name+, which must be the Ruby method name to use when
+        # performing the invocation on the web service object.
+        #
+        # The signatures for the method input parameters and return value can
+        # by specified in +options+.
+        #
+        # A signature is an array of one or more parameter specifiers. 
+        # A parameter specifier can be one of the following:
+        #
+        # * A symbol or string of representing one of the Action Web Service base types.
+        #   See ActionWebService::Signature for a canonical list of the base types.
+        # * The Class object of the parameter type
+        # * A single-element Array containing one of the two preceding items. This
+        #   will cause Action Web Service to treat the parameter at that position
+        #   as an array containing only values of the given type.
+        # * A Hash containing as key the name of the parameter, and as value
+        #   one of the three preceding items
+        # 
+        # If no method input parameter or method return value signatures are given,
+        # the method is assumed to take no parameters and/or return no values of
+        # interest, and any values that are received by the server will be
+        # discarded and ignored.
+        #
+        # Valid options:
+        # [<tt>:expects</tt>]             Signature for the method input parameters
+        # [<tt>:returns</tt>]             Signature for the method return value
+        # [<tt>:expects_and_returns</tt>] Signature for both input parameters and return value
+        def api_method(name, options={})
+          unless options.is_a?(Hash)
+            raise(ActionWebServiceError, "Expected a Hash for options")
+          end
+          validate_options([:expects, :returns, :expects_and_returns], options.keys)
+          if options[:expects_and_returns]
+            expects = options[:expects_and_returns]
+            returns = options[:expects_and_returns]
+          else
+            expects = options[:expects]
+            returns = options[:returns]
+          end
+          expects = canonical_signature(expects)
+          returns = canonical_signature(returns)
+          if expects
+            expects.each do |type|
+              type = type.element_type if type.is_a?(ArrayType)
+              if type.type_class.ancestors.include?(ActiveRecord::Base) && !allow_active_record_expects
+                raise(ActionWebServiceError, "ActiveRecord model classes not allowed in :expects")
+              end
+            end
+          end
+          name = name.to_sym
+          public_name = public_api_method_name(name)
+          method = Method.new(name, public_name, expects, returns)
+          write_inheritable_hash("api_methods", name => method)
+          write_inheritable_hash("api_public_method_names", public_name => name)
+        end
+
+        # Whether the given method name is a service method on this API
+        def has_api_method?(name)
+          api_methods.has_key?(name)
+        end
+  
+        # Whether the given public method name has a corresponding service method
+        # on this API
+        def has_public_api_method?(public_name)
+          api_public_method_names.has_key?(public_name)
+        end
+  
+        # The corresponding public method name for the given service method name
+        def public_api_method_name(name)
+          if inflect_names
+            name.to_s.camelize
+          else
+            name.to_s
+          end
+        end
+  
+        # The corresponding service method name for the given public method name
+        def api_method_name(public_name)
+          api_public_method_names[public_name]
+        end
+  
+        # A Hash containing all service methods on this API, and their
+        # associated metadata.
+        def api_methods
+          read_inheritable_attribute("api_methods") || {}
+        end
+
+        # The Method instance for the given public API method name, if any
+        def public_api_method_instance(public_method_name)
+          api_method_instance(api_method_name(public_method_name))
+        end
+
+        # The Method instance for the given API method name, if any
+        def api_method_instance(method_name)
+          api_methods[method_name]
+        end
+
+        # The Method instance for the default API method, if any
+        def default_api_method_instance
+          return nil unless name = default_api_method
+          instance = read_inheritable_attribute("default_api_method_instance")
+          if instance && instance.name == name
+            return instance
+          end
+          instance = Method.new(name, public_api_method_name(name), nil, nil)
+          write_inheritable_attribute("default_api_method_instance", instance)
+          instance
+        end
+
+        private
+          def api_public_method_names
+            read_inheritable_attribute("api_public_method_names") || {}
+          end
+  
+          def validate_options(valid_option_keys, supplied_option_keys)
+            unknown_option_keys = supplied_option_keys - valid_option_keys
+            unless unknown_option_keys.empty?
+              raise(ActionWebServiceError, "Unknown options: #{unknown_option_keys}")
+            end
+          end
+      end
+    end
+
+    # Represents an API method and its associated metadata, and provides functionality
+    # to assist in commonly performed API method tasks.
+    class Method
+      attr :name
+      attr :public_name
+      attr :expects
+      attr :returns
+
+      def initialize(name, public_name, expects, returns)
+        @name = name
+        @public_name = public_name
+        @expects = expects
+        @returns = returns
+        @caster = ActionWebService::Casting::BaseCaster.new(self)
+      end
+      
+      # The list of parameter names for this method
+      def param_names
+        return [] unless @expects
+        @expects.map{ |type| type.name }
+      end
+
+      # Casts a set of Ruby values into the expected Ruby values
+      def cast_expects(params)
+        @caster.cast_expects(params)
+      end
+
+      # Cast a Ruby return value into the expected Ruby value
+      def cast_returns(return_value)
+        @caster.cast_returns(return_value)
+      end
+
+      # Returns the index of the first expected parameter
+      # with the given name
+      def expects_index_of(param_name)
+        return -1 if @expects.nil?
+        (0..(@expects.length-1)).each do |i|
+          return i if @expects[i].name.to_s == param_name.to_s
+        end
+        -1
+      end
+
+      # Returns a hash keyed by parameter name for the given
+      # parameter list
+      def expects_to_hash(params)
+        return {} if @expects.nil?
+        h = {}
+        @expects.zip(params){ |type, param| h[type.name] = param }
+        h
+      end
+
+      # Backwards compatibility with previous API
+      def [](sig_type)
+        case sig_type
+        when :expects
+          @expects.map{|x| compat_signature_entry(x)}
+        when :returns
+          @returns.map{|x| compat_signature_entry(x)}
+        end
+      end
+
+      # String representation of this method
+      def to_s
+        fqn = ""
+        fqn << (@returns ? (friendly_param(@returns[0], false) + " ") : "void ")
+        fqn << "#{@public_name}("
+        fqn << @expects.map{ |p| friendly_param(p) }.join(", ") if @expects
+        fqn << ")"
+        fqn
+      end
+
+      private
+        def compat_signature_entry(entry)
+          if entry.array?
+            [compat_signature_entry(entry.element_type)]
+          else
+            if entry.spec.is_a?(Hash)
+              {entry.spec.keys.first => entry.type_class}
+            else
+              entry.type_class
+            end
+          end
+        end
+
+        def friendly_param(type, show_name=true)
+          name = type.name.to_s
+          type_type = type.array?? type.element_type.type.to_s : type.type.to_s
+          str = type.array?? (type_type + '[]') : type_type
+          show_name ? (str + " " + name) : str
+        end
+    end
+  end
+end