scotttam-RocketAMF 0.2.2

data/README.rdoc

@@ -0,0 +1,45 @@
+== DESCRIPTION:
+
+RocketAMF is a full featured AMF0/3 serializer and deserializer with support for
+Flash -> Ruby and Ruby -> Flash class mapping, custom serializers, remoting
+gateway helpers that follow AMF0/3 messaging specs, and a suite of specs to
+ensure adherence to the specification documents put out by Adobe. In addition,
+it now fully supports Ruby 1.9.
+
+== INSTALL:
+
+  gem install RocketAMF --source="http://gemcutter.org"
+
+== SIMPLE EXAMPLE:
+
+  require 'rocketamf'
+
+  hash = {:apple => "Apfel", :red => "Rot", :eyes => "Augen"}
+  File.open("amf.dat", 'w') do |f|
+    f.write RocketAMF.serialize(hash, 3) # Use AMF3 encoding because it's smaller
+  end
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Stephen Augenstein and Jacob 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 RocketAMF plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'scotttam-RocketAMF'
+  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    = 'scotttam-RocketAMF'
+  s.version = '0.2.2'
+  s.summary = 'Fast AMF serializer/deserializer with remoting request/response wrappers to simplify integration'
+
+  s.files        = FileList['README.rdoc', 'Rakefile', 'lib/**/*.rb', 'spec/**/*.rb', 'spec/**/*.bin', 'spec/spec.opts']
+  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  = ['Jacob Henry', 'Stephen Augenstein', "Joc O'Connor", "Scott Tamosunas"]
+  s.email    = 'perl.programmer@gmail.com'
+  s.homepage = 'http://github.com/scotttam/rocket-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/rocketamf.rb

@@ -0,0 +1,128 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+$:.unshift "#{File.expand_path(File.dirname(__FILE__))}/rocketamf/"
+
+require 'rocketamf/class_mapping'
+require 'rocketamf/constants'
+require 'rocketamf/remoting'
+
+# Joc's monkeypatch for string bytesize (only available in 1.8.7+)
+if !"amf".respond_to? :bytesize
+  class String
+    def bytesize
+      self.size
+    end
+  end
+end
+
+# RocketAMF is a full featured AMF0/3 serializer and deserializer with support
+# for Flash -> Ruby and Ruby -> Flash class mapping, custom serializers,
+# remoting gateway helpers that follow AMF0/3 messaging specs, and a suite of
+# specs to ensure adherence to the specification documents put out by Adobe.
+#
+# == Serialization & Deserialization
+#
+# RocketAMF provides two main methods - <tt>RocketAMF.serialize(obj, amf_version=0)</tt>
+# and <tt>RocketAMF.deserialize(source, amf_version=0)</tt>. To use, simple pass
+# in the string to deserialize and the version if different from the default. To
+# serialize an object, simply call <tt>RocketAMF.serialize</tt> with the object
+# and the proper version. If you're working only with AS3, it is more effiecient
+# to use the version 3 encoding, as it caches duplicate string to reduce
+# serialized size. However for greater compatibility the default, AMF version 0,
+# should work fine.
+#
+# == Mapping Classes Between Flash and Ruby
+#
+# RocketAMF provides a simple class mapping tool to facilitate serialization and
+# deserialization of typed objects. Refer to the documentation of
+# <tt>RocketAMF::ClassMapping</tt> for more details. If the provided class
+# mapping tool is not sufficient for your needs, you also have the option to
+# replace it with a class mapper of your own devising that matches the documented
+# API.
+#
+# == Remoting
+#
+# You can use RocketAMF bare to write an AMF gateway using the following code.
+# In addition, you can use rack-amf (http://github.com/warhammerkid/rack-amf)
+# which simplifies the code necessary to set up a functioning AMF gateway.
+#
+#   # helloworld.ru
+#   require 'rocketamf'
+#
+#   class HelloWorldApp
+#     APPLICATION_AMF = 'application/x-amf'.freeze
+#
+#     def call env
+#       if is_amf?(env)
+#         # Wrap request and response
+#         env['rack.input'].rewind
+#         request = RocketAMF::Envelope.new.populate_from_stream(env['rack.input'].read)
+#         response = RocketAMF::Envelope.new
+#
+#         # Handle request
+#         response.each_method_call request do |method, args|
+#           raise "Service #{method} does not exists" unless method == 'App.helloWorld'
+#           'Hello world'
+#         end
+#
+#         # Pass back response
+#         response_str = response.serialize
+#         return [200, {'Content-Type' => APPLICATION_AMF, 'Content-Length' => response_str.length.to_s}, [response_str]]
+#       else
+#         return [200, {'Content-Type' => 'text/plain', 'Content-Length' => '16' }, ["Rack AMF gateway"]]
+#       end
+#     end
+#
+#     private
+#     def is_amf? env
+#       return false unless env['CONTENT_TYPE'] == APPLICATION_AMF
+#       return false unless env['PATH_INFO'] == '/amf'
+#       return true
+#     end
+#   end
+#
+#   run HelloWorldApp.new
+module RocketAMF
+  begin
+    raise LoadError, 'C extensions not implemented'
+  rescue LoadError
+    require 'rocketamf/pure'
+  end
+
+  # Deserialize the AMF string _source_ of the given AMF version into a Ruby
+  # data structure and return it
+  def self.deserialize source, amf_version = 0
+    if amf_version == 0
+      RocketAMF::Deserializer.new.deserialize(source)
+    elsif amf_version == 3
+      RocketAMF::AMF3Deserializer.new.deserialize(source)
+    else
+      raise AMFError, "unsupported version #{amf_version}"
+    end
+  end
+
+  # Serialize the given Ruby data structure _obj_ into an AMF stream using the
+  # given AMF version
+  def self.serialize obj, amf_version = 0
+    if amf_version == 0
+      RocketAMF::Serializer.new.serialize(obj)
+    elsif amf_version == 3
+      RocketAMF::AMF3Serializer.new.serialize(obj)
+    else
+      raise AMFError, "unsupported version #{amf_version}"
+    end
+  end
+
+  # We use const_missing to define the active ClassMapper at runtime. This way,
+  # heavy modification of class mapping functionality is still possible without
+  # forcing extenders to redefine the constant.
+  def self.const_missing const #:nodoc:
+    if const == :ClassMapper
+      RocketAMF.const_set(:ClassMapper, RocketAMF::ClassMapping.new)
+    else
+      super(const)
+    end
+  end
+
+  # The base exception for AMF errors.
+  class AMFError < StandardError; end
+end

