ruby_gaurden 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc546e0183aa5317cd7f463490262c6929e20a8a5261dd6731d6578abce11907
+  data.tar.gz: c8fdd3f6d9777ff56780fd933f21cd34432e8dd80656019853fdb0c3e9ec9ee1
+SHA512:
+  metadata.gz: a2a9efa813c4d0cf4eca8471b0d93bdce036ba946e0ef3373148f8993d00d606535b6200671ae03832d0af83bef0e1e25397e502f49223342f88c30a1997526f
+  data.tar.gz: 5f9892a85b6b83826556f797f6ba6ea709a0307ee4a52665492121d96a261026a405a514dcb3fd152930934bcac910c8c0ad256987472e5bffaa99155287d457

data/lib/ruby_gaurden/bed.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class Bed
+    include Execution
+    include RuntimeEnvironment
+    include Bindings
+    include Bridging
+    include ThreadSafety
+
+    # Creates a new instance of the Bed and executes the provided source.
+    # @param args [Array] Arguments passed to #execute.
+    # @return [Object] The result of the execution.
+    # @see #execute
+    def self.execute(...)
+      new.execute(...)
+    end
+  end
+end

data/lib/ruby_gaurden/bed_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class BedError < Error
+    def self.[](class_name)
+      bed_class_name = :"Bed#{class_name}"
+
+      if const_defined?(bed_class_name) && (klass = const_get(bed_class_name)) < self
+        klass
+      else
+        const_set(bed_class_name, Class.new(self))
+      end
+    end
+  end
+end

data/lib/ruby_gaurden/bindings.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  module Bindings
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def bindings
+        @bindings ||= if superclass.respond_to?(:bindings)
+                        superclass.bindings.dup
+                      else
+                        []
+                      end
+      end
+
+      private
+
+      def binds(target, proc = nil, &block)
+        actual_proc = proc || block || -> {}
+        bindings << [target, actual_proc]
+      end
+    end
+
+    def initialize(*)
+      super
+
+      self.class.bindings.each do |target, proc|
+        bind target, lambda { |*args|
+          instance_exec(*args, &proc)
+        }
+      end
+    end
+
+    def bind(target, proc = -> {})
+      context.attach(target, proc)
+    end
+  end
+end

