police-dataflow 0.0.1

data/lib/police/dataflow/proxying.rb

@@ -0,0 +1,179 @@
+module Police
+
+module DataFlow
+
+# The complex method dispatching logic used by ProxyBase.
+#
+# ProxyBase is the superclass for all proxy classes, which makes it visible to
+# application code. For this reason, we avoid defining any methods there.
+module Proxying
+  # Creates a label-holding proxy for an object.
+  #
+  # @param [Object] proxied the object to be proxied
+  # @param [Array<Integer>] label_keys 
+  # @return [Police::DataFlow::ProxyBase] an object that can carry labels, and
+  #     performs label-propagation as it redirects received messages to the
+  #     proxied object
+  def self.proxy(proxied, label_set, autoflow_set)
+    proxy_class = Police::DataFlow::Proxies.for proxied.class, label_set
+    proxy_class.new proxied, proxy_class, label_set, autoflow_set
+  end
+  
+  # Creates proxies for a class' instance methods.
+  #
+  # The proxy methods are defined as instance methods for the proxying class,
+  # because all the proxied objects that have the same class will need the same
+  # proxies.
+  #
+  # @param [Class] proxy_class a Police::DataFlow::Proxy subclass that will
+  #     receive the new proxy method definitions
+  # @param [Class] klass the class whose instance methods will be proxied
+  # @return [NilClass] nil
+  def self.add_class_methods(proxy_class, klass)
+    # NOTE: this is thread-safe because, at worst, the effort of adding methods
+    #       will be re-duplicated
+    klass.public_instance_methods(true).each do |method|
+      add_class_method proxy_class, klass.instance_method(method), :public
+    end
+    klass.protected_instance_methods(true).each do |method|
+      add_class_method proxy_class, klass.instance_method(method), :protected
+    end
+    klass.private_instance_methods(true).each do |method|
+      add_class_method proxy_class, klass.instance_method(method), :private
+    end
+    nil
+  end
+
+  # Adds a method to a proxy class.
+  #
+  # @param [Module] proxy_class the class that will receive the proxy method
+  # @param [Method] method_def the definition of the method to be proxied
+  # @param [Symbol] access the proxied method's access level (:public,
+  #     :protected, or :private)
+  def self.add_class_method(proxy_class, method_def, access)
+    # Avoid redefining methods, because that blows up VM caches.
+    if proxy_class.method_defined?(method_def.name) ||
+        proxy_class.private_method_defined?(method_def.name)
+      return
+    end
+    
+    # Define the method.
+    proxy_class.class_eval proxy_method_definition(
+        proxy_class.__police_classes__, method_def, access)
+    # Set its access level.
+    proxy_class.__send__ access, method_def.name
+  end
+  
+  # The full definition of a proxy method.
+  #
+  # @param [Array<Police::DataFlow::Label>] label_classes the label classes
+  #     supported by the proxy class
+  # @param [Method] method_def the definition of the method to be proxied
+  # @param [Symbol] access the proxied method's access level (:public,
+  #     :protected, or :private)
+  # @return [String] a chunk of Ruby that can be eval'ed in the context of a
+  #     proxy class to define a proxy for the given method
+  def self.proxy_method_definition(label_classes, method_def, access)
+    # NOTE: it might be tempting to attempt to pass a block to the proxied
+    #       method at all times, and try to yield to the original block when our
+    #       block is invoked; this would work most of the time, but it would
+    #       break methods such as Enumerable#map and String#scan, whose behavior
+    #       changes depending on whether or not a block is passed to them
+    ["def #{method_def.name}(#{proxy_argument_list(method_def, true)})",
+       "return_value = if block",
+         proxy_method_call(method_def, access, false) + " do |*yield_args|",
+           proxy_yield_args_decorating(label_classes, method_def),
+           "block_return = yield(*yield_args)",
+           # TODO(pwnall): consider adding a yield value filter
+           "next block_return",
+         "end",
+       "else",
+         proxy_method_call(method_def, access, false),
+       "end",
+        proxy_return_decorating(label_classes, method_def),
+       "return return_value",
+     "end"].join ';'
+  end
+  
+  # The proxying call to a method.
+  #
+  # @param [Method] method_def the definition of the method to be proxied
+  # @param [Symbol] access the proxied method's access level (:public,
+  #     :protected, or :private)
+  # @param [Boolean] include_block if true, the method call passes the block
+  #     that the proxy has received; if false, the block is ignored
+  # @return [String] a chunk of Ruby that can be used to call the given method
+  #     when defining a proxy for it
+  def self.proxy_method_call(method_def, access, include_block)
+    arg_list = proxy_argument_list method_def, include_block
+
+    if access == :public
+      "@__police_proxied__.#{method_def.name}(#{arg_list})"
+    else
+      "@__police_proxied__.__send__(:#{method_def.name}, #{arg_list})"
+    end
+  end
+  
+  # Code that labels the values yielded by a decorated method to its block. 
+  #
+  # @param [Array<Police::DataFlow::Label>] label_classes the label classes
+  #     supported by the proxy class
+  # @param [Method] method_def the definition of the decorated method
+  # @return [String] a chunk of Ruby that can be used to invoke the yield args
+  #     decorators of the labels held by a labeled object's proxy
+  def self.proxy_yield_args_decorating(label_classes, method_def)
+    method_name = method_def.name
+    arg_list = proxy_argument_list method_def, false
+    code_lines = ['labels = @__police_labels__']
+    label_classes.each do |label_class|
+      next unless hook = label_class.yield_args_hook(method_name)
+      label_key = label_class.__id__
+      code_lines << "labels[#{label_key}].each { |label, _| " \
+          "label.#{hook}(self, yield_args, #{arg_list}) }"
+    end
+    (code_lines.length > 1) ? code_lines.join('; ') : ''
+  end
+  
+  # Code that labels return value of a decorated method.
+  #
+  # @param [Array<Police::DataFlow::Label>] label_classes the label classes
+  #     supported by the proxy class
+  # @param [Method] method_def the definition of the method to be proxied
+  # @return [String] a chunk of Ruby that can be used to invoke the return value
+  #     decorators of the labels held by a labeled object's proxy
+  def self.proxy_return_decorating(label_classes, method_def)
+    method_name = method_def.name
+    arg_list = proxy_argument_list method_def, false
+    code_lines = ['labels = @__police_labels__']
+    label_classes.each do |label_class|
+      next unless hook = label_class.return_hook(method_name)
+      label_key = label_class.__id__
+      code_lines << "labels[#{label_key}].each { |label, _| " \
+          "return_value = label.#{hook}(return_value, self, #{arg_list}) }"
+    end
+    (code_lines.length > 1) ? code_lines.join('; ') : ''
+  end
+  
+  # The list of arguments used to define a proxy for the given method.
+  #
+  # @param [Method] method_def the definition of the method to be proxied
+  # @param [Boolean] captue_block if true, the method captures the block that it
+  #     receives
+  # @return [String] a chunk of Ruby that can be used as the argument list when
+  #     defining a proxy for the given method
+  def self.proxy_argument_list(method_def, capture_block)
+    arg_list = if method_def.arity >= 0
+      # Fixed number of arguments.
+      (1..method_def.arity).map { |i| "arg#{i}" }
+    else
+      # Variable number of arguments.
+      ((1..(-method_def.arity - 1)).map { |i| "arg#{i}" } << '*args')
+    end
+    arg_list << '&block' if capture_block
+    arg_list.join ', '
+  end
+end  # namespace Police::DataFlow::Proxying
+
+end  # namespace Police::DataFlow
+
+end  # namespace Police

