Class: Dia::RubyBlock

Inherits:
Object
  • Object
show all
Includes:
SharedFeatures
Defined in:
lib/dia/ruby_block.rb

Overview

The RubyBlock class provides an interface for executing a block of ruby code in a sandbox.

Instance Attribute Summary collapse

Attributes included from SharedFeatures

#pid

Instance Method Summary collapse

Methods included from SharedFeatures

#exit_status, #running?, #terminate

Constructor Details

#initialize(profile, &block) ⇒ Dia::RubyBlock

Returns an instance of Dia::RubyBlock.

Parameters:

  • Profile (String) —

    Accepts one of five profiles which can be found under the Profiles module.

  • Block (Proc) —

    Accepts a block or Proc object as its second argument.

Raises:

  • (ArgumentError) —

    It will raise an ArgumentError if a profile and block isn’t supplied to the constructor



98
99
100
101
102
103
104
105
106
107
 
# File 'lib/dia/ruby_block.rb', line 98

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_exception          = false
  @redirect_stdout = false
  @redirect_stderr = false
  @pipes           = {}
end

Instance Attribute Details

#exception ⇒ Dia::ExceptionStruct? (readonly) Also known as: e

Provides access to the data of an exception object that has been rescued in the process that was last used to execute a sandbox. This feature is disabled by default.

Returns:

  • (Dia::ExceptionStruct) —

    Returns an instance of ExceptionStruct when an exception has been rescued.

  • (nil) —

    Returns nil when there is no exception available.

  • (nil) —

    Returns nil if Dia was not set to rescue exceptions before a call to #run or #run_nonblock.

See Also:

Since:

  • 1.5



267
268
269
 
# File 'lib/dia/ruby_block.rb', line 267

def exception
  @exception
end

#redirect_stderr=(boolean) ⇒ void #redirect_stderr ⇒ Object, Boolean

Overloads:



37
38
39
 
# File 'lib/dia/ruby_block.rb', line 37

def redirect_stderr
  @redirect_stderr
end

#redirect_stdout=(boolean) ⇒ void #redirect_stdout ⇒ Object, Boolean

Overloads:



62
63
64
 
# File 'lib/dia/ruby_block.rb', line 62

def redirect_stdout
  @redirect_stdout
end

#rescue_exception= ⇒ void #rescue_exception ⇒ Object, Boolean

Overloads:

  • #rescue_exception= ⇒ void

    This method returns an undefined value.

    This method can enable or disable a feature that will try to rescue exceptions that are raised in the process that is spawned to execute a sandbox.

    Parameters:

    • Enable (Boolean) —

      Passing true will enable the capture of exceptions.

    • Disable (Boolean) —

      Passing false will disable the capture of exceptions.

    See Also:

    Since:

    • 2.0.0

  • #rescue_exception ⇒ Object, Boolean

    This method provides access to the object passed to #rescue_exception=

    Returns:

    See Also:



87
88
89
 
# File 'lib/dia/ruby_block.rb', line 87

def rescue_exception
  @rescue_exception
end

#stderr ⇒ String? (readonly)

Provides access to the Standard Error stream of the process that was last used to execute a sandbox. This feature is disabled by default.

Returns:

  • (String) —

    Returns the contents of stderr as a String.

  • (nil) —

    Returns nil when no data is available on stderr.

  • (nil) —

    Returns nil if Dia was not set to redirect stderr before a call to #run or #run_nonblock.

See Also:



171
172
173
 
# File 'lib/dia/ruby_block.rb', line 171

def stderr
  @stderr
end

#stdout ⇒ String? (readonly)

Provides access to the Standard Output stream of the process that was last used to execute a sandbox. This feature is disabled by default.

Returns:

  • (String) —

    Returns the contents of stdout as a String.

  • (nil) —

    Returns nil when no data is available on stdout.

  • (nil) —

    Returns nil if Dia was not set to redirect stdout before a call to #run or #run_nonblock.

See Also:



126
127
128
 
# File 'lib/dia/ruby_block.rb', line 126

def stdout
  @stdout
end

Instance Method Details

#exception_raised? ⇒ Boolean

