dia 1.5 → 2.0.0

data/README.mkd

@@ -0,0 +1,67 @@
+# Dia  
+Through the use of technology found on Apple's Leopard and Snow Leopard 
+operating systems, Dia can create dynamic and robust sandbox environments 
+for applications and for blocks of ruby code. The Ruby API was designed to be 
+simple, and a joy to use. I hope you feel the same way :-)
+
+## Quick Example
+
+* RubyBlock
+
+        require('rubygems')
+        require('dia')
+        require('open-uri')
+
+        sandbox = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          open('http://www.google.com')
+        end
+
+        sandbox.rescue_exception = true
+        sandbox.run
+        puts "Exception  : #{sandbox.exception.klass}"
+        puts "Message    : #{sandbox.exception.message}"
+
+* Application
+
+        require('rubygems')
+        require('dia')
+
+        sandbox = Dia::Application.new(Dia::Profiles::NO_INTERNET,
+                                       '/path/to/firefox')
+
+        sandbox.run_nonblock 
+        sandbox.terminate
+
+## Documentation
+
+* [API Documentation](http://yardoc.org/docs/robgleeson-Dia/)   
+  Written using YARD, the API documentation makes a great reference.  
+  *The API documentation linked is for the latest stable release*
+
+* [Mailing list](http://groups.google.com/group/ruby-dia)   
+  Troubleshoot your problems with other Dia users on the Google Groups mailing list.  
+
+* Wiki documentation  
+  *Work in progress*
+
+## Supported Rubies.
+
+The following Ruby implementations have had the test suite run against them, and
+reported a 100% success rate.
+
+* MRI
+  * 1.8.7-p299
+  * 1.9.1-p378
+  * 1.9.2-rc1    
+* REE
+  * Ruby Enterprise Edition 2010.02 (1.8.7-p253)
+
+MacRuby is not supported because it does not support Kernel.fork, and it won't add support
+for fork anytime soon(if ever).  
+JRuby has experimental support for fork, but I haven't tried it.
+ 
+## Bugs  
+Bug reports are _very_ welcome, and can be reported through the
+[issue tracker](http://github.com/robgleeson/dia/issues).
+
+

data/dia.gemspec

@@ -0,0 +1,49 @@
+# -*- encoding: utf-8 -*-
+require('./lib/dia')
+
+Gem::Specification.new do |s|
+
+  s.name    = %q{dia}
+  s.version = Dia::VERSION
+  s.authors = ["Robert Gleeson"]
+  s.email   = %q{rob@flowof.info}
+  s.date    = Time.now.strftime("%Y-%m-%d")
+  
+  s.description = %q{Through the use of technology found on Apple's Leopard and Snow Leopard 
+                     operating systems, Dia can create dynamic and robust sandbox environments 
+                     for applications and for blocks of ruby code. 
+                     The Ruby API was designed to be simple, and a joy to use. 
+                     I hope you feel the same way :-)}
+
+  s.summary     = %q{Through the use of technology found on Apple's Leopard and Snow Leopard 
+                     operating systems, Dia can create dynamic and robust sandbox environments 
+                     for applications and for blocks of ruby code. 
+                     The Ruby API was designed to be simple, and a joy to use. 
+                     I hope you feel the same way :-)}
+
+ 
+  s.require_paths = ["lib"]
+  s.files         = Dir["lib/**/*.rb"] + Dir["test/**/*.rb"] + %w(COPYING README.mkd dia.gemspec)
+  s.test_files    = Dir["test/**/*.rb"]
+  
+
+  s.add_runtime_dependency(%q<ffi>, ["= 0.6.2"])
+  s.add_development_dependency(%q<yard>, [">= 0"])
+  s.has_rdoc = %q{yard}
+
+  s.post_install_message = <<-MESSAGE  
+  -------------------------------------------------------------------- 
+  Dia (#{Dia::VERSION})
+  
+  Thanks for installing Dia, #{Dia::VERSION}! 
+
+  >=2.0.0 releases include public API changes that are not backward
+  compatiable with older releases. Be sure to check the docs!
+ 
+  [Github]             http://github.com/robgleeson/dia
+  [API Documentation]  http://yardoc.org/docs/robgleeson-dia/
+  [Mailing List (new)] http://groups.google.com/group/ruby-dia
+  --------------------------------------------------------------------  
+  MESSAGE
+
+end

data/lib/dia.rb

@@ -1,11 +1,14 @@
-gem 'ffi', '= 0.6.2'
-require 'ffi'
-require File.join(File.dirname(__FILE__), 'dia/profiles.rb')
-require File.join(File.dirname(__FILE__), 'dia/commonapi.rb')
-require File.join(File.dirname(__FILE__), 'dia/sandbox.rb')
+gem('ffi', '0.6.2')
+require('ffi') 
+require('ostruct')
+require(File.expand_path('dia/shared_features'  , File.dirname(__FILE__)))
+require(File.expand_path('dia/functions'        , File.dirname(__FILE__)))
+require(File.expand_path('dia/profiles'         , File.dirname(__FILE__)))
+require(File.expand_path('dia/ruby_block'       , File.dirname(__FILE__)))
+require(File.expand_path('dia/application'      , File.dirname(__FILE__)))
+require(File.expand_path('dia/exceptions'       , File.dirname(__FILE__)))
+require(File.expand_path('dia/exception_struct' , File.dirname(__FILE__)))
 
 module Dia
-  VERSION = '1.5'
-  class SandboxException < StandardError; end
+  VERSION = '2.0.0'
 end
-

data/lib/dia/application.rb

@@ -0,0 +1,49 @@
+module Dia
+
+  class Application
+    include Dia::SharedFeatures
+
+
+    # @param [String] Profile     Accepts one of five profiles found under the {Dia::Profiles} 
+    #                             module.
+    #
+    # @param [String] Application Accepts a path to an application.
+    #
+    # @raise [ArgumentError]      It may raise an ArgumentError if it isn't possible to use a
+    #                             particular profile with this type of sandbox.
+    def initialize(profile, app)
+      @profile = profile
+      @app     = app
+      raise(ArgumentError, "Dia::Profiles::NO_OS_SERVICES is not applicable to the Application " \
+                           "sandbox.") if Dia::Profiles::NO_OS_SERVICES == @profile
+    end
+
+    # This method will spawn a child process, initialize a sandbox environment, and call exec()
+    # to start your application.
+    # 
+    # @return [Fixnum]  Returns the Process ID(PID) of the child process used to execute an 
+    #                   application in a sandbox.
+    def run
+      @pid = fork do 
+        initialize_sandbox
+        exec(@app)
+      end
+
+      _, @exit_status = Process.wait2(@pid)
+      @pid
+    end
+
+    # An identical but non-blocking form of {#run}.
+    def run_nonblock
+      @pid = fork do
+        initialize_sandbox
+        exec(@app)
+      end
+
+      @exit_status = Process.detach(@pid)
+      @pid
+    end
+
+  end
+
+end

data/lib/dia/exception_struct.rb

@@ -0,0 +1,7 @@
+module Dia
+ # @attr_reader [String] klass     Returns Exception#class as a String.
+ # @attr_reader [String] message   Returns Exception#message as a String.
+ # @attr_reader [String] backtrace Returns Exception#backtrace as a String.
+ class ExceptionStruct < Struct.new(:klass, :message, :backtrace)
+ end
+end

data/lib/dia/exceptions.rb

@@ -0,0 +1,5 @@
+module Dia
+  module Exceptions
+    SandboxException = Class.new(StandardError)
+  end
+end

data/lib/dia/functions.rb

@@ -0,0 +1,8 @@
+module Dia
+  module Functions
+    extend(FFI::Library)
+    ffi_lib(%w(system))
+    attach_function(:sandbox_init, [ :pointer, :uint64, :pointer ], :int)
+    attach_function(:sandbox_free_error, [ :pointer ], :void)  
+  end
+end

data/lib/dia/profiles.rb

@@ -1,8 +1,7 @@
 module Dia
-  
   module Profiles
-    extend FFI::Library
-    ffi_lib(%w(sandbox system libSystem.B.dylib))
+    extend(FFI::Library)
+    ffi_lib(%w(system))
     
     NO_INTERNET                    = attach_variable(:kSBXProfileNoInternet,
                                                      :string).read_string
@@ -14,8 +13,5 @@ module Dia
                                                      :string).read_string
     NO_OS_SERVICES                 = attach_variable(:kSBXProfilePureComputation,
                                                      :string).read_string
-    
   end
-  
 end
-    

data/lib/dia/ruby_block.rb

@@ -0,0 +1,319 @@
+module Dia
+
+  class RubyBlock
+
+    require('io/wait') 
+    require('stringio') 
+    include Dia::SharedFeatures
+
+
+    # @param  [String] Profile Accepts one of five profiles which can be found
+    #                          under the {Dia::Profiles} module.
+    #
+    # @param  [Proc]   Block   Accepts a block or Proc object as its second argument.
+    #
+    # @raise  [ArgumentError]  It will raise an ArgumentError if a profile and block 
+    #                          isn't supplied to the constructor
+    #
+    # @return [Dia::RubyBlock] Returns an instance of Dia::RubyBlock.
+    def initialize(profile, &block)
+      raise(ArgumentError, "It is required that a block be passed to the constructor.\n" \
+                           "Please consult the documentation.") unless block_given?
+      @profile         = profile
+      @proc            = block
+      @rescue          = false
+      @redirect_stdout = false
+      @redirect_stderr = false
+      @pipes           = {}
+    end
+
+
+    # When the "capture stdout" feature is enabled, this method will return the contents
+    # of the standard output stream for the child process used to execute your sandbox.
+    #
+    # @return [String, nil]       Returns the contents of stdout.   
+    #                             Returns nil when no data is available on stdout, or when the 
+    #                             "capture stdout" feature is disabled.
+    #
+    # @see #redirect_stdout= This feature is disabled by default. See how to enable it.
+    #   
+    def stdout
+      if pipes_readable?(@pipes[:stdout_reader], @pipes[:stdout_writer])
+        @pipes[:stdout_writer].close
+        @stdout = @pipes[:stdout_reader].read
+        @pipes[:stdout_reader].close
+      end
+      @stdout
+    end
+
+    # This method can enable or disable a feature that will capture standard output
+    # in the child process that is spawned to execute a sandbox.
+    #
+    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value.
+    # @return [Boolean] Returns the calling argument.
+    # @see    #stdout   See #stdout for accessing the contents of stdout.
+    def redirect_stdout=(boolean)
+      @redirect_stdout = boolean
+    end
+
+    # This method will tell you if standatd output is being redirected in the child
+    # process used to execute your sandbox.
+    #
+    # @see    #redirect_stdout=   See how to enable the "redirect stdout" feature.
+    #
+    # @return [Boolean] Returns true or false.
+    def redirect_stdout?
+      !!@rescue_stdout
+    end
+
+    # This method will tell you if standard error is being redirected in the child process
+    # used to execute your sandbox.
+    #
+    # @see    #redirect_stderr= See how to enable the "redirect stderr" feature. 
+    # @return [Boolean] returns true or false.
+    def redirect_stderr?
+      !!@rescue_stderr
+    end
+
+    # This method can enable or disable a feature that will capture standard error output
+    # in the child process that is spawned to execute a sandbox.
+    #
+    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value.
+    # @return [Boolean] Returns the calling argument.
+    # @see    #stdout   See #stderr for accessing the contents of stderr.
+    def redirect_stderr=(boolean)
+      @redirect_stderr = boolean
+    end
+
+
+    # When the "capture stderr" feature is enabled, this method will return the contents
+    # of the standard error stream for the child process used to execute your sandbox.
+    #
+    # @return [String, nil]       Returns the contents of stderr.   
+    #                             Returns nil when no data is available on stderr, or when the 
+    #                             "capture stderr" feature is disabled.
+    #
+    # @see #redirect_stderr= This feature is disabled by default. See how to enable it.
+    #   
+    def stderr
+      if pipes_readable?(@pipes[:stderr_reader], @pipes[:stderr_writer])
+        @pipes[:stderr_writer].close
+        @stderr = @pipes[:stderr_reader].read
+        @pipes[:stderr_reader].close
+      end
+      @stderr
+    end
+
+    # This method will tell you if an exception has been raised in the child process
+    # used to execute your sandbox.   
+    # The "capture exception" feature must be enabled for this method to ever
+    # return true. 
+    # 
+    # @see    #rescue_exception= See #rescue_exception= for enabling the capture
+    #                            of raised exceptions in your sandbox.
+    #
+    # @see    #exception         See the #exception method for accessing an 
+    #                            exception raised in your sandbox.
+    #
+    # @return [Boolean]          Returns true or false.
+    def exception_raised?
+      !!exception
+    end
+
+    # This method will tell you if the {#rescue_exception=} feature is enabled by
+    # returning a boolean.
+    #
+    # @see    #rescue_exception= See #rescue_exception= for enabling the capture
+    #                            of raised exceptions in your sandbox.
+    #
+    # @see    #exception         See the #exception method for accessing an 
+    #                            exception raised in your sandbox.
+    #
+    # @return [Boolean] Returns true or false.
+    # @since  2.0.0
+    def rescue_exception?
+      !!@rescue
+    end
+
+    # This method can enable or disable a feature that will try to capture 
+    # raised exceptions in the child process that is spawned to execute a sandbox.
+    #
+    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value. 
+    #
+    # @return [Boolean] Returns the calling argument.
+    #
+    # @see    #exception See #exception for information on how to access 
+    #                    the data of an exception raised in your sandbox.
+    #
+    # @since 2.0.0
+    def rescue_exception=(boolean)
+      @rescue = boolean
+    end
+
+    # When the "capture exceptions" feature is enabled and an exception has been raised in
+    # the child process used to execute your sandbox, this method will return a subclass
+    # of Struct whose attributes represent the exception data. 
+    #
+    # Every call {#run} or {#run_nonblock} will reset the instance variable referencing the
+    # object storing exception data to nil.
+    # 
+    # @return [Dia::ExceptionStruct, nil] Returns an instance of {Dia::ExceptionStruct} or nil 
+    #                                     when there is no exception available.  
+    #
+    # @see #rescue_exception=             The "capture exception" feature is disabled by default.  
+    #                                     See how to enable it.
+    #
+    # @see Dia::ExceptionStruct           The documentation for Dia::ExceptionStruct.
+    #
+    # @since 1.5
+    def exception
+      if pipes_readable?(@pipes[:exception_reader], @pipes[:exception_writer]) 
+        @pipes[:exception_writer].close
+        @e = ExceptionStruct.new *Marshal.load(@pipes[:exception_reader].read).values_at(:klass, 
+                                                                                         :message, 
+                                                                                         :backtrace)
+        @pipes[:exception_reader].close
+      end
+      @e
+    end
+
+    # The run method will spawn a child process to execute the block supplied to the constructer 
+    # in a sandbox.   
+    # This method will block. See {#run_nonblock} for the non-blocking form of
+    # this method.
+    #
+    # @param  [Arguments] Arguments   A variable amount of arguments that will 
+    #                                 be passed onto the block supplied to the 
+    #                                 constructer. Optional.
+    #
+    # @raise  [SystemCallError]       It may raise a number of subclasses of SystemCallError 
+    #                                 in a child process if a sandbox violates imposed 
+    #                                 restrictions.   
+    #
+    # @raise  [Dia::SandboxException] It may raise 
+    #                                 {Dia::Exceptions::SandboxException}
+    #                                 in a child process if it was not possible
+    #                                 to initialize a sandbox environment. 
+    #
+    # @return [Fixnum]                The Process ID(PID) that the sandbox has
+    #                                 been launched under.
+    def run(*args)
+      launch(*args) 
+
+      # parent ..
+      _, @exit_status = Process.wait2(@pid)
+      @pid
+    end
+
+    # An identical, but non-blocking form of {#run}.
+    def run_nonblock(*args)  
+      launch(*args)
+
+      @exit_status = Process.detach(@pid)
+      @pid
+    end
+
+    private
+      # @api private
+      def launch(*args)
+        @e = @stdout = nil
+        close_pipes_if_needed
+        open_pipes_if_needed
+
+        @pid = fork do
+          redirect(:stdout) if @redirect_stdout
+          redirect(:stderr) if @redirect_stderr
+          if @rescue
+            begin
+              initialize_sandbox
+              @proc.call(*args)
+            rescue SystemExit, SignalException, NoMemoryError => e 
+              raise(e)
+            rescue Exception => e
+              begin     
+                write_exception(e) 
+              rescue SystemExit, SignalException, NoMemoryError => e
+                raise(e)
+              rescue Exception => e
+                write_exception(e)
+              end
+            ensure
+              write_stdout_and_stderr_if_needed
+              close_pipes_if_needed
+            end
+          else
+            begin
+              initialize_sandbox
+              @proc.call(*args)
+            ensure
+              write_stdout_and_stderr_if_needed
+              close_pipes_if_needed
+            end
+          end
+        end
+      end
+
+      # @api private
+      def write_stdout_and_stderr_if_needed
+        if @redirect_stdout
+          $stdout.rewind
+          @pipes[:stdout_reader].close
+          @pipes[:stdout_writer].write($stdout.read)
+          @pipes[:stdout_writer].close
+        end
+
+        if @redirect_stderr
+          $stderr.rewind
+          @pipes[:stderr_reader].close
+          @pipes[:stderr_writer].write($stderr.read)
+          @pipes[:stderr_writer].close
+        end
+      end
+
+      # @api private
+      def close_pipes_if_needed
+        @pipes.each do |key, pipe|
+          if !pipe.nil? && !pipe.closed?
+            pipe.close
+          end
+        end
+      end
+
+      # @api private
+      def open_pipes_if_needed
+        @pipes[:exception_reader], @pipes[:exception_writer] = IO.pipe if @rescue
+        @pipes[:stdout_reader]   , @pipes[:stdout_writer]    = IO.pipe if @redirect_stdout
+        @pipes[:stderr_reader]   , @pipes[:stderr_writer]    = IO.pipe if @redirect_stderr
+      end
+
+      # @api private
+      def write_exception(e)
+        @pipes[:exception_writer].write(Marshal.dump({ :klass     => e.class.to_s    ,
+                                    :backtrace => e.backtrace.join("\n"),
+                                    :message   => e.message.to_s }) )
+      end
+
+      # @api private
+      def pipes_readable?(reader, writer)
+        (reader && writer) && 
+        (!reader.closed? && !writer.closed?) && 
+        (reader.ready?)
+      end
+
+      # @api private
+      def redirect(symbol)
+        level    = $VERBOSE
+        $VERBOSE = nil
+        if symbol == :stdout 
+          $stdout  = StringIO.new
+          Object.const_set(:STDOUT, $stdout)
+        else
+          $stderr  = StringIO.new
+          Object.const_set(:STDERR, $stderr)
+        end
+        $VERBOSE = level
+      end
+    
+  end
+
+end