dia 1.2 → 1.3.pre

Sign up to get free protection for your applications and to get access to all the features.
Files changed (7) hide show
  1. data/.yardopts +2 -0
  2. data/NEWS.md +10 -0
  3. data/README.md +13 -11
  4. data/TODO.md +1 -1
  5. data/lib/dia/sandbox.rb +48 -39
  6. data/lib/dia.rb +1 -1
  7. metadata +9 -8
data/.yardopts ADDED
@@ -0,0 +1,2 @@
1
+ -m markdown
2
+
data/NEWS.md CHANGED
@@ -1,4 +1,14 @@
1
1
  ## NEWS
2
+
3
+ ### 1.3
4
+ * Dia::Sandbox only exposes its instance variables through getters now. No more setters.
5
+ * Dia::Sandbox#app_path is now Dia::Sandbox#app
6
+ * 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,
7
+ but only one or the other may be supplied to the constructer.
8
+ * Removed Dia::SandBox in favor of Dia::Sandbox.
9
+ * Added "has_rdoc = 'yard'" to the gem spec.
10
+ * Added ".yardopts" to the list of files in the gem spec.
11
+
2
12
  ### 1.2
3
13
  * I've decided to use Dia::Sandbox instead of Dia::SandBox but it won't be removed until 1.3 .. (Deprecated for 1.2)
4
14
  * 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 CHANGED
@@ -10,41 +10,43 @@
10
10
  * No file system writes, exlcuding writing to /tmp.
11
11
  * A complete lockdown of Operating System resources.
12
12
 
13
- ## How?
13
+ ## How it is done
14
14
  FFI, and the C header "sandbox.h" (found on OSX).
15
15
 
16
- ## Example 1 (Running an application under a sandbox)
16
+ ## Examples
17
+
18
+ ### Example 1 (Running an application under a sandbox)
17
19
 
18
20
  require 'rubygems'
19
21
  require 'dia'
20
22
 
21
- sandbox = Dia::Sandbox.new("/Applications/Firefox.app/Contents/MacOS/firefox-bin", Dia::Profiles::NO_INTERNET)
23
+ sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET, "/Applications/Firefox.app/Contents/MacOS/firefox-bin")
22
24
  sandbox.run
23
- puts "Launched #{sandbox.app_path} with a pid of #{sandbox.pid} using the profile #{sandbox.profile}"
25
+ puts "Launched #{sandbox.app} with a pid of #{sandbox.pid} using the profile #{sandbox.profile}"
24
26
 
25
- ## Example 2 (Running ruby under a sandbox)
27
+ ### Example 2 (Running ruby under a sandbox)
26
28
 
27
29
  require 'rubygems'
28
30
  require 'dia'
29
31
  require 'open-uri'
30
32
 
31
- sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES)
32
- sandbox.run_with_block do
33
+ sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
33
34
  open(URI.parse('http://www.google.com')).read
34
35
  end
36
+ sandbox.run
35
37
 
36
- ## Example 3 (Terminating a sandbox)
38
+ ### Example 3 (Terminating a sandbox)
37
39
 
38
40
  require 'rubygems'
39
41
  require 'dia'
40
- sandbox = Dia::Sandbox.new("/Applications/Firefox.app/Contents/MacOS/firefox-bin", Dia::Profiles::NO_INTERNET)
42
+ sandbox = Dia::Sandbox.new(Dia::Profiles::NO_INTERNET, "/Applications/Firefox.app/Contents/MacOS/firefox-bin")
41
43
  sandbox.run
42
44
  sleep(5)
43
45
  sandbox.terminate
44
46
 
45
- ## Install?
47
+ ## Install
46
48
 
47
- It's on gemcutter.
49
+ It's available at gemcutter:
48
50
 
49
51
  gem install dia
50
52
 
data/TODO.md CHANGED
@@ -1,4 +1,4 @@
1
1
  ## TODO
