rack-amf 0.0.1

data/README.rdoc

@@ -0,0 +1,55 @@
+== DESCRIPTION:
+
+What will eventually become a full featured AMF gateway implemented as a Rack middleware and AMF0/3 serializers and deserializers. Currently includes a fully compliant AMF0/AMF3 deserializer, AMF3 serializer, and a Rack middleware that supports both standard AMF calls and <tt>RemoteObject</tt> calls.
+
+== INSTALL:
+
+  gem install rack-amf --source="http://gemcutter.org"
+
+== EXAMPLE:
+
+config.ru:
+
+  require 'rack/amf'
+  use Rack::AMF
+  
+  class TestService
+    def sayHello
+      'Hello'
+    end
+  end
+  
+  Rack::AMF::Services.register('TestService', TestService.new)
+  
+  run lambda {|env| [200, { 'Content-Type' => 'text/plain', 'Content-Length' => '16' }, ["Rack AMF gateway"] ] }
+
+== TODO:
+
+* Write some Rails helpers so that using Rack AMF as a Rails Metal is easy.
+  * Support ActiveRecord serialization/deserialization
+  * Auto-map to Rails controllers
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Tony Hillerson based on work by Aaron Smith
+
+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/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+require 'spec/rake/spectask'
+
+desc 'Default: run the specs.'
+task :default => :spec
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', 'spec/spec.opts']
+end
+
+desc 'Generate documentation for the rubyamf plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rack AMF'
+  rdoc.options << '--line-numbers' << '--main' << 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name    = 'rack-amf'
+  s.version = '0.0.1'
+  s.summary = 'AMF serializer/deserializer and AMF gateway packaged as a rack middleware'
+
+  s.files        = FileList['README.rdoc', 'Rakefile', 'lib/**/*.rb', 'spec/**/*.rb']
+  s.require_path = 'lib'
+  s.test_files   = Dir[*['spec/**/*_spec.rb']]
+
+  s.has_rdoc         = true
+  s.extra_rdoc_files = ['README.rdoc']
+  s.rdoc_options     = ['--line-numbers', '--main', 'README.rdoc']
+
+  s.authors  = ['Tony Hillerson', 'Stephen Augenstein']
+  s.email    = 'perl.programmer@gmail.com'
+  s.homepage = 'http://github.com/warhammerkid/rack-amf'
+
+  s.platform = Gem::Platform::RUBY
+end
+
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
+desc 'Generate a gemspec file'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end

data/lib/amf/class_mapping.rb