data/lib/ruby_gaurden/bridging.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+require 'json'
+require 'active_support/concern'
+
+module RubyGaurden
+  module Bridging
+    extend ActiveSupport::Concern
+
+    included do
+      binds('__rb_exit') { |status| raise Error, "Exit with status #{status.inspect}" }
+      binds('__rb_stdout_write') { |data| stdout << data }
+      binds('__rb_stderr_write') { |data| stderr << data }
+
+      executes <<-RUBY
+        # backtick_javascript: true
+        require 'native'
+        require 'singleton'
+        require 'json'
+
+        module RubyGaurden
+          VERSION = #{RubyGaurden::VERSION.inspect}
+
+          class CurrentBedProxy
+            include Singleton
+          end
+
+          def self.planted?
+            true
+          end
+
+          def self.current
+            CurrentBedProxy.instance
+          end
+
+          # Handles method invocation from the host, ensuring data is correctly
+          # translated and errors are caught.
+          def self.__invoke_from_host(method_name, args_json)
+            args = JSON.parse(args_json)
+            value = ::Object.send(method_name, *args)
+
+            { isCaught: false, val: value.to_json }
+          rescue Exception => e
+            { isCaught: true, val: [e.class.name, e.message].to_json }
+          end
+
+          # Handles code evaluation from the host.
+          def self.__eval_from_host(js_source)
+            value = `eval(js_source)`
+            { isCaught: false, val: value.to_json }
+          rescue Exception => e
+            { isCaught: true, val: [e.class.name, e.message].to_json }
+          end
+        end
+
+        module Kernel
+          def exit(status = 0)
+            `__rb_exit(status)`
+          end
+        end
+
+        $stdout.write_proc = ->(data) { `__rb_stdout_write(data)` }
+        $stderr.write_proc = ->(data) { `__rb_stderr_write(data)` }
+
+        `
+          globalThis.__rb_bridge_invoke = function(methodName, argsJson) {
+            return Opal.RubyGaurden.$__invoke_from_host(methodName, argsJson).$to_n();
+          };
+
+          globalThis.__rb_eval_wrapper = function(source) {
+            return Opal.RubyGaurden.$__eval_from_host(source).$to_n();
+          };
+        `
+      RUBY
+    end
+
+    class_methods do
+      # Exposes host methods to the sandbox, allowing sandboxed code to call
+      # back into the main Ruby process safely via JSON serialization.
+      # @param method_names [Array<Symbol, String>] Methods on the host to expose.
+      # @note Blocks are not supported for bridged methods.
+      def exposes(*method_names)
+        method_names.each do |method_name|
+          handle = "__rb_expose_#{method_name}"
+          binds(handle, ->(json) { send(method_name, *JSON.parse(json)).to_json })
+
+          executes(<<-RUBY)
+            # backtick_javascript: true
+            def (RubyGaurden::CurrentBedProxy.instance).#{method_name}(*args, &block)
+              raise ArgumentError, "Blocks not supported" if block
+              JSON.parse(`#{handle}(\#{args.to_json})`)
+            end
+          RUBY
+        end
+      end
+    end
+
+    # Returns the accumulated stdout produced by the sandbox.
+    # @return [Array<String>]
+    def stdout
+      @stdout ||= []
+    end
+
+    # Returns the accumulated stderr produced by the sandbox.
+    # @return [Array<String>]
+    def stderr
+      @stderr ||= []
+    end
+
+    # Clears the IO buffers (stdout and stderr).
+    def reset_io!
+      @stdout = []
+      @stderr = []
+    end
+
+    # Directly invokes a Ruby method defined inside the sandbox.
+    # This bypasses the Ruby-to-JS compilation step for the call itself.
+    # @param method_name [Symbol, String] The name of the method to call.
+    # @param args [Array] Arguments to pass to the method.
+    # @return [Object] The result of the method call.
+    # @raise [BedError] if the method raises an exception inside the sandbox.
+    def call(method_name, *args)
+      # We use JSON to move data across the bridge to avoid V8/Ruby object mapping overhead
+      # and to ensure Opal objects are correctly initialized.
+      serialized_args = args.to_json
+      result = context.call('__rb_bridge_invoke', method_name.to_s, serialized_args)
+      handle_bridge_result(result)
+    end
+
+    private
+
+    def eval_compiled_source(source)
+      result = context.call('__rb_eval_wrapper', source)
+      handle_bridge_result(result) # result is the Ruby Hash returned by MiniRacer
+    rescue MiniRacer::ScriptTerminatedError => e
+      raise TimeoutError, e.message
+    rescue MiniRacer::RuntimeError, StandardError => e
+      raise e if e.is_a?(RubyGaurden::Error)
+
+      raise ExecutionError, e.message
+    end
+
+    def handle_bridge_result(result)
+      return unless result.is_a?(Hash)
+
+      if result.fetch('isCaught', false)
+        class_name, message = result_value(result)
+        raise BedError[class_name], message
+      end
+
+      result_value(result)
+    rescue MiniRacer::RuntimeError, StandardError => e
+      raise e if e.is_a?(RubyGaurden::Error)
+
+      raise ExecutionError, e.message
+    end
+
+    def result_value(result)
+      result['val'] ? JSON.parse(result['val'], quirks_mode: true) : nil
+    end
+  end
+end

data/lib/ruby_gaurden/compilation_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class CompilationError < Error
+  end
+end

data/lib/ruby_gaurden/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class Error < StandardError
+  end
+end

data/lib/ruby_gaurden/execution.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+require 'active_support/concern'
+require 'mini_racer'
+
+module RubyGaurden
+  module Execution
+    extend ActiveSupport::Concern
+
+    DEFAULT_MAXIMUM_EXECUTION_TIME = 1000
+    DEFAULT_MAX_MEMORY = 512 * 1024 * 1024 # 512MB default limit
+
+    class_methods do
+      def maximum_execution_time
+        @maximum_execution_time ||= superclass.maximum_execution_time if superclass.respond_to?(:maximum_execution_time)
+      end
+
+      def maximum_memory
+        @maximum_memory ||= superclass.maximum_memory if superclass.respond_to?(:maximum_memory)
+      end
+
+      # Sets the maximum time a script can execute before being terminated.
+      # @param seconds [Integer, Float] Time in seconds.
+      def times_out_in(seconds)
+        @maximum_execution_time = seconds
+      end
+
+      # Sets the maximum memory the V8 context can consume.
+      # @param bytes [Integer] Memory limit in bytes.
+      def limits_memory_to(bytes)
+        @maximum_memory = bytes
+      end
+
+      # Accesses the thread-safe pool of pre-warmed V8 contexts.
+      # @return [Thread::Queue]
+      def context_pool
+        @context_pool ||= ::Queue.new
+      end
+
+      # Pre-warms a specified number of V8 contexts and adds them to the pool.
+      # @param size [Integer] The number of contexts to create.
+      def warm_up(size = 1)
+        size.times { context_pool.push(create_context) }
+      end
+
+      # Creates a fresh V8 context and evaluates the initialization source.
+      # Use this to bypass the pool if needed or to manually populate it.
+      # @return [MiniRacer::Context]
+      def create_context
+        # Use a large timeout (30s) for initialization to ensure the large Opal
+        # runtime loads even if the user set a small timeout for their code.
+        MiniRacer::Context.new(
+          timeout: (maximum_execution_time || DEFAULT_MAXIMUM_EXECUTION_TIME) * 1000,
+          max_memory: maximum_memory || DEFAULT_MAX_MEMORY
+        ).tap do |ctx|
+          # We use a secondary timeout for the init phase. If this fails,
+          # the context is not returned/tapped, preventing a "broken"
+          # context from entering the pool or being used by an instance.
+          ctx.eval(send(:initialization_source), timeout: 30_000)
+        end
+      end
+    end
+
+    def maximum_execution_time
+      @maximum_execution_time ||= self.class.maximum_execution_time
+    end
+
+    def maximum_memory
+      @maximum_memory ||= self.class.maximum_memory
+    end
+
+    def maximum_execution_time_ms
+      return unless maximum_execution_time
+
+      maximum_execution_time * 1000
+    end
+
+    def context
+      @context ||= checkout_context
+    end
+
+    private
+
+    def checkout_context
+      self.class.context_pool.pop(true)
+    rescue ThreadError
+      self.class.create_context
+    end
+
+    def eval_compiled_source(source)
+      context.eval source
+    rescue MiniRacer::RuntimeError => e
+      raise ExecutionError, e.message
+    rescue MiniRacer::ScriptTerminatedError => e
+      raise TimeoutError, e.message
+    end
+  end
+end

