philiprehberger-safe_exec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83e5765edb1f180e4207173f2c002a3a35daefadb3e6e96c99aba519ade19914
+  data.tar.gz: c3137cd1943bbd2e2fbff2efd618ac315c36be91b7861d56825dd423ee461778
+SHA512:
+  metadata.gz: 28a46f5aeb95d0d913377c5562bfb4c5351627bee26b50fae4d2fb636791f517d3cfaf0f28c545da4905747912bf8afc5f3f152709eb6d0ca71ce02ce4cfcc31
+  data.tar.gz: dfcc2017095f5acbf78d495171daddaab7af0128563c4cc232eea6813898d2fe679c56017ed842c287dd17103cd6cacf97433ae9572cb64a44cc9c0b9e98fcd1

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Arithmetic operations: addition, subtraction, multiplication, division
+- Comparison operators: ==, !=, >, <, >=, <=
+- Boolean operators: &&, ||, !
+- String concatenation via + operator
+- Hash and array access via bracket notation and dot notation
+- Context variable bindings
+- Timeout support for runaway expressions
+- Custom tokenizer and recursive descent parser (no eval, send, or method_missing)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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/README.md

@@ -0,0 +1,109 @@
+# philiprehberger-safe_exec
+
+[![Tests](https://github.com/philiprehberger/rb-safe-exec/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-safe-exec/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-safe_exec.svg)](https://rubygems.org/gems/philiprehberger-safe_exec)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-safe-exec)](LICENSE)
+
+Sandboxed expression evaluator with whitelisted operations
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-safe_exec"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-safe_exec
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/safe_exec"
+
+Philiprehberger::SafeExec.evaluate('2 + 3 * 4')           # => 14
+Philiprehberger::SafeExec.evaluate('(2 + 3) * 4')         # => 20
+Philiprehberger::SafeExec.evaluate('price * 1.08', { price: 100 })  # => 108.0
+```
+
+### Arithmetic
+
+```ruby
+Philiprehberger::SafeExec.evaluate('10 + 5')   # => 15
+Philiprehberger::SafeExec.evaluate('10 - 5')   # => 5
+Philiprehberger::SafeExec.evaluate('10 * 5')   # => 50
+Philiprehberger::SafeExec.evaluate('10 / 3')   # => 3 (integer division)
+Philiprehberger::SafeExec.evaluate('10.0 / 3') # => 3.333...
+```
+
+### Comparisons and Booleans
+
+```ruby
+Philiprehberger::SafeExec.evaluate('5 > 3')              # => true
+Philiprehberger::SafeExec.evaluate('5 == 5')              # => true
+Philiprehberger::SafeExec.evaluate('true && false')       # => false
+Philiprehberger::SafeExec.evaluate('!false || true')      # => true
+Philiprehberger::SafeExec.evaluate('age >= 18 && age < 65', { age: 25 })  # => true
+```
+
+### String Operations
+
+```ruby
+Philiprehberger::SafeExec.evaluate("'hello' + ' ' + 'world'")  # => "hello world"
+Philiprehberger::SafeExec.evaluate("name == 'Alice'", { name: 'Alice' })  # => true
+```
+
+### Hash and Array Access
+
+```ruby
+context = { items: [10, 20, 30], user: { 'name' => 'Alice', 'role' => 'admin' } }
+
+Philiprehberger::SafeExec.evaluate('items[0]', context)        # => 10
+Philiprehberger::SafeExec.evaluate("user['name']", context)    # => "Alice"
+Philiprehberger::SafeExec.evaluate('user.role', context)       # => "admin"
+```
+
+### Timeout
+
+```ruby
+Philiprehberger::SafeExec.evaluate('1 + 1', {}, timeout: 2)
+# Raises Philiprehberger::SafeExec::TimeoutError if evaluation exceeds 2 seconds
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `SafeExec.evaluate(expr, context, timeout:)` | Evaluate an expression with context variables and optional timeout |
+
+### Supported Operations
+
+| Category | Operations |
+|----------|-----------|
+| Arithmetic | `+`, `-`, `*`, `/` |
+| Comparison | `==`, `!=`, `>`, `<`, `>=`, `<=` |
+| Boolean | `&&`, `\|\|`, `!` |
+| String | concatenation via `+`, comparison |
+| Access | `array[index]`, `hash['key']`, `hash.key` |
+| Literals | integers, floats, strings, booleans, nil |
+| Grouping | parentheses `()` |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/safe_exec/evaluator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SafeExec
+    # Evaluates an AST node tree against a context hash
+    class Evaluator
+      # @param context [Hash] variable bindings for evaluation
+      def initialize(context = {})
+        @context = normalize_context(context)
+      end
+
+      # Evaluate an AST node
+      #
+      # @param node [Hash] the AST node
+      # @return [Object] the evaluation result
+      # @raise [Philiprehberger::SafeExec::Error] on evaluation errors
+      def evaluate(node)
+        case node[:type]
+        when :literal then node[:value]
+        when :identifier then resolve_identifier(node[:name])
+        when :binary then evaluate_binary(node)
+        when :comparison then evaluate_comparison(node)
+        when :and then evaluate(node[:left]) && evaluate(node[:right])
+        when :or then evaluate(node[:left]) || evaluate(node[:right])
+        when :not then !evaluate(node[:operand])
+        when :negate then -evaluate(node[:operand])
+        when :index then evaluate_index(node)
+        when :property then evaluate_property(node)
+        else raise Error, "unknown node type: #{node[:type]}"
+        end
+      end
+
+      private
+
+      def normalize_context(context)
+        context.transform_keys(&:to_s)
+      end
+
+      def resolve_identifier(name)
+        raise Error, "undefined variable: #{name}" unless @context.key?(name)
+
+        @context[name]
+      end
+
+      def evaluate_binary(node)
+        left = evaluate(node[:left])
+        right = evaluate(node[:right])
+
+        case node[:op]
+        when '+' then evaluate_add(left, right)
+        when '-' then left - right
+        when '*' then left * right
+        when '/' then evaluate_divide(left, right)
+        else raise Error, "unknown operator: #{node[:op]}"
+        end
+      end
+
+      def evaluate_add(left, right)
+        if left.is_a?(String) || right.is_a?(String)
+          left.to_s + right.to_s
+        else
+          left + right
+        end
+      end
+
+      def evaluate_divide(left, right)
+        raise Error, 'division by zero' if right.is_a?(Numeric) && right.zero?
+
+        if left.is_a?(Integer) && right.is_a?(Integer)
+          left / right
+        else
+          left.to_f / right.to_f
+        end
+      end
+
+      def evaluate_comparison(node)
+        left = evaluate(node[:left])
+        right = evaluate(node[:right])
+
+        case node[:op]
+        when '==' then left == right
+        when '!=' then left != right
+        when '>' then left > right
+        when '<' then left < right
+        when '>=' then left >= right
+        when '<=' then left <= right
+        else raise Error, "unknown comparison: #{node[:op]}"
+        end
+      end
+
+      def evaluate_index(node)
+        object = evaluate(node[:object])
+        key = evaluate(node[:key])
+
+        case object
+        when Array
+          raise Error, "array index must be an integer, got #{key.class}" unless key.is_a?(Integer)
+
+          object[key]
+        when Hash
+          object[key] || object[key.to_s] || object[key.to_sym]
+        else
+          raise Error, "cannot index into #{object.class}"
+        end
+      end
+
+      def evaluate_property(node)
+        object = evaluate(node[:object])
+        name = node[:name]
+
+        case object
+        when Hash
+          object[name] || object[name.to_s] || object[name.to_sym]
+        else
+          raise Error, "cannot access property '#{name}' on #{object.class}"
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/safe_exec/parser.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SafeExec
+    # Recursive descent parser that builds an AST from tokens
+    class Parser
+      def initialize(tokens)
+        @tokens = tokens
+        @pos = 0
+      end
+
+      # Parse the token stream into an AST node
+      #
+      # @return [Hash] the AST node
+      # @raise [Philiprehberger::SafeExec::Error] on parse errors
+      def parse
+        node = parse_or
+        raise Error, "unexpected token: #{current&.value}" if current
+
+        node
+      end
+
+      private
+
+      def current
+        @tokens[@pos]
+      end
+
+      def advance
+        token = @tokens[@pos]
+        @pos += 1
+        token
+      end
+
+      def expect(type)
+        token = advance
+        raise Error, "expected #{type}, got #{token&.type || 'end of input'}" unless token&.type == type
+
+        token
+      end
+
+      def parse_or
+        left = parse_and
+        while current&.type == :operator && current.value == '||'
+          advance
+          right = parse_and
+          left = { type: :or, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_and
+        left = parse_equality
+        while current&.type == :operator && current.value == '&&'
+          advance
+          right = parse_equality
+          left = { type: :and, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_equality
+        left = parse_comparison
+        while current&.type == :operator && %w[== !=].include?(current.value)
+          op = advance.value
+          right = parse_comparison
+          left = { type: :comparison, op: op, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_comparison
+        left = parse_addition
+        while current&.type == :operator && %w[> < >= <=].include?(current.value)
+          op = advance.value
+          right = parse_addition
+          left = { type: :comparison, op: op, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_addition
+        left = parse_multiplication
+        while current&.type == :operator && %w[+ -].include?(current.value)
+          op = advance.value
+          right = parse_multiplication
+          left = { type: :binary, op: op, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_multiplication
+        left = parse_unary
+        while current&.type == :operator && %w[* /].include?(current.value)
+          op = advance.value
+          right = parse_unary
+          left = { type: :binary, op: op, left: left, right: right }
+        end
+        left
+      end
+
+      def parse_unary
+        if current&.type == :operator && current.value == '!'
+          advance
+          operand = parse_unary
+          return { type: :not, operand: operand }
+        end
+
+        if current&.type == :operator && current.value == '-'
+          advance
+          operand = parse_unary
+          return { type: :negate, operand: operand }
+        end
+
+        parse_access
+      end
+
+      def parse_access
+        node = parse_primary
+
+        while current
+          if current.type == :lbracket
+            advance
+            index = parse_or
+            expect(:rbracket)
+            node = { type: :index, object: node, key: index }
+          elsif current.type == :dot
+            advance
+            property = expect(:identifier)
+            node = { type: :property, object: node, name: property.value }
+          else
+            break
+          end
+        end
+
+        node
+      end
+
+      def parse_primary
+        token = current
+        raise Error, 'unexpected end of expression' unless token
+
+        case token.type
+        when :number
+          advance
+          value = token.value.include?('.') ? token.value.to_f : token.value.to_i
+          { type: :literal, value: value }
+        when :string
+          advance
+          { type: :literal, value: token.value[1..-2] }
+        when :boolean
+          advance
+          { type: :literal, value: token.value == 'true' }
+        when :null
+          advance
+          { type: :literal, value: nil }
+        when :identifier
+          advance
+          { type: :identifier, name: token.value }
+        when :lparen
+          advance
+          node = parse_or
+          expect(:rparen)
+          node
+        else
+          raise Error, "unexpected token: #{token.value}"
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/safe_exec/tokenizer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SafeExec
+    # Tokenizes expression strings into an array of typed tokens
+    module Tokenizer
+      TOKEN_PATTERNS = [
+        [:number, /\A-?\d+(?:\.\d+)?/],
+        [:string, /\A'[^']*'/],
+        [:string, /\A"[^"]*"/],
+        [:boolean, /\A(?:true|false)\b/],
+        [:null, /\Anil\b/],
+        [:operator, /\A(?:&&|\|\||[!=]=|>=|<=|[+\-*\/><!])/],
+        [:lparen, /\A\(/],
+        [:rparen, /\A\)/],
+        [:lbracket, /\A\[/],
+        [:rbracket, /\A\]/],
+        [:dot, /\A\./],
+        [:comma, /\A,/],
+        [:identifier, /\A[a-zA-Z_][a-zA-Z0-9_]*/],
+        [:whitespace, /\A\s+/]
+      ].freeze
+
+      Token = Struct.new(:type, :value, keyword_init: true)
+
+      # Tokenize an expression string
+      #
+      # @param input [String] the expression to tokenize
+      # @return [Array<Token>] the token list
+      # @raise [Philiprehberger::SafeExec::Error] on unexpected characters
+      def self.tokenize(input)
+        tokens = []
+        pos = 0
+
+        while pos < input.length
+          matched = false
+
+          TOKEN_PATTERNS.each do |type, pattern|
+            match = input[pos..].match(pattern)
+            next unless match
+
+            tokens << Token.new(type: type, value: match[0]) unless type == :whitespace
+            pos += match[0].length
+            matched = true
+            break
+          end
+
+          raise Error, "unexpected character at position #{pos}: '#{input[pos]}'" unless matched
+        end
+
+        tokens
+      end
+    end
+  end
+end

data/lib/philiprehberger/safe_exec/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module SafeExec
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/safe_exec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'safe_exec/version'
+require_relative 'safe_exec/tokenizer'
+require_relative 'safe_exec/parser'
+require_relative 'safe_exec/evaluator'
+
+module Philiprehberger
+  module SafeExec
+    class Error < StandardError; end
+
+    # Raised when evaluation exceeds the timeout
+    class TimeoutError < Error; end
+
+    DEFAULT_TIMEOUT = 5
+
+    # Evaluate a sandboxed expression with an optional context
+    #
+    # @param expr [String] the expression to evaluate
+    # @param context [Hash] variable bindings
+    # @param timeout [Numeric] maximum evaluation time in seconds
+    # @return [Object] the evaluation result
+    # @raise [Error] on parse or evaluation errors
+    # @raise [TimeoutError] if evaluation exceeds the timeout
+    def self.evaluate(expr, context = {}, timeout: DEFAULT_TIMEOUT)
+      result = nil
+      error = nil
+
+      thread = Thread.new do
+        tokens = Tokenizer.tokenize(expr)
+        ast = Parser.new(tokens).parse
+        result = Evaluator.new(context).evaluate(ast)
+      rescue Error => e
+        error = e
+      end
+
+      unless thread.join(timeout)
+        thread.kill
+        raise TimeoutError, "expression evaluation timed out after #{timeout} seconds"
+      end
+
+      raise error if error
+
+      result
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-safe_exec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: Safely evaluate arithmetic, comparison, and boolean expressions from
+  untrusted input. Uses a custom parser with no eval, send, or method_missing. Includes
+  timeout support.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/safe_exec.rb
+- lib/philiprehberger/safe_exec/evaluator.rb
+- lib/philiprehberger/safe_exec/parser.rb
+- lib/philiprehberger/safe_exec/tokenizer.rb
+- lib/philiprehberger/safe_exec/version.rb
+homepage: https://github.com/philiprehberger/rb-safe-exec
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-safe-exec
+  source_code_uri: https://github.com/philiprehberger/rb-safe-exec
+  changelog_uri: https://github.com/philiprehberger/rb-safe-exec/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-safe-exec/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+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.5.22
+signing_key:
+specification_version: 4
+summary: Sandboxed expression evaluator with whitelisted operations
+test_files: []