data/police-dataflow.gemspec

@@ -0,0 +1,62 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "police-dataflow"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Victor Costan"]
+  s.date = "2012-03-28"
+  s.description = "Pure Ruby implementtion of data flow label propagation."
+  s.email = "victor@costan.us"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "lib/police-dataflow.rb",
+    "lib/police/dataflow.rb",
+    "lib/police/dataflow/core_extensions.rb",
+    "lib/police/dataflow/guarding.rb",
+    "lib/police/dataflow/label.rb",
+    "lib/police/dataflow/labeling.rb",
+    "lib/police/dataflow/proxies.rb",
+    "lib/police/dataflow/proxy_base.rb",
+    "lib/police/dataflow/proxying.rb",
+    "police-dataflow.gemspec",
+    "test/dataflow/core_extensions_test.rb",
+    "test/dataflow/labeling_test.rb",
+    "test/dataflow/proxies_test.rb",
+    "test/dataflow/proxy_base_test.rb",
+    "test/dataflow/proxying_test.rb",
+    "test/helper.rb",
+    "test/helpers/auto_flow_fixture.rb",
+    "test/helpers/no_flow_fixture.rb",
+    "test/helpers/proxying_fixture.rb"
+  ]
+  s.homepage = "http://github.com/csail/police"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.21"
+  s.summary = "Data flow label propagation"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/test/dataflow/core_extensions_test.rb

