rocketamf_pure 1.0.0

data/README.rdoc

@@ -0,0 +1,47 @@
+== DESCRIPTION:
+
+RocketAMF is a full featured AMF0/3 serializer and deserializer with support for
+bi-directional Flash to Ruby class mapping, custom serialization and mapping,
+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. If the C
+components compile, then RocketAMF automatically takes advantage of them to
+provide a substantial performance benefit. In addition, RocketAMF is fully
+compatible with Ruby 1.9.
+
+== INSTALL:
+
+  gem install RocketAMF
+
+== 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 to serialize
+  end
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Stephen Augenstein and Jacob Henry
+
+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,9 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+desc 'Run all specs in the spec directory'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/benchmark.rb

@@ -0,0 +1,73 @@
+$:.unshift(File.dirname(__FILE__) + '/lib')
+require 'rubygems'
+require 'rocketamf'
+require 'rocketamf/pure/deserializer' # Only ext gets included by default if available
+require 'rocketamf/pure/serializer'
+
+OBJECT_COUNT = 100000
+TESTS = 5
+
+class TestClass
+  attr_accessor :prop_a, :prop_b, :prop_c, :prop_d, :prop_e
+
+  def populate some_arg=nil # Make sure class mapper doesn't think populate is a property
+    @@count ||= 1
+    @prop_a = "asdfasdf #{@@count}"
+    @prop_b = "simple string"
+    @prop_c = 3120094.03
+    @prop_d = Time.now
+    @prop_e = 3120094
+    @@count += 1
+    self
+  end
+end
+
+objs = []
+OBJECT_COUNT.times do
+  objs << TestClass.new.populate
+end
+
+["native", "pure"].each do |type|
+  # Set up class mapper
+  cm = if type == "pure"
+    RocketAMF::ClassMapping
+  else
+    RocketAMF::Ext::FastClassMapping
+  end
+  cm.define do |m|
+    m.map :as => 'TestClass', :ruby => 'TestClass'
+  end
+
+  [0, 3].each do |version|
+    # 2**24 is larger than anyone is ever going to run this for
+    min_serialize = 2**24
+    min_deserialize = 2**24
+
+    puts "Testing #{type} AMF#{version}:"
+    TESTS.times do
+      ser = if type == "pure"
+        RocketAMF::Pure::Serializer.new(cm.new)
+      else
+        RocketAMF::Ext::Serializer.new(cm.new)
+      end
+      start_time = Time.now
+      out = ser.serialize(version, objs)
+      end_time = Time.now
+      puts "\tserialize run: #{end_time-start_time}s"
+      min_serialize = [end_time-start_time, min_serialize].min
+
+      des = if type == "pure"
+        RocketAMF::Pure::Deserializer.new(cm.new)
+      else
+        RocketAMF::Ext::Deserializer.new(cm.new)
+      end
+      start_time = Time.now
+      temp = des.deserialize(version, out)
+      end_time = Time.now
+      puts "\tdeserialize run: #{end_time-start_time}s"
+      min_deserialize = [end_time-start_time, min_deserialize].min
+    end
+    puts "\tminimum serialize time: #{min_serialize}s"
+    puts "\tminimum deserialize time: #{min_deserialize}s"
+  end
+end

data/lib/rocketamf.rb

