dia 1.2 → 1.3.pre

data/.yardopts

@@ -0,0 +1,2 @@
+-m markdown
+

data/NEWS.md

@@ -1,4 +1,14 @@
 ## NEWS
+
+### 1.3
+* Dia::Sandbox only exposes its instance variables through getters now. No more setters.
+* Dia::Sandbox#app_path is now Dia::Sandbox#app
+* Removed run\_with\_block in favor of passing a block to the constructer. Dia::Sandbox#run is used to execute a block or an application now, 
+  but only one or the other may be supplied to the constructer.
+* Removed Dia::SandBox in favor of Dia::Sandbox.
+* Added "has_rdoc = 'yard'" to the gem spec.
+* Added ".yardopts" to the list of files in the gem spec.
+
 ### 1.2
 * I've decided to use Dia::Sandbox instead of Dia::SandBox but it won't be removed until 1.3 .. (Deprecated for 1.2)
 * I've decided to remove the explicit exit() call in a sandbox spawned with run\_with\_block .. (Introduced in 1.1 Final)

data/README.md

@@ -10,41 +10,43 @@
 * No file system writes, exlcuding writing to /tmp.
 * A complete lockdown of Operating System resources.
 
-## How?
+## How it is done
 FFI, and the C header "sandbox.h" (found on OSX).
 
-## Example 1 (Running an application under a sandbox)
+## Examples
+
+### Example 1 (Running an application under a sandbox)
 
     require 'rubygems'
     require 'dia'
 
-    sandbox = Dia::Sandbox.new("/Applications/Firefox.app/Contents/MacOS/firefox-bin", Dia::Profiles::NO_INTERNET)
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET, "/Applications/Firefox.app/Contents/MacOS/firefox-bin")
     sandbox.run
-    puts "Launched #{sandbox.app_path} with a pid of #{sandbox.pid} using the profile #{sandbox.profile}"
+    puts "Launched #{sandbox.app} with a pid of #{sandbox.pid} using the profile #{sandbox.profile}"
 
-## Example 2 (Running ruby under a sandbox)
+### Example 2 (Running ruby under a sandbox)
 
     require 'rubygems'
     require 'dia'
     require 'open-uri'
     
-    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES)
-    sandbox.run_with_block do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
       open(URI.parse('http://www.google.com')).read
     end
+    sandbox.run
     
-## Example 3 (Terminating a sandbox)
+### Example 3 (Terminating a sandbox)
 
     require 'rubygems'
     require 'dia'
-    sandbox = Dia::Sandbox.new("/Applications/Firefox.app/Contents/MacOS/firefox-bin", Dia::Profiles::NO_INTERNET)
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET, "/Applications/Firefox.app/Contents/MacOS/firefox-bin")
     sandbox.run
     sleep(5)
     sandbox.terminate
     
-## Install?
+## Install
 
-It's on gemcutter.  
+It's available at gemcutter: 
 
     gem install dia
 

data/TODO.md

@@ -1,4 +1,4 @@
 ## TODO
 
 ### 1.3
-* Deprecate and remove Dia::SandBox in favor of Dia::Sandbox ..
+* Remove link to experimental branch in gemspec before release

data/lib/dia/sandbox.rb

@@ -1,59 +1,68 @@
 module Dia
   
-  class SandBox
+  class Sandbox
   
     include Dia::CommonAPI
     
-    # We're going to deprecate Dia::SandBox in favor of Dia::Sandbox in the next release.
-    Dia::Sandbox = SandBox
-    
-    attr_accessor :app_path
-    attr_accessor :profile
-    attr_accessor :pid
+    attr_reader :app
+    attr_reader :profile
+    attr_reader :pid
+    attr_reader :blk
     
+    # The constructer accepts a profile as the first parameter, and an application path _or_ block as its second parameter.  
+    #
+    # @example
+    #
+    #     # Passing an application to the constructer ..
+    #     sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES, 'ping google.com')
+    #     
+    #     # Passing a block to the constructer ..
+    #     sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+    #       File.open('foo.txt', 'w') do |f|
+    #         f.puts "bar"
+    #       end
+    #     end
+    #
+    # @see Dia::Sandbox#run See Dia::Sandbox#run for executing the sandbox.
+    #
     # @param  [Constant]     Profile      The profile to be used when creating a sandbox.
-    # @param  [String]       Application  The path to an application you want to sandbox. Optional.
+    # @param  [Proc]         Proc         A proc object you want to run under a sandbox.   
+    #                                     Omit the "Application" parameter if passed.
+    # @param  [String]       Application  The path to an application you want to run under a sandbox.   
+    #                                     Omit the "Proc" parameter if passed.
     # @return [Dia::SandBox] Returns an instance of Dia::SandBox