data/lib/ruby_gaurden/execution_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class ExecutionError < Error
+  end
+end

data/lib/ruby_gaurden/runtime_environment.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+require 'active_support/concern'
+require 'opal'
+
+module RubyGaurden
+  module RuntimeEnvironment
+    extend ActiveSupport::Concern
+
+    MAX_CACHE_SIZE = 1000
+
+    included do
+      uses 'opal'
+      requires 'opal'
+    end
+
+    class_methods do
+      def compiled_cache
+        @compiled_cache ||= {}
+      end
+
+      private
+
+      # Declares a gem dependency to be loaded into the sandbox.
+      # @param gem_names [Array<String>] List of gem names.
+      def uses(*gem_names)
+        @uses ||= []
+        @uses += gem_names
+      end
+
+      # Declares a file or feature to be required within the sandbox.
+      # @param paths [Array<String>] List of paths to require.
+      def requires(*paths)
+        @requires ||= []
+        @requires += paths
+      end
+
+      # Defines Ruby code to be executed during the initialization of every sandbox instance.
+      # Useful for setting up global state or helper classes.
+      # @param source [String] The Ruby code to execute during boot.
+      def executes(source)
+        @executes ||= []
+        @executes << source
+      end
+
+      def initialization_source
+        @initialization_source ||= build_initialization_source
+      rescue SyntaxError, StandardError => e
+        raise CompilationError, e.message
+      end
+
+      def build_initialization_source
+        builder = Opal::Builder.new(compiler_options: { arity_check: true, dynamic_require_severity: :error })
+        builder.build('opal')
+
+        # Ensure the builder can resolve requirements by including the gems
+        inherited_values(:@uses).uniq.each { |g| builder.use_gem(g) }
+        inherited_values(:@requires).uniq.each { |p| builder.build(p) }
+        inherited_values(:@executes).each { |s| builder.build_str(s, '(executes)') }
+
+        builder.to_s
+      end
+
+      def inherited_values(ivar)
+        ancestors.reverse.flat_map do |ancestor|
+          ancestor.instance_variable_defined?(ivar) ? ancestor.instance_variable_get(ivar) : []
+        end
+      end
+    end
+
+    # Executes a string of Ruby code within the sandbox instance.
+    # Results are cached by the source string to optimize repeated calls.
+    # @param source [String] The Ruby code to execute.
+    # @return [Object] The result of the execution, translated to host Ruby objects.
+    # @raise [CompilationError] if the code has syntax errors.
+    # @raise [ExecutionError] if the code raises an exception during runtime.
+    def execute(source)
+      js = self.class.compiled_cache[source] || compile_and_cache(source)
+      eval_compiled_source(js)
+    end
+
+    # Compiles Ruby source to JavaScript and clears the cache if the limit is reached.
+    # @param source [String] Ruby source code.
+    # @return [String] Compiled JavaScript.
+    def compile_and_cache(source)
+      prune_cache! if self.class.compiled_cache.size >= MAX_CACHE_SIZE
+      self.class.compiled_cache[source] = Opal::Compiler.new(source, file: '(execute)', arity_check: true).compile
+    rescue SyntaxError => e
+      raise CompilationError, e.message
+    end
+
+    # Prune the oldest 10% of entries (at least 1) to avoid performance cliffs.
+    # Since Ruby Hashes maintain insertion order, this behaves like FIFO.
+    def prune_cache!
+      self
+        .class
+        .compiled_cache
+        .keys
+        .first([1, MAX_CACHE_SIZE / 10].max)
+        .each { |k| self.class.compiled_cache.delete(k) }
+    end
+  end
+end