@@ -0,0 +1,51 @@
+require File.expand_path('../helper.rb', File.dirname(__FILE__))
+
+describe Police::DataFlow do
+  before do
+    @object = 'Hello'
+    @class = @object.class
+    @label = AutoFlowFixture.new
+  end
+  
+  describe '#label' do
+    describe 'with a single label' do
+      before do
+        @object = Police::DataFlow.label @object, @label
+      end
+      
+      it 'labels the object correctly' do
+        Police::DataFlow.labels(@object).must_equal [@label]
+      end
+      
+      it 'is idempotent' do
+        same_object = Police::DataFlow.label @object, @label
+        same_object.must_equal @object
+        Police::DataFlow.labels(@object).must_equal [@label]
+      end
+      
+      it 'returns a working proxy' do
+        @object.length.must_equal 5
+        @object.class.must_equal @class
+      end
+      
+      it 'returns a label-preserving proxy' do
+        @object << ' world'
+        @object.length.must_equal 11
+        Police::DataFlow.labels(@object).must_equal [@label]
+      end
+    end
+    
+    describe 'with two labels' do
+      before do
+        @label2 = NoFlowFixture.new
+        @object = Police::DataFlow.label @object, @label
+        @object = Police::DataFlow.label @object, @label2
+      end
+      
+      it 'labels the object correctly' do
+        Set.new(Police::DataFlow.labels(@object)).
+            must_equal Set.new([@label, @label2])
+      end
+    end
+  end
+end

data/test/dataflow/labeling_test.rb

@@ -0,0 +1,74 @@
+require File.expand_path('../helper.rb', File.dirname(__FILE__))
+
+describe Police::DataFlow do
+  before do
+    @object = 'Hello'
+    @class = @object.class
+    @p_label = AutoFlowFixture.new
+  end
+  
+  describe '#label' do
+    describe 'with a single label' do
+      before do
+        @object = Police::DataFlow.label @object, @p_label
+      end
+      
+      it 'labels the object correctly' do
+        Police::DataFlow.labels(@object).must_equal [@p_label]
+      end
+      
+      it 'is idempotent' do
+        same_object = Police::DataFlow.label @object, @p_label
+        same_object.must_equal @object
+        Police::DataFlow.labels(@object).must_equal [@p_label]
+      end
+      
+      it 'is idempotent vs label type' do
+        
+      end
+      
+      it 'returns a working proxy' do
+        @object.length.must_equal 5
+        @object.class.must_equal @class
+      end
+      
+      it 'returns a label-preserving proxy' do
+        @object << ' world'
+        @object.length.must_equal 11
+        Police::DataFlow.labels(@object).must_equal [@p_label]
+      end
+      
+      it 'returns a label-propagating proxy' do
+        Police::DataFlow.labels(@object[2..5]).must_equal [@p_label]
+      end
+    end
+    
+    describe 'with two labels' do
+      before do
+        @n_label = NoFlowFixture.new
+        @object = Police::DataFlow.label @object, @p_label
+        @object = Police::DataFlow.label @object, @n_label
+      end
+      
+      it 'labels the object correctly' do
+        Set.new(Police::DataFlow.labels(@object)).
+            must_equal Set.new([@p_label, @n_label])
+      end
+      
+      it 'propagates the labels correctly' do
+        Police::DataFlow.labels(@object[2..5]).must_equal [@p_label]
+      end
+    end
+  end
+  
+  describe '#labels' do
+    it 'returns an empty array for un-labeled objects' do
+      Police::DataFlow.labels(@object).must_equal []
+    end
+
+    it 'returns a populated array for labeled objects' do
+      labeled = Police::DataFlow.label @object, @p_label
+      Police::DataFlow.labels(labeled).must_equal [@p_label]
+    end
+  end
+end

