cleanroom-next 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05b7bbf84ca0dda05ebb3e5f4bff790af5e69b7f6f7081dd24549c759a84cf71
+  data.tar.gz: e4347462a89a0a8f1c11ce338da4f8dfab9ff65fbea6900c09c3678b8b332cf1
+SHA512:
+  metadata.gz: 5fa0e7784212b46b7367f725e7113e91f68160721a961ddf131e08d3b5cd8db3944f6749b81d6ef1933a4a282b0be5c1bd840ac8f9c310d67ed4d4c871aae5c1
+  data.tar.gz: 1853e7e1fb508cba0a5d3270e7264ad0d192639f0e3c180edee211c786a24d42367fc596ebd96a7525ab6b25af5bc34926347d3d9916349a560e8bc447d8c133

data/lib/cleanroom/errors.rb

@@ -0,0 +1,38 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Cleanroom
+  # Base class for errors raised by Cleanroom
+  class Error < StandardError; end
+
+  # Error raised when trying to access a non accessible variable or method
+  class InaccessibleError < Error
+    def initialize(name, instance)
+      super()
+      @name = name
+      @instance = instance
+    end
+
+    # @return [String] The error message
+    def to_s
+      <<~ERROR_MESSAGE.gsub(/\r?\n/, ' ')
+        Undefined local variable or method `#{@name}' for #{@instance}. It may have
+        been removed for the purposes of evaluating the DSL or for added security. If
+        you feel you have reached this message in error, please open an issue.
+      ERROR_MESSAGE
+    end
+  end
+end

data/lib/cleanroom/rspec.rb

@@ -0,0 +1,57 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative '../cleanroom'
+
+require 'rspec' unless defined?(RSpec)
+
+#
+# Assert a given method is exposed on a class.
+#
+# @example Checking against an instance
+#   expect(:method1).to be_an_exposed_method_on(instance)
+#
+# @example Checking against a class
+#   expect(:method1).to be_an_exposed_method_on(klass)
+#
+RSpec::Matchers.define :be_an_exposed_method_on do |object|
+  match do |name|
+    if object.is_a?(Class)
+      object.exposed_methods.key?(name.to_sym)
+    else
+      object.class.exposed_methods.key?(name.to_sym)
+    end
+  end
+end
+
+#
+# Assert a given class or instance has an exposed method.
+#
+# @example Checking against an instance
+#   expect(instance).to have_exposed_method(:method1)
+#
+# @example Checking against a class
+#   expect(klass).to have_exposed_method(:method1)
+#
+RSpec::Matchers.define :have_exposed_method do |name|
+  match do |object|
+    if object.is_a?(Class)
+      object.exposed_methods.key?(name.to_sym)
+    else
+      object.class.exposed_methods.key?(name.to_sym)
+    end
+  end
+end

data/lib/cleanroom/version.rb

@@ -0,0 +1,24 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Cleanroom
+  #
+  # The version of the Cleanroom gem.
+  #
+  # @return [String]
+  #
+  VERSION = '1.0.1'
+end

data/lib/cleanroom.rb

@@ -0,0 +1,236 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative 'cleanroom/errors'
+require_relative 'cleanroom/version'
+
+# The cleanroom pattern is a safer, more convenient, Ruby-like approach for
+# limiting the information exposed by a DSL while giving users the ability to
+# write awesome code!
+module Cleanroom
+  #
+  # Callback for when this module is included.
+  #
+  # @param [Class] base
+  #
+  def self.included(base)
+    base.send(:extend,  ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  #
+  # Callback for when this module is included.
+  #
+  # @param [Class] base
+  #
+  def self.extended(base)
+    base.send(:extend,  ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  #
+  # Class methods
+  #
+  module ClassMethods
+    #
+    # Evaluate the file in the context of the cleanroom.
+    #
+    # @param [Class] instance
+    #   the instance of the class to evaluate against
+    # @param [String] filepath
+    #   the path of the file to evaluate
+    #
+    def evaluate_file(instance, filepath)
+      absolute_path = File.expand_path(filepath)
+      file_contents = File.read(absolute_path)
+      evaluate(instance, file_contents, absolute_path, 1)
+    end
+
+    #
+    # Evaluate the string or block in the context of the cleanroom.
+    #
+    # @param [Class] instance
+    #   the instance of the class to evaluate against
+    def evaluate(instance, ...)
+      cleanroom.new(instance).instance_eval(...)
+    end
+
+    #
+    # Expose the given method to the DSL.
+    #
+    # @param [Symbol] name
+    #
+    def expose(name)
+      raise NameError, "undefined method `#{name}' for class `#{self.name}'" unless public_method_defined?(name)
+
+      exposed_methods_with_kwargs[name] = true if instance_method(name).parameters.any? { |(arg_type, _arg_name)| KWARGS_TYPES.include?(arg_type) }
+      exposed_methods[name] = true
+    end
+
+    #
+    # The list of exposed methods.
+    #
+    # @return [Hash]
+    #
+    def exposed_methods
+      @exposed_methods ||= from_superclass(:exposed_methods, {}).dup
+    end
+
+    private
+
+    # Define the types of argument types that point kwargs arguments.
+    # Useful to treat them differently as when defining a method with kwargs, Ruby will pass parameters having a to_hash method differently to such methods:
+    #
+    # See this example illustrating the difference in treatment with and without kwargs in the method definition:
+    # def without_kwargs(*args)
+    #   p args
+    # end
+    # def with_kwargs(*args, **kwargs)
+    #   p args
+    #   p kwargs
+    # end
+    # s_without_to_hash = 'Without to_hash'
+    # s_with_to_hash = 'With to_hash'
+    # s_with_to_hash.define_singleton_method(:to_hash) { { string: self.to_s } }
+    # without_kwargs(s_without_to_hash)
+    #   ["Without to_hash"]
+    # without_kwargs(s_with_to_hash)
+    #   ["With to_hash"]
+    # with_kwargs(s_without_to_hash)
+    #   ["Without to_hash"]
+    #   {}
+    # with_kwargs(s_with_to_hash)
+    #   []
+    #   {:string=>"With to_hash"}
+    KWARGS_TYPES = %i[key keyreq]
+
+    #
+    # The list of exposed methods with kwargs.
+    #
+    # @return [Hash]
+    #
+    def exposed_methods_with_kwargs
+      @exposed_methods_with_kwargs ||= from_superclass(:exposed_methods_with_kwargs, {}).dup
+    end
+
+    #
+    # The cleanroom instance for this class. This method is intentionally
+    # NOT cached!
+    #
+    # @return [Class]
+    #
+    def cleanroom
+      exposed = exposed_methods.keys
+      exposed_with_kwargs = exposed_methods_with_kwargs.keys
+      parent = name || 'Anonymous'
+
+      Class.new(Object) do
+        class << self
+          def class_eval
+            raise Cleanroom::InaccessibleError.new(:class_eval, self)
+          end
+
+          def instance_eval
+            raise Cleanroom::InaccessibleError.new(:instance_eval, self)
+          end
+        end
+
+        define_method(:initialize) do |instance|
+          define_singleton_method(:__instance__) do
+            # Since Ruby 2.6, the first frame of `caller` for code evaluated via
+            # `instance_eval`/`eval` is labeled "(eval at <file>:<line>)", where
+            # the location is the very call site of `instance_eval` - here
+            # cleanroom.rb itself. That made the previous
+            # `caller[0].include?(__FILE__)` check wrongly grant DSL code access
+            # to the wrapped instance. Eval frames must be excluded: only real
+            # frames inside this file may call __instance__.
+            calling_frame = caller_locations(1, 1).first
+            unless calling_frame && !calling_frame.path.start_with?('(') && calling_frame.path.include?(__FILE__)
+              raise Cleanroom::InaccessibleError.new(:__instance__, self)
+            end
+
+            instance
+          end
+        end
+
+        (exposed - exposed_with_kwargs).each do |exposed_method|
+          define_method(exposed_method) do |*args, &block|
+            __instance__.public_send(exposed_method, *args, &block)
+          end
+        end
+
+        exposed_with_kwargs.each do |exposed_method|
+          define_method(exposed_method) do |*args, **kwargs, &block|
+            __instance__.public_send(exposed_method, *args, **kwargs, &block)
+          end
+        end
+
+        define_method(:class_eval) do
+          raise Cleanroom::InaccessibleError.new(:class_eval, self)
+        end
+
+        define_method(:inspect) do
+          "#<#{parent} (Cleanroom)>"
+        end
+        alias_method :to_s, :inspect
+      end
+    end
+
+    #
+    # Get the value from the superclass, if it responds, otherwise return
+    # +default+. Since class instance variables are **not** inherited upon
+    # subclassing, this is a required check to ensure subclasses inherit
+    # exposed DSL methods.
+    #
+    # @param [Symbol] method_name
+    #   the name of the method to find
+    # @param [Object] default
+    #   the default value to return if not found
+    #
+    def from_superclass(method_name, default = nil)
+      return default if superclass == Cleanroom
+
+      superclass.respond_to?(method_name) ? superclass.send(method_name) : default
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+  module InstanceMethods
+    #
+    # Evaluate the file against the current instance.
+    #
+    # @param (see Cleanroom.evaluate_file)
+    # @return [self]
+    #
+    def evaluate_file(filepath)
+      self.class.evaluate_file(self, filepath)
+      self
+    end
+
+    #
+    # Evaluate the contents against the current instance.
+    #
+    # @param (see Cleanroom.evaluate_file)
+    # @return [self]
+    #
+    def evaluate(...)
+      self.class.evaluate(self, ...)
+      self
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: cleanroom-next
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Seth Vargo
+- Muriel Salvan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ruby is an excellent programming language for creating and managing custom
+  DSLs, but how can you securely evaluate a DSL while explicitly controlling the methods
+  exposed to the user? Our good friends instance_eval and instance_exec are great,
+  but they expose all methods - public, protected, and private - to the user. Even
+  worse, they expose the ability to accidentally or intentionally alter the behavior
+  of the system! The cleanroom pattern is a safer, more convenient, Ruby-like approach
+  for limiting the information exposed by a DSL while giving users the ability to
+  write awesome code!
+email:
+- sethvargo@gmail.com
+- muriel@x-aeon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cleanroom.rb
+- lib/cleanroom/errors.rb
+- lib/cleanroom/rspec.rb
+- lib/cleanroom/version.rb
+homepage: https://github.com/Muriel-Salvan/cleanroom
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: "(More) safely evaluate Ruby DSLs with cleanroom"
+test_files: []