data/lib/rocketamf/class_mapping.rb

@@ -0,0 +1,231 @@
+require 'rocketamf/values/typed_hash'
+require 'rocketamf/values/array_collection'
+require 'rocketamf/values/messages'
+
+module RocketAMF
+  # 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:
+  #
+  #   RocketAMF::ClassMapper.define do |m|
+  #     m.map :as => 'AsClass', :ruby => 'RubyClass'
+  #     m.map :as => 'vo.User', :ruby => 'Model::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.
+  #
+  #   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
+  #   RocketAMF::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.
+  #
+  #   class CustomSerializer
+  #     def can_handle? obj
+  #       true
+  #     end
+  #   
+  #     def serialize obj
+  #       {}
+  #     end
+  #   end
+  #   RocketAMF::ClassMapper.object_serializers << CustomSerializer.new
+  #
+  # == Complete Replacement
+  #
+  # In some cases, it may be beneficial to replace the default provider of class
+  # mapping completely. In this case, simply assign an instance of your own class
+  # mapper to <tt>RocketAMF::ClassMapper</tt> after loading RocketAMF. Through
+  # the magic of <tt>const_missing</tt>, <tt>ClassMapper</tt> is only defined after
+  # the first access by default, so you get no annoying warning messages. Custom
+  # class mappers must implement the following methods: <tt>get_as_class_name</tt>,
+  # <tt>get_ruby_obj</tt>, <tt>populate_ruby_obj</tt>, <tt>props_for_serialization</tt>.
+  #
+  # Example:
+  #
+  #   require 'rubygems'
+  #   require 'rocketamf'
+  #   
+  #   RocketAMF::ClassMapper = MyCustomClassMapper.new
+  #   # No warning about already initialized constant ClassMapper
+  #   RocketAMF::ClassMapper.class # MyCustomClassMapper
+  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 => 'RocketAMF::Values::AbstractMessage'
+        map :as => 'flex.messaging.messages.RemotingMessage', :ruby => 'RocketAMF::Values::RemotingMessage'
+        map :as => 'flex.messaging.messages.AsyncMessage', :ruby => 'RocketAMF::Values::AsyncMessage'
+        map :as => 'flex.messaging.messages.CommandMessage', :ruby => 'RocketAMF::Values::CommandMessage'
+        map :as => 'flex.messaging.messages.AcknowledgeMessage', :ruby => 'RocketAMF::Values::AcknowledgeMessage'
+        map :as => 'flex.messaging.messages.ErrorMessage', :ruby => 'RocketAMF::Values::ErrorMessage'
+        map :as => 'flex.messaging.io.ArrayCollection', :ruby => 'RocketAMF::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:
+    #
+    #   RocketAMF::ClassMapper.define do |m|
+    #     m.map :as => 'AsClass', :ruby => 'RubyClass'
+    #   end
+    def define #:yields: mapping_set
+      yield mappings
+    end
+
+    # Reset all class mappings except the defaults
+    def reset
+      @mappings = nil
+    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
+    # <tt>RocketAMF::Values::TypedHash</tt> with the serialized class name.
+    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 = {}
+      @ignored_props ||= Object.new.public_methods
+      (ruby_obj.public_methods - @ignored_props).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.to_s] = ruby_obj.send(method_name) if method_def.arity == 0
+      end
+      props
+    end
+
+    private
+    def mappings
+      @mappings ||= MappingSet.new
+    end
+  end
+end