Deprecated.

This method is deprecated. #exception_rescued? should be used instead.

Returns:

  • (Boolean) 


225
226
227
228
229
 
# File 'lib/dia/ruby_block.rb', line 225

def exception_raised?
  $stderr.puts 'WARNING: Dia::RubyBlock#exception_raised? is deprecated and will be ' \
               'removed from Dia in a future release.'
  !!exception
end

#exception_rescued? ⇒ Boolean

This method will tell you if an exception has been rescued in the process that was last used to execute a sandbox.

Returns:

  • (Boolean) —

    Returns true when an exception has been rescued.

  • (Boolean) —

    Returns false when an exception has not been rescued.

  • (Boolean) —

    Returns false if Dia was not set to rescue exceptions before a call to #run or #run_nonblock.

See Also:



217
218
219
 
# File 'lib/dia/ruby_block.rb', line 217

def exception_rescued?
  !!exception
end

#redirect_stderr? ⇒ Boolean

This method will tell you if Standard Error output is being redirected in the process spawned to execute a sandbox.

Returns:

  • (Boolean) —

    Returns true when Standard Error output is being redirected.

  • (Boolean) —

    Returns false when Standard Error output is not being redirected.

See Also:



198
199
200
 
# File 'lib/dia/ruby_block.rb', line 198

def redirect_stderr?
  !!@redirect_stderr
end

#redirect_stdout? ⇒ Boolean

This method will tell you if Standard Output is being redirected in the process spawned to execute a sandbox.

Returns:

  • (Boolean) —

    Returns true when Standard Output is being redirected.

  • (Boolean) —

    Returns false when Standard Output is not being redirected.

See Also:



153
154
155
 
# File 'lib/dia/ruby_block.rb', line 153

def redirect_stdout?
  !!@redirect_stdout
end

#rescue_exception? ⇒ Boolean

This method will tell you if an exception will be rescued in the process that is spawned to execute a sandbox.

Returns:

  • (Boolean) —

    Returns true when exceptions are being rescued.

  • (Boolean) —

    Returns false when are exceptions are not being rescued.

See Also:

Since:

  • 2.0.0



242
243
244
 
# File 'lib/dia/ruby_block.rb', line 242

def rescue_exception?
  !!@rescue_exception
end

#run(*args) ⇒ Fixnum

The run method will spawn a child process and execute the block supplied to the constructor in a sandbox.

This method will block. See #run_nonblock for the non-blocking form of this method.

**Side Effects:**

Parameters:

  • Arguments (Arguments) —

    A variable amount of arguments that will be passed onto the the block supplied to the constructor.

Returns:

  • (Fixnum) —

    It returns the Process ID of the spawned process

Raises:

  • (SystemCallError) —

    It will raise a number of subclasses of SystemCallError in a child process if a sandbox violates imposed restrictions.

  • (Dia::SandboxException) —

    It will raise Exceptions::SandboxException in a child process if it was not possible to initialize a sandbox.



316
317
318
319
320
321
322
 
# File 'lib/dia/ruby_block.rb', line 316

def run(*args)
  launch(*args) 

  # parent ..
  _, @exit_status = Process.wait2(@pid)
  @pid
end

#run_nonblock(*args) ⇒ Fixnum

An identical, but non-blocking form of #run.

Returns:

  • (Fixnum) 


326
327
328
329
330
331
 
# File 'lib/dia/ruby_block.rb', line 326

def run_nonblock(*args)  
  launch(*args)

  @exit_status = Process.detach(@pid)
  @pid
end

#value ⇒ String?

Provides access to the return value of the block that has been supplied to the constructor.

Returns:

  • (String) —

    Returns the result of #inspect on the return value of the block that has been executed.

  • (nil) —

    Returns nil if #run or #run_nonblock has not been called yet.



285
286
287
288
289
290
291
292
 
# File 'lib/dia/ruby_block.rb', line 285

def value
  if pipes_readable?(@pipes[:return_reader], @pipes[:return_writer])
    @pipes[:return_writer].close
    @return = @pipes[:return_reader].read
    @pipes[:return_reader].close
  end
  @return
end