2
2
 
3
3
  ### 1.3
4
- * Deprecate and remove Dia::SandBox in favor of Dia::Sandbox ..
4
+ * Remove link to experimental branch in gemspec before release
data/lib/dia/sandbox.rb CHANGED
@@ -1,59 +1,68 @@
1
1
  module Dia
2
2
 
3
- class SandBox
3
+ class Sandbox
4
4
 
5
5
  include Dia::CommonAPI
6
6
 
7
- # We're going to deprecate Dia::SandBox in favor of Dia::Sandbox in the next release.
8
- Dia::Sandbox = SandBox
9
-
10
- attr_accessor :app_path
11
- attr_accessor :profile
12
- attr_accessor :pid
7
+ attr_reader :app
8
+ attr_reader :profile
9
+ attr_reader :pid
10
+ attr_reader :blk
13
11
 
12
+ # The constructer accepts a profile as the first parameter, and an application path _or_ block as its second parameter.
13
+ #
14
+ # @example
15
+ #
16
+ # # Passing an application to the constructer ..
17
+ # sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES, 'ping google.com')
18
+ #
19
+ # # Passing a block to the constructer ..
20
+ # sandbox = Dia::Sandbox.new(Dia::Profiles::NO_OS_SERVICES) do
21
+ # File.open('foo.txt', 'w') do |f|
22
+ # f.puts "bar"
23
+ # end
24
+ # end
25
+ #
26
+ # @see Dia::Sandbox#run See Dia::Sandbox#run for executing the sandbox.
27
+ #
14
28
  # @param [Constant] Profile The profile to be used when creating a sandbox.
15
- # @param [String] Application The path to an application you want to sandbox. Optional.
29
+ # @param [Proc] Proc A proc object you want to run under a sandbox.
30
+ # Omit the "Application" parameter if passed.
31
+ # @param [String] Application The path to an application you want to run under a sandbox.
32
+ # Omit the "Proc" parameter if passed.
16
33
  # @return [Dia::SandBox] Returns an instance of Dia::SandBox
17
- def initialize(profile = Dia::Profiles::NO_OS_SERVICES, app_path=nil)
18
- @app_path = app_path
19
- @profile = profile
20
- end
21
34
 
22
- # The run method will spawn a child process and run the application supplied in the constructer under a sandbox.
23
- #
24
- # @raise [ArgumentError] Will raise an ArgumentError if an application has not been supplied to
25
- # the constructer.
26
- # @raise [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated.
27
- # @return [Fixnum] The Process ID(PID) that the sandboxed application is being run under.
28
- def run
29
- raise ArgumentError, "No application path supplied" if @app_path.nil?
30
-
31
- @pid = fork do
32
- if ( ret = sandbox_init(@profile, 0x0001, error = FFI::MemoryPointer.new(:pointer)) ) != 0
33
- raise Dia::SandBoxException, "Couldn't sandbox #{@app_path}, sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
34
- end
35
- exec(@app_path)
35
+ def initialize(profile, app=nil, &blk)
36
+ if (app && blk) || (app.nil? && blk.nil?)
37
+ raise ArgumentError, 'Application or Proc object expected'
36
38
  end
37
39
 
38
- # parent ..
39
- Process.detach(@pid)
40
+ @app = app
41
+ @blk = blk
42
+ @profile = profile
43
+ @pid = nil
40
44
  end
41
-
42
- # The run\_with\_block method will spawn a child process and run a supplied block of ruby code in a sandbox.
45
+
46
+ # The run method will spawn a child process and run the application _or_ block supplied in the constructer under a sandbox.
47
+ # This method will not block.
43
48
  #
44
- # It may raise any number of exceptions if the sandbox could be initiated ..
45
- # It depends on the restrictions of the sandbox and if the block violates a restriction imposed by
46
- # the sandbox .. In any case, the parent process will not be affected and if you want to catch an exception you
47
- # should do so in your block.
49
+ # @raise [SystemCallError] In the case of running a block, a number of subclasses of SystemCallError may be raised if the block violates sandbox restrictions.
50
+ # The parent process will not be affected and if you wish to catch exceptions you should do so in your block.
48
51
  #