@@ -0,0 +1,210 @@
+require 'amf/values/typed_hash'
+require 'amf/values/array_collection'
+require 'amf/values/messages'
+
+module AMF
+  # == Class Mapping
+  #
+  # Handles class name mapping between actionscript and ruby and assists in
+  # serializing and deserializing data between them. Simply map an AS class to a
+  # ruby class and when the object is (de)serialized it will end up as the
+  # appropriate class.
+  #
+  # Example:
+  #
+  #   AMF::ClassMapper.define do |m|
+  #     m.map :as => 'AsClass', :ruby => 'RubyClass'
+  #     m.map :as => 'vo.User', :ruby => 'User'
+  #   end
+  #
+  # == Object Population/Serialization
+  #
+  # In addition to handling class name mapping, it also provides helper methods
+  # for populating ruby objects from AMF and extracting properties from ruby objects
+  # for serialization. Support for hash-like objects and objects using
+  # <tt>attr_accessor</tt> for properties is currently built in, but custom classes
+  # may need custom support. As such, it is possible to create a custom populator
+  # or serializer.
+  #
+  # Populators are processed in insert order and must respond to the <tt>can_handle?</tt>
+  # and <tt>populate</tt> methods.
+  #
+  # Example:
+  #
+  #   class CustomPopulator
+  #     def can_handle? obj
+  #       true
+  #     end
+  #   
+  #     def populate obj, props, dynamic_props
+  #       obj.merge! props
+  #       obj.merge!(dynamic_props) if dynamic_props
+  #     end
+  #   end
+  #   AMF::ClassMapper.object_populators << CustomPopulator.new
+  #
+  # Serializers are also processed in insert order and must respond to the
+  # <tt>can_handle?</tt> and <tt>serialize</tt> methods.
+  #
+  # Example:
+  #
+  #   class CustomSerializer
+  #     def can_handle? obj
+  #       true
+  #     end
+  #   
+  #     def serialize obj
+  #       {}
+  #     end
+  #   end
+  #   AMF::ClassMapper.object_serializers << CustomSerializer.new
+  class ClassMapping
+    # Container for all mapped classes
+    class MappingSet
+      def initialize #:nodoc:
+        @as_mappings = {}
+        @ruby_mappings = {}
+
+        # Map defaults
+        map :as => 'flex.messaging.messages.AbstractMessage', :ruby => 'AMF::Values::AbstractMessage'
+        map :as => 'flex.messaging.messages.RemotingMessage', :ruby => 'AMF::Values::RemotingMessage'
+        map :as => 'flex.messaging.messages.AsyncMessage', :ruby => 'AMF::Values::AsyncMessage'
+        map :as => 'flex.messaging.messages.CommandMessage', :ruby => 'AMF::Values::CommandMessage'
+        map :as => 'flex.messaging.messages.AcknowledgeMessage', :ruby => 'AMF::Values::AcknowledgeMessage'
+        map :as => 'flex.messaging.messages.ErrorMessage', :ruby => 'AMF::Values::ErrorMessage'
+        map :as => 'flex.messaging.io.ArrayCollection', :ruby => 'AMF::Values::ArrayCollection'
+      end
+
+      # Map a given AS class to a ruby class.
+      #
+      # Use fully qualified names for both.
+      #
+      # Example:
+      #
+      #   m.map :as 'com.example.Date', :ruby => 'Example::Date'
+      def map params
+        [:as, :ruby].each {|k| params[k] = params[k].to_s} # Convert params to strings
+        @as_mappings[params[:as]] = params[:ruby]
+        @ruby_mappings[params[:ruby]] = params[:as]
+      end
+
+      # Returns the AS class name for the given ruby class name, returing nil if
+      # not found
+      def get_as_class_name class_name #:nodoc:
+        @ruby_mappings[class_name.to_s]
+      end
+
+      # Returns the ruby class name for the given AS class name, returing nil if
+      # not found
+      def get_ruby_class_name class_name #:nodoc:
+        @as_mappings[class_name.to_s]
+      end
+    end
+
+    # Array of custom object populators.
+    attr_reader :object_populators
+
+    # Array of custom object serializers.
+    attr_reader :object_serializers
+
+    def initialize #:nodoc:
+      @object_populators = []
+      @object_serializers = []
+    end
+
+    # Define class mappings in the block. Block is passed a MappingSet object as
+    # the first parameter.
+    #
+    # Example:
+    #
+    #   AMF::ClassMapper.define do |m|
+    #     m.map :as => 'AsClass', :ruby => 'RubyClass'
+    #   end
+    def define #:yields: mapping_set
+      yield mappings
+    end
+
+    # Returns the AS class name for the given ruby object. Will also take a string
+    # containing the ruby class name
+    def get_as_class_name obj
+      # Get class name
+      if obj.is_a?(String)
+        ruby_class_name = obj
+      elsif obj.is_a?(Values::TypedHash)
+        ruby_class_name = obj.type
+      else
+        ruby_class_name = obj.class.name
+      end
+
+      # Get mapped AS class name
+      mappings.get_as_class_name ruby_class_name
+    end
+
+    # Instantiates a ruby object using the mapping configuration based on the
+    # source AS class name. If there is no mapping defined, it returns a hash.
+    def get_ruby_obj as_class_name
+      ruby_class_name = mappings.get_ruby_class_name as_class_name
+      if ruby_class_name.nil?
+        # Populate a simple hash, since no mapping
+        return Values::TypedHash.new(as_class_name)
+      else
+        ruby_class = ruby_class_name.split('::').inject(Kernel) {|scope, const_name| scope.const_get(const_name)}
+        return ruby_class.new
+      end
+    end
+
+    # Populates the ruby object using the given properties
+    def populate_ruby_obj obj, props, dynamic_props=nil
+      # Process custom populators
+      @object_populators.each do |p|
+        next unless p.can_handle?(obj)
+        p.populate obj, props, dynamic_props
+        return obj
+      end
+
+      # Fallback populator
+      props.merge! dynamic_props if dynamic_props
+      hash_like = obj.respond_to?("[]=")
+      props.each do |key, value|
+        if obj.respond_to?("#{key}=")
+          obj.send("#{key}=", value)
+        elsif hash_like
+          obj[key.to_sym] = value
+        end
+      end
+      obj
+    end
+
+    # Extracts all exportable properties from the given ruby object and returns
+    # them in a hash
+    def props_for_serialization ruby_obj
+      # Proccess custom serializers
+      @object_serializers.each do |s|
+        next unless s.can_handle?(ruby_obj)
+        return s.serialize(ruby_obj)
+      end
+
+      # Handle hashes
+      if ruby_obj.is_a?(Hash)
+        # Stringify keys to make it easier later on and allow sorting
+        h = {}
+        ruby_obj.each {|k,v| h[k.to_s] = v}
+        return h
+      end
+
+      # Fallback serializer
+      props = {}
+      ruby_obj.public_methods(false).each do |method_name|
+        # Add them to the prop hash if they take no arguments
+        method_def = ruby_obj.method(method_name)
+        props[method_name] = ruby_obj.send(method_name) if method_def.arity == 0
+      end
+      props
+    end
+
+    private
+    def mappings
+      @mappings ||= MappingSet.new
+    end
+  end
+end