data/test/dataflow/proxies_test.rb

@@ -0,0 +1,40 @@
+require File.expand_path('../helper.rb', File.dirname(__FILE__))
+
+describe Police::DataFlow::Proxies do
+  describe '#for' do
+    before do
+      @label_set = {}
+      @autoflow_set = {}
+      Police::DataFlow::Labeling.add_label_to_set NoFlowFixture.new,
+          @label_set, @autoflow_set
+    end
+  
+    let(:result) do
+      Police::DataFlow::Proxies.for ProxyingFixture, @label_set
+    end
+    after { Police::DataFlow::Proxies.clear_cache }
+  
+    it 'creates a Police::DataFlow::ProxyBase subclass' do
+      result.superclass.must_equal Police::DataFlow::ProxyBase
+    end
+    
+    it 'caches classes' do
+      Police::DataFlow::Proxies.for(ProxyingFixture, @label_set).
+          must_equal result
+    end
+    
+    it 'creates different proxies for different classes' do
+      Police::DataFlow::Proxies.for(Class.new(ProxyingFixture), @label_set).
+          wont_equal result
+    end
+    
+    it 'creates different proxies for sets of different label classes' do
+      label_set = @label_set.clone
+      autoflow_set = @autoflow_set.clone
+      Police::DataFlow::Labeling.add_label_to_set AutoFlowFixture.new,
+          label_set, autoflow_set
+      Police::DataFlow::Proxies.for(ProxyingFixture, label_set).
+          wont_equal result
+    end
+  end
+end

data/test/dataflow/proxy_base_test.rb