data/lib/ruby_gaurden/thread_safety.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+require 'active_support/concern'
+require 'monitor'
+
+module RubyGaurden
+  module ThreadSafety
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def maximum_execution_time
+        synchronize { super }
+      end
+
+      def initialization_source
+        synchronize { super }
+      end
+
+      def bindings
+        synchronize { super }
+      end
+
+      private
+
+      def times_out_in(...)
+        synchronize { super }
+      end
+
+      def uses(...)
+        synchronize { super }
+      end
+
+      def requires(...)
+        synchronize { super }
+      end
+
+      def executes(...)
+        synchronize { super }
+      end
+
+      def binds(...)
+        synchronize { super }
+      end
+
+      def exposes(...)
+        synchronize { super }
+      end
+
+      def synchronize(&)
+        monitor.synchronize(&)
+      end
+
+      def monitor
+        @monitor ||= Monitor.new
+      end
+    end
+
+    def maximum_execution_time
+      synchronize { super }
+    end
+
+    def execute(...)
+      synchronize { super }
+    end
+
+    def synchronize(&)
+      monitor.synchronize(&)
+    end
+
+    def monitor
+      @monitor ||= Monitor.new
+    end
+  end
+end

data/lib/ruby_gaurden/timeout_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden'
+
+module RubyGaurden
+  class TimeoutError < Error
+  end
+end

data/lib/ruby_gaurden/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyGaurden
+  VERSION = '0.1.0'
+end

data/lib/ruby_gaurden.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'ruby_gaurden/version'
+
+module RubyGaurden
+  autoload :Bindings, 'ruby_gaurden/bindings'
+  autoload :BedError, 'ruby_gaurden/bed_error'
+  autoload :Bridging, 'ruby_gaurden/bridging'
+  autoload :CompilationError, 'ruby_gaurden/compilation_error'
+  autoload :Error, 'ruby_gaurden/error'
+  autoload :Execution, 'ruby_gaurden/execution'
+  autoload :ExecutionError, 'ruby_gaurden/execution_error'
+  autoload :Bed, 'ruby_gaurden/bed'
+  autoload :RuntimeEnvironment, 'ruby_gaurden/runtime_environment'
+  autoload :ThreadSafety, 'ruby_gaurden/thread_safety'
+  autoload :TimeoutError, 'ruby_gaurden/timeout_error'
+
+  module_function
+
+  # Checks if the current execution context is inside a sandbox.
+  # @return [Boolean] true if inside a sandbox, false otherwise.
+  def planted?
+    false
+  end
+
+  # Returns the current sandbox proxy instance if running inside a sandbox.
+  # @return [Object, nil] The proxy instance or nil if outside a sandbox.
+  def current
+    nil
+  end
+
+  # Convenience method to execute Ruby code in a fresh, one-off sandbox.
+  # @param args [Array] Arguments passed to Bed.execute.
+  # @return [Object] The result of the execution.
+  def execute(...)
+    Bed.execute(...)
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: ruby_gaurden
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tayler Phillips
+bindir: bin
+cert_chain: []
+date: 2026-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: mini_racer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: opal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+email:
+- taylerphillips20@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ruby_gaurden.rb
+- lib/ruby_gaurden/bed.rb
+- lib/ruby_gaurden/bed_error.rb
+- lib/ruby_gaurden/bindings.rb
+- lib/ruby_gaurden/bridging.rb
+- lib/ruby_gaurden/compilation_error.rb
+- lib/ruby_gaurden/error.rb
+- lib/ruby_gaurden/execution.rb
+- lib/ruby_gaurden/execution_error.rb
+- lib/ruby_gaurden/runtime_environment.rb
+- lib/ruby_gaurden/thread_safety.rb
+- lib/ruby_gaurden/timeout_error.rb
+- lib/ruby_gaurden/version.rb
+homepage: https://github.com/Phillita/ruby_gaurden
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/Phillita/ruby_gaurden
+  changelog_uri: https://github.com/Phillita/ruby_gaurden/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Phillita/ruby_gaurden/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: RubyGaurden allows the execution of untrusted Ruby code safely in a walled
+  garden.
+test_files: []