-    def initialize(profile = Dia::Profiles::NO_OS_SERVICES, app_path=nil)
-      @app_path = app_path
-      @profile = profile
-    end
     
-    # The run method will spawn a child process and run the application supplied in the constructer under a sandbox.
-    #  
-    # @raise  [ArgumentError]         Will raise an ArgumentError if an application has not been supplied to 
-    #                                 the constructer.
-    # @raise  [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated.
-    # @return [Fixnum] The Process ID(PID) that the sandboxed application is being run under.
-    def run
-      raise ArgumentError, "No application path supplied"  if @app_path.nil?
-      
-      @pid = fork do
-        if ( ret = sandbox_init(@profile, 0x0001, error = FFI::MemoryPointer.new(:pointer)) ) != 0
-          raise Dia::SandBoxException, "Couldn't sandbox #{@app_path}, sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
-        end
-        exec(@app_path)
+    def initialize(profile, app=nil, &blk)
+      if (app && blk) || (app.nil? && blk.nil?) 
+        raise ArgumentError, 'Application or Proc object expected'
       end
       
-      # parent ..
-      Process.detach(@pid)
+      @app      = app
+      @blk      = blk
+      @profile  = profile
+      @pid      = nil
     end
-  
-    # The run\_with\_block method will spawn a child process and run a supplied block of ruby code in a sandbox.
+    
+    # The run method will spawn a child process and run the application _or_ block supplied in the constructer under a sandbox.  
+    # This method will not block.
     #
-    # It may raise any number of exceptions if the sandbox could be initiated ..
-    # It depends on the restrictions of the sandbox and if the block violates a restriction imposed by
-    # the sandbox .. In any case, the parent process will not be affected and if you want to catch an exception you
-    # should do so in your block.
+    # @raise  [SystemCallError]       In the case of running a block, a number of subclasses of SystemCallError may be raised if the block violates sandbox restrictions.
+    #                                 The parent process will not be affected and if you wish to catch exceptions you should do so in your block.
     #
-    # @raise  [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated. 
-    # @return [Fixnum] The Process ID(PID) that the sandboxed block of code is being run under.
-    def run_with_block &blk
+    # @raise  [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated.
+    # @return [Fixnum]                The Process ID(PID) that the sandboxed application is being run under.
+    def run
+      
       @pid = fork do
         if ( ret = sandbox_init(@profile, 0x0001, error = FFI::MemoryPointer.new(:pointer)) ) != 0
-          raise Dia::SandBoxException, "Unable to initialize sandbox .. sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
+          raise Dia::SandBoxException, "Couldn't sandbox #{@app}, sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
+        end
+        
+        if @app_path
+          exec(@app_path)
+        else
+          @blk.call
         end
-        yield
       end
       
       # parent ..

data/lib/dia.rb

@@ -5,7 +5,7 @@ require File.join(File.dirname(__FILE__), 'dia/commonapi.rb')
 require File.join(File.dirname(__FILE__), 'dia/sandbox.rb')
 
 module Dia
-  VERSION = '1.2'
+  VERSION = '1.3.pre'
   class SandBoxException < StandardError; end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dia
 version: !ruby/object:Gem::Version 
-  version: "1.2"
+  version: 1.3.pre
 platform: ruby
 authors: 
 - Robert Gleeson
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-20 00:00:00 +00:00
+date: 2010-02-21 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,7 +32,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.2.4
     version: 
-description: Dia allows you to sandbox applications and/or a block of ruby on the OSX platform
+description: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
 email: rob@flowof.info
 executables: []
 
@@ -49,11 +49,12 @@ files:
 - lib/dia/profiles.rb
 - lib/dia/sandbox.rb
 - lib/dia.rb
-has_rdoc: true
+- .yardopts
+has_rdoc: yard
 homepage: 
 licenses: []
 
-post_install_message: "  ********************************************************************\n  Thanks for installing Dia! (1.2)\n  \n  Don't forget to check NEWS.md for what has changed in this release:\n  http://github.com/robgleeson/Dia/blob/master/NEWS.md\n  \n  You can chat with us at irc.freenode.net / #flowof.info if you have\n  any problems. Feel free to join us!\n  ********************************************************************\n"
+post_install_message: "  ********************************************************************\n  Thanks for installing Dia! (1.3.pre)\n  \n  Don't forget to check NEWS.md for what has changed in this release:\n  http://github.com/robgleeson/Dia/blob/experimental/NEWS.md\n  \n  You can chat with us at irc.freenode.net / #flowof.info if you have\n  any problems. Feel free to join us!\n  ********************************************************************\n"
 rdoc_options: []
 
 require_paths: 
@@ -66,9 +67,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
   version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: 1.3.1
   version: 
 requirements: []
 
@@ -76,6 +77,6 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Dia allows you to sandbox applications and/or a block of ruby on the OSX platform
+summary: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
 test_files: []