dia 1.4 → 1.5.pre

data/HACKING.md

@@ -1,7 +1,13 @@
+## Coding style
+* Abide by the "80 Column Rule" when it is practical.
+* methods should be identified by parenthesis all the time - foo(), bar(1,2,3).
+
 ## Git policy
+* "master" should always be in a _working state_.
+* Pre releases should never be merged into "master", but should live in
+  experimental instead.
+* The experimental branch is the _one and only_ gateway to being merged into
+  master .. and topic branches should branch off from "experimental".
+
+  
 
-* "master" should always be in a _working state_, so no experimental code ..
-* Pre releases should never be merged into "master", but should stay in experimental .. 
-* The experimental branch is the _one and only_ gateway to being merged into master ..  
-  So, if you're working on a feature, branch off from experimental, merge back into experimental, and when deemed stable experimental
-  will be merged into master ..

data/LICENSE

@@ -0,0 +1,22 @@
+ Copyright (c) 2010 Robert Gleeson   
+  
+ 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/NEWS.md

@@ -1,5 +1,11 @@
 ## NEWS
 
+### 1.5
+* Dia::Sandbox#running?, Dia::Sandbox#exit_status, and Dia::Sandbox#terminate will return nil if you call them before
+  calling Dia::Sandbox#run().
+* Added Dia::Sandbox#exit_status for collecting the exit status of a child process running under a sandbox.
+* Dia::Sandbox#run was not returning the PID of the process running under a sandbox like told in the documentation - it is now.
+
 ### 1.4
 * A typo broke support for launching applications in a sandbox. (Bug affects 1.3 and all the 1.4 *pre* releases)
 * Mac OSX 10.5 reported as working! (Bug fix)  
@@ -28,16 +34,12 @@
 
 ### 1.1 (final)
 * Dia::SandBox#run\_with\_block will exit the child process spawned by itself incase the user forgets to ..
-
 * Added some tests for Dia::Sandbox.new#run\_with\_block ..  
   We ain't got full coverage but we're getting there.
-  
 * A person reported that ffi 0.6.0 does not work with dia ..  
   Supplied an explicit dependency on ffi 0.5.4 until I figure it out.
-    
 * You can run a block of ruby under a sandbox now but I had to change the order of arguments in the constructer ..  
   First argument is the profile, and (optionally) the second is the application path.  
   If you're running a block of ruby, you can forget about the second.
-  
 * I documented my methods!
 

data/README.md

@@ -1,21 +1,39 @@
 ## "Dia"
 
-"Dia" allows you to sandbox an application or block of ruby on the OSX platform by restricting what access to Operating System resources they can have.  
+"Dia" allows you to sandbox an application or block of ruby on the OSX platform by restricting what access to 
+Operating System resources they can have.  
+
+## How it is done
+It uses the FFI library, and the features exposed by the sandbox header on OSX.
 
 ## What restrictions can you apply?  
 
-* No internet access.
-* No network access of any kind.
-* No file system writes.
-* No file system writes, exlcuding writing to /tmp.
-* A complete lockdown of Operating System resources.
+Restrictions are applied through a "Profile" that is the first argument to `Dia::Sandbox.new`.  
+There are five profiles in total that you can choose from out-of-the-box:
 
-## How it is done
-It uses the FFI library, and the features exposed by the sandbox header on OSX.
+* No internet access  
+  Using the profile Dia::Profiles::NO_INTERNET.
+
+* No network access of any kind  
+  Using the profile Dia::Profiles::NO_NETWORKING.
+
+* No file system writes  
+  Using the profile Dia::Profiles::NO_FILESYSTEM_WRITE.
+
+* No file system writes, excluding writing to /tmp  
+  Using the profile Dia::Profiles::NO_FILESYSTEM_WRITE_EXCEPT_TMP.
+  
+* No OS services at all(No internet, No Networking, No File I/O)  
+  Using the profile Dia::Profiles::NO_OS_SERVICES.
+
+_See Below_ for examples.
 
 ## Examples
 
-### Example 1 (Running an application under a sandbox)
+**Running FireFox under a sandbox**
+
+This example demonstrates how you would sandbox an application, in this example, 'FireFox'.  
+If you try this example yourself, you will see that FireFox cannot visit any websites on the internet.
 
     require 'rubygems'
     require 'dia'