data/lib/amf/common.rb

@@ -0,0 +1,28 @@
+module AMF
+  class << self
+    # Deserialize the AMF string _source_ into a Ruby data structure and return it.
+    def deserialize source, amf_version = 0
+      if amf_version == 0
+        AMF::Deserializer.new.deserialize(source)
+      elsif amf_version == 3
+        AMF::AMF3Deserializer.new.deserialize(source)
+      else
+        raise AMFError, "unsupported version #{amf_version}"
+      end
+    end
+
+    # Serialize the given Ruby data structure _obj_ into an AMF stream
+    def serialize obj, amf_version = 0
+      if amf_version == 0
+        AMF::Serializer.new.serialize(obj)
+      elsif amf_version == 3
+        AMF::AMF3Serializer.new.serialize(obj)
+      else
+        raise AMFError, "unsupported version #{amf_version}"
+      end
+    end
+  end
+
+  # The base exception for AMF errors.
+  class AMFError < StandardError; end
+end

data/lib/amf/constants.rb

@@ -0,0 +1,46 @@
+module AMF
+  # AMF0 Type Markers
+  AMF0_NUMBER_MARKER       = 0x00 #"\000"
+  AMF0_BOOLEAN_MARKER      = 0x01 #"\001"
+  AMF0_STRING_MARKER       = 0x02 #"\002"
+  AMF0_OBJECT_MARKER       = 0x03 #"\003"
+  AMF0_MOVIE_CLIP_MARKER   = 0x04 #"\004" # Unused
+  AMF0_NULL_MARKER         = 0x05 #"\005"
+  AMF0_UNDEFINED_MARKER    = 0x06 #"\006"
+  AMF0_REFERENCE_MARKER    = 0x07 #"\a"
+  AMF0_HASH_MARKER         = 0x08 #"\b"
+  AMF0_OBJECT_END_MARKER   = 0x09 #"\t"
+  AMF0_STRICT_ARRAY_MARKER = 0x0A #"\n"
+  AMF0_DATE_MARKER         = 0x0B #"\v"
+  AMF0_LONG_STRING_MARKER  = 0x0C #"\f"
+  AMF0_UNSUPPORTED_MARKER  = 0x0D #"\r"
+  AMF0_RECORDSET_MARKER    = 0x0E #"\016" # Unused
+  AMF0_XML_MARKER          = 0x0F #"\017"
+  AMF0_TYPED_OBJECT_MARKER = 0x10 #"\020"
+  AMF0_AMF3_MARKER         = 0x11 #"\021"
+
+  # AMF3 Type Markers
+  AMF3_UNDEFINED_MARKER    =  0x00 #"\000"
+  AMF3_NULL_MARKER         =  0x01 #"\001"
+  AMF3_FALSE_MARKER        =  0x02 #"\002"
+  AMF3_TRUE_MARKER         =  0x03 #"\003"
+  AMF3_INTEGER_MARKER      =  0x04 #"\004"
+  AMF3_DOUBLE_MARKER       =  0x05 #"\005"
+  AMF3_STRING_MARKER       =  0x06 #"\006"
+  AMF3_XML_DOC_MARKER      =  0x07 #"\a"
+  AMF3_DATE_MARKER         =  0x08 #"\b"
+  AMF3_ARRAY_MARKER        =  0x09 #"\t"
+  AMF3_OBJECT_MARKER       =  0x0A #"\n"
+  AMF3_XML_MARKER          =  0x0B #"\v"
+  AMF3_BYTE_ARRAY_MARKER   =  0x0C #"\f"
+
+  # Other Markers, some reused
+  EMPTY_STRING             = AMF3_NULL_MARKER
+  ANONYMOUS_OBJECT         = AMF3_NULL_MARKER
+  DYNAMIC_OBJECT           = AMF3_XML_MARKER
+  CLOSE_DYNAMIC_OBJECT     = AMF3_NULL_MARKER
+  CLOSE_DYNAMIC_ARRAY      = AMF3_NULL_MARKER
+
+  MAX_INTEGER              = 268435455
+  MIN_INTEGER              = -268435456
+end