@@ -0,0 +1,212 @@
+$:.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 "date"
+require "stringio"
+require 'rocketamf/extensions'
+require 'rocketamf/class_mapping'
+require 'rocketamf/constants'
+require 'rocketamf/remoting'
+
+# RocketAMF is a full featured AMF0/3 serializer and deserializer with support for
+# bi-directional Flash to Ruby class mapping, custom serialization and mapping,
+# 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. If the C
+# components compile, then RocketAMF automatically takes advantage of them to
+# provide a substantial performance benefit. In addition, RocketAMF is fully
+# compatible with Ruby 1.9.
+#
+# == Performance
+#
+# RocketAMF provides native C extensions for serialization, deserialization,
+# remoting, and class mapping. If your environment supports them, RocketAMF will
+# automatically take advantage of the C serializer, deserializer, and remoting
+# support. The C class mapper has some substantial performance optimizations that
+# make it incompatible with the pure Ruby class mapper, and so it must be manually
+# enabled. For more information see <tt>RocketAMF::ClassMapping</tt>. Below are
+# some benchmarks I took using using a simple little benchmarking utility I whipped
+# up, which can be found in the root of the repository.
+#
+#   # 100000 objects
+#   # Ruby 1.8
+#   Testing native AMF0:
+#     minimum serialize time: 1.229868s
+#     minimum deserialize time: 0.86465s
+#   Testing native AMF3:
+#     minimum serialize time: 1.444652s
+#     minimum deserialize time: 0.879407s
+#   Testing pure AMF0:
+#     minimum serialize time: 25.427931s
+#     minimum deserialize time: 11.706084s
+#   Testing pure AMF3:
+#     minimum serialize time: 31.637864s
+#     minimum deserialize time: 14.773969s
+#
+# == Serialization & Deserialization
+#
+# RocketAMF provides two main methods - <tt>serialize</tt> and <tt>deserialize</tt>.
+# Deserialization takes a String or StringIO object and the AMF version if different
+# from the default. Serialization takes any Ruby object and the version if different
+# from the default. Both default to AMF0, as it's more widely supported and slightly
+# faster, but AMF3 does a better job of not sending duplicate data. Which you choose
+# depends on what you need to communicate with and how much serialized size matters.
+#
+# == 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/rubyamf/rack-amf) or
+# RubyAMF (http://github.com/rubyamf/rubyamf), both of which provide rack-compliant
+# AMF gateways.
+#
+#   # 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
+#
+# == Advanced Serialization (encode_amf and IExternalizable)
+#
+# RocketAMF provides some additional functionality to support advanced
+# serialization techniques. If you define an <tt>encode_amf</tt> method on your
+# object, it will get called during serialization. It is passed a single argument,
+# the serializer, and it can use the serializer stream, the <tt>serialize</tt>
+# method, the <tt>write_array</tt> method, the <tt>write_object</tt> method, and
+# the serializer version. Below is a simple example that uses <tt>write_object</tt>
+# to customize the property hash that is used for serialization.
+#
+# Example:
+#
+#   class TestObject
+#     def encode_amf ser
+#       ser.write_object self, @attributes
+#     end
+#   end
+#
+# If you plan on using the <tt>serialize</tt> method, make sure to pass in the
+# current serializer version, or you could create a message that cannot be deserialized.
+#
+# Example:
+#
+#   class VariableObject
+#     def encode_amf ser
+#       if ser.version == 0
+#         ser.serialize 0, true
+#       else
+#         ser.serialize 3, false
+#       end
+#     end
+#   end
+#
+# If you wish to send and receive IExternalizable objects, you will need to
+# implement <tt>encode_amf</tt>, <tt>read_external</tt>, and <tt>write_external</tt>.
+# Below is an example of a ResultSet class that extends Array and serializes as
+# an array collection. RocketAMF can automatically serialize arrays as
+# ArrayCollection objects, so this is just an example of how you might implement
+# an object that conforms to IExternalizable.
+#
+# Example:
+#
+#   class ResultSet < Array
+#     def encode_amf ser
+#       if ser.version == 0
+#         # Serialize as simple array in AMF0
+#         ser.write_array self
+#       else
+#         # Serialize as an ArrayCollection object
+#         # It conforms to IExternalizable, does not have any dynamic properties,
+#         # and has no "sealed" members. See the AMF3 specs for more details about
+#         # object traits.
+#         ser.write_object self, nil, {
+#           :class_name => "flex.messaging.io.ArrayCollection",
+#           :externalizable => true,
+#           :dynamic => false,
+#           :members => []
+#         }
+#       end
+#     end
+#
+#     # Write self as array to stream
+#     def write_external ser
+#       ser.write_array(self)
+#     end
+#
+#     # Read array out and replace data with deserialized array.
+#     def read_external des
+#       replace(des.read_object)
+#     end
+#   end
+module RocketAMF
+  require 'rocketamf/pure'
+
+  # Deserialize the AMF string _source_ of the given AMF version into a Ruby
+  # data structure and return it. Creates an instance of <tt>RocketAMF::Deserializer</tt>
+  # with a new instance of <tt>RocketAMF::ClassMapper</tt> and calls deserialize
+  # on it with the given source and amf version, returning the result.
+  def self.deserialize source, amf_version = 0
+    des = RocketAMF::Deserializer.new(RocketAMF::ClassMapper.new)
+    des.deserialize(amf_version, source)
+  end
+
+  # Serialize the given Ruby data structure _obj_ into an AMF stream using the
+  # given AMF version. Creates an instance of <tt>RocketAMF::Serializer</tt>
+  # with a new instance of <tt>RocketAMF::ClassMapper</tt> and calls serialize
+  # on it with the given object and amf version, returning the result.
+  def self.serialize obj, amf_version = 0
+    ser = RocketAMF::Serializer.new(RocketAMF::ClassMapper.new)
+    ser.serialize(amf_version, obj)
+  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)
+    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,237 @@
+require 'rocketamf/values/typed_hash'
+require 'rocketamf/values/messages'
+
+module RocketAMF
+  # Container for all mapped classes
+  class MappingSet
+    # Creates a mapping set object and populates the default mappings
+    def initialize
+      @as_mappings = {}
+      @ruby_mappings = {}
+      map_defaults
+    end
+
+    # Adds required mapping configs, calling map for the required base mappings.
+    # Designed to allow extenders to take advantage of required default mappings.
+    def 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 => 'DSA', :ruby => 'RocketAMF::Values::AsyncMessageExt'
+      map :as => 'flex.messaging.messages.CommandMessage', :ruby => 'RocketAMF::Values::CommandMessage'
+      map :as => 'DSC', :ruby => 'RocketAMF::Values::CommandMessageExt'
+      map :as => 'flex.messaging.messages.AcknowledgeMessage', :ruby => 'RocketAMF::Values::AcknowledgeMessage'
+      map :as => 'DSK', :ruby => 'RocketAMF::Values::AcknowledgeMessageExt'
+      map :as => 'flex.messaging.messages.ErrorMessage', :ruby => 'RocketAMF::Values::ErrorMessage'
+      self
+    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
+
+  # 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 require subclassing the class mapper to add support.
+  #
+  # == Complete Replacement
+  #
+  # In some cases, it may be beneficial to replace the default provider of class
+  # mapping completely. In this case, simply assign your class mapper class 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 on instances: <tt>use_array_collection</tt>,
+  # <tt>get_as_class_name</tt>, <tt>get_ruby_obj</tt>, <tt>populate_ruby_obj</tt>,
+  # and <tt>props_for_serialization</tt>. In addition, it should have a class level
+  # <tt>mappings</tt> method that returns the mapping set it's using, although its
+  # not required. If you'd like to see an example of what complete replacement
+  # offers, check out RubyAMF (http://github.com/rubyamf/rubyamf).
+  #
+  # Example:
+  #
+  #   require 'rubygems'
+  #   require 'rocketamf'
+  #   
+  #   RocketAMF::ClassMapper = MyCustomClassMapper
+  #   # No warning about already initialized constant ClassMapper
+  #   RocketAMF::ClassMapper # MyCustomClassMapper
+  #
+  # == C ClassMapper
+  #
+  # The C class mapper, <tt>RocketAMF::Ext::FastClassMapping</tt>, has the same
+  # public API that <tt>RubyAMF::ClassMapping</tt> does, but has some additional
+  # performance optimizations that may interfere with the proper serialization of
+  # objects. To reduce the cost of processing public methods for every object,
+  # its implementation of <tt>props_for_serialization</tt> caches valid properties
+  # by class, using the class as the hash key for property lookup. This means that
+  # adding and removing properties from instances while serializing using a given
+  # class mapper instance will result in the changes not being detected.  As such,
+  # it's not enabled by default. So long as you aren't planning on modifying
+  # classes during serialization using <tt>encode_amf</tt>, the faster C class
+  # mapper should be perfectly safe to use.
+  #
+  # Activating the C Class Mapper:
+  #
+  #   require 'rubygems'
+  #   require 'rocketamf'
+  #   RocketAMF::ClassMapper = RocketAMF::Ext::FastClassMapping
+  class ClassMapping
+    class << self
+      # Global configuration variable for sending Arrays as ArrayCollections.
+      # Defaults to false.
+      attr_accessor :use_array_collection
+
+      # Returns the mapping set with all the class mappings that is currently
+      # being used.
+      def mappings
+        @mappings ||= MappingSet.new
+      end
+
+      # Define class mappings in the block. Block is passed a <tt>MappingSet</tt> object
+      # as the first parameter.
+      #
+      # Example:
+      #
+      #   RocketAMF::ClassMapper.define do |m|
+      #     m.map :as => 'AsClass', :ruby => 'RubyClass'
+      #   end
+      def define &block #:yields: mapping_set
+        yield mappings
+      end
+
+      # Reset all class mappings except the defaults and return
+      # <tt>use_array_collection</tt> to false
+      def reset
+        @use_array_collection = false
+        @mappings = nil
+      end
+    end
+
+    attr_reader :use_array_collection
+
+    # Copies configuration from class level configs to populate object
+    def initialize
+      @mappings = self.class.mappings
+      @use_array_collection = self.class.use_array_collection === true
+    end
+
+    # Returns the ActionScript 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
+      elsif obj.is_a?(Hash)
+        return nil
+      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 ActionScript 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. props and
+    # dynamic_props will be hashes with symbols for keys.
+    def populate_ruby_obj obj, props, dynamic_props=nil
+      props.merge! dynamic_props if dynamic_props
+
+      # Don't even bother checking if it responds to setter methods if it's a TypedHash
+      if obj.is_a?(Values::TypedHash)
+        obj.merge! props
+        return obj
+      end
+
+      # Some type of object
+      hash_like = obj.respond_to?("[]=")
+      props.each do |key, value|
+        if obj.respond_to?("#{key}=")
+          obj.send("#{key}=", value)
+        elsif hash_like
+          obj[key] = value
+        end
+      end
+      obj
+    end
+
+    # Extracts all exportable properties from the given ruby object and returns
+    # them in a hash. If overriding, make sure to return a hash wth string keys
+    # unless you are only going to be using the native C extensions, as the pure
+    # ruby serializer performs a sort on the keys to acheive consistent, testable
+    # results.
+    def props_for_serialization ruby_obj
+      # 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
+
+      # Generic object 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
+  end
+end