@@ -24,19 +42,28 @@ It uses the FFI library, and the features exposed by the sandbox header on OSX.
     sandbox.run
     puts "Launched #{sandbox.app} with a pid of #{sandbox.pid} using the profile #{sandbox.profile}"
 
-### Example 2 (Running ruby under a sandbox)
+**Running Ruby under a sandbox**
+
+This example demonstrates how you would sandbox a block of ruby code.  
+In this example, the block of ruby code tries to access the internet but the profile(Dia::Profiles::NO_INTERNET) doesn't 
+allow this block of ruby to contact the internet and an exception is raised(in a child process - your app will continute to
+execute normally).
 
     require 'rubygems'
     require 'dia'
     require 'net/http'
     require 'open-uri'
     
-    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
       open(URI.parse('http://www.google.com')).read
     end
     sandbox.run
     
-### Example 3 (Terminating a sandbox)
+**Terminating a sandbox**
+
+Sometimes we might want to stop a sandbox from running any longer. `Dia::Sandbox#terminate` is provided to 
+terminate a sandbox - in this example, FireFox is running under a sandboxed environment and terminated after 
+running for 5 seconds.
 
     require 'rubygems'
     require 'dia'
@@ -45,7 +72,9 @@ It uses the FFI library, and the features exposed by the sandbox header on OSX.
     sleep(5)
     sandbox.terminate
     
-### Example 4 (Checking if a sandbox is running)
+**Checking if a sandbox is alive**
+
+If you need to check if a sandbox you have spawned is still running, you can use the `Dia::Sandbox#running?` method.
 
     require 'rubygems'
     require 'dia'
@@ -56,33 +85,25 @@ It uses the FFI library, and the features exposed by the sandbox header on OSX.
     sandbox.run
     puts sandbox.running? # => true
 
+
+.. Please see the yardoc [documentation](http://yardoc.org/docs/robgleeson-Dia) for more in-depth coverage of these methods, 
+in particular the documentation for the `Dia::Sandbox` class.
+
 ## Install
 
 It's available at gemcutter: 
 
-    gem install dia
+`gem install dia`
 
-## License(MIT)
+## Bugs
+
+No known bugs right now. [Found a bug?](http://github.com/robgleeson/dia/issues).
+
+## Contact
+
+* IRC  
+  irc.freenode.net/#flowof.info as 'robgleeson'
+
+* Mail  
+  rob [at] flowof.info
 
- Copyright (c) 2010 Robert Gleeson   
-  
- 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/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.4'
+  VERSION = '1.5.pre'
   class SandboxException < StandardError; end
 end
 

data/lib/dia/commonapi.rb

@@ -1,6 +1,3 @@
-require 'rubygems'
-require 'ffi'
-
 module Dia
   module CommonAPI
     extend FFI::Library

data/lib/dia/profiles.rb

@@ -4,13 +4,18 @@ module Dia
     extend FFI::Library
     ffi_lib(%w(sandbox system libSystem.B.dylib))
     
-    NO_INTERNET                    = attach_variable(:kSBXProfileNoInternet, :string).read_string
-    NO_NETWORKING                  = attach_variable(:kSBXProfileNoNetwork, :string).read_string
-    NO_FILESYSTEM_WRITE            = attach_variable(:kSBXProfileNoWrite, :string).read_string
-    NO_FILESYSTEM_WRITE_EXCEPT_TMP = attach_variable(:kSBXProfileNoWriteExceptTemporary, :string).read_string
-    NO_OS_SERVICES                 = attach_variable(:kSBXProfilePureComputation, :string).read_string
+    NO_INTERNET                    = attach_variable(:kSBXProfileNoInternet,
+                                                     :string).read_string
+    NO_NETWORKING                  = attach_variable(:kSBXProfileNoNetwork,
+                                                      :string).read_string
+    NO_FILESYSTEM_WRITE            = attach_variable(:kSBXProfileNoWrite, 
+                                                     :string).read_string
+    NO_FILESYSTEM_WRITE_EXCEPT_TMP = attach_variable(:kSBXProfileNoWriteExceptTemporary,
+                                                     :string).read_string
+    NO_OS_SERVICES                 = attach_variable(:kSBXProfilePureComputation,
+                                                     :string).read_string
     
   end
   
 end
-    
+    

data/lib/dia/sandbox.rb

@@ -9,7 +9,8 @@ module Dia
     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.  
+    # The constructer accepts a profile as the first parameter, and an 
+    # application path _or_ block as its second parameter.  
     #
     # @example
     #
@@ -25,10 +26,16 @@ module Dia
     #
     # @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  [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.   
+    # @param  [Constant]     Profile      The profile to be used when creating a
+    #                                     sandbox.
+    #
+    # @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
     
@@ -43,21 +50,36 @@ module Dia
       @pid      = nil
     end
     
-    # The run method will spawn a child process and run the application _or_ block supplied to the constructer under a sandbox.  
+    # The run method will spawn a child process and run the application _or_
+    # block supplied to the constructer under a sandbox.  
     # This method will not block.
     #
-    # @param  [Arguments]             A variable amount of arguments that will be passed onto the block supplied to the constructer. 
+    # @param  [Arguments] Arguments   A variable amount of arguments that will 
+    #                                 be passed onto the block supplied to the 
+    #                                 constructer. Optional.
+    #
+    # @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  [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.
     #
-    # @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.
+    # @return [Fixnum]                The Process ID(PID) that the sandboxed 
+    #                                 application is being run under.
     def run(*args)
-      
       @pid = fork do
-        if sandbox_init(FFI::MemoryPointer.from_string(@profile), 0x0001, err = FFI::MemoryPointer.new(:pointer)) == -1
-          raise Dia::SandboxException, "Failed to initialize sandbox (#{err.read_pointer.read_string})"
+        if sandbox_init(FFI::MemoryPointer.from_string(@profile), 
+                        0x0001, 
+                        err = FFI::MemoryPointer.new(:pointer)) == -1
+
+          raise(Dia::SandboxException, "Failed to initialize sandbox" /
+                                       "(#{err.read_pointer.read_string})")
         end
         
         if @app
@@ -68,31 +90,57 @@ module Dia
       end
       
       # parent ..
-      Process.detach(@pid)
+      @thr = Process.detach(@pid)
+      @pid
     end
-    
+   
+    # The exit_status method will return the exit status of the child process 
+    # running in a sandbox.  
+    # This method *will* block until the child process exits.
+    #
+    # @return [Fixnum, nil] Returns the exit status of the process that ran
+    #                       under a sandbox.
+    #                       Returns nil if Dia::Sandbox#run has not 
+    #                       been called yet, or if the process stopped
+    #                       abnormally(ie: through SIGKILL, or #terminate). 
+    def exit_status()
+      @thr.value().exitstatus() unless @thr.nil?
+    end
+
     # The terminate method will send SIGKILL to a process running in a sandbox.
     # By doing so, it effectively terminates the sandbox.
     #
-    # @raise  [SystemCallError] It may raise a number of subclasses of SystemCallError if a call to Process.kill was unsuccessful ..
-    # @return [Fixnum]          It will return 1 when successful ..
-    def terminate
-      Process.kill('SIGKILL', @pid)
+    # @raise  [SystemCallError] It may raise a number of subclasses of 
+    #                           SystemCallError if a call to Process.kill 
+    #                           was unsuccessful ..
+    #
+    # @return [Fixnum, nil]     It will return 1 when successful, and 
+    #                           it will return "nil" if Dia::Sandbox#run() 
+    #                           has not been called yet. 
+    def terminate()
+      Process.kill('SIGKILL', @pid) unless @pid.nil?
     end
     
-    # The running? method will return true if a sandbox is running, and false otherwise.
-    # It does so by sending a signal to the process running a sandbox.
+    # The running? method will return true if a sandbox is running, 
+    # and false otherwise.  
     #
-    # @raise  [SystemCallError] It may raise a subclass of SystemCallError if you do not have permission to send a signal
+    # @raise  [SystemCallError] It may raise a subclass of SystemCallError if 
+    #                           you do not have permission to send a signal
     #                           to the process running in a sandbox.
     #
-    # @return [Boolean]         It will return true or false.
-    def running?
-      begin
-        Process.kill(0, @pid)
-        true
-      rescue Errno::ESRCH
-        false
+    # @return [Boolean,nil]     It will return true or false if the sandbox 
+    #                           is running or not, and it will return "nil"
+    #                           if Dia::Sandbox#run has not been called yet.
+    def running?()
+      if @pid.nil?
+        nil
+      else
+        begin
+          Process.kill(0, @pid)
+          true
+        rescue Errno::ESRCH
+          false
+        end
       end
     end
     

data/test/suite/check_if_sandbox_is_alive_test.rb

@@ -19,5 +19,11 @@ BareTest.suite "Dia::Sandbox#running?", :tags => [ :running? ] do
     sleep(1)
     equal(false, sandbox.running?)
   end
-  
-end
+ 
+  assert("nil will be returned if Dia::Sandbox#run hasn't been called before a call to #running?()") do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
+      # ...
+    end
+    equal(nil, sandbox.running?)
+  end
+end

data/test/suite/exit_status_test.rb

@@ -0,0 +1,16 @@
+BareTest.suite('Dia::Sandbox#exit_status') do
+  assert('The exit status of a child process running under a sandbox is returned.') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
+      exit(10)
+    end
+    sandbox.run
+    equal(10, sandbox.exit_status)
+  end
+
+  assert("nil will be returned if Dia::Sandbox#run hasn't been called before a call to #exit_status") do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
+    end
+    equal(nil, sandbox.exit_status)
+  end
+
+end

data/test/suite/run_block_in_sandbox_test.rb

@@ -123,4 +123,10 @@ BareTest.suite 'Dia::Sandbox#run', :tags => [ :run ] do
     equal('foobar', answer)
   end
 
-end
+  assert('A Ruby block will return the PID of the spawned child process after executing #run') do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
+      # ...
+    end
+    equal(Fixnum, sandbox.run.class)
+  end
+end

data/test/suite/terminate_sandbox_test.rb

@@ -18,4 +18,12 @@ BareTest.suite 'Dia::Sandbox#terminate', :tags => [ :terminate ] do
     
   end
   
-end
+  assert("nil will be returned if Dia::Sandbox#run hasn't been called before a call to #terminate") do
+    sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET) do
+      # ...
+    end
+
+    equal(nil, sandbox.terminate)
+  end
+
+end

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: dia
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  prerelease: true
   segments: 
   - 1
-  - 4
-  version: "1.4"
+  - 5
+  - pre
+  version: 1.5.pre
 platform: ruby
 authors: 
 - Robert Gleeson
@@ -13,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-27 00:00:00 +00:00
+date: 2010-05-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -56,7 +57,10 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id003
-description: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
+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: []
 
@@ -74,11 +78,12 @@ files:
 - lib/dia/sandbox.rb
 - lib/dia.rb
 - .yardopts
+- LICENSE
 has_rdoc: yard
 homepage: 
 licenses: []
 
-post_install_message: "  ********************************************************************\n  Dia (1.4)\n  \n  * A typo that would result in being unable to launch an application\n    under a sandbox has been fixed (1.3 and 1.4.pre were affected)\n    \n  * The Mac OSX 10.5 bug has been reported as fixed! \n    Many thanks to \"Josh Creek\" for reporting, and helping me debug the\n    problem until we solved it.\n  ********************************************************************\n"
+post_install_message: "  ********************************************************************\n  Dia (1.5.pre)\n  \n  Thanks for installing Dia, 1.5.pre! \n  \n  Keep up with the latest @ GitHub:\n  http://github.com/robgleeson/dia\n  ********************************************************************\n"
 rdoc_options: []
 
 require_paths: 
@@ -92,21 +97,24 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: 
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
+summary: Dia allows you to sandbox application(s) or block(s) of rubyon the OSX platform by restricting access to operating systemresources
 test_files: 
 - test/setup.rb
 - test/suite/check_if_sandbox_is_alive_test.rb
+- test/suite/exit_status_test.rb
 - test/suite/passing_parameters_to_constructer_test.rb
 - test/suite/run_block_in_sandbox_test.rb
 - test/suite/terminate_sandbox_test.rb