49
- # @raise [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated.
50
- # @return [Fixnum] The Process ID(PID) that the sandboxed block of code is being run under.
51
- def run_with_block &blk
52
+ # @raise [Dia::SandBoxException] Will raise Dia::SandBoxException in a child process and exit if the sandbox could not be initiated.
53
+ # @return [Fixnum] The Process ID(PID) that the sandboxed application is being run under.
54
+ def run
55
+
52
56
  @pid = fork do
53
57
  if ( ret = sandbox_init(@profile, 0x0001, error = FFI::MemoryPointer.new(:pointer)) ) != 0
54
- raise Dia::SandBoxException, "Unable to initialize sandbox .. sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
58
+ raise Dia::SandBoxException, "Couldn't sandbox #{@app}, sandbox_init returned #{ret} with error message: '#{error.get_pointer(0).read_string}'"
59
+ end
60
+
61
+ if @app_path
62
+ exec(@app_path)
63
+ else
64
+ @blk.call
55
65
  end
56
- yield
57
66
  end
58
67
 
59
68
  # parent ..
data/lib/dia.rb CHANGED
@@ -5,7 +5,7 @@ require File.join(File.dirname(__FILE__), 'dia/commonapi.rb')
5
5
  require File.join(File.dirname(__FILE__), 'dia/sandbox.rb')
6
6
 
7
7
  module Dia
8
- VERSION = '1.2'
8
+ VERSION = '1.3.pre'
9
9
  class SandBoxException < StandardError; end
10
10
  end
11
11
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: dia
3
3
  version: !ruby/object:Gem::Version
4
- version: "1.2"
4
+ version: 1.3.pre
5
5
  platform: ruby
6
6
  authors:
7
7
  - Robert Gleeson
@@ -9,7 +9,7 @@ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
11
 
12
- date: 2010-02-20 00:00:00 +00:00
12
+ date: 2010-02-21 00:00:00 +00:00
13
13
  default_executable:
14
14
  dependencies:
15
15
  - !ruby/object:Gem::Dependency
@@ -32,7 +32,7 @@ dependencies:
32
32
  - !ruby/object:Gem::Version
33
33
  version: 0.2.4
34
34
  version:
35
- description: Dia allows you to sandbox applications and/or a block of ruby on the OSX platform
35
+ description: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
36
36
  email: rob@flowof.info
37
37
  executables: []
38
38
 
@@ -49,11 +49,12 @@ files:
49
49
  - lib/dia/profiles.rb
50
50
  - lib/dia/sandbox.rb
51
51
  - lib/dia.rb
52
- has_rdoc: true
52
+ - .yardopts
53
+ has_rdoc: yard
53
54
  homepage:
54
55
  licenses: []
55
56
 
56
- 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"
57
+ 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"
57
58
  rdoc_options: []
58
59
 
59
60
  require_paths:
@@ -66,9 +67,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
66
67
  version:
67
68
  required_rubygems_version: !ruby/object:Gem::Requirement
68
69
  requirements:
69
- - - ">="
70
+ - - ">"
70
71
  - !ruby/object:Gem::Version
71
- version: "0"
72
+ version: 1.3.1
72
73
  version:
73
74
  requirements: []
74
75
 
@@ -76,6 +77,6 @@ rubyforge_project:
76
77
  rubygems_version: 1.3.5
77
78
  signing_key:
78
79
  specification_version: 3
79
- summary: Dia allows you to sandbox applications and/or a block of ruby on the OSX platform
80
+ summary: Dia allows you to sandbox application(s) or block(s) of ruby on the OSX platform by restricting access to operating system resources
80
81
  test_files: []
81
82