@@ -0,0 +1,145 @@
+require File.expand_path('../helper.rb', File.dirname(__FILE__))
+
+describe Police::DataFlow::ProxyBase do
+  before do
+    @label = AutoFlowFixture.new
+    @label_set = {}
+    @autoflow_set = {}
+    Police::DataFlow::Labeling.add_label_to_set @label, @label_set,
+                                                @autoflow_set
+    @proxied = ProxyingFixture.new
+    @proxy_class = Police::DataFlow::Proxies.for ProxyingFixture, @label_set
+    @proxy = @proxy_class.new @proxied, @proxy_class, @label_set, @autoflow_set
+  end
+  after { Police::DataFlow::Proxies.clear_cache }
+  
+  it 'proxies public methods' do
+    # NOTE: this test exercises the slow path in method_missing
+    @proxy.route('One', 'Two').must_equal ['One', 'Two']
+  end
+  
+  it 'allows labels to filter the return value of public methods' do
+    # NOTE: this test exercises the slow path in method_missing
+    Police::DataFlow.labels(@proxy.route('One', 'Two')).must_equal [@label]
+  end
+  
+  describe 'after proxying public methods' do
+    before { @proxy.route 'One', 'Two' }
+    
+    it 'defines proxied methods on the fly' do
+      @proxy_class.public_method_defined?(:route).must_equal true
+      @proxy_class.instance_method(:route).owner.must_equal @proxy_class
+    end
+
+    it 'still proxies public methods' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      @proxy.route('One', 'Two').must_equal ['One', 'Two']
+    end
+    
+    it 'still allows labels to filter the return value of public methods' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      Police::DataFlow.labels(@proxy.route('One', 'Two')).must_equal [@label]
+    end
+
+    it 'can still build proxies' do
+      other_proxy = @proxy_class.new ProxyingFixture.new, @proxy_class, 
+          @label_set, @autoflow_set
+      other_proxy.route('One', 'Two').must_equal ['One', 'Two']
+    end
+  end
+  
+  it 'proxies public methods with blocks' do
+    # NOTE: this test exercises the slow path in method_missing
+    result = []
+    @proxy.route('One', 'Two') { |*args| result << args }
+    result.must_equal [['One', 'Two']]
+  end
+  
+  it 'allows labels to filter the yielded values of public methods' do
+    # NOTE: this test exercises the slow path in method_missing
+    @proxy.route('One', 'Two') do |*args|
+      args.each { |arg| Police::DataFlow.labels(arg).must_equal [@label] }
+    end
+  end
+
+  describe 'after proxying public methods with blocks' do
+    before { @proxy.route('One', 'Two') { |*args| } }
+    
+    it 'defines proxied methods on the fly' do
+      @proxy_class.public_method_defined?(:route).must_equal true
+      @proxy_class.instance_method(:route).owner.must_equal @proxy_class
+    end
+
+    it 'still proxies public methods with blocks' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      result = []
+      @proxy.route('One', 'Two') { |*args| result << args }
+      result.must_equal [['One', 'Two']]
+    end
+
+    it 'still allows labels to filter the yielded values of public methods' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      @proxy.route('One', 'Two') do |*args|
+        args.each { |arg| Police::DataFlow.labels(arg).must_equal [@label] }
+      end
+    end
+  end  
+
+  it 'proxies protected methods' do
+    # NOTE: this test exercises the slow path in method_missing
+    @proxy.__send__(:add, 'One', 'Two').must_equal 'One, Two'
+  end
+
+  it 'allows labels to filter the return value of protected methods' do
+    # NOTE: this test exercises the slow path in method_missing
+    Police::DataFlow.labels(@proxy.__send__(:add, 'One', 'Two')).
+        must_equal [@label]
+  end
+  
+  
+  describe 'after proxying protected methods' do
+    before { @proxy.__send__ :add, 'One', 'Two' }
+    
+    it 'defines proxied methods on the fly' do
+      @proxy_class.protected_method_defined?(:add).must_equal true
+      @proxy_class.instance_method(:add).owner.must_equal @proxy_class
+    end
+
+    it 'still proxies protected methods' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      @proxy.__send__(:add, 'One', 'Two').must_equal 'One, Two'
+    end
+
+    it 'still allows labels to filter the return value of protected methods' do
+      # NOTE: this test exercises the auto-generated proxy method's fast path
+      Police::DataFlow.labels(@proxy.__send__(:add, 'One', 'Two')).
+          must_equal [@label]
+    end
+  end
+  
+  it 'proxies magic methods' do
+    @proxy.magic_meth('One', 'Two').must_equal ['meth', 'One', 'Two']
+  end
+
+  it 'allows labels to filter the return value of magic methods' do
+    Police::DataFlow.labels(@proxy.magic_meth('One', 'Two')).must_equal [@label]
+  end
+
+  describe 'after proxying magic methods' do
+    before do
+      @proxy.magic_meth 'One', 'Two'
+    end
+
+    it 'does not define magic proxied methods' do
+      @proxy_class.public_method_defined?(:magic_meth).must_equal false
+    end    
+  end
+  
+  it 'proxies ==' do
+    (@proxy == nil).must_equal '== proxied'
+  end
+
+  it 'proxies !=' do
+    (@proxy != nil).must_equal '!= proxied